From 6fa1836eca5cc469a4613ada8f4b76ab46a2e801 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 2 Oct 2026 12:20:31 +1000 Subject: [PATCH] feat(agentworker): answer MCP sampling from the task's model A task hosts the same configured MCP servers as a chat turn, but the worker's provider builder passed no sampling handler, so a task-scoped server's sampling/createMessage request got a JSON-RPC method-not-found while the identical request succeeded on the chat path. The worker runs its own model runtime, so it can answer. Thread a sampling handler built from the task's builder model into the worker's MCP provider builder, beside the chat path's handler. Build the task's model runtime once and share it with the stage runners instead of creating a second client for sampling. Move the sampling message mapping and max-token bound to agentexec, next to the runtime both paths call models through, so a server gets the same bound on either path. Carry the catalog's reasoning flag in ModelLimits: a reasoning-class builder model must omit the max-token bound its provider rejects, exactly as the chat path does. --- docs/data/generated/dev-docs.json | 2 +- docs/prds/mcp-tool-completion.md | 18 +- internal/agentexec/sampling.go | 66 ++++++ internal/agentexec/sampling_test.go | 98 +++++++++ internal/app/agentworker/mcp_providers.go | 24 ++- .../app/agentworker/mcp_providers_test.go | 14 +- internal/app/agentworker/mcp_sampling.go | 67 ++++++ internal/app/agentworker/mcp_sampling_test.go | 193 ++++++++++++++++++ internal/app/agentworker/task_execution.go | 22 +- internal/app/archied/mcp_sampling.go | 52 +---- internal/app/archied/mcp_sampling_test.go | 12 -- internal/app/archied/model_catalog.go | 2 +- .../app/archied/model_output_bound_test.go | 2 +- internal/config/config.go | 5 + 14 files changed, 490 insertions(+), 87 deletions(-) create mode 100644 internal/agentexec/sampling.go create mode 100644 internal/agentexec/sampling_test.go create mode 100644 internal/app/agentworker/mcp_sampling.go create mode 100644 internal/app/agentworker/mcp_sampling_test.go 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