Add Go SDK and generator

[ThomasK33]

Overview

This PR introduces a Go SDK for ACP, including terminal support, context-aware APIs with cancellation, a modular code generator, structured error handling, JSON parity tests with golden files, and updated docs/examples.

What’s Supported

• Go SDK: Agent/Client interfaces, connection management, request/response dispatch, generated types/constants.
• Terminal: Dedicated ClientTerminal interface and terminal content handling.
• Context & Cancellation: All interface methods accept context.Context with cancellation propagation.
• Content Types: Text, audio, image, diffs (with/without old), resource blobs/links/text, terminal content.
• Session Flow: Initialize, new session, updates (agent/user message chunks, plan, tool calls: read/edit/locations/rawinput/update).
• Filesystem: Read/write text file request/response types.
• Permissions: Request permission flow and outcomes (selected/cancelled).
• Errors: JSON-formatted RequestError for structured client consumption.
• Codegen: Internal IR + emit phases generating *_gen.go for types, constants, helpers, and interfaces.

Implementation Notes

• Interface Structure: Methods grouped into stable, experimental, and optional for cleaner API surfaces.
• Terminal Split: Terminal-related methods factored into a standalone ClientTerminal interface.
• Codegen Architecture: Modular generator at go/cmd/generate/internal/{ir,emit,load,util} with simplified dispatch helpers and signatures.
• Types & Unions: Optional fields are modeled with pointers; unions are generated to encode optionality accurately.
• Helpers Extraction: Shared helper logic moved to static go/helpers.go (reduces generated code size).
• Examples: Agent, client, Gemini, and Claude Code examples demonstrate typical usage.

Testing

• Parity Tests: Golden-file JSON parity tests in go/testdata/json_golden cover content variants, FS ops, session updates, permissions, tool‑call forms, and terminal content.
• Constructors Validation: Tests verify that constructor helpers and generated constructors match the golden JSON.
• Example Tests: Example-based tests for agent/client/gemini flows validate end-to-end behavior.

Docs & Examples

• Go README: The installation and usage guide is under go/README.md.
• Docs Page: Go library included in docs/libraries/go.mdx with package info and examples.
• Samples: Updated and expanded examples (agent, client, gemini, Claude Code) using context-aware APIs.

---

Change-Id: Ic3a8ca18551872870ebc922dcdce7ec1669c9fd6
Signed-off-by: Thomas Kosiewski tk@coder.com

[cla-bot]

We require contributors to sign our Contributor License Agreement, and we don't have @ThomasK33 on file. You can sign our CLA at https://zed.dev/cla. Once you've signed, post a comment here that says '@cla-bot check'.

[ThomasK33]

@cla-bot check

[cla-bot]

The cla-bot has been summoned, and re-checked this pull request!

[ConradIrwin]

Thanks for this, it looks great!

One thing I noticed is that if you run the rust example client with the go example agent, it crashes because it returns "authMethods":null vs "authMethods":[] or just omitting the field. Not sure how easy that is to fix, but would be nice to have that work out of the box.

[deepakdinesh1123]

Thank you very much for this

I tried to use this to integrate crush in Zed editor (ref: https://github.com/deepakdinesh1123/crush/blob/feat/acp/internal/acpagent/acp.go), as soon as I launch a new thread with crush agent in Zed I get the error failed to deserialize response before a session is even created, might be related to the issue @ConradIrwin is mentioning if not please let me know if I am using the SDK incorrectly.

[ConradIrwin]

@deepakdinesh1123 Does it work if you set AuthMethods to the empty array?

[deepakdinesh1123]

@ConradIrwin the typ acp.AuthenticateResponse is as follows

type AuthenticateResponse struct{}

and the method authenticate method signature is

func (a *ACPAgent) Authenticate(ctx context.Context, _ acp.AuthenticateRequest) error { return nil }

so I was not able to return any response other than the error as nil

[ConradIrwin]

I think the problem is the InitializeResponse:

type InitializeResponse struct {
	AgentCapabilities AgentCapabilities `json:"agentCapabilities,omitempty"`
	AuthMethods []AuthMethod `json:"authMethods"` <--- THIS ONE
	ProtocolVersion ProtocolVersion `json:"protocolVersion"`
}

[ThomasK33]

Hey @ConradIrwin, you're right.

Let me look into extending the codegen to either serialize to the default values specified in the schema.json file if it's the Go default value, or find another smart solution.

Updating the go/example/agent/main.go to include

func (a *exampleAgent) Initialize(ctx context.Context, params acp.InitializeRequest) (acp.InitializeResponse, error) {
	return acp.InitializeResponse{
		ProtocolVersion: acp.ProtocolVersionNumber,
		AgentCapabilities: acp.AgentCapabilities{
			LoadSession: false,
		},
		AuthMethods: []acp.AuthMethod{},
	}, nil
}

seems to fix the issue as you suggested.

[ConradIrwin]

👍 Also happy to make changes to how the schema is generated if there's a way we can express "undefined is fine, but null causes rust's serde to throw a fit"

[ThomasK33]

👍 Also happy to make changes to how the schema is generated if there's a way we can express "undefined is fine, but null causes rust's serde to throw a fit"

Since most of this is generated code, it's fine for now. The generator can handle serialization and deserialization of default values, working around Go's default value serialization issues.

Also, I added a Nix flake to set up a dev shell with all the necessary packages to run the npm scripts. Let me know if you’d prefer to remove it—I'm OK with that.

[ConradIrwin]

Having a nix flake seems fine (assuming I don't have to use it :D).

Do the latest set of changes fix the serialization thing? Is there anything else you wanted to tidy up before merging this?

[deepakdinesh1123]

@ThomasK33

I am getting this error when I try to build a version of crush that is using this module

invalid receiver type SetSessionModeResponse  (pointer or interface type) (compiler InvalidRecv)

due to this in types_gen.go

type SetSessionModeResponse any

func (v *SetSessionModeResponse) Validate() error {
	return nil
}

[morgankrey]

@ThomasK33 let us know if we can help get this over the line!

[ThomasK33]

@ThomasK33 let us know if we can help get this over the line!

Hey @morgankrey, sorry, I somehow did not see the ping.
I rebased and regenerated the Go parts; they should be good to merge.

---

@deepakdinesh1123 I also tested it against your crush fork with the acp subcommand.
I can use the following patch on your feat/acp branch to work in Zed and CLIs.

Inline Patch on `feat/acp`

diff --git a/internal/acpagent/acp.go b/internal/acpagent/acp.go
index e20a351d..c4c63481 100644
--- a/internal/acpagent/acp.go
+++ b/internal/acpagent/acp.go
@@ -12,6 +12,8 @@ import (
 	acp "github.com/zed-industries/agent-client-protocol/go"
 )
 
+var _ acp.Agent = (*ACPAgent)(nil)
+
 type ACPAgent struct {
 	app  *app.App
 	conn *acp.AgentSideConnection
@@ -63,9 +65,10 @@ func (a *ACPAgent) Cancel(ctx context.Context, params acp.CancelNotification) er
 }
 
 func (a *ACPAgent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.PromptResponse, error) {
-	_, err := a.app.Sessions.Get(ctx, string(params.SessionId))
+	sessionID := string(params.SessionId)
+	_, err := a.app.Sessions.Get(ctx, sessionID)
 	if err != nil {
-		return acp.PromptResponse{}, fmt.Errorf("session %s not found", string(params.SessionId))
+		return acp.PromptResponse{}, fmt.Errorf("session %s not found", sessionID)
 	}
 
 	content := ""
@@ -75,7 +78,7 @@ func (a *ACPAgent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Pr
 		}
 	}
 
-	done, err := a.app.CoderAgent.Run(context.Background(), string(params.SessionId), content)
+	done, err := a.app.CoderAgent.Run(ctx, sessionID, content)
 	if err != nil {
 		return acp.PromptResponse{}, err
 	}
@@ -134,6 +137,7 @@ func (a *ACPAgent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Pr
 					case message.BinaryContent:
 					case message.ImageURLContent:
 					case message.Finish:
+						return acp.PromptResponse{StopReason: acp.StopReasonEndTurn}, nil
 					case message.TextContent:
 						// Only send the delta (new text content)
 						if len(part.Text) > len(lastTextSent) {
@@ -169,7 +173,13 @@ func (a *ACPAgent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Pr
 			}
 		}
 	}
+}
 
+func (a *ACPAgent) Authenticate(ctx context.Context, _ acp.AuthenticateRequest) (acp.AuthenticateResponse, error) {
+	return acp.AuthenticateResponse{}, nil
 }
 
-func (a *ACPAgent) Authenticate(ctx context.Context, _ acp.AuthenticateRequest) error { return nil }
+// SetSessionMode implements acp.Agent.
+func (a *ACPAgent) SetSessionMode(ctx context.Context, params acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error) {
+	return acp.SetSessionModeResponse{}, nil
+}

[morgankrey]

Awesome - @benbrandt @rtfeldman ready for review!

[benbrandt]

Closing in favor of: https://github.com/coder/acp-go-sdk