diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 49030d5a0..0c491a3ee 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -352,7 +352,7 @@ "url": "/dev/prds/mcp-tool-completion/", "title": "MCP client and tool-guardrail completion", "section": "PRDs", - "body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behaviour changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commented MCP block gets the new field documented\nwith its default.\n\n**Testing.** Unit test asserting two concurrent `Call`s to the same\n`Client` block on each other when the flag is false and don't when true —\nfakeable with a slow fake transport. `task check`.\n\n## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substrate (`#179`)\n\n**Decision.** These two beads are one design decision, not two: `#179` is an\nalternate execution backend for `#178`, not separate scope. Sandbox MCP\nservers that a chat-turn config marks as untrusted (a new\n`Sandboxed bool` field on `MCPServer`, default `false` — existing\nconfigured servers are unaffected) behind the same `ContainerPool` the\ndaemon already uses to run agent work\n(`internal/container/pool.go`, per CLAUDE.md's `WriteTaskJSON` trap and the\n`Acquire`/`Release` lifecycle `daemon.go`'s `acquireTaskContainer` already\nproves). Do not build a second sandbox mechanism: an MCP stdio server is a\nsubprocess exactly like an agent task container's entrypoint, so launching it\nvia `ContainerPool.Acquire` with stdio piped to the `mcp.Client` transport is\nthe smallest change, not new plumbing.\n\nFirecracker is **not** built now. `ContainerPool`'s existing Docker-backed\nisolation is the shipped backend; Firecracker becomes a second\nimplementation of the same acquire/release contract only if a concrete\nescape or resource-isolation gap is measured against Docker-backed sandboxing\nin production. Recording this as the deletion/promotion gate keeps `#179`\nhonestly `OPEN` instead of speculatively building an unused backend, per\nCLAUDE.md's Architectural Simplicity rule.\n\n**Call site.** `internal/config/config.go` (`MCPServer.Sandboxed`), the MCP\nclient constructor (route sandboxed servers' process launch through\n`container.Pool.Acquire` instead of `os/exec` directly), and\n`internal/container/pool.go` (confirm its `Acquire` contract accepts a\nstdio-piped, non-worktree workload — if it assumes a git worktree\nper CLAUDE.md's `WriteTaskJSON` note, add the narrower entrypoint variant\nthere rather than duplicating the pool).\n\n**Error/failure mapping.**\n\n| condition | contract error |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried |\n| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go`), not a new retry loop |\n\n**Testing.** `Sandboxed=false` path is the existing, already-tested\nunsandboxed flow — no change. `Sandboxed=true` needs a real\n`ContainerPool` (Docker) — manual smoke command, not `task check`; document\nthe exact command in the runbook this PRD's issue links to once implemented.\n\n## Sequential tool dispatch with per-result previews (`#182`)\n\n**Decision.** This coexists with concurrent dispatch (`#183`, closed) as a\nsecond, explicit mode selected by the caller — not a replacement. Concurrent\ndispatch is for independent tool calls in one turn; sequential-with-preview\nis for a turn where each result should be surfaced to the operator (or the\nnext tool call) before the next call fires — e.g. a mutating tool chain where\nshowing intermediate state matters. Add a `DispatchMode` enum\n(`Concurrent`/`Sequential`) to whatever type selects the closed\n`#183` concurrent path, defaulting to `Concurrent` (its only behaviour).\n\n**Call site.** The tool-dispatch entry point that `#183`'s closed\nimplementation lives in (grep the concurrent-dispatch symbol added for\n`#183` — same file gets the sequential branch, not a parallel file). Preview\nsurfacing reuses whatever channel-adapter interface already streams\nintermediate turn output (the same seam `internal/channels/telegram/` and\nother adapters use for streaming deltas) — do not invent a second preview\ntransport.\n\n**Testing.** Fakeable with a fake tool that returns staged results; assert\npreview callbacks fire in order before the next call starts. `task check`.\n\n## Call site inventory\n\n| concern | file | change |\n| --------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- |\n| MCP client transports (stdio/HTTP/SSE) | `internal/tools/mcp/transport*.go` | none — already handles this |\n| MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) |\n| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |\n| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |\n| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |\n| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |\n| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this |\n| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) |\n| Guardrails / classification / registry / disclosure | `internal/tools/guardrail.go`, `classification.go`, `registry.go`, `disclosure.go` | none — already handles this |\n| `config.example.toml` MCP block | `config.example.toml` | doc update for new fields |\n\n## Execution: multi-agent team breakdown\n\n| sub-feature | issue | implementer scope | suggested council lenses | why |\n| ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |\n| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |\n| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation |\n| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding |\n| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both |\n\n## File and link the beads\n\n- `#151`, `#177`, `#178`, `#179`, `#182` each get their description updated to\n point at this doc's matching `##` heading instead of restating the design.\n- Close `#179` as a design decision (link here) rather than leaving it open\n as separate scope — it is not built now, and the doc records why.\n- Add the suggested lenses to each issue directly.\n" + "body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client. The agent worker hosts the same configured MCP servers on the\ntask path and runs its own model runtime, so `internal/app/agentworker` wires\nthe same seam from the task's builder model: a server that samples succeeds\ninside a chat turn and inside a task, never one and not the other. The message\nmapping and the token bound are shared (`internal/agentexec`, next to the\nruntime both paths call models through) so both paths bound a sample\nidentically.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`) and the task model path already exists\n(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both\nrather than adding a parallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behaviour changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commented MCP block gets the new field documented\nwith its default.\n\n**Testing.** Unit test asserting two concurrent `Call`s to the same\n`Client` block on each other when the flag is false and don't when true —\nfakeable with a slow fake transport. `task check`.\n\n## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substrate (`#179`)\n\n**Decision.** These two beads are one design decision, not two: `#179` is an\nalternate execution backend for `#178`, not separate scope. Sandbox MCP\nservers that a chat-turn config marks as untrusted (a new\n`Sandboxed bool` field on `MCPServer`, default `false` — existing\nconfigured servers are unaffected) behind the same `ContainerPool` the\ndaemon already uses to run agent work\n(`internal/container/pool.go`, per CLAUDE.md's `WriteTaskJSON` trap and the\n`Acquire`/`Release` lifecycle `daemon.go`'s `acquireTaskContainer` already\nproves). Do not build a second sandbox mechanism: an MCP stdio server is a\nsubprocess exactly like an agent task container's entrypoint, so launching it\nvia `ContainerPool.Acquire` with stdio piped to the `mcp.Client` transport is\nthe smallest change, not new plumbing.\n\nFirecracker is **not** built now. `ContainerPool`'s existing Docker-backed\nisolation is the shipped backend; Firecracker becomes a second\nimplementation of the same acquire/release contract only if a concrete\nescape or resource-isolation gap is measured against Docker-backed sandboxing\nin production. Recording this as the deletion/promotion gate keeps `#179`\nhonestly `OPEN` instead of speculatively building an unused backend, per\nCLAUDE.md's Architectural Simplicity rule.\n\n**Call site.** `internal/config/config.go` (`MCPServer.Sandboxed`), the MCP\nclient constructor (route sandboxed servers' process launch through\n`container.Pool.Acquire` instead of `os/exec` directly), and\n`internal/container/pool.go` (confirm its `Acquire` contract accepts a\nstdio-piped, non-worktree workload — if it assumes a git worktree\nper CLAUDE.md's `WriteTaskJSON` note, add the narrower entrypoint variant\nthere rather than duplicating the pool).\n\n**Error/failure mapping.**\n\n| condition | contract error |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried |\n| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go`), not a new retry loop |\n\n**Testing.** `Sandboxed=false` path is the existing, already-tested\nunsandboxed flow — no change. `Sandboxed=true` needs a real\n`ContainerPool` (Docker) — manual smoke command, not `task check`; document\nthe exact command in the runbook this PRD's issue links to once implemented.\n\n## Sequential tool dispatch with per-result previews (`#182`)\n\n**Decision.** This coexists with concurrent dispatch (`#183`, closed) as a\nsecond, explicit mode selected by the caller — not a replacement. Concurrent\ndispatch is for independent tool calls in one turn; sequential-with-preview\nis for a turn where each result should be surfaced to the operator (or the\nnext tool call) before the next call fires — e.g. a mutating tool chain where\nshowing intermediate state matters. Add a `DispatchMode` enum\n(`Concurrent`/`Sequential`) to whatever type selects the closed\n`#183` concurrent path, defaulting to `Concurrent` (its only behaviour).\n\n**Call site.** The tool-dispatch entry point that `#183`'s closed\nimplementation lives in (grep the concurrent-dispatch symbol added for\n`#183` — same file gets the sequential branch, not a parallel file). Preview\nsurfacing reuses whatever channel-adapter interface already streams\nintermediate turn output (the same seam `internal/channels/telegram/` and\nother adapters use for streaming deltas) — do not invent a second preview\ntransport.\n\n**Testing.** Fakeable with a fake tool that returns staged results; assert\npreview callbacks fire in order before the next call starts. `task check`.\n\n## Call site inventory\n\n| concern | file | change |\n| --------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- |\n| MCP client transports (stdio/HTTP/SSE) | `internal/tools/mcp/transport*.go` | none — already handles this |\n| MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) |\n| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |\n| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |\n| Sampling handler wiring (chat path) | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |\n| Sampling handler wiring (task path) | `internal/app/agentworker/mcp_sampling.go`, `mcp_providers.go` | new (`#151`), answers from the task's builder model |\n| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |\n| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this |\n| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) |\n| Guardrails / classification / registry / disclosure | `internal/tools/guardrail.go`, `classification.go`, `registry.go`, `disclosure.go` | none — already handles this |\n| `config.example.toml` MCP block | `config.example.toml` | doc update for new fields |\n\n## Execution: multi-agent team breakdown\n\n| sub-feature | issue | implementer scope | suggested council lenses | why |\n| ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |\n| Server-initiated sampling | `#151` | `client.go` dispatch branch, chat-path and task-path handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |\n| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation |\n| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding |\n| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both |\n\n## File and link the beads\n\n- `#151`, `#177`, `#178`, `#179`, `#182` each get their description updated to\n point at this doc's matching `##` heading instead of restating the design.\n- Close `#179` as a design decision (link here) rather than leaving it open\n as separate scope — it is not built now, and the doc records why.\n- Add the suggested lenses to each issue directly.\n" }, { "url": "/dev/prds/memory-engine-unification/", diff --git a/docs/prds/mcp-tool-completion.md b/docs/prds/mcp-tool-completion.md index 82bf47b82..d45a43988 100644 --- a/docs/prds/mcp-tool-completion.md +++ b/docs/prds/mcp-tool-completion.md @@ -56,11 +56,18 @@ messages by method name (the same switch that already routes `internal/app/archied/main.go` that routes the sampling request through the same chat-model call path `chatGenerateOptions` already uses, so a server-initiated sample gets the daemon's configured model, not a second -provider client. +provider client. The agent worker hosts the same configured MCP servers on the +task path and runs its own model runtime, so `internal/app/agentworker` wires +the same seam from the task's builder model: a server that samples succeeds +inside a chat turn and inside a task, never one and not the other. The message +mapping and the token bound are shared (`internal/agentexec`, next to the +runtime both paths call models through) so both paths bound a sample +identically. **Reuse check.** The chat model invocation path already exists -(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a -parallel model-calling path for MCP sampling. +(`chatGenerateOptions`, `main.go`) and the task model path already exists +(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both +rather than adding a parallel model-calling path for MCP sampling. **Failure mapping.** @@ -170,7 +177,8 @@ preview callbacks fire in order before the next call starts. `task check`. | MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) | | MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` | | Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) | -| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` | +| Sampling handler wiring (chat path) | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` | +| Sampling handler wiring (task path) | `internal/app/agentworker/mcp_sampling.go`, `mcp_providers.go` | new (`#151`), answers from the task's builder model | | Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) | | Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this | | Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) | @@ -181,7 +189,7 @@ preview callbacks fire in order before the next call starts. `task check`. | sub-feature | issue | implementer scope | suggested council lenses | why | | ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | -| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract | +| Server-initiated sampling | `#151` | `client.go` dispatch branch, chat-path and task-path handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract | | Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation | | Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding | | Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both | diff --git a/internal/agentexec/sampling.go b/internal/agentexec/sampling.go new file mode 100644 index 000000000..55dcabdfd --- /dev/null +++ b/internal/agentexec/sampling.go @@ -0,0 +1,66 @@ +package agentexec + +import ( + "errors" + "fmt" + + "github.com/samcharles93/ai-sdk/chat" + + protocol "github.com/samcharles93/archie-core/internal/tools/mcp" +) + +// DefaultSamplingMaxTokens bounds a server-requested completion when the +// request does not set maxTokens. A sampling request is a delegated +// sub-completion, not a full turn, so one MCP server cannot spend a +// turn-sized output allowance on a single request. +const DefaultSamplingMaxTokens = 4096 + +// SamplingMessages maps a server's sampling messages onto chat messages. Both +// MCP sampling host paths use it -- the daemon's chat handler and the agent +// worker's task handler -- so the same server is answered the same way +// wherever the client runs. A non-text content block or an unknown role is +// rejected rather than silently dropped: answering from a partial prompt would +// be a wrong answer, not a degraded one. +func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) { + if len(req.Messages) == 0 { + return nil, errors.New("mcp sampling: the request has no messages") + } + messages := make([]chat.Message, 0, len(req.Messages)) + for i, message := range req.Messages { + if message.Content.Type != "" && message.Content.Type != "text" { + return nil, fmt.Errorf("mcp sampling: message %d has unsupported content type %q", i, message.Content.Type) + } + var role chat.Role + switch message.Role { + case "user": + role = chat.RoleUser + case "assistant": + role = chat.RoleAssistant + default: + return nil, fmt.Errorf("mcp sampling: message %d has unsupported role %q", i, message.Role) + } + messages = append(messages, chat.Message{Role: role, Content: message.Content.Text}) + } + return messages, nil +} + +// SamplingMaxTokens bounds a delegated completion to the request's own +// maxTokens, falling back to DefaultSamplingMaxTokens, and never past the +// model's own output ceiling (zero when the ceiling is unknown). A +// reasoning-class model gets no bound at all: its provider rejects the +// `max_tokens` parameter the chat-completions provider emits for a non-zero +// bound. Both the daemon's chat path and the agent worker answer sampling +// with this, so the same server gets the same bound on either path. +func SamplingMaxTokens(requested, modelCeiling int, reasoning bool) int { + maxTokens := requested + if maxTokens <= 0 { + maxTokens = DefaultSamplingMaxTokens + } + if modelCeiling > 0 && maxTokens > modelCeiling { + maxTokens = modelCeiling + } + if reasoning { + return 0 + } + return maxTokens +} diff --git a/internal/agentexec/sampling_test.go b/internal/agentexec/sampling_test.go new file mode 100644 index 000000000..149837a67 --- /dev/null +++ b/internal/agentexec/sampling_test.go @@ -0,0 +1,98 @@ +package agentexec + +import ( + "strings" + "testing" + + "github.com/samcharles93/ai-sdk/chat" + + protocol "github.com/samcharles93/archie-core/internal/tools/mcp" +) + +func TestSamplingMessagesMapsRolesAndRejectsUnsupportedInput(t *testing.T) { + tests := []struct { + name string + request protocol.SamplingRequest + want []chat.Message + wantErr string + }{ + { + name: "user and assistant text map to chat roles", + request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{ + {Role: "user", Content: protocol.SamplingContent{Type: "text", Text: "2+2?"}}, + {Role: "assistant", Content: protocol.SamplingContent{Type: "", Text: "4"}}, + }}, + want: []chat.Message{ + {Role: chat.RoleUser, Content: "2+2?"}, + {Role: chat.RoleAssistant, Content: "4"}, + }, + }, + { + name: "no messages is a refusal", + request: protocol.SamplingRequest{}, + wantErr: "the request has no messages", + }, + { + name: "non-text content is a refusal", + request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{ + {Role: "user", Content: protocol.SamplingContent{Type: "image"}}, + }}, + wantErr: "unsupported content type", + }, + { + name: "unknown role is a refusal", + request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{ + {Role: "system", Content: protocol.SamplingContent{Type: "text", Text: "hi"}}, + }}, + wantErr: "unsupported role", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got, err := SamplingMessages(tc.request) + if tc.wantErr != "" { + if err == nil || !strings.Contains(err.Error(), tc.wantErr) { + t.Fatalf("SamplingMessages error = %v, want it to mention %q", err, tc.wantErr) + } + return + } + if err != nil { + t.Fatalf("SamplingMessages error = %v, want nil", err) + } + if len(got) != len(tc.want) { + t.Fatalf("SamplingMessages returned %d messages, want %d", len(got), len(tc.want)) + } + for i := range got { + if got[i].Role != tc.want[i].Role || got[i].Content != tc.want[i].Content { + t.Errorf("message %d = %+v, want %+v", i, got[i], tc.want[i]) + } + } + }) + } +} + +func TestSamplingMaxTokens(t *testing.T) { + tests := []struct { + name string + requested int + ceiling int + reasoning bool + wantTokens int + }{ + {name: "requested bound is honoured", requested: 64, ceiling: 1024, wantTokens: 64}, + {name: "absent request falls back to the default", requested: 0, ceiling: 8192, wantTokens: DefaultSamplingMaxTokens}, + {name: "request is capped by the model ceiling", requested: 8192, ceiling: 1024, wantTokens: 1024}, + {name: "unknown ceiling keeps the request", requested: 8192, ceiling: 0, wantTokens: 8192}, + {name: "reasoning model gets no bound", requested: 64, ceiling: 1024, reasoning: true, wantTokens: 0}, + {name: "reasoning model with absent request gets no bound", requested: 0, ceiling: 0, reasoning: true, wantTokens: 0}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got := SamplingMaxTokens(tc.requested, tc.ceiling, tc.reasoning); got != tc.wantTokens { + t.Fatalf("SamplingMaxTokens(%d, %d, %v) = %d, want %d", tc.requested, tc.ceiling, tc.reasoning, got, tc.wantTokens) + } + }) + } +} diff --git a/internal/app/agentworker/mcp_providers.go b/internal/app/agentworker/mcp_providers.go index 2d43ec376..5a4606cb6 100644 --- a/internal/app/agentworker/mcp_providers.go +++ b/internal/app/agentworker/mcp_providers.go @@ -23,18 +23,26 @@ type mcpProviderSet struct { registry *tools.Registry } -type mcpProviderBuilder func(config.MCPServer) (toolprovider.Engine, string, error) +type mcpProviderBuilder func(config.MCPServer, mcp.SamplingHandler) (toolprovider.Engine, string, error) // startMCPProviders creates MCP transports from config, starts them, -// discovers tools, and registers them into a local registry. Returns -// nil when there are no servers configured. -func startMCPProviders(ctx context.Context, servers []config.MCPServer, log *slog.Logger) (*mcpProviderSet, error) { - return startMCPProvidersWith(ctx, servers, log, buildMCPProvider) +// discovers tools, and registers them into a local registry. A non-nil +// sampling handler answers server-initiated sampling/createMessage requests +// (nil leaves the method refused, the client's own default). Returns nil when +// there are no servers configured. +func startMCPProviders( + ctx context.Context, + servers []config.MCPServer, + sampling mcp.SamplingHandler, + log *slog.Logger, +) (*mcpProviderSet, error) { + return startMCPProvidersWith(ctx, servers, sampling, log, buildMCPProvider) } func startMCPProvidersWith( ctx context.Context, servers []config.MCPServer, + sampling mcp.SamplingHandler, log *slog.Logger, build mcpProviderBuilder, ) (*mcpProviderSet, error) { @@ -51,7 +59,7 @@ func startMCPProvidersWith( continue } - provider, transportType, err := build(server) + provider, transportType, err := build(server, sampling) if errors.Is(err, errUnknownMCPTransport) { log.Warn("mcp server skipped: unknown transport", "name", name, "transport", transportType) continue @@ -78,7 +86,7 @@ func startMCPProvidersWith( return set, nil } -func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, error) { +func buildMCPProvider(server config.MCPServer, sampling mcp.SamplingHandler) (toolprovider.Engine, string, error) { name := strings.TrimSpace(server.Name) transportType := strings.ToLower(strings.TrimSpace(server.Transport)) if transportType == "" { @@ -89,7 +97,7 @@ func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, err if err != nil { return nil, transportType, err } - return mcptoolprovider.New(name, transport, server.ParallelToolCalls), transportType, nil + return mcptoolprovider.New(name, transport, server.ParallelToolCalls, mcptoolprovider.WithSamplingHandler(sampling)), transportType, nil } func mcpTransportForServer( diff --git a/internal/app/agentworker/mcp_providers_test.go b/internal/app/agentworker/mcp_providers_test.go index 16d89e9a6..3a62e2e18 100644 --- a/internal/app/agentworker/mcp_providers_test.go +++ b/internal/app/agentworker/mcp_providers_test.go @@ -167,7 +167,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - provider, transportType, err := buildMCPProvider(tc.server) + provider, transportType, err := buildMCPProvider(tc.server, nil) if transportType != tc.wantTransport { t.Fatalf("transport = %q, want %q", transportType, tc.wantTransport) } @@ -344,7 +344,7 @@ func TestStartMCPProvidersPreservesOptionalProviderBehavior(t *testing.T) { "valid-two": {id: "valid-two", entries: []tools.ToolEntry{testTool("shared")}}, } buildCalls := make(map[string]int) - build := func(server config.MCPServer) (toolprovider.Engine, string, error) { + build := func(server config.MCPServer, _ protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) { buildCalls[server.Name]++ switch server.Name { case "unknown": @@ -365,7 +365,7 @@ func TestStartMCPProvidersPreservesOptionalProviderBehavior(t *testing.T) { {Name: "valid-one"}, {Name: "valid-two"}, } - set, err := startMCPProvidersWith(t.Context(), servers, slog.New(slog.DiscardHandler), build) + set, err := startMCPProvidersWith(t.Context(), servers, nil, slog.New(slog.DiscardHandler), build) if err != nil { t.Fatalf("error = %v, want nil when valid providers remain available", err) } @@ -409,14 +409,14 @@ func TestStartMCPProvidersReturnsNilWithoutAvailableProviders(t *testing.T) { { name: "unknown transport is skipped without error", servers: []config.MCPServer{{Name: "unknown"}}, - build: func(config.MCPServer) (toolprovider.Engine, string, error) { + build: func(config.MCPServer, protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) { return nil, "unknown", errUnknownMCPTransport }, }, { name: "first provider error is returned", servers: []config.MCPServer{{Name: "first"}, {Name: "second"}}, - build: func(server config.MCPServer) (toolprovider.Engine, string, error) { + build: func(server config.MCPServer, _ protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) { if server.Name == "first" { return nil, "stdio", firstErr } @@ -430,12 +430,12 @@ func TestStartMCPProvidersReturnsNilWithoutAvailableProviders(t *testing.T) { t.Run(tc.name, func(t *testing.T) { build := tc.build if build == nil { - build = func(config.MCPServer) (toolprovider.Engine, string, error) { + build = func(config.MCPServer, protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) { t.Fatal("builder called without configured servers") return nil, "", nil } } - set, err := startMCPProvidersWith(t.Context(), tc.servers, slog.New(slog.DiscardHandler), build) + set, err := startMCPProvidersWith(t.Context(), tc.servers, nil, slog.New(slog.DiscardHandler), build) if set != nil { t.Fatalf("provider set = %#v, want nil", set) } diff --git a/internal/app/agentworker/mcp_sampling.go b/internal/app/agentworker/mcp_sampling.go new file mode 100644 index 000000000..6cb383f80 --- /dev/null +++ b/internal/app/agentworker/mcp_sampling.go @@ -0,0 +1,67 @@ +package agentworker + +import ( + "context" + "errors" + "fmt" + "strings" + + "github.com/samcharles93/ai-sdk/core" + "github.com/samcharles93/ai-sdk/runtime" + + "github.com/samcharles93/archie-core/internal/agentexec" + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/tools/mcp" +) + +// taskSamplingModel is the model a task-scoped MCP server's sampling request +// is answered with: the task's builder model, the same fallback an agent stage +// whose role is unset uses (workflow.AgentStage.resolveModel) and the same +// role the daemon's chat path falls back to. Empty means the task has no model +// to answer with. +func taskSamplingModel(cfg config.TaskConfig) string { + return strings.TrimSpace(cfg.Models["builder"]) +} + +// taskSamplingHandler answers an MCP server's sampling/createMessage request +// from the task's own model runtime, the same way the daemon's chat path +// answers it from its chat model. The worker hosts the same configured MCP +// servers as a chat turn, so without this a server's sampling request is +// answered on one path and refused on the other. A missing runtime or model is +// a refused request, never a dropped one: the client maps the returned error +// to a JSON-RPC error for that request alone. +func taskSamplingHandler(llm *runtime.Runtime, cfg config.TaskConfig) mcp.SamplingHandler { + return func(ctx context.Context, req mcp.SamplingRequest) (mcp.SamplingResult, error) { + if llm == nil { + return mcp.SamplingResult{}, errors.New("mcp sampling: no model runtime is configured") + } + model := taskSamplingModel(cfg) + if model == "" { + return mcp.SamplingResult{}, errors.New("mcp sampling: no builder model is configured") + } + messages, err := agentexec.SamplingMessages(req) + if err != nil { + return mcp.SamplingResult{}, err + } + limits := cfg.ModelLimits[model] + options := core.GenerateOptions{ + Messages: messages, + System: req.SystemPrompt, + MaxSteps: 1, + MaxTokens: agentexec.SamplingMaxTokens(req.MaxTokens, limits.MaxOutputTokens, limits.Reasoning), + } + if req.Temperature != nil { + options.Temperature = float32(*req.Temperature) + } + result, err := llm.Chat(ctx, model, options) + if err != nil { + return mcp.SamplingResult{}, fmt.Errorf("mcp sampling: %w", err) + } + return mcp.SamplingResult{ + Model: model, + Role: "assistant", + Content: mcp.SamplingContent{Type: "text", Text: result.Text}, + StopReason: string(result.FinishReason), + }, nil + } +} diff --git a/internal/app/agentworker/mcp_sampling_test.go b/internal/app/agentworker/mcp_sampling_test.go new file mode 100644 index 000000000..9d7cc7a86 --- /dev/null +++ b/internal/app/agentworker/mcp_sampling_test.go @@ -0,0 +1,193 @@ +package agentworker + +import ( + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "sync" + "testing" + + "github.com/samcharles93/archie-core/internal/agentexec" + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/tools/mcp" +) + +// capturedChatRequest is the JSON body the OpenAI-compatible provider sent for +// the last call, which is where the max-token parameter is chosen. +type capturedChatRequest struct { + mu sync.Mutex + body map[string]any +} + +func (c *capturedChatRequest) get() map[string]any { + c.mu.Lock() + defer c.mu.Unlock() + return c.body +} + +// newCapturingChatAPI answers every completion and records the wire body, so a +// test can assert the parameter the provider actually emitted rather than an +// option the handler merely set. +func newCapturingChatAPI(t *testing.T, capture *capturedChatRequest) *httptest.Server { + t.Helper() + api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var body map[string]any + _ = json.NewDecoder(r.Body).Decode(&body) + capture.mu.Lock() + capture.body = body + capture.mu.Unlock() + w.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"test",`+ + `"choices":[{"index":0,"message":{"role":"assistant","content":"ok"},"finish_reason":"stop"}],`+ + `"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`) + })) + t.Cleanup(api.Close) + return api +} + +// newSamplingModelServer stands in for an OpenAI-compatible provider so a +// sampling request can be answered without a real backend. +func newSamplingModelServer(t *testing.T) *httptest.Server { + t.Helper() + api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"gpt-5.6",`+ + `"choices":[{"index":0,"message":{"role":"assistant","content":"four"},"finish_reason":"stop"}],`+ + `"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`) + })) + t.Cleanup(api.Close) + return api +} + +func testSamplingRequest() mcp.SamplingRequest { + return mcp.SamplingRequest{ + Messages: []mcp.SamplingMessage{{ + Role: "user", + Content: mcp.SamplingContent{Type: "text", Text: "2+2?"}, + }}, + MaxTokens: 16, + } +} + +// TestTaskSamplingHandlerAnswersFromWorkerModel proves a task-scoped MCP +// server's sampling request is answered by the worker's own model. A task +// hosts the same configured MCP servers as a chat turn, so without this the +// server is answered on the chat path and refused on the task path. +func TestTaskSamplingHandlerAnswersFromWorkerModel(t *testing.T) { + api := newSamplingModelServer(t) + llm := agentexec.NewRuntime(map[string]agentexec.Provider{ + "openai": {Class: "openai", BaseURL: api.URL}, + }) + handler := taskSamplingHandler(llm, config.TaskConfig{Models: map[string]string{"builder": "openai/gpt-5.6"}}) + + result, err := handler(t.Context(), testSamplingRequest()) + if err != nil { + t.Fatalf("sampling handler = %v, want a completion", err) + } + if result.Model != "openai/gpt-5.6" { + t.Errorf("result.Model = %q, want the task's builder model", result.Model) + } + if result.Role != "assistant" || result.Content.Type != "text" || result.Content.Text != "four" { + t.Errorf("result = %+v, want an assistant text completion", result) + } +} + +// TestTaskSamplingHandlerRefusesCleanly proves a worker with no usable model +// answers the request with an error instead of panicking or dropping it: the +// server sees a failed request, not a dead session. +func TestTaskSamplingHandlerRefusesCleanly(t *testing.T) { + tests := []struct { + name string + llm bool + model string + want string + }{ + {name: "no model runtime", llm: false, model: "openai/gpt-5.6", want: "no model runtime"}, + {name: "no builder model configured", llm: true, want: "no builder model"}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + llm := agentexec.NewRuntime(nil) + if tc.llm { + llm = agentexec.NewRuntime(map[string]agentexec.Provider{"openai": {Class: "openai"}}) + } + models := map[string]string{} + if tc.model != "" { + models["builder"] = tc.model + } + _, err := taskSamplingHandler(llm, config.TaskConfig{Models: models})(t.Context(), testSamplingRequest()) + if err == nil { + t.Fatal("sampling handler returned no error with no usable model") + } + if !strings.Contains(err.Error(), tc.want) { + t.Errorf("error = %q, want it to mention %q", err, tc.want) + } + }) + } +} + +// TestTaskSamplingBoundFollowsModelClass proves the worker consumes the +// reasoning flag carried in TaskConfig.ModelLimits: a reasoning-class builder +// model gets no max-token bound (its provider rejects the max_tokens parameter +// the chat-completions provider emits), while a classic model gets the +// request's own bound. +func TestTaskSamplingBoundFollowsModelClass(t *testing.T) { + tests := []struct { + name string + reasoning bool + wantBound bool + wantValue int + }{ + {name: "reasoning model", reasoning: true}, + {name: "classic model", wantBound: true, wantValue: 16}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + capture := &capturedChatRequest{} + api := newCapturingChatAPI(t, capture) + llm := agentexec.NewRuntime(map[string]agentexec.Provider{ + "openai": {Class: "openai", BaseURL: api.URL}, + }) + cfg := config.TaskConfig{ + Models: map[string]string{"builder": "openai/gpt-5.6"}, + ModelLimits: map[string]config.ModelLimits{ + "openai/gpt-5.6": {MaxOutputTokens: 128000, Reasoning: tc.reasoning}, + }, + } + if _, err := taskSamplingHandler(llm, cfg)(t.Context(), testSamplingRequest()); err != nil { + t.Fatalf("sampling handler error = %v", err) + } + bound, present := capture.get()["max_tokens"] + if present != tc.wantBound { + t.Fatalf("request body max_tokens present = %v (value %v), want %v; body = %v", present, bound, tc.wantBound, capture.get()) + } + if present && bound != float64(tc.wantValue) { + t.Fatalf("request body max_tokens = %v, want %d; body = %v", bound, tc.wantValue, capture.get()) + } + }) + } +} + +// TestBuildMCPProviderWiresTaskSamplingHandler proves the worker's MCP +// provider builder hands the provider the sampling handler, so the seam a task +// run builds providers through is the one that answers sampling -- not only +// the handler in isolation. +func TestBuildMCPProviderWiresTaskSamplingHandler(t *testing.T) { + handler := taskSamplingHandler(agentexec.NewRuntime(map[string]agentexec.Provider{ + "openai": {Class: "openai"}, + }), config.TaskConfig{Models: map[string]string{"builder": "openai/gpt-5.6"}}) + + provider, _, err := buildMCPProvider(config.MCPServer{Name: "sampling", Command: "server"}, handler) + if err != nil { + t.Fatalf("buildMCPProvider: %v", err) + } + field := reflect.ValueOf(provider).Elem().FieldByName("samplingHandler") + if field.IsNil() { + t.Fatal("task MCP provider carries no sampling handler: a task-scoped server's sampling/createMessage request is refused") + } +} diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index 0f65996c3..f32c9191d 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -10,6 +10,8 @@ import ( "path/filepath" "strconv" + "github.com/samcharles93/ai-sdk/runtime" + "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" @@ -202,15 +204,17 @@ func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy, allow []s runner.AllowTools = allow } -// stageRunners builds the runner every agent stage uses. -func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, log *slog.Logger) (agentexec.Runner, error) { +// stageRunners builds the runner every agent stage uses. llm is the task's +// shared model runtime (the one its MCP providers answer sampling from); the +// registry path reuses it rather than building a second one. +func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, llm *runtime.Runtime, log *slog.Logger) (agentexec.Runner, error) { if req.Harness != nil { // The built-in loop has no route to a model from a Kit container. return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil } var agent agentexec.Runner if mcpSet != nil && mcpSet.registry != nil { - agent = agentexec.NewLoopRunner(agentexec.NewRuntime(req.Providers), log, mcpSet.registry) + agent = agentexec.NewLoopRunner(llm, log, mcpSet.registry) } else { agent = newRunner(req.Providers, log) } @@ -261,8 +265,14 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen // start from. defer restoreWorktreeOwnership(trees, workDir, log)() - // Start MCP providers and build a local tool registry. - mcpSet, mcpErr := startMCPProviders(ctx, req.MCPServers, log) + // The MCP providers a task hosts share the same model runtime its agent + // stages run on, so a server-initiated sampling request is answered from + // the task's own model rather than a second provider client. + var llm *runtime.Runtime + if len(req.MCPServers) > 0 { + llm = agentexec.NewRuntime(req.Providers) + } + mcpSet, mcpErr := startMCPProviders(ctx, req.MCPServers, taskSamplingHandler(llm, req.Cfg), log) if mcpSet != nil { defer mcpSet.cleanup(ctx, log) } @@ -270,7 +280,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen log.Warn("mcp providers had errors, continuing with available tools", "err", mcpErr) } - agent, err := stageRunners(req, mcpSet, newRunner, log) + agent, err := stageRunners(req, mcpSet, newRunner, llm, log) if err != nil { return nil, err } diff --git a/internal/app/archied/mcp_sampling.go b/internal/app/archied/mcp_sampling.go index bf8e2e38d..16cd1698b 100644 --- a/internal/app/archied/mcp_sampling.go +++ b/internal/app/archied/mcp_sampling.go @@ -5,18 +5,12 @@ import ( "errors" "fmt" - "github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/core" + "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/tools/mcp" ) -// samplingDefaultMaxTokens bounds a server-requested completion when the -// request does not set maxTokens. A sampling request is a delegated -// sub-completion, not a full turn; this keeps one MCP server from spending a -// turn-sized output allowance on a single request. -const samplingDefaultMaxTokens = 4096 - // mcpSamplingHandler answers an MCP server's sampling/createMessage request // from the daemon's own chat model, so a server can ask for a completion // without archie opening a second provider path. A missing runtime or model @@ -36,7 +30,7 @@ func (b *boot) mcpSamplingHandler() mcp.SamplingHandler { if model == "" { return mcp.SamplingResult{}, errors.New("mcp sampling: no chat model is configured") } - messages, err := samplingMessages(req) + messages, err := agentexec.SamplingMessages(req) if err != nil { return mcp.SamplingResult{}, err } @@ -66,46 +60,12 @@ func (b *boot) mcpSamplingHandler() mcp.SamplingHandler { } } -// samplingMessages maps the server's messages onto chat messages. A -// non-text content block or an unknown role is rejected rather than silently -// dropped: answering from a partial prompt would be a wrong answer, not a -// degraded one. -func samplingMessages(req mcp.SamplingRequest) ([]chat.Message, error) { - if len(req.Messages) == 0 { - return nil, errors.New("mcp sampling: the request has no messages") - } - messages := make([]chat.Message, 0, len(req.Messages)) - for i, message := range req.Messages { - if message.Content.Type != "" && message.Content.Type != "text" { - return nil, fmt.Errorf("mcp sampling: message %d has unsupported content type %q", i, message.Content.Type) - } - var role chat.Role - switch message.Role { - case "user": - role = chat.RoleUser - case "assistant": - role = chat.RoleAssistant - default: - return nil, fmt.Errorf("mcp sampling: message %d has unsupported role %q", i, message.Role) - } - messages = append(messages, chat.Message{Role: role, Content: message.Content.Text}) - } - return messages, nil -} - // samplingMaxTokens bounds the completion to the request's own maxTokens, // falling back to a conservative default, and never past the model's own -// output ceiling. A reasoning-class model gets no bound at all: its provider -// rejects the `max_tokens` parameter the chat-completions provider emits for a -// non-zero bound. +// output ceiling. The bound itself is shared with the agent worker's sampling +// path (agentexec.SamplingMaxTokens) so the same server sees the same bound on +// either path. func samplingMaxTokens(req mcp.SamplingRequest, models *chatModelManager, model string) int { details, ok := models.ModelDetails(model) - maxTokens := req.MaxTokens - if maxTokens <= 0 { - maxTokens = samplingDefaultMaxTokens - } - if ok && details.MaxOutputTokens > 0 && maxTokens > details.MaxOutputTokens { - maxTokens = details.MaxOutputTokens - } - return maxTokensForRequest(ok && details.Reasoning, maxTokens) + return agentexec.SamplingMaxTokens(req.MaxTokens, details.MaxOutputTokens, ok && details.Reasoning) } diff --git a/internal/app/archied/mcp_sampling_test.go b/internal/app/archied/mcp_sampling_test.go index 9740e2f5a..fa2dd7d4f 100644 --- a/internal/app/archied/mcp_sampling_test.go +++ b/internal/app/archied/mcp_sampling_test.go @@ -96,15 +96,3 @@ func TestMCPSamplingHandlerRefusesCleanlyWithNoModel(t *testing.T) { }) } } - -func TestSamplingMessagesRejectsUnsupportedContent(t *testing.T) { - _, err := samplingMessages(mcp.SamplingRequest{ - Messages: []mcp.SamplingMessage{{ - Role: "user", - Content: mcp.SamplingContent{Type: "image"}, - }}, - }) - if err == nil || !strings.Contains(err.Error(), "unsupported content type") { - t.Fatalf("samplingMessages error = %v, want an unsupported-content refusal", err) - } -} diff --git a/internal/app/archied/model_catalog.go b/internal/app/archied/model_catalog.go index 5ee99baf4..ad1003dab 100644 --- a/internal/app/archied/model_catalog.go +++ b/internal/app/archied/model_catalog.go @@ -22,7 +22,7 @@ func applyModelCatalog(cfg *config.Config, snapshot modelcatalog.Snapshot) []str for _, model := range provider.Models { ref := provider.ID + "/" + model.ID models = append(models, ref) - limits[ref] = config.ModelLimits{ContextWindow: model.ContextWindow, MaxOutputTokens: model.MaxOutputTokens} + limits[ref] = config.ModelLimits{ContextWindow: model.ContextWindow, MaxOutputTokens: model.MaxOutputTokens, Reasoning: model.Reasoning} } } cfg.ModelLimits = limits diff --git a/internal/app/archied/model_output_bound_test.go b/internal/app/archied/model_output_bound_test.go index 5cc49e040..18ed001ea 100644 --- a/internal/app/archied/model_output_bound_test.go +++ b/internal/app/archied/model_output_bound_test.go @@ -132,7 +132,7 @@ func TestMCPSamplingParameterNameFollowsModelClass(t *testing.T) { modelRef: "openai/gpt-4o", model: modelcatalog.Model{ID: "gpt-4o", MaxOutputTokens: 128000}, wantBound: true, - wantValue: samplingDefaultMaxTokens, + wantValue: agentexec.DefaultSamplingMaxTokens, }, } diff --git a/internal/config/config.go b/internal/config/config.go index 14f2de528..04f57afe8 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -598,6 +598,11 @@ type IdentityConfig struct { type ModelLimits struct { ContextWindow int `json:"context_window"` MaxOutputTokens int `json:"max_output_tokens"` + // Reasoning marks a reasoning-class model. It is derived from the model + // catalog (never operator-authored) and carried to the agent worker so a + // task-scoped MCP sampling request omits the max-token bound those models + // reject, exactly as the daemon's chat path does. + Reasoning bool `json:"reasoning,omitempty"` } // TaskConfig is the non-secret subset of Config needed to run workflow