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