README
¶
example/client
Overview
example/client is a package main demo client for the github.com/coder/acp-go-sdk module. It starts an agent subprocess and talks to it over the child's stdin and stdout through acp.NewClientSideConnection. It sends one Initialize, one NewSession, and one Prompt request, and it prints the session updates it receives. The unexported type exampleClient implements the acp.Client callbacks: file reads and writes use the local disk, and the terminal methods are stubs.
Interface
- No exported top-level symbols. The package declares only the unexported identifiers
exampleClient(fieldinput, the channel of stdin lines),displayUpdateKind,main,mustCwd, andreadLines[main.go:main] [main.go:exampleClient] [main.go:readLines]. - Compile-time assertion
var _ acp.Client = (*exampleClient)(nil)[main.go:exampleClient]. exampleClientmethods that satisfyacp.Client:RequestPermission[main.go:RequestPermission],SessionUpdate[main.go:SessionUpdate],WriteTextFile[main.go:WriteTextFile],ReadTextFile[main.go:ReadTextFile],CreateTerminal[main.go:CreateTerminal],TerminalOutput[main.go:TerminalOutput],ReleaseTerminal[main.go:ReleaseTerminal],WaitForTerminalExit[main.go:WaitForTerminalExit],KillTerminal[main.go:KillTerminal].- CLI: with at least one argument,
os.Args[1]is the agent program andos.Args[2:]are its arguments [main.go:main]. - CLI: with no arguments, the client runs
go run <clientDir>/../agent, whereclientDiris the directory ofmain.gofromruntime.Caller(0)[main.go:main]. This is the example agent. - Environment variables: this file reads none.
exec.CommandContextlooks upgo, or an agent command without a path separator, throughPATH, and the child inherits the full environment [main.go:main]. Initializerequest:ProtocolVersionisacp.ProtocolVersionNumber,Fs.ReadTextFileandFs.WriteTextFilearetrue,Terminalistrue,SessionsetsConfigOptions.BooleanandNotices, andElicitationsetsFormandUrl[main.go:main].NewSessionrequest:Cwdis the process working directory frommustCwd, andMcpServersis empty [main.go:main][main.go:mustCwd].Promptrequest: one text block,"Hello, agent!"[main.go:main].SessionUpdateprints agent message text, notices (severity, title and description), tool calls with theirnamewhen set, and tool call updates. For plan, agent thought, and user message updates, it prints only the kind name fromdisplayUpdateKind[main.go:SessionUpdate][main.go:displayUpdateKind].
Invariants
ReadTextFileandWriteTextFilereturn an error when the path is not absolute [main.go:ReadTextFile][main.go:WriteTextFile].WriteTextFilecreates missing parent directories with mode0o755, then writes the file withos.WriteFile: a new file gets mode0o644, and an existing file is truncated and keeps its permissions (modes before umask) [main.go:WriteTextFile].ReadTextFiletreatsLineas a 1-based start line, clamped to the number of lines. It appliesLimitas a line count only whenLimitis greater than 0 [main.go:ReadTextFile].RequestPermissionasks again until the user enters a valid 1-based option number, and printsInvalid option. Please try again.for other input [main.go:RequestPermission].RequestPermissionreturns aCancelledoutcome when stdin ends before a valid option number is entered [main.go:RequestPermission].mainexits with status 1 whenruntime.Callerfails, when the sibling../agentdirectory does not exist, or whencmd.Start,Initialize, orNewSessionfails [main.go:main].- A
Prompterror is printed to stderr but does not change the exit status [main.go:main]. mustCwdreturns"."whenos.Getwdfails [main.go:mustCwd].- Terminal methods return fixed values:
CreateTerminalreturnsTerminalId"term-1",TerminalOutputreturns empty output withTruncatedfalse, and the other terminal methods return empty responses [main.go:CreateTerminal][main.go:TerminalOutput][main.go:ReleaseTerminal][main.go:WaitForTerminalExit][main.go:KillTerminal]. - The connection logger is
slog.Default()[main.go:main].
Side Effects
- Stdin:
mainstarts one goroutine (readLines) that readsos.Stdinline by line. EveryRequestPermissioncall takes lines from its channel, so no call drops lines that a later call needs [main.go:readLines] [main.go:RequestPermission]. - Stdout: permission prompts, session updates, file operation messages, and progress messages are printed with
fmt.Printfandfmt.Println[main.go:RequestPermission][main.go:SessionUpdate][main.go:WriteTextFile][main.go:ReadTextFile][main.go:main]. Terminal stubs print their request values [main.go:CreateTerminal][main.go:TerminalOutput][main.go:ReleaseTerminal][main.go:WaitForTerminalExit][main.go:KillTerminal]. - Stderr: error messages are written with
fmt.Fprintf(os.Stderr, ...). A*acp.RequestErroris printed as indented JSON. The child process stderr is connected toos.Stderr[main.go:main]. - Filesystem:
os.MkdirAllandos.WriteFileon the requested path [main.go:WriteTextFile].os.ReadFileon the requested path [main.go:ReadTextFile].os.Staton the sibling agent directory [main.go:main].os.Getwdfor the session working directory [main.go:mustCwd]. - Subprocess:
exec.CommandContextstartsos.Args[1]orgo run <agentPath>. The client ignores errors fromStdinPipeandStdoutPipe[main.go:main]. - Subprocess termination:
cmd.Process.Killruns on theInitializeandNewSessionerror paths and at the end ofmain, and its errors are ignored [main.go:main]. - Process termination:
os.Exit(1)on the error paths listed under Invariants [main.go:main]. - Network: none directly. Protocol traffic goes over the child's stdio [main.go:main].
- Context:
maincreates a cancellable context and cancels it withdefer[main.go:main]. - Goroutines: this file starts one, the stdin reader in
readLines.acp.NewClientSideConnectionstarts the connection's own goroutines (four, plus one per inbound request, see the root README). Locks and global mutable state: none in this file [main.go:readLines] [main.go:main].
Verification
- Run:
go vet ./example/client
Documentation
¶
There is no documentation for this package.
Click to show internal directories.
Click to hide internal directories.