@zackbart/connecta 0.10.4 → 0.10.6

package/documentation/rich-output-design.md

@@ -0,0 +1,212 @@
+# Rich MCP output from programs — design record
+
+The decision record for [#267](https://github.com/zackbart/connecta/issues/267):
+whether and how an `execute_code` program may deliver MCP-native output — text,
+images, audio — instead of only a single JSON return value. The verdicts live in
+[`ethos.md`](../ethos.md); this document carries the argument, the contract
+precisely enough to implement, and the shapes that were considered and refused.
+The implementation landed via
+[#270](https://github.com/zackbart/connecta/issues/270): the contract clauses
+below (`M1`–`M10`) are now normative in [`code-mode.md`](./code-mode.md)'s
+"Emitted output" section, which wins where the two disagree. This document
+remains the argument and the record of rejected shapes.
+
+## The problem
+
+A program returns one JSON value, bounded at 24,000 serialized characters
+(`R2`). That is the right contract for data: compose, project, return only what
+you need. It is no contract at all for an image. Base64 is not projectable — a
+program cannot "return less" of a screenshot — so any rich block a downstream
+tool produces dies at the exit guard, converted to a truncation envelope whose
+preview is the head of a base64 string, which is of use to no one.
+
+The asymmetry is already visible in the classic surface. `call_tool` forwards
+non-text downstream blocks to the client untouched when they fit the result cap
+(the fix for issue #43 made the guard measure every block, then pass them
+through in original order). And on the intake side, a host call **inside** a
+program is not size-capped at all: `unwrapMcpResult` hands mixed content
+through as a raw object, base64 and all. So today a downstream image survives
+the trip *into* the sandbox and survives the classic surface entirely — the one
+place it cannot survive is the exit of the surface connecta calls primary.
+
+## The shape: `connecta.emit(block)`
+
+One new provider function. A program emits zero or more validated MCP content
+blocks during its run; the host collects them request-locally and appends them
+to the final `execute_code` result, after the JSON envelope, in emission order.
+
+The single most load-bearing fact about this shape: **it does not touch the
+executor contract.** `Executor.execute()` still returns
+`{ result, error?, logs? }`, which is what keeps the interface structurally
+compatible with `DynamicWorkerExecutor` from `@cloudflare/codemode` — a class
+connecta does not control and must not fork. `emit` is a provider function like
+`connecta.call`: both executors already bridge provider calls (QuickJS over
+child-process IPC, the Dynamic Worker over isolate RPC), so emitted bytes cross
+the guest boundary exactly once, as an argument, and are never seen again by
+the sandbox, the `ExecuteResult`, or the `R2` guard. Executor parity is not a
+test obligation bolted on afterward; it is structural. A third-party executor
+that correctly bridges provider functions gets emission without writing a line.
+
+### Contract (drafts for code-mode.md)
+
+**M1.** `connecta.emit(block)` accepts exactly one MCP content block of type
+`text`, `image`, or `audio`:
+
+```
+{ type: "text",  text: string }
+{ type: "image", data: string /* base64 */, mimeType: string }
+{ type: "audio", data: string /* base64 */, mimeType: string }
+```
+
+The shape is validated strictly at the call — required fields present, no
+extra fields, no `annotations`, no `_meta`. An invalid block throws a
+catchable error and nothing is accepted. Rejected, not stripped: silently
+deleting fields would deliver something the program did not ask to emit.
+There is no sugar form (`emit("text")` is invalid); sugar is how a
+one-shape contract grows hair.
+
+**M2.** Emitted blocks are collected on the host in emission order and
+delivered only with a successful result: the response's `content` array is the
+JSON envelope text block first, then the emitted blocks. When at least one
+block was emitted the envelope gains `emitted: N`; when none were, the
+response is byte-for-byte the ordinary path (the `R6` discipline).
+`structuredContent` remains the JSON envelope alone — emission is a
+presentation channel, not a second data channel.
+
+**M3.** The return value and emission are independent. `R2` applies to the
+return value exactly as before and never measures emitted bytes; a truncated
+return value does not suppress emitted blocks, and emitted blocks do not
+shrink the return budget.
+
+**M4.** A program that ends in an error delivers no emitted blocks. The error
+envelope reports `emittedDiscarded: N` when N > 0, so the discard is visible
+rather than silent. Partial rich output from a failed program is ambiguity,
+not a deliverable.
+
+**M5.** Two budgets, both deployment-configurable, both failing loudly at the
+`emit` call: an aggregate serialized-byte budget (default 4,000,000 bytes) and
+a block count (default 32). An emit that would exceed either throws a
+catchable error naming the budget and the room remaining; the block is not
+partially accepted, and prior accepted blocks are unaffected. There is no
+`get_result` stash and no paging: the program learns it is over budget while
+it can still choose differently, which is `R4`'s spirit applied to bytes that
+genuinely cannot be shrunk — refuse at the door instead of paging after the
+fact.
+
+**M6.** Connecta claims no provenance. Every emitted block is program output,
+trusted exactly as much as the program's return value — no more because its
+bytes happen to have come from a downstream call, no less because they were
+assembled in the sandbox. Preserving a downstream image means re-emitting it:
+the program selects the block from the raw downstream result (which reaches it
+uncapped) and emits it. The host attaches no attribution.
+
+**M7.** `emit` does not spend the host-call budget (`L4`). Its bounds are
+`M5`'s and only `M5`'s.
+
+**M8.** `ExecuteResult` is unchanged. No executor — QuickJS, Dynamic Worker,
+or third-party — needs modification, and the parity suite runs the same
+emitting program through both vitest projects and asserts identical delivered
+content.
+
+**M9.** Emission is request-local and unstreamed. Blocks exist only in the
+finished response; nothing is pushed early, nothing survives the request, and
+`emit` resolving means "accepted into the collection," never "delivered."
+
+**M10.** Activity remains payload-free by construction. With
+`diagnostics: true` the diagnostics block gains one aggregate — emitted block
+count and serialized bytes — numbers only, per `R8`.
+
+### Intake, specified
+
+`unwrapMcpResult`'s current behavior becomes contract rather than accident: an
+all-text downstream result is JSON-parsed when possible (as today), and a
+result carrying non-text blocks passes through as the raw object, `content`
+array intact, uncapped. That raw fallthrough is the preservation path `M6`
+depends on. Bounding it would kill re-emission at intake; projecting it would
+repeat the mistake `R1` refuses.
+
+## Sizing rationale
+
+The 24,000-character return boundary is a *context* budget — the return value
+lands in the model's window as text. Emitted image and audio blocks do not:
+MCP-aware hosts deliver them as media, which models ingest at media prices,
+not base64-text prices. So the emission budget is a *transport* bound, not a
+context bound, and 4,000,000 serialized bytes (roughly a 3 MB binary after
+base64's 4/3 inflation — two or three real screenshots) is deliberately far
+above `R2` without being a file-hosting ambition. Deployments that know their
+client's limits tune it; the default just has to make `emit` useful for the
+motivating case without inviting anyone to ship video through an MCP response.
+
+## Security posture
+
+- **Nothing is minted.** `emit` grants no authority: it cannot cause a fetch,
+  reference a credential, or make the host serve anything. It moves bytes the
+  program already had into the response.
+- **Strict typing is the lure defense.** The block validator accepting only
+  `text`, `image`, and `audio` is what keeps a program from emitting a
+  `resource_link` whose URI a helpful client might dereference. The refused
+  types are refused precisely because they are pointers, and pointers get
+  followed.
+- **Image-borne injection is the existing class.** A downstream screenshot
+  containing hostile text is the same hazard through `emit` as through
+  `call_tool`'s block passthrough today; connecta's posture is unchanged — all
+  tool output is untrusted input to the client, and connecta adds no claim
+  otherwise.
+
+## Considered and refused
+
+**A sentinel return shape** (`return { $mcpContent: [...] }`). Overloads the
+one data channel with a magic key that collides with honest data, subjects
+rich blocks to the `R2` guard they cannot survive, and turns "what did this
+program return" into a parse question. The return value stays a value.
+
+**Widening `ExecuteResult` or the `Executor` interface.** The obvious place
+and the wrong one: the interface's value is that `@cloudflare/codemode`'s
+executor already satisfies it. A `content` field connecta added would either
+fork the Workers executor or wait on a vendor; and every third-party executor
+would need matching surgery. Refused as a class, not just deferred.
+
+**Provenance-preserving handles** (downstream blocks stay host-side; the guest
+gets `{ $ref }` tokens to pass to `emit`). Honest attribution, but it creates
+host-side object identity that generated code holds references to —
+capability-shaped machinery in the one place the ethos says generated code
+mints nothing. And the label buys nothing: no MCP client trusts a tool result
+more because an aggregator vouches for its lineage. Re-emission delivers the
+same bytes with a simpler story: everything a program emits is program output.
+
+**`resource` and `resource_link` emission.** Connecta already refuses to
+aggregate resources; letting programs emit them would introduce through the
+back door a surface the front door refused, and a guest-minted URI is a lure
+(see the posture above). A future argument would have to be a new one.
+
+**A `get_result` stash for over-budget emissions.** Paging exists for
+downstream payloads a model could not shrink; an over-budget emission is a
+program decision that has not happened yet. Failing the `emit` call while the
+program can still adapt beats stashing megabytes nobody may page.
+
+**Streaming or partial delivery.** Standing invariant — no server push,
+nothing request-bound survives the request. Emission is collect-then-deliver
+by construction (`M9`).
+
+**Delivering emissions from failed programs.** The blocks may describe a world
+the error contradicts. Failure delivers the error, the logs, and an honest
+count of what was discarded (`M4`).
+
+## Verification sketch
+
+- Parity: one emitting program, both vitest projects (`WORKERS_SUITES`),
+  identical delivered content arrays.
+- Validation: each rejected shape (missing field, extra field, `annotations`,
+  unknown type, bare string) throws catchably and accepts nothing.
+- Budgets: byte and count budgets fail at the crossing call, prior blocks
+  intact; error names the budget.
+- Independence: over-`R2` return value + emitted blocks → truncation envelope
+  *and* delivered blocks in one response.
+- Discard: throwing program with prior emits → error envelope with
+  `emittedDiscarded`, no blocks in `content`.
+- Byte-for-byte: a program that never emits produces today's exact response.
+
+The implementation issue carries these as acceptance criteria; the clauses
+fold into `code-mode.md` under a new "Emitted output" section when it closes,
+and the test-map row in [`operations.md`](./operations.md) lands with the
+suite.

package/ethos.md

@@ -18,13 +18,15 @@ order, and amending it is a design decision, not a drive-by edit.
 - **Two equal ways in.** `remoteMcp()` proxies a downstream MCP server;
   `api()` hand-writes a deliberate tool surface over a plain HTTP API. Both
   come out identical: same addresses, same catalog, same safety rules.
-- **Every meta-tool earns its keep**, and the bar has gone up. The default
-  answer to "agents need X" is the program surface: a capability has to be
-  shown inexpressible through it before it earns a top-level tool, and one
-  that isn't worth its context cost still goes. Seven tools counting
-  `execute_code` where a deployment has an executor, which is what a model
-  sees by default; nine where it doesn't
-  ([#224](https://github.com/zackbart/connecta/issues/224)).
+- **Seven tools, an executor required.** The primary surface is a program, so
+  every deployment runs an executor — a Dynamic Worker on Cloudflare, QuickJS
+  behind its optional-peer subpath on Node — and one without refuses to boot
+  ([#273](https://github.com/zackbart/connecta/issues/273)). Every meta-tool
+  earns its keep: the default answer to "agents need X" is the program
+  surface, and a capability has to be shown inexpressible through it before
+  it earns a top-level tool
+  ([#224](https://github.com/zackbart/connecta/issues/224)). Packaging is
+  unchanged: required describes the deployment, never the dependencies.
 - **Safe by default.** Only tools explicitly annotated read-only are callable
   without crossing the destructive boundary — directly or from generated code;
   everything else goes through `call_destructive_tool`, where the MCP host can
@@ -33,12 +35,6 @@ order, and amending it is a design decision, not a drive-by edit.
 - **One fetch-native core, two runtimes.** The same code runs unchanged on
   Cloudflare Workers and in Node — a Worker or a Docker stack, your pick. Web
   APIs only in the core; Node touches live behind explicit subpaths.
-- **An executor is the assumed posture.** The primary surface is a program, so
-  the deployment connecta is written toward has one — a Dynamic Worker on
-  Cloudflare, QuickJS behind its optional-peer subpath on Node. Configuring one
-  is what selects the code-first surface; executor-free stays supported as
-  compatibility, not as an equal citizen. Packaging is unchanged: assumed is
-  about defaults, never about dependencies.
 - **Observable, never administrable.** Operator pages show connector status,
   masked credentials, and payload-free activity. They can rotate a secret;
   they cannot add a connector, change policy, or alter what an agent can call.
@@ -79,12 +75,10 @@ proposing one without a new argument is not.
 | Agent credential recovery | accepted | one `auth_required` route through `authorize_connector`; only an operator handles secrets ([#192](https://github.com/zackbart/connecta/issues/192)) |
 | Operator-issued MCP access tokens | accepted | named, revocable authentication gives header-capable clients a small alternative to OAuth; tokens identify callers but never scope tools or become operator credentials |
 | Structured result surface | accepted | canonical `structuredContent` plus complete compact `content`; summary-only text is gated on host-forwarding evidence ([#191](https://github.com/zackbart/connecta/issues/191)) |
-| Code mode (`execute_code`) | accepted | the primary read, discovery, and composition surface: smaller serialized definitions (the exploration estimated ~32%, the shipped fold measures 19.6% — see the consolidation row), far smaller results once composition and projection happen before the model sees them, and a cold-start model that read the interface without help ([exploration](./documentation/code-first-exploration.md)) |
-| Code-first as the user-facing default | accepted | owner decision, 2026-07-30: "we don't need a deploy time flip, I'm the only one who uses it… We already decided it's good let's just do it." One operator, one deployment, and the exploration plus the smoke runs were enough judgment for him; the gate below was written for a user base connecta does not have ([#224](https://github.com/zackbart/connecta/issues/224)) |
-| The repeated per-model eval as the flip's gate | removed | it decided a question the owner has now decided himself; [`eval/code-first-gate`](./eval/code-first-gate/README.md) remains as measurement — the arms are real deployment shapes and it still reports which surface performs — but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222)) |
-| Surface consolidation to seven tools | accepted | folding `list_connectors`, `describe_tools`, and `batch_call` into the program surface deletes the overlapping routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code. Measured at 19.6% fewer serialized definition bytes than the ten-tool shape the same deployment used to serve (10,675B → 8,587B), correcting the exploration's ~32% ([#224](https://github.com/zackbart/connecta/issues/224)) |
-| Executor-assumed posture | accepted | the primary surface is a program, so a deployment without an executor can only ever be the compatibility shape; packaging invariants are untouched ([#224](https://github.com/zackbart/connecta/issues/224)) |
-| Classic surface retention | accepted | what an executor-free deployment necessarily serves, the rollback path, and the eval's control arm; `surface: "classic"` alongside an executor is the only knob, and whether classic is ever removed is a separate future decision ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| Code mode (`execute_code`) | accepted | the primary read, discovery, and composition surface: smaller serialized definitions, far smaller results once composition and projection happen before the model sees them, and a cold-start model that read the interface without help ([exploration](./documentation/code-first-exploration.md), [#224](https://github.com/zackbart/connecta/issues/224)) |
+| Code-first as the default; the eval gate retired | accepted | owner decision, 2026-07-30: one operator, no deploy-time flip; [`eval/code-first-gate`](./eval/code-first-gate/README.md) survives as measurement, but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222), [#224](https://github.com/zackbart/connecta/issues/224)) |
+| Surface consolidation to seven tools | accepted | `list_connectors`, `describe_tools`, and `batch_call` fold into the program surface, deleting the routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| Classic (executor-free) surface | removed | supersedes its provisional retention under [#224](https://github.com/zackbart/connecta/issues/224) — an executor is mandatory, and a deployment without one refuses to boot rather than serving a fallback shape ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Connector shortcut namespaces in programs | accepted | sugar over canonical addressing, kept but frozen — every expansion invents a collision class `<connectorId>.<toolName>` already solved ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Automatic host-side projection of program results | refused | the measured win was program-authored projection; a host heuristic drops fields a program chose to return and is invisible in the transcript ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Caller-visible execution diagnostics | accepted | optional request-local timing and size aggregates make catalog, connector, and executor costs distinguishable without persisting payloads, adding a tool, or charging normal responses context ([#247](https://github.com/zackbart/connecta/issues/247)) |
@@ -94,6 +88,10 @@ proposing one without a new argument is not.
 | MRTR / `input_required` passthrough | gated | statelessly relayable via `requestState`, but no host or downstream emits it yet; fails loudly until adoption evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size; paging on a polling extension adds round trips for nothing ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | fixed TTL + fingerprint is battle-tested and catalog reads are ~3 ms; earns its way in with refresh-churn evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
+| Rich program output (`connecta.emit`) | accepted | one host-collected emission channel: programs emit strictly validated text/image/audio blocks, delivered after the result envelope on success only; budgets fail loudly at the emit call ([design record](./documentation/rich-output-design.md), [#267](https://github.com/zackbart/connecta/issues/267)) |
+| Result-channel widening of the `Executor` contract | refused | `ExecuteResult` stays `{ result, error?, logs? }` — structural compatibility with `@cloudflare/codemode` is the parity guarantee; emission rides the provider bridge instead ([#267](https://github.com/zackbart/connecta/issues/267)) |
+| Guest-emitted `resource` / `resource_link` blocks | gated | a program can never mint a URI a client may dereference; MCP UI ([#266](https://github.com/zackbart/connecta/issues/266)) may design the one carve-out — programs supply only content, connecta mints the `ui://` address outside the sandbox ([#267](https://github.com/zackbart/connecta/issues/267)) |
+| Provenance tracking for emitted content | refused | everything a program emits is program output; handles or attribution labels are capability-shaped machinery that changes no client's trust posture ([#267](https://github.com/zackbart/connecta/issues/267)) |
 
 ## Invariants
 

package/examples/worker/README.md

@@ -111,6 +111,7 @@ into `src/index.ts`**, so the example deploys without a database. To enable it:
      duration_ms    INTEGER NOT NULL,
      attempts       INTEGER NOT NULL,
      error_code     TEXT,
+     friction       TEXT,
      server_name    TEXT NOT NULL,
      server_version TEXT NOT NULL,
      deployment_id  TEXT
@@ -120,14 +121,21 @@ into `src/index.ts`**, so the example deploys without a database. To enable it:
      ON tool_call_activity (occurred_at_ms DESC, id DESC);
    ```
 
-   **Already have this table?** `actor_namespace` was added after the original
-   example, and `CREATE TABLE IF NOT EXISTS` will not add it to a table that
-   already exists. Add it as a migration:
+   **Already have this table?** `actor_namespace` and `friction` were added
+   after the original example, and `CREATE TABLE IF NOT EXISTS` will not add
+   them to a table that already exists. Add them as migrations:
 
    ```sql
    ALTER TABLE tool_call_activity ADD COLUMN actor_namespace TEXT;
+   ALTER TABLE tool_call_activity ADD COLUMN friction TEXT;
    ```
 
+   `friction` is stored rather than derived because one of its classes belongs
+   to a call that *succeeded*: a result too large to return inline is friction
+   for the agent and carries no error code. Rows written before the column keep
+   working — the mapping module derives their friction from `error_code` — and
+   `error_code IS NOT NULL` remains an honest count of failures.
+
    Do this **before** deploying the updated `d1-activity.ts`: its `INSERT`
    names the column, so against an un-migrated table every write fails with
    `no such column`. Activity writes are best-effort by design — connecta logs

package/examples/worker/src/d1-activity-row.ts

@@ -23,11 +23,44 @@ export interface ActivityEvent {
   durationMs: number;
   attempts: number;
   errorCode?: string;
+  friction?:
+    | "tool_not_found"
+    | "schema_retry"
+    | "destructive_reroute"
+    | "auth_required"
+    | "result_too_large";
   serverName: string;
   serverVersion: string;
   deploymentId?: string;
 }
 
+/**
+ * Backfill for rows written before `friction` had a column of its own. Every
+ * arm must agree with the package's own `agentFrictionForCode`; the repository
+ * test suite pins that, because a dashboard that groups by friction should not
+ * change its answer depending on which side of a migration a row landed on.
+ * Friction that never had an error code — an oversized but successful result —
+ * is only recoverable from the column, which is why the column exists.
+ */
+function frictionForCode(code: string | null): ActivityEvent["friction"] {
+  switch (code) {
+    case "unknown_address":
+    case "unknown_tool":
+    case "ambiguous_tool_alias":
+      return "tool_not_found";
+    case "invalid_args":
+      return "schema_retry";
+    case "destructive_tool_requires_approval":
+      return "destructive_reroute";
+    case "auth_required":
+      return "auth_required";
+    case "result_too_large":
+      return "result_too_large";
+    default:
+      return undefined;
+  }
+}
+
 export interface ActivityRow {
   id: string;
   occurred_at_ms: number;
@@ -42,6 +75,7 @@ export interface ActivityRow {
   duration_ms: number;
   attempts: number;
   error_code: string | null;
+  friction: ActivityEvent["friction"] | null;
   server_name: string;
   server_version: string;
   deployment_id: string | null;
@@ -64,6 +98,10 @@ export function activityEventToRow(
     duration_ms: event.durationMs,
     attempts: event.attempts,
     error_code: event.errorCode ?? null,
+    // Stored beside the code rather than derived from it: a truncated result is
+    // friction on a call that succeeded, so it has no error code to derive from
+    // — and `error_code IS NOT NULL` stays an honest count of failures.
+    friction: event.friction ?? null,
     server_name: event.serverName,
     server_version: event.serverVersion,
     deployment_id: event.deploymentId ?? null,
@@ -73,6 +111,7 @@ export function activityEventToRow(
 export function activityRowToEvent(
   row: ActivityRow,
 ): ActivityEvent {
+  const friction = row.friction ?? frictionForCode(row.error_code);
   return {
     schemaVersion: 1,
     id: row.id,
@@ -91,6 +130,7 @@ export function activityRowToEvent(
     durationMs: row.duration_ms,
     attempts: row.attempts,
     ...(row.error_code ? { errorCode: row.error_code } : {}),
+    ...(friction ? { friction } : {}),
     serverName: row.server_name,
     serverVersion: row.server_version,
     ...(row.deployment_id

package/examples/worker/src/d1-activity.ts

@@ -50,8 +50,8 @@ export function d1ActivityStore(db: D1Database): ActivityStore {
             id, occurred_at_ms, request_id, actor_kind, actor_id,
             actor_namespace,
             connector_id, tool_name, source, outcome, duration_ms, attempts,
-            error_code, server_name, server_version, deployment_id
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            error_code, friction, server_name, server_version, deployment_id
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         )
         .bind(
           row.id,
@@ -67,6 +67,7 @@ export function d1ActivityStore(db: D1Database): ActivityStore {
           row.duration_ms,
           row.attempts,
           row.error_code,
+          row.friction ?? null,
           row.server_name,
           row.server_version,
           row.deployment_id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/src/activity.ts

@@ -1,5 +1,25 @@
+import { boundedEchoText } from "./errors.js";
 import type { Logger } from "./types.js";
 
+/**
+ * How long an identity field may be before the store stops believing it.
+ *
+ * `connectorId` and `toolName` are ordinarily operator- and connector-authored,
+ * and 128 bytes is far past any real one. But an address that resolved to
+ * nothing is recorded *as written*, which puts a caller-authored string in both
+ * fields — and "payload-free by construction" has to mean the event type has
+ * nowhere to put a payload, not merely that connecta declines to. A 40 KB
+ * invented connector id is a payload wearing an id's clothing.
+ *
+ * Clamped rather than dropped: the invented id is precisely what an operator
+ * needs to see, and its first 128 bytes identify the mistake as well as all
+ * 40,000 would. The `…` marker keeps a clamped value from reading as a real one.
+ */
+const MAX_ACTIVITY_NAME_BYTES = 128;
+
+/** Two names and the dot between them. */
+const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
+
 export type ActivityCallSource =
   | "call_tool"
   | "call_destructive_tool"
@@ -12,6 +32,35 @@ export type ActivityOutcome =
   | "timeout"
   | "cancelled";
 
+export type AgentFriction =
+  | "tool_not_found"
+  | "schema_retry"
+  | "destructive_reroute"
+  | "auth_required"
+  | "result_too_large";
+
+/** Coarse recovery class derived without inspecting payloads or error prose. */
+export function agentFrictionForCode(
+  code: string | undefined,
+): AgentFriction | undefined {
+  switch (code) {
+    case "unknown_address":
+    case "unknown_tool":
+    case "ambiguous_tool_alias":
+      return "tool_not_found";
+    case "invalid_args":
+      return "schema_retry";
+    case "destructive_tool_requires_approval":
+      return "destructive_reroute";
+    case "auth_required":
+      return "auth_required";
+    case "result_too_large":
+      return "result_too_large";
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Authenticated identity attached to an activity event. `id` is intentionally
  * optional: open deployments and shared bearer tokens cannot honestly identify
@@ -48,7 +97,14 @@ export interface ToolCallActivityEvent {
   outcome: ActivityOutcome;
   durationMs: number;
   attempts: number;
+  /** Set only when the call actually failed; a truncated success has none. */
   errorCode?: string;
+  /**
+   * Payload-free recovery class. Usually derived from `errorCode`, but it can
+   * also stand alone: a result too large to return inline is friction for the
+   * agent while remaining an `outcome: "success"` call with no error code.
+   */
+  friction?: AgentFriction;
   serverName: string;
   serverVersion: string;
   deploymentId?: string;
@@ -121,6 +177,7 @@ export type ActivityEventInput = Pick<
   | "durationMs"
   | "attempts"
   | "errorCode"
+  | "friction"
 >;
 
 /**
@@ -133,20 +190,24 @@ export function recordToolActivity(
   input: ActivityEventInput,
 ): void {
   if (!context) return;
+  // A caller-supplied class wins because it knows something the code table
+  // cannot: friction that belongs to a call which did not fail.
+  const friction = input.friction ?? agentFrictionForCode(input.errorCode);
   const event: ToolCallActivityEvent = {
     schemaVersion: 1,
     id: crypto.randomUUID(),
     occurredAt: new Date().toISOString(),
     requestId: context.requestId,
     actor: context.actor,
-    connectorId: input.connectorId,
-    toolName: input.toolName,
-    address: input.address,
+    connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
+    toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
+    address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
     source: input.source,
     outcome: input.outcome,
     durationMs: Math.max(0, Math.trunc(input.durationMs)),
     attempts: Math.max(1, Math.trunc(input.attempts)),
     ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+    ...(friction ? { friction } : {}),
     serverName: context.serverInfo.name,
     serverVersion: context.serverInfo.version,
     ...(context.deploymentId