feat: Merge remote-tracking branch 'upstream/main' into fix/out-of-order-messages

Author: e.s.prilutskiy

.github/workflows/ci.yaml

@@ -25,7 +25,7 @@ jobs:
       actions: write
     steps:
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           fetch-tags: true
@@ -35,7 +35,7 @@ jobs:
         uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
 
       - name: Cache Nix store
-        uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        uses: nix-community/cache-nix-action@106bba72ed8e29c8357661199511ef07790175e9 # v7.0.1
         with:
           primary-key: nix-acp-go-sdk-${{ runner.os }}-${{ hashFiles('**/*.nix', 'flake.lock') }}
           restore-prefixes-first-match: nix-acp-go-sdk-${{ runner.os }}-

README.md

@@ -14,7 +14,7 @@ Learn more about the protocol itself at <https://agentclientprotocol.com>.
 <!-- `$ printf 'go get github.com/coder/acp-go-sdk@v%s\n' "$(cat schema/version)"` as bash -->
 
 ```bash
-go get github.com/coder/acp-go-sdk@v0.6.3
+go get github.com/coder/acp-go-sdk@v0.10.7
 ```
 
 ## Get Started
@@ -64,6 +64,71 @@ Helper constructors are provided to reduce boilerplate when working with union t
 - Tool content: `acp.ToolContent`, `acp.ToolDiffContent`, `acp.ToolTerminalRef`.
 - Utility: `acp.Ptr[T]` for pointer fields in request/update structs.
 
+### Extension methods
+
+ACP supports **extension methods** for custom JSON-RPC methods whose names start with `_`.
+Use them to add functionality without conflicting with future ACP versions.
+
+#### Handling inbound extension methods
+
+Implement `acp.ExtensionMethodHandler` on your Agent or Client. Your handler will be
+invoked for any incoming method starting with `_`.
+
+```go
+// HandleExtensionMethod handles ACP extension methods (names starting with "_").
+func (a MyAgent) HandleExtensionMethod(ctx context.Context, method string, params json.RawMessage) (any, error) {
+	switch method {
+	case "_example.com/hello":
+		var p struct {
+			Name string `json:"name"`
+		}
+		if err := json.Unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return map[string]any{"greeting": "hello " + p.Name}, nil
+	default:
+		return nil, acp.NewMethodNotFound(method)
+	}
+}
+```
+
+> Note: Per the ACP spec, unknown extension notifications should be ignored.
+> This SDK suppresses noisy logs for unhandled extension notifications that return
+> “Method not found”.
+
+#### Calling extension methods
+
+From either side, use `CallExtension` / `NotifyExtension` on the connection.
+
+```go
+raw, err := conn.CallExtension(ctx, "_example.com/hello", map[string]any{"name": "world"})
+if err != nil {
+	return err
+}
+
+var resp struct {
+	Greeting string `json:"greeting"`
+}
+if err := json.Unmarshal(raw, &resp); err != nil {
+	return err
+}
+
+if err := conn.NotifyExtension(ctx, "_example.com/progress", map[string]any{"pct": 50}); err != nil {
+	return err
+}
+```
+
+#### Advertising extension support via `_meta`
+
+ACP uses the `_meta` field inside capability objects as the negotiation/advertising
+surface for extensions.
+
+- Client -> Agent: `InitializeRequest.ClientCapabilities.Meta`
+- Agent -> Client: `InitializeResponse.AgentCapabilities.Meta`
+
+Keys `traceparent`, `tracestate`, and `baggage` are reserved in `_meta` for W3C trace
+context/OpenTelemetry compatibility.
+
 ### Study a Production Implementation
 
 For a complete, production‑ready integration, see the

acp_test.go

