Documentation
¶
Overview ¶
Package acp implements the Agent Client Protocol (ACP) frontend: it lets an editor (Zed, JetBrains, Neovim, ...) spawn codebot as a child process and drive it over JSON-RPC 2.0 on stdio. It is the fourth frontend alongside the TUI, print, and RPC modes — a thin adapter over agent.Session, leaving the agentcore kernel and the harness untouched.
Stdout is the protocol channel in this mode; nothing else may write to it (logging and diagnostics go to stderr).
Index ¶
- func Serve(rt *bootstrap.Runtime, version string, fs *WorkspaceFS) error
- type WorkspaceFS
- func (w *WorkspaceFS) Open(ctx context.Context, path string) (io.ReadCloser, error)
- func (w *WorkspaceFS) ReadFile(ctx context.Context, path string) ([]byte, error)
- func (w *WorkspaceFS) Stat(ctx context.Context, path string) (agentcoretools.FileInfo, error)
- func (w *WorkspaceFS) WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
func Serve(rt *bootstrap.Runtime, version string, fs *WorkspaceFS) error
Serve runs codebot as an ACP agent over stdio, blocking until the client disconnects. fs is the editor-backed WorkspaceFS injected into the runtime's tools at boot; Serve binds the live connection to it. Pass nil to keep the local filesystem.
Types ¶
type WorkspaceFS ¶
type WorkspaceFS struct {
agentcoretools.OSWorkspaceFS // fallback for stat/readdir/mkdir and non-text reads
// contains filtered or unexported fields
}
WorkspaceFS is the ACP-backed agentcore WorkspaceFS: read/write of text files is routed to the editor (fs/read_text_file, fs/write_text_file) so the agent sees unsaved buffer contents and writes land back in the editor. Everything else — stat, directory listing, mkdir, and any file the editor can't serve as text (binary, images, or when the client lacks the capability) — falls back to the local filesystem via the embedded OSWorkspaceFS.
The connection and session id are bound lazily: the backend is constructed before Boot (so it can be injected into the tools), while the ACP connection only exists once Serve starts. Until bound, every method transparently uses the OS fallback.
func NewWorkspaceFS ¶
func NewWorkspaceFS() *WorkspaceFS
NewWorkspaceFS creates an unbound ACP backend. Until bindConn/setSession/ setCaps are called it behaves exactly like the local filesystem.
Diagnostics go to stderr (log is concurrency-safe and stdout is the protocol channel). The fallback to disk on an editor read error stays, but is no longer silent — it is the only signal that the editor's buffer view was bypassed.
func (*WorkspaceFS) Open ¶
func (w *WorkspaceFS) Open(ctx context.Context, path string) (io.ReadCloser, error)
Open returns the editor buffer (if available) as a reader, else the OS file.
Reads keep a silent OS fallback on purpose: it is how images and binaries are served (the editor's text endpoint errors on them, and we must read the bytes to sniff/decode), and how brand-new or editor-unknown files are read. A read is non-destructive, so degrading to the on-disk copy is safe — unlike a write (see WriteFile).
func (*WorkspaceFS) Stat ¶
func (w *WorkspaceFS) Stat(ctx context.Context, path string) (agentcoretools.FileInfo, error)
Stat reports metadata. For a file the editor can serve as text it synthesizes a FileInfo whose Version is a hash of the *current buffer* — so the read-before-write check tracks unsaved edits (disk mtime would not change for them) and the agent can stat a buffer that has no file on disk yet. Anything the editor can't serve as text (directories, binaries, images, or when unbound/uncapable) falls through to the local filesystem.
func (*WorkspaceFS) WriteFile ¶
func (w *WorkspaceFS) WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error
WriteFile writes through the editor when it is bound and advertises the capability; otherwise it writes the local file.
Unlike reads, a failed editor write is NOT silently retried against disk: the editor is the source of truth in that mode, so writing behind its back would desync the buffer and the file and leave the user thinking the edit landed in the editor. We surface the error instead. (Falling back is only correct when the editor was never going to handle the write — unbound or no capability.)
Source Files