@adia-ai/agent 0.8.29 → 0.8.30

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.8.30] — 2026-08-07
+
+### Added
+- **MCP-client mode — an MCP server as a tool/resource source (gh#666).** `createAgent({ integrations: [mcpServer({ url, headers })] })` connects over streamable-HTTP, lists the server's tools, and registers each one through the tier-2 integration registry (`register` fail-fast on a name collision, `buildToolDispatch` as the one ToolDef builder). From there they are ordinary `ToolDef`s: the guardrail chain sees the calls, the tracer records the executions, `checkInput` runs at the boundary, failures come back as `isError` tool_results. Additive throughout — an agent declaring no `integrations` produces the same request, events, and session as before (the byte-identity baseline is untouched).
+  - **Lazy, memoized connection.** `createAgent` stays synchronous; the handshake happens on the first turn, or eagerly via the new `agent.connect()`, which reports `{ url, serverInfo, protocolVersion, tools, resources }` per server. `agent.close()` ends the sessions. A failed connect is not cached — the next turn retries.
+  - **Failure semantics.** Unreachable server, non-2xx, an unspeakable protocol version, a failed `tools/list`, a tool-name collision, or more tools than `maxTools` all **throw `McpConnectionError`** (infrastructure faults the model cannot work around); a failed `tools/call`, a mid-session disconnect, or a server-reported `isError` reaches the model as an `isError` tool_result and the loop continues. There is no path that silently yields an empty tool list. `maxTools` (default `MAX_INTEGRATIONS`) throws instead of dropping the overflow the way `resolveIntegrations`' cap does, which is why MCP registration does not route through `resolveIntegrations` (it has neither a persona list nor an env key).
+  - **Resources map onto the existing two modes.** Every server resource is `tool` mode by default (`read_<name>`); `attach: [name|uri]` promotes the ones the app wants inlined every turn. **gh#671 is ruled here: no third `'internal'` resource mode.** A mode declares who invokes and when, and engine-internal retrieval names no mediated party — its dependency is already `services` and its visibility already `ctx.trace` in the `workflow` phase. Recorded in the README.
+  - **No new runtime dependency.** The streamable-HTTP client is hand-rolled (~200 lines, `fetch`-only, browser-safe): initialize + `notifications/initialized` + `tools/list` + `tools/call` + `resources/list` + `resources/read`, session-header echo, protocol-version negotiation, cursor pagination, and JSON *or* SSE response bodies. Verified against the real in-repo `packages/a2ui/mcp` SDK server over HTTP (30 tools, 4 resources, tool call and resource read). **stdio is unsupported** — it needs a child process, so it is Node-only by construction. Browser use needs a CORS-enabled server or the host's existing proxy; this package ships no proxy, and `fetchImpl` is the injection seam.
+  - **Per-request deadline, default 60s** (`McpTransportOptions.timeoutMs`, `DEFAULT_MCP_TIMEOUT_MS`; `0` disables). It covers the fetch AND the wait for the answer on an SSE body, so a server that accepts a POST and then says nothing fails instead of hanging. 60s rather than a handshake-sized number because an MCP `tools/call` may run an LLM server-side (the in-repo a2ui server's `generate_ui` does). A connect timeout throws; a call timeout reaches the model as an `isError` tool_result.
+  - **Abort plumbed end to end** — `SendOpts.signal` reaches an in-flight `tools/call` / `resources/read`, so a user cancellation cancels the server request rather than abandoning it. The signal of the turn that triggers a connect cancels that handshake only; it never stays attached to the resulting connection.
+  - **Failures leave no session open** — a source that fails after its handshake closes its own session, a failing second source closes the first one's, and `close()` during an in-flight connect wins (the late arrival closes what it opened and rejects rather than reinstalling itself). `close()` does not spend the agent: a later `send()` reconnects.
+  - **New trace phase `mcp`** (`connect` / `connect:failed`) on `TRACE_PHASES`; contributed tools still execute under `tool`.
+  - **New test fixture** `mcp-fixture.mjs` — an in-process MCP server behind a `fetch`-shaped function, covering both response body shapes.
+- **Attach-mode resources are contained, not trusted (behavior change).** `attachLayers` now escapes the two structural sequences (`<resource`, `</resource`) in a resource BODY and the attribute specials in its `name` / `description`. A body containing `</resource>` previously closed its own envelope, and everything after it read as prompt — a file, a database row, or an MCP server could write instructions into the system prompt that way. Only those sequences are escaped: attached bodies are catalog JSON, component markup and docs, and mangling every `<` would degrade the data the model reads every turn for a property those two sequences already give. Applies to every attach resource, hand-declared or MCP. A prompt only changes if it contained one of those sequences.
+- **`ResourceDef.get` receives `(input, ctx)`** — `ctx.signal` is the turn's cancellation, so a resource read can be aborted. Additive: a one-argument `get` is unaffected.
+- **`IntegrationManifest.validation: 'local' | 'remote'`** (default `'local'`, behavior unchanged). `'remote'` says the executor is the authoritative validator, so registration accepts the schema as written instead of enforcing `checkInput`'s allowlist — an MCP server's schema reaches the model verbatim rather than being trimmed to a locally-enforceable subset that describes the tool less accurately.
+- **W2 hardening — guardrails, tracing, session memory, partial tool input (gh#665).** All additive; a config that declares none of them produces the same requests, the same events, and the same session as before.
+  - **Guardrails** (`defineGuardrail`, `AgentConfig.guardrails`) — the deterministic layer between the model and the world, declared once at `createAgent`. `toolCall` guardrails allow / rewrite / deny a call before it executes (a deny feeds the model an `isError` tool_result naming the guardrail; the loop continues); `output` guardrails allow / rewrite / deny the model's completed text for **the round that ends the turn** — text from a round that also called tools is intermediate and passes through unguarded (README records the caveat) — where a deny ends the turn with no assistant text and the synthetic `stopReason: 'guardrail_denied'`. A rewrite or denial is followed by a `{ text: '', snapshot }` event: a UI folding text events by appending must treat an empty delta as a replace from `snapshot`. They chain in declaration order — a rewrite feeds the next, the first deny short-circuits. `onToolCall` is now exactly one guardrail of the `toolCall` kind, unchanged in behavior and wording, running ahead of the declared chain. New render-only `guardrail` event.
+  - **Tracing** (`AgentConfig.trace`, `createTracer`, `consoleSink`, `TRACE_PHASES`) — structured records for prompt assembly, each provider call and response, each tool execution, each workflow step verdict, each guardrail intervention, and the turn's token usage. Two consumers of one record: a render-only `trace` event on the stream and a pluggable sink (`true` → console). Off by default; a throwing sink warns instead of failing the turn. No exporter protocol, no dependency.
+  - **Session memory** (`Session.memory`, `remember()`, `ToolContext.remember`) — a per-session JSON-safe key/value slot written ONLY through `reduce()` via the new `memory` event (a null value deletes a key). A tool asks for a write through `ctx.remember(patch)`; the loop yields the event after that tool's result, and drains anything still queued before every `done` — so a final-round tool's write, or a guardrail's (guardrails receive the same context), is emitted rather than silently dropped. Non-JSON-safe patches throw at the write, naming the path (`assertJsonSafe`). Cross-session persistence stays a seam: memory serializes with the Session, storage remains the caller's.
+  - **Partial tool-input deltas** — the new `@adia-ai/llm` `tool_use_delta` chunk surfaces as a render-only `tool_input_delta` event (`id`, `name`, `partial`, `snapshot`). The snapshot is raw, incomplete JSON; nothing executes off it, and the complete `tool_use` chunk is unchanged. `scriptClient` gained `ScriptedTurn.toolUseDeltas` to script the path.
+
+### Changed
+- **Workflow contract repairs — the five W1 findings (gh#665).** Additive except where noted:
+  - **`until` may return a VERDICT** — `{ accepted, reason, detail, data }`. Only an object with a boolean `accepted` is read as a verdict; **every other return is read for its truthiness**, so a pre-verdict predicate (`r => r.messages.length`, `r => r.id`) keeps meaning what it always meant rather than being treated as a malformed verdict and silently flipping to rejected. The reason lands on the attempt, so consumers stop recomputing why a step was rejected.
+  - **`WorkflowAttempt` gains `round`, and optional `reason` / `detail` / `data` / `gateRejected`.** `round` is always present — a consumer doing an exact deep-equal on an attempt object sees one new key.
+  - **Workflow-level exit gate** — `defineWorkflow(name, steps, { exitGate })`, the check every accepted result passes through, declared once instead of restated per step. A **terminal step (no `until`) is not exit-gated**: the floor of a ladder is the answer of last resort. Declare `until: () => true` on the last step to gate it like the others.
+  - **Same-step retry** — `WorkflowStep.retry = { maxRounds }` re-runs a step against its own rejection verdict before falling through. `ctx.round` (1-based) and `ctx.feedback` (the previous verdict) reach `run`; each round is its own `attempts` entry. An exit-gate rejection consumes a round like any other and arrives on the next round's `ctx.feedback` carrying `gateRejected: true` (the marker is on the Verdict, not only on the attempt).
+  - **Services channel** — `WorkflowContext.services` is what a run may USE (llmAdapter, clients, stores), separate from `input`, which is what it is ABOUT. Declared on `AgentConfig.services` and/or per run; per-run wins. `input` is unchanged and not deprecated for consumer-owned shapes.
+  - **`agent.run`'s fourth argument may be an options object** (`{ onEvent, services, signal }`) as well as the v0 bare `onEvent` function.
+
+### Changed (v0 → v1, previously recorded)
+- **No longer experimental — the A2UI pipeline migration validated the contracts (gh#664).** `packages/a2ui/compose` now declares its engine escalation ladder as a `defineWorkflow` (`strategies/cascade.js`, reachable as the reserved engine name `auto`), and the A2UI MCP surface declares its corpus reads as `mode:'tool'` resources and `refine_ui` as a `defineTool`. Three contracts changed under that pressure, all additive:
+  - **Workflow predicates may be async, and `until` receives the context.** `until?: (result, ctx) => boolean | Promise<boolean>`, `when?: (ctx) => boolean | Promise<boolean>`. A real acceptance gate for a generated surface reads catalog JSON off disk; a sync-only predicate forced every consumer to pre-resolve its gate outside the workflow, which is where cascades get duplicated.
+  - **`WorkflowResult.attempts`** — `{ step, accepted, result }` per step that ran, in order. The escalation trace was previously unrecoverable from the result: consumers could see who won but not who was tried or why the ladder climbed.
+  - **`ResourceDef.inputSchema`** (tool-mode only; throws on an attach-mode resource) and a `get` that may return a non-string, JSON-serialized on the way out. Without the schema a tool-mode resource was a zero-argument read, which cannot express `search_chunks(query, kind, limit)`.
+
+### Maintenance
+- **`src/` touched in this release window** (14 file(s), e.g. `src/agent.ts`) — carried by the entries above.
+
 ## [0.8.29] — 2026-08-06
 
 ### Maintenance

package/README.md

@@ -6,8 +6,22 @@ Composable chat-agent harness. Assemble an agent from four declared parts —
 serializable `Session`, and the one shared event reducer; it renders nothing
 (pair it with `web-modules/chat` or any UI).
 
-> **Experimental** until the A2UI pipeline migration validates the contracts
-> (tracked in [gh#579](https://github.com/adiahealth/gen-ui-kit/issues/579)).
+The contracts are validated by a real consumer: the A2UI generation pipeline
+runs on them ([gh#664](https://github.com/adiahealth/gen-ui-kit/issues/664))
+— its engine escalation ladder is a workflow
+(`packages/a2ui/compose/strategies/cascade.js`), its corpus reads are
+tool-mode resources, and its refiner is a defined tool. What that migration
+could not express became this package's hardening pass
+([gh#665](https://github.com/adiahealth/gen-ui-kit/issues/665)): workflow
+verdicts, exit gates, same-step retry, a services channel, guardrails,
+tracing, session memory, and partial tool-input deltas.
+
+Deferred, with reason: **`@genui/adia-producer`'s bridge keeps its own loop.**
+The retry seam covers per-tier round budgets, but the bridge also owns a
+turn-wide `maxProviderCallsPerTurn` budget spanning steps, a genui `TurnTrace`,
+and `OrchestrationExhaustedError` semantics that come from `@genui/producer`
+— none of which this package models, and modelling them here would import
+another package's orchestration vocabulary into a general harness.
 
 ## Install
 
@@ -40,13 +54,17 @@ const agent = createAgent({
   workflows: [
     defineWorkflow('generate', [
       { name: 'zettel',     run: zettel,     until: r => r.strategy === 'composition-match' },
-      { name: 'free-form',  run: freeForm,   until: r => r.ok },
+      { name: 'free-form',  run: freeForm,   until: async r => r.ok && await passesGate(r) },
       { name: 'monolithic', run: monolithic },                // terminal — always accepted
     ]),
   ],
   resources: [
     defineResource({ name: 'visit-summary', mode: 'attach', get: fetchSummary }), // app-controlled
-    defineResource({ name: 'care-plan',     mode: 'tool',   get: readPlan }),     // model-controlled
+    defineResource({                                                              // model-controlled
+      name: 'care-plan', mode: 'tool',
+      inputSchema: { type: 'object', properties: { section: { type: 'string' } } },
+      get: ({ section }) => readPlan(section),   // non-string returns are JSON-serialized
+    }),
   ],
   maxToolRounds: 8,
 });
@@ -64,9 +82,101 @@ await agent.run(session, 'generate', { intent });
 | Part | Declared with | What the harness does |
 |---|---|---|
 | Prompt | `promptLayer(name, text, {cache})` | Static layers first, `cache_control` on the last cached one (Anthropic block array; joined string elsewhere) |
-| Tools | `defineTool({name, inputSchema, execute\|endpoint})` | JSON-schema check at the call boundary, then the execute-and-feed-back loop (bounded by `maxToolRounds`; gate calls via `onToolCall`) |
-| Workflows | `defineWorkflow(name, steps)` | Sequential cascade — `until` accepts, absent `until` is terminal, `when` skips |
-| Resources | `defineResource({name, mode, get})` | `attach` → dynamic prompt layer each turn; `tool` → a read-only `read_<name>` tool |
+| Tools | `defineTool({name, inputSchema, execute\|endpoint})` | JSON-schema check at the call boundary, then the execute-and-feed-back loop (bounded by `maxToolRounds`) |
+| Workflows | `defineWorkflow(name, steps, {exitGate})` | Sequential cascade — `until` accepts, absent `until` is terminal, `when` skips, `retry` re-runs the same step |
+| Resources | `defineResource({name, mode, inputSchema, get})` | `attach` → dynamic prompt layer each turn; `tool` → a read-only `read_<name>` tool taking `inputSchema`'s arguments |
+
+**The attach envelope contains what it wraps.** An attach-mode resource
+inlines somebody else's bytes into the system prompt, so a body containing
+`</resource>` would otherwise close its own envelope and everything after it
+would read as prompt — a file, a database row, or an MCP server could write
+instructions into the system prompt that way. `attachLayers` escapes the two
+structural sequences (`<resource` and `</resource`) in the body and the
+attribute specials in `name` / `description`. Only those: attached bodies here
+are catalog JSON, component markup and docs, and mangling every `<` in them to
+close one hole would degrade the data the model reads on every turn for a
+containment property those two sequences already give. Everything else arrives
+byte-for-byte. This applies to every attach resource, hand-declared or MCP.
+
+A resource's `get` receives `(input, ctx)` — `ctx.signal` is the turn's
+cancellation. Existing one-argument `get`s are unaffected.
+
+Three cross-cutting layers ride on top: **guardrails** (veto/rewrite),
+**tracing** (structured records of what the harness did), and **session
+memory** (a JSON-safe slot on the Session). Tools and resources may also
+arrive from **an MCP server** instead of being hand-declared — see
+[MCP-client mode](#mcp-client-mode).
+
+### Workflows in detail
+
+`until` and `when` may both be async, and `until` also receives the context
+(`until(result, ctx)`) — the acceptance gate for a generated artifact
+usually has to read something. The result carries the whole run:
+
+```js
+const { result, step, accepted, attempts } = await agent.run(session, 'generate', { intent });
+// attempts: [{ step:'zettel', accepted:false, reason:'no-emission', round:1, result:… },
+//            { step:'free-form', accepted:true, round:1, result:… }]
+```
+
+`attempts` lists every step round that RAN (a `when`-skipped step doesn't
+appear), in order, with its verdict — that list is the escalation trace a UI
+renders. `accepted` is false only when the last step also rejected; give the
+ladder a terminal step (no `until`) if you want a guaranteed answer.
+
+**Verdicts.** `until` may return a verdict object —
+`{ accepted, reason, detail, data }` — or **any other value, read for its
+truthiness**, which is what a pre-verdict predicate (`r => r.messages.length`)
+already did. Only an object with a boolean `accepted` is treated as a verdict.
+The reason lands on the attempt, so a consumer renders why the ladder climbed
+instead of recomputing it:
+
+```js
+until: (r) => r.messages.length
+  ? { accepted: true }
+  : { accepted: false, reason: 'no-emission', detail: 'engine emitted nothing' },
+```
+
+**Exit gate.** The check every step's result must pass is declared once on
+the workflow instead of restated in every `until`:
+
+```js
+defineWorkflow('generate', steps, {
+  exitGate: async (result, ctx) => await validatesAgainstCatalog(result, ctx.input),
+});
+```
+
+It runs after a step's own `until` accepted, and a rejection falls the ladder
+through exactly like an `until` rejection (the attempt carries
+`gateRejected: true` and `reason: 'gate-rejected'`). A **terminal step — one
+with no `until` — is not exit-gated**: the floor of a ladder is the answer of
+last resort. Give the last step `until: () => true` if you want it gated too.
+
+**Same-step retry.** A step may retry against its own rejection before
+falling through:
+
+```js
+{ name: 'repair', retry: { maxRounds: 3 },
+  run: (ctx) => generate(ctx.input, ctx.feedback),   // ctx.round is 1-based
+  until: (r) => r.valid ? { accepted: true } : { accepted: false, reason: 'invalid', data: r.errors } }
+```
+
+`ctx.feedback` is the previous round's verdict; each round is its own entry
+in `attempts`. `maxRounds` counts total runs (2 = one retry). A workflow
+**exit-gate** rejection consumes a round exactly like an `until` rejection,
+and reaches the next round as `ctx.feedback` carrying `gateRejected: true` —
+so a repair round can tell the gate's objection from the step's own.
+
+**Services.** `ctx.input` is what the run is ABOUT; `ctx.services` is what it
+may USE. Declare them on the agent, per run, or both (per-run wins):
+
+```js
+createAgent({ …, services: { llmAdapter, store } });
+await agent.run(session, 'generate', { intent }, { services: { llmAdapter: turnAdapter } });
+```
+
+Services used to ride `input`, and still may — nothing breaks — but a new
+consumer should keep `input` the subject and put dependencies here.
 
 ## Events
 
@@ -77,17 +187,30 @@ can react to — the loop throws for nothing tool-shaped.
 ```
 { type:'message', role:'user', text }
 { type:'text', text, snapshot } · { type:'thinking', text }
+{ type:'tool_input_delta', id, name, partial, snapshot }
 { type:'tool_use', id, name, input } · { type:'tool_result', id, name, output, isError? }
 { type:'step', workflow, step, data? }
 { type:'progress', stage } · { type:'surface', surfaceId, line }
+{ type:'guardrail', name, target, action, reason?, toolName?, toolUseId? }
+{ type:'trace', record } · { type:'memory', patch }
 { type:'done', text, usage, stopReason } · { type:'error', error }
 ```
 
-`stopReason` passes through raw from the provider; the loop adds exactly one
-synthetic value, `max_tool_rounds`, when the bound is hit.
+`stopReason` passes through raw from the provider; the loop adds exactly two
+synthetic values — `max_tool_rounds` when the bound is hit, and
+`guardrail_denied` when an output guardrail vetoed the turn.
+
+`thinking` / `step` / `error` / `progress` / `surface` / `tool_input_delta` /
+`guardrail` / `trace` are render-only — `reduce()` folds them into no session
+change. `memory` is the one new event that DOES change the session.
 
-`thinking` / `step` / `error` / `progress` / `surface` are render-only —
-`reduce()` folds them into no session change.
+### Partial tool input
+
+While a provider streams a tool call's arguments, each fragment surfaces as
+`tool_input_delta` (Anthropic `input_json_delta`, OpenAI partial argument
+strings; Gemini streams complete calls and emits none). `snapshot` is the raw
+JSON so far — **incomplete and unparseable until the matching `tool_use`
+arrives**. Render progress from it; execute only on `tool_use`.
 
 ### Progress events (CHAT-HARNESS law 3)
 
@@ -144,6 +267,250 @@ loop as `agent.send()`. A silent-apply message yields nothing and never
 touches the provider — the caller already applied it directly (e.g. to a
 surface's data-model store).
 
+## MCP-client mode
+
+Point the agent at an [MCP](https://modelcontextprotocol.io) server and its
+tools and resources join the declared ones. Nothing downstream knows the
+difference: the calls go through the guardrail chain, the tracer records the
+executions, `checkInput` runs at the boundary, a failure comes back as an
+`isError` tool_result. MCP is a *source* of tools, not a second kind of tool.
+
+```js
+import { createAgent, mcpServer } from '@adia-ai/agent';
+
+const agent = createAgent({
+  llm: { model: 'claude-sonnet-4-6', proxyUrl: '/api/chat' },
+  integrations: [
+    mcpServer({
+      url: 'https://mcp.example.com/mcp',
+      headers: { authorization: `Bearer ${token}` },  // v1 auth: headers only
+      prefix: 'wiki_',            // namespace its tool names
+      tools: ['search', 'fetch'], // allowlist; absent = everything it lists
+      maxTools: 24,               // loud cap, default MAX_INTEGRATIONS (16)
+      attach: ['style-guide'],    // resources to inline every turn
+      timeoutMs: 60_000,          // per request; 0 disables (default 60s)
+    }),
+  ],
+});
+
+const report = await agent.connect();   // optional — otherwise the first turn does it
+// [{ url, serverInfo, protocolVersion, tools: [...], resources: [{name, uri, mode}] }]
+await agent.close();                    // ends the MCP session(s)
+```
+
+**Connection is lazy and memoized.** `createAgent` is synchronous and a
+constructor that reaches the network is a constructor that can fail, so the
+handshake happens on the first turn — or eagerly on `agent.connect()`, which
+returns what each server offered. `agent.tools` lists the declared set until
+the sources connect, and everything afterwards. A failed connect is not
+cached as a verdict: the next turn tries again.
+
+**Failure is loud where it must be and model-visible where it can be.**
+
+| When | What happens |
+|---|---|
+| Server unreachable, non-2xx, unspeakable protocol version, `tools/list` fails | `McpConnectionError` **thrown** out of `connect()` / `send()`. An infrastructure fault the model cannot work around — the same class as a missing `@adia-ai/llm`, never a silent empty tool list |
+| Two sources (or a source and a declared tool) contribute the same tool name | `McpConnectionError` at connect — set a `prefix` |
+| More tools listed than `maxTools` | `McpConnectionError` naming the count. `resolveIntegrations`' cap silently drops the overflow; this one refuses to serve two thirds of a server without saying so |
+| A `tools/call` fails, times out, is aborted, or the server goes away mid-session | `isError` tool_result (`McpCallError`'s message). The model sees it and the loop continues |
+| The server answers `isError: true` | Same — the error text reaches the model as an error, never as prose that reads like an answer |
+| An **attach-mode** resource's `resources/read` fails mid-session | `McpCallError` **thrown out of `send()`** during prompt assembly. There is no turn to degrade into: the prompt the model was going to see is the thing that could not be built |
+
+**Nothing waits forever.** Every round trip carries `timeoutMs` (default
+`DEFAULT_MCP_TIMEOUT_MS`, 60 s), covering both the fetch and the wait for the
+answer to arrive on an SSE body — a server that accepts a POST and then says
+nothing is a real failure mode and is otherwise indistinguishable from a hang.
+The default has to clear the slowest legitimate answer, and for MCP that is a
+tool that thinks (the in-repo a2ui server runs an LLM inside `tools/call`), so
+it is generous rather than handshake-sized; raise it per source for a slower
+server, or set `0` if you own the clock through `signal`. A timeout during
+connect throws; a timeout during a call reaches the model like any other call
+failure.
+
+**Abort is plumbed end to end.** `agent.send(session, text, { signal })` puts
+that signal on the turn's `ctx`, and an MCP `tools/call` or `resources/read`
+carries it to the wire — a user who cancels mid-answer cancels the server call
+instead of leaving it running and ignored. Aborting the turn that happens to
+be doing the connect cancels the handshake too; the signal does *not* stay
+attached to the resulting connection, so a later turn is unaffected.
+
+**Failures leave nothing open.** If a source fails after its handshake
+succeeded, its session is closed before the error propagates; if the second of
+two sources fails, the first one's session is closed too. `close()` during an
+in-flight connect wins — the late arrival closes what it opened and rejects
+with "the agent was closed while connecting" rather than quietly reinstalling
+itself. `close()` ends the sessions but does not spend the agent: a later
+`send()` reconnects.
+
+**Schemas pass through verbatim.** A server's JSON Schema reaches the model
+unmodified, including keywords `checkInput` cannot enforce. The server is the
+authoritative validator (its rejection returns as an error result), so a
+faithful copy of a contract someone else owns beats a locally-enforceable
+subset that describes the tool less accurately. The manifest states this with
+the new `IntegrationManifest.validation: 'remote'` rather than leaving it
+implied; `'local'` (the default, and every hand-declared integration) keeps
+the strict registration allowlist, because there the only validator is us.
+
+**Transport is streamable-HTTP, hand-rolled, no new dependency.**
+`@modelcontextprotocol/sdk` brings a server framework, stdio/websocket
+transports, an auth stack and zod for a client subset that is six JSON-RPC
+methods over one POST endpoint; this package stays dependency-free apart from
+`@adia-ai/llm`. The SDK still belongs in `packages/a2ui/mcp`, which *serves*.
+**stdio is not supported** — it needs a child process, so it is Node-only by
+construction and no in-repo consumer wants it; a `mcpServerStdio()` Node entry
+point is the shape to add if one does.
+
+**In a browser, the server must be reachable by `fetch`** — meaning it sends
+CORS headers for your origin, or you put it behind the same proxy you already
+route `@adia-ai/llm` through (`proxyUrl`) and point `url` at that path. This
+package deliberately ships no proxy: a server-side pass-through is the host
+app's, and forwarding `mcp-session-id` and `mcp-protocol-version` both ways is
+all it has to do. `fetchImpl` is the injection seam (tests use it for the
+in-process server; a host can use it to route through its own client). The
+in-repo `packages/a2ui/mcp` server sends no CORS headers today, so reaching
+it from a page means proxying it; from Node it works directly.
+
+### MCP resources, and the gh#671 ruling
+
+A server's resources map onto the two existing modes and **no new one**:
+
+- **`tool` (default)** — the harness cannot know which of a remote server's
+  resources belong in every prompt, and attaching all of them grows the
+  system prompt without bound. So each becomes a `read_<name>` tool.
+- **`attach`** — the APP promotes specific resources by name or URI
+  (`attach: ['style-guide']`), and those are fetched and inlined every turn.
+
+That is exactly MCP's own application-controlled vs. model-controlled
+distinction, expressed with the modes the harness already has.
+
+[gh#671](https://github.com/adiahealth/gen-ui-kit/issues/671) asked whether
+engine-internal retrieval (zettel and free-form reading corpus content on
+their own schedule inside a workflow step's `run`) needs a third mode —
+`'internal'`. **Ruled no, and W3 did not need one either.** A resource mode
+is a declaration of *who invokes it and when*, and both existing modes name a
+party the harness mediates: `attach` = the harness fetches, `tool` = the model
+asks. `'internal'` would name "engine code, whenever it likes", which is not
+a mediation — it is a function call. Declaring it would put into the resource
+contract a thing the model can never call and the harness never fetches,
+buying nothing but a second way to spell `await`. The two things the issue
+actually wanted are already contracts: the dependency is declared through
+**`services`** (W2), and the invocation is visible through **`ctx.trace`** in
+the `workflow` phase. Server-pushed MCP resources do not need it either —
+every read is either app-scheduled or model-asked.
+
+**Everything a server returns is DATA.** A tool description, a resource body,
+an error string — a description that reads like an instruction is still a
+description. It lands in the tool spec or inside a `<resource>` envelope and
+decides nothing about what the harness does. Guardrails are how you constrain
+what a remote tool may actually do.
+
+## Guardrails
+
+The deterministic layer between the model and the world — code that runs
+outside the model's context and cannot be talked past. Declared once at
+`createAgent`, two attach points, both optional:
+
+```js
+import { defineGuardrail } from '@adia-ai/agent';
+
+createAgent({
+  llm: { … },
+  guardrails: [
+    defineGuardrail({
+      name: 'scope-to-tenant',
+      // Before the call executes: allow (or return nothing), rewrite, deny.
+      toolCall: (call, ctx) => ({ action: 'rewrite', input: { ...call.input, tenantId } }),
+    }),
+    defineGuardrail({
+      name: 'redact',
+      // On the model's completed text for the round.
+      output: (text) => ({ action: 'rewrite', text: text.replace(SSN, '[redacted]') }),
+    }),
+  ],
+});
+```
+
+Guardrails run in declaration order and chain: a rewrite feeds the next one,
+the first `deny` short-circuits.
+
+- **Tool-call deny** → the model gets an `isError` tool_result naming the
+  guardrail and its reason, and the loop continues. Nothing executes.
+- **Output deny** → the turn ends with no assistant text and
+  `stopReason: 'guardrail_denied'`; the reason rides the `guardrail` event.
+- **Output rewrite** → the rewritten text is what `done` carries and what the
+  transcript keeps. A final `{ text: '', snapshot: <rewritten> }` event
+  follows, and a denial sends `{ text: '', snapshot: '' }`.
+  **A UI that folds `text` events by APPENDING the delta must treat an empty
+  delta as a replace from `snapshot`, or it will keep showing the original
+  while the transcript says otherwise** — `web-modules/chat`'s
+  `wireAgentEvents` does exactly this via `chatShell.setStreamedText()`.
+
+Two scope limits worth knowing before you rely on the output chain:
+
+- **Output guardrails see the text of the round that ENDS the turn.** Text
+  from a round that also called tools is intermediate reasoning the model
+  supersedes, and denying it has no coherent answer for the tool calls
+  emitted beside it — so it passes through unguarded and reaches the
+  transcript. Put the check on `toolCall` if what matters is what the model
+  is about to DO.
+- **A guardrail may `ctx.remember(patch)`** — it receives the same context a
+  tool does. The write is drained as a `memory` event before `done`, never
+  dropped.
+
+`onToolCall` is now exactly one guardrail of the `toolCall` kind: it still
+works, still denies with its original wording, and runs ahead of the declared
+chain.
+
+A guardrail decides from the call and the harness's own context. Text
+produced by a model, a tool, or a resource is DATA — a guardrail that lets
+such text talk it into allowing something is not a guardrail.
+
+## Tracing
+
+Off by default. `trace: true` uses the console sink; a function IS the sink.
+Every record is also a `trace` event on the stream:
+
+```js
+const agent = createAgent({ llm: { … }, trace: (record) => myLogger.debug(record) });
+// { phase, name, at, sessionId?, data? }
+```
+
+`phase` is the closed vocabulary (`TRACE_PHASES`, guarded by
+`isTracePhase()`): `prompt` (assembly: layer count, cached blocks, chars),
+`request` / `response` (per provider call: round, model, tool count, stop
+reason, ms), `tool` (per execution: name, id, ms, isError), `workflow`
+(`step:start` / `step:verdict` with the verdict reason), `guardrail` (each
+non-allow decision), `usage` (the turn's token totals), `mcp` (`connect` /
+`connect:failed` per source — a tool a server contributed then executes
+under `tool` like any other). A sink that throws
+warns and the turn continues. There is no exporter protocol and no
+dependency — an OpenTelemetry bridge is a caller-side function.
+
+## Session memory
+
+Per-session, JSON-safe, and written ONLY through `reduce()` — the same
+single-writer rule the messages obey:
+
+```js
+import { remember } from '@adia-ai/agent';
+
+session = reduce(session, remember({ patientId: 'p_7', tone: 'brief' }));
+session.memory;                                  // { patientId: 'p_7', tone: 'brief' }
+session = reduce(session, remember({ tone: null }));   // null deletes the key
+```
+
+A tool writes by ASKING: `ctx.remember(patch)` queues the patch, and the loop
+yields it as a `memory` event right after that tool's result — and drains
+anything still queued before `done`, so a final-round tool's write (or a
+guardrail's, which shares the context) is never dropped. The asker never
+touches state.
+
+A patch that would not survive `JSON.stringify` → `JSON.parse` unchanged (a
+Date, a function, `undefined`, a class instance) throws at the write, naming
+the path. Memory rides the Session through `toJSON`/`fromJSON`; **where that
+JSON is stored stays the caller's** — cross-session persistence is a seam
+this package deliberately does not implement.
+
 ## Byte-identity baseline (CHAT-HARNESS law 2)
 
 Every axis on `AgentConfig` is optional, and absence must produce a
@@ -170,3 +537,9 @@ like any other pinned contract.
 `scriptClient(turns)` is a deterministic `LLMClient`: script `[{text, toolUse}]`
 turns and drive the whole loop keylessly. It also records every `ChatOpts` it
 was called with (`client.calls`) so tests can assert what reached the wire.
+
+`mcp-fixture.mjs`'s `createTestMcpServer({ tools, resources, … })` is the
+same idea for MCP: an in-process server behind a `fetch`-shaped function
+(`fetchImpl`), speaking real JSON-RPC with session headers, cursor
+pagination, `isError` results, and either a JSON or an SSE response body —
+no network, no ports, no SDK.

package/agent.d.ts

@@ -15,7 +15,10 @@ import { type ResourceDef } from './resource.js';
 import { type Session } from './session.js';
 import type { AgentEvent } from './events.js';
 import { type ClientMessage } from './frame.js';
+import { type Guardrail } from './guardrail.js';
+import { type McpServerReport, type McpSource } from './mcp.js';
 import type { ToolContext, ToolDef } from './tools.js';
+import { type TraceConfig } from './trace.js';
 import { type Workflow, type WorkflowResult } from './workflow.js';
 export interface AgentConfig {
     /** Client defaults (model, proxyUrl, apiKey…) handed to createClient(),
@@ -31,12 +34,38 @@ export interface AgentConfig {
     workflows?: Array<Workflow<never, never>> | Workflow[];
     resources?: ResourceDef[];
     maxToolRounds?: number;
-    /** Gate every tool call; false denies it (isError feedback, loop continues). */
+    /** Gate every tool call; false denies it (isError feedback, loop continues).
+     *  Superseded by `guardrails` — this is now adapted into exactly one
+     *  guardrail of the `toolCall` kind and runs FIRST, ahead of the declared
+     *  chain. Kept because it is the v0 seam consumers already call. */
     onToolCall?: (call: ToolUse, ctx: ToolContext) => boolean | Promise<boolean>;
+    /** The deterministic layer between the model and the world: veto or
+     *  rewrite tool calls and model output (see guardrail.ts). */
+    guardrails?: Guardrail[];
+    /** Structured tracing: `true` → the console sink, a function → that sink.
+     *  Absent → no trace events, no console output, no request difference. */
+    trace?: TraceConfig;
+    /** Dependencies every workflow run may USE (llmAdapter, clients, stores).
+     *  Reaches steps as `ctx.services`, merged with per-run services. */
+    services?: Record<string, unknown>;
+    /** External sources whose tools and resources join the declared ones —
+     *  today, MCP servers (`mcpServer({ url })`). Connected LAZILY on the
+     *  first turn and memoized, because `createAgent` is synchronous and a
+     *  constructor that reaches the network is a constructor that can fail.
+     *  Call `agent.connect()` to do it eagerly and inspect the result. */
+    integrations?: McpSource[];
 }
 export interface SendOpts {
     signal?: AbortSignal;
 }
+/** `agent.run`'s options — the fourth argument may still be a bare
+ *  `onEvent` function (the v0 shape). */
+export interface RunOpts {
+    onEvent?: (event: AgentEvent) => void;
+    /** Per-run dependencies, merged over `AgentConfig.services`. */
+    services?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
 export interface Agent {
     createSession(id?: string): Session;
     send(session: Session, text: string, opts?: SendOpts): AsyncGenerator<AgentEvent>;
@@ -45,9 +74,21 @@ export interface Agent {
      *  A silent-apply message (shouldRunTurn ⇒ false) yields nothing and
      *  never touches the loop — the caller already applied it directly. */
     sendClientMessage(session: Session, msg: ClientMessage, opts?: SendOpts): AsyncGenerator<AgentEvent>;
-    run<TResult = unknown>(session: Session, workflowName: string, input?: unknown, onEvent?: (event: AgentEvent) => void): Promise<WorkflowResult<TResult>>;
-    /** The assembled tool set (declared + tool-mode resources) — inspectable. */
+    run<TResult = unknown>(session: Session, workflowName: string, input?: unknown, opts?: RunOpts | ((event: AgentEvent) => void)): Promise<WorkflowResult<TResult>>;
+    /** The assembled tool set — declared tools, tool-mode resources, and (once
+     *  the sources have connected) everything MCP contributed. Before the
+     *  first turn or an explicit `connect()`, it is the declared set. */
     tools: ToolDef[];
+    /** Connect the declared `integrations` now and report what each server
+     *  offered. Idempotent and memoized: the turn loop awaits the same
+     *  promise. Rejects with `McpConnectionError` when a server is
+     *  unreachable, mis-speaks the protocol, or collides with a declared tool
+     *  name — never resolves to a quietly empty tool list. */
+    connect(): Promise<McpServerReport[]>;
+    /** Close every MCP session (best effort). A Node process that exits
+     *  without it leaves sessions the server times out on its own; a browser
+     *  page unload is the same. */
+    close(): Promise<void>;
 }
 export declare function createAgent(config: AgentConfig): Agent;
 //# sourceMappingURL=agent.d.ts.map

package/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAYjE,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAe,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAIhF,MAAM,WAAW,WAAW;IAC1B;;8EAE0E;IAC1E,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;IACvD,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAClF;;;2EAGuE;IACvE,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACrG,GAAG,CAAC,OAAO,GAAG,OAAO,EACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GACpC,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,6EAA6E;IAC7E,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAgFtD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["src/agent.ts"],"names":[],"mappings":"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"}