@@ -1,10 +1,14 @@
 package acp
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
+	"log/slog"
 	"slices"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -22,8 +26,12 @@ type clientFuncs struct {
 	ReleaseTerminalFunc     func(context.Context, ReleaseTerminalRequest) (ReleaseTerminalResponse, error)
 	TerminalOutputFunc      func(context.Context, TerminalOutputRequest) (TerminalOutputResponse, error)
 	WaitForTerminalExitFunc func(context.Context, WaitForTerminalExitRequest) (WaitForTerminalExitResponse, error)
+
+	HandleExtensionMethodFunc func(context.Context, string, json.RawMessage) (any, error)
 }
 
+var _ ExtensionMethodHandler = (*clientFuncs)(nil)
+
 var _ Client = (*clientFuncs)(nil)
 
 func (c clientFuncs) WriteTextFile(ctx context.Context, p WriteTextFileRequest) (WriteTextFileResponse, error) {
@@ -94,21 +102,30 @@ func (c *clientFuncs) WaitForTerminalExit(ctx context.Context, params WaitForTer
 	return WaitForTerminalExitResponse{}, nil
 }
 
+func (c clientFuncs) HandleExtensionMethod(ctx context.Context, method string, params json.RawMessage) (any, error) {
+	if c.HandleExtensionMethodFunc != nil {
+		return c.HandleExtensionMethodFunc(ctx, method, params)
+	}
+	return nil, NewMethodNotFound(method)
+}
+
 type agentFuncs struct {
-	InitializeFunc      func(context.Context, InitializeRequest) (InitializeResponse, error)
-	NewSessionFunc      func(context.Context, NewSessionRequest) (NewSessionResponse, error)
-	LoadSessionFunc     func(context.Context, LoadSessionRequest) (LoadSessionResponse, error)
-	AuthenticateFunc    func(context.Context, AuthenticateRequest) (AuthenticateResponse, error)
-	PromptFunc          func(context.Context, PromptRequest) (PromptResponse, error)
-	CancelFunc          func(context.Context, CancelNotification) error
-	SetSessionModeFunc  func(ctx context.Context, params SetSessionModeRequest) (SetSessionModeResponse, error)
-	SetSessionModelFunc func(ctx context.Context, params SetSessionModelRequest) (SetSessionModelResponse, error)
+	InitializeFunc     func(context.Context, InitializeRequest) (InitializeResponse, error)
+	NewSessionFunc     func(context.Context, NewSessionRequest) (NewSessionResponse, error)
+	LoadSessionFunc    func(context.Context, LoadSessionRequest) (LoadSessionResponse, error)
+	AuthenticateFunc   func(context.Context, AuthenticateRequest) (AuthenticateResponse, error)
+	PromptFunc         func(context.Context, PromptRequest) (PromptResponse, error)
+	CancelFunc         func(context.Context, CancelNotification) error
+	SetSessionModeFunc func(ctx context.Context, params SetSessionModeRequest) (SetSessionModeResponse, error)
+
+	HandleExtensionMethodFunc func(context.Context, string, json.RawMessage) (any, error)
 }
 
 var (
-	_ Agent             = (*agentFuncs)(nil)
-	_ AgentLoader       = (*agentFuncs)(nil)
-	_ AgentExperimental = (*agentFuncs)(nil)
+	_ Agent                  = (*agentFuncs)(nil)
+	_ AgentLoader            = (*agentFuncs)(nil)
+	_ AgentExperimental      = (*agentFuncs)(nil)
+	_ ExtensionMethodHandler = (*agentFuncs)(nil)
 )
 
 func (a agentFuncs) Initialize(ctx context.Context, p InitializeRequest) (InitializeResponse, error) {
@@ -161,12 +178,11 @@ func (a agentFuncs) SetSessionMode(ctx context.Context, params SetSessionModeReq
 	return SetSessionModeResponse{}, nil
 }
 
-// SetSessionModel implements AgentExperimental.
-func (a agentFuncs) SetSessionModel(ctx context.Context, params SetSessionModelRequest) (SetSessionModelResponse, error) {
-	if a.SetSessionModelFunc != nil {
-		return a.SetSessionModelFunc(ctx, params)
+func (a agentFuncs) HandleExtensionMethod(ctx context.Context, method string, params json.RawMessage) (any, error) {
+	if a.HandleExtensionMethodFunc != nil {
+		return a.HandleExtensionMethodFunc(ctx, method, params)
 	}
-	return SetSessionModelResponse{}, nil
+	return nil, NewMethodNotFound(method)
 }
 
 // Test bidirectional error handling similar to typescript/acp.test.ts
@@ -354,7 +370,7 @@ func TestConnectionHandlesMessageOrdering(t *testing.T) {
 	}
 	if _, err := as.RequestPermission(context.Background(), RequestPermissionRequest{
 		SessionId: "test-session",
-		ToolCall: RequestPermissionToolCall{
+		ToolCall: ToolCallUpdate{
 			Title:      Ptr("Execute command"),
 			Kind:       ptr(ToolKindExecute),
 			Status:     ptr(ToolCallStatusPending),
@@ -887,7 +903,7 @@ func TestRequestHandlerCanMakeNestedRequest(t *testing.T) {
 		PromptFunc: func(ctx context.Context, p PromptRequest) (PromptResponse, error) {
 			_, err := ag.RequestPermission(ctx, RequestPermissionRequest{
 				SessionId: p.SessionId,
-				ToolCall: RequestPermissionToolCall{
+				ToolCall: ToolCallUpdate{
 					ToolCallId: "call_1",
 					Title:      Ptr("Test permission"),
 				},
@@ -921,3 +937,171 @@ func TestRequestHandlerCanMakeNestedRequest(t *testing.T) {
 		t.Fatalf("prompt failed: %v", err)
 	}
 }
+
+type extEchoParams struct {
+	Msg string `json:"msg"`
+}
+
+type extEchoResult struct {
+	Msg string `json:"msg"`
+}
+
+type agentNoExtensions struct{}
+
+func (agentNoExtensions) Authenticate(ctx context.Context, params AuthenticateRequest) (AuthenticateResponse, error) {
+	return AuthenticateResponse{}, nil
+}
+
+func (agentNoExtensions) Initialize(ctx context.Context, params InitializeRequest) (InitializeResponse, error) {
+	return InitializeResponse{}, nil
+}
+
+func (agentNoExtensions) Cancel(ctx context.Context, params CancelNotification) error { return nil }
+
+func (agentNoExtensions) NewSession(ctx context.Context, params NewSessionRequest) (NewSessionResponse, error) {
+	return NewSessionResponse{}, nil
+}
+
+func (agentNoExtensions) Prompt(ctx context.Context, params PromptRequest) (PromptResponse, error) {
+	return PromptResponse{}, nil
+}
+
+func (agentNoExtensions) SetSessionMode(ctx context.Context, params SetSessionModeRequest) (SetSessionModeResponse, error) {
+	return SetSessionModeResponse{}, nil
+}
+
+func TestExtensionMethods_ClientToAgentRequest(t *testing.T) {
+	c2aR, c2aW := io.Pipe()
+	a2cR, a2cW := io.Pipe()
+
+	method := "_vendor.test/echo"
+
+	ag := NewAgentSideConnection(agentFuncs{
+		HandleExtensionMethodFunc: func(ctx context.Context, gotMethod string, params json.RawMessage) (any, error) {
+			if gotMethod != method {
+				return nil, NewInternalError(map[string]any{"expected": method, "got": gotMethod})
+			}
+			var p extEchoParams
+			if err := json.Unmarshal(params, &p); err != nil {
+				return nil, err
+			}
+			return extEchoResult{Msg: p.Msg}, nil
+		},
+	}, a2cW, c2aR)
+
+	_ = ag
+
+	c := NewClientSideConnection(&clientFuncs{}, c2aW, a2cR)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	raw, err := c.CallExtension(ctx, method, extEchoParams{Msg: "hi"})
+	if err != nil {
+		t.Fatalf("CallExtension: %v", err)
+	}
+	var resp extEchoResult
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if resp.Msg != "hi" {
+		t.Fatalf("unexpected response: %#v", resp)
+	}
+}
+
+func TestExtensionMethods_UnknownRequest_ReturnsMethodNotFound(t *testing.T) {
+	c2aR, c2aW := io.Pipe()
+	a2cR, a2cW := io.Pipe()
+
+	NewAgentSideConnection(agentNoExtensions{}, a2cW, c2aR)
+	c := NewClientSideConnection(&clientFuncs{}, c2aW, a2cR)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	_, err := c.CallExtension(ctx, "_vendor.test/missing", extEchoParams{Msg: "hi"})
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	var re *RequestError
+	if !errors.As(err, &re) {
+		t.Fatalf("expected *RequestError, got %T: %v", err, err)
+	}
+	if re.Code != -32601 {
+		t.Fatalf("expected -32601 method not found, got %d", re.Code)
+	}
+}
+
+func TestExtensionMethods_UnknownNotification_DoesNotLog(t *testing.T) {
+	c2aR, c2aW := io.Pipe()
+	a2cR, a2cW := io.Pipe()
+
+	done := make(chan struct{})
+
+	ag := NewAgentSideConnection(agentFuncs{
+		HandleExtensionMethodFunc: func(ctx context.Context, method string, params json.RawMessage) (any, error) {
+			close(done)
+			return nil, NewMethodNotFound(method)
+		},
+	}, a2cW, c2aR)
+
+	var logBuf bytes.Buffer
+	ag.SetLogger(slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug})))
+
+	c := NewClientSideConnection(&clientFuncs{}, c2aW, a2cR)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	if err := c.NotifyExtension(ctx, "_vendor.test/notify", map[string]any{"hello": "world"}); err != nil {
+		t.Fatalf("NotifyExtension: %v", err)
+	}
+
+	select {
+	case <-done:
+		// ok
+	case <-ctx.Done():
+		t.Fatalf("timeout waiting for notification handler")
+	}
+
+	if strings.Contains(logBuf.String(), "failed to handle notification") {
+		t.Fatalf("unexpected notification error log: %s", logBuf.String())
+	}
+}
+
+func TestExtensionMethods_AgentToClientRequest(t *testing.T) {
+	c2aR, c2aW := io.Pipe()
+	a2cR, a2cW := io.Pipe()
+
+	method := "_vendor.test/echo"
+
+	_ = NewClientSideConnection(&clientFuncs{
+		HandleExtensionMethodFunc: func(ctx context.Context, gotMethod string, params json.RawMessage) (any, error) {
+			if gotMethod != method {
+				return nil, NewInternalError(map[string]any{"expected": method, "got": gotMethod})
+			}
+			var p extEchoParams
+			if err := json.Unmarshal(params, &p); err != nil {
+				return nil, err
+			}
+			return extEchoResult{Msg: p.Msg}, nil
+		},
+	}, c2aW, a2cR)
+
+	ag := NewAgentSideConnection(agentFuncs{}, a2cW, c2aR)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	raw, err := ag.CallExtension(ctx, method, extEchoParams{Msg: "hi"})
+	if err != nil {
+		t.Fatalf("CallExtension: %v", err)
+	}
+	var resp extEchoResult
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if resp.Msg != "hi" {
+		t.Fatalf("unexpected response: %#v", resp)
+	}
+}

agent.go

@@ -22,7 +22,7 @@ func NewAgentSideConnection(agent Agent, peerInput io.Writer, peerOutput io.Read
 	asc := &AgentSideConnection{}
 	asc.agent = agent
 	asc.sessionCancels = make(map[string]context.CancelFunc)
-	asc.conn = NewConnection(asc.handle, peerInput, peerOutput)
+	asc.conn = NewConnection(asc.handleWithExtensions, peerInput, peerOutput)
 	return asc
 }