@zackbart/connecta 0.10.4 → 0.10.6

package/dist/skills.d.ts

@@ -10,7 +10,7 @@ export declare const CONNECTA_INSTRUCTIONS = "Connecta exposes integrations behi
  */
 export declare const CODE_FIRST_INSTRUCTIONS = "Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2\u20134 distinctive action/object terms and includeSchemas=\"compact\", then one call_tool \u2014 a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: \"usage\" }).";
 export declare const USAGE_SKILL = "# Connecta usage\n\n## Choose the smallest execution tool\n\nUse exact addresses returned by discovery; never invent one. Search with 2\u20134 distinctive action/object terms rather than the full request, and omit `limit` initially so the default page stays small.\n\n- Unknown address: `search_tools({ query, includeSchemas: \"compact\" })`; every match then includes its input shape plus any declared output shape and annotations.\n- Compact shape still ambiguous: `describe_tools({ addresses: [...] })`; use `format: \"json\"` only for exact constraints.\n- One explicitly read-only call: `call_tool`.\n- Two to ten independent explicitly read-only calls: `batch_call`.\n- Dependent read-only calls, loops, joins, branching, or large-result reduction: `execute_code` when available.\n- Any unannotated, write-capable, or destructive call: `call_destructive_tool`, individually and only after reviewing its schema and consequences.\n- Truncated result: retry with `fields` when possible; otherwise page it with `get_result`.\n- `auth_required`: use `authorize_connector`, give its recovery handoff to the operator, then retry the original call.\n\nUse `list_connectors({ probe: false })` for a fast observed-health inventory; use `probe: true` only to diagnose live health or authorization.\n\n## Code mode\n\nUnknown addresses plus dependent calls: search inside the run, not in an outer `search_tools`. Parallelize independent calls with `Promise.all` or `connecta.batch`.\n\nConnector namespace calls and `connecta.call` use the same read-only gate and throw on downstream errors. Catch only failures the workflow can handle; let authorization failures return to the agent for recovery.\n\nSkip code mode for one call, calls suited to `batch_call`, or tools lacking `readOnlyHint: true`. Return only the needed reduction.\n";
-export declare const CODE_FIRST_USAGE_SKILL = "# Connecta usage\n\n## The surface\n\nSeven tools: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills`. Broad discovery and multi-call work live inside a program rather than in top-level tools.\n\n## Choose the smallest execution tool\n\nUse exact addresses returned by discovery; never invent one. Search with 2\u20134 distinctive action/object terms rather than the full request.\n\n- One read at an unknown address: `search_tools({ query, includeSchemas: \"compact\" })`, then `call_tool` once. A lone cold call is cheaper direct than through a program.\n- Anything wider \u2014 two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one `execute_code` run.\n- Any unannotated, write-capable, or destructive call: `call_destructive_tool`, individually and only after reviewing its schema and consequences. Generated code cannot make one.\n- Truncated result: retry with `fields` when possible; otherwise page it with `get_result`.\n- `auth_required`: use `authorize_connector`, give its recovery handoff to the operator, then retry the original call.\n\n## Inside a program\n\nOne async arrow function. The only capabilities are one global per connector (`<connectorId>.<toolName>(args)`), the four `connecta` functions, and `console.log`.\n\n- What exists: `connecta.search({})` browses every catalog; add `safety: \"readOnly\"` for only calls the program can execute, and `connector: \"<id>\"` to browse one. This filters discovery results, not authority, and each match carries its `address` and annotations.\n- Exact schemas for known addresses: `connecta.describe({ addresses: [...] })`; `format: \"json\"` only for exact constraints.\n- Two to ten independent calls: `connecta.batch([...])`. Each outcome is `{ address, ok: true, data }` or `{ address, ok: false, error, errorDetails: { code, retryable } }`, which is also how a program tells a policy refusal from a transient failure.\n- Search inside the run rather than searching first, and return only the reduction the answer needs \u2014 never raw payloads.\n- Only tools annotated `readOnlyHint: true` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.\n";
+export declare const CODE_FIRST_USAGE_SKILL = "# Connecta usage\n\n## The surface\n\nSeven tools: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills`. Broad discovery and multi-call work live inside a program rather than in top-level tools.\n\n## Choose the smallest execution tool\n\nUse exact addresses returned by discovery; never invent one. Search with 2\u20134 distinctive action/object terms rather than the full request.\n\n- One read at an unknown address: `search_tools({ query, includeSchemas: \"compact\" })`, then `call_tool` once. A lone cold call is cheaper direct than through a program.\n- Anything wider \u2014 two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one `execute_code` run.\n- Any unannotated, write-capable, or destructive call: `call_destructive_tool`, individually and only after reviewing its schema and consequences. Generated code cannot make one.\n- Truncated result: retry with `fields` when possible; otherwise page it with `get_result`.\n- `auth_required`: use `authorize_connector`, give its recovery handoff to the operator, then retry the original call.\n\n## Inside a program\n\nOne async arrow function. The only capabilities are one global per connector (`<connectorId>.<toolName>(args)`), the four `connecta` functions, and `console.log`.\n\n- What exists: `connecta.search({})` browses every catalog; add `safety: \"readOnly\"` for only calls the program can execute, and `connector: \"<id>\"` to browse one. This filters discovery results, not authority, and each match carries its `address` and annotations.\n- Exact schemas for known addresses: `connecta.describe({ address: \"connector.tool\" })` for one or `connecta.describe({ addresses: [...] })` for many; `format: \"json\"` only for exact constraints.\n- Two to ten independent calls: `connecta.batch([...])`. Each outcome is `{ address, ok: true, data }` or `{ address, ok: false, error, errorDetails: { code, retryable } }`, which is also how a program tells a policy refusal from a transient failure.\n- Search inside the run rather than searching first, and return only the reduction the answer needs \u2014 never raw payloads.\n- Only tools annotated `readOnlyHint: true` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.\n";
 /**
  * Appended to USAGE_SKILL only when the deployment actually has at least one
  * connector guide. A deployment with none — every deployment that has not

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,qBAAqB,+vBACysB,CAAC;AAE5uB;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,+yBAC4vB,CAAC;AAEjyB,eAAO,MAAM,WAAW,yyDAwBvB,CAAC;AAEF,eAAO,MAAM,sBAAsB,8yEAyBlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,odAIpC,CAAC;AASF,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAIhE;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAI5E;AAsCD,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAGvE;AAyDD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,GAAE,eAA2B,GACnC,YAAY,EAAE,CAehB;AAED,MAAM,MAAM,WAAW,GACrB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,GAAE,eAA2B,GACnC,WAAW,CAwCb"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,qBAAqB,+vBACysB,CAAC;AAE5uB;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,+yBAC4vB,CAAC;AAEjyB,eAAO,MAAM,WAAW,yyDAwBvB,CAAC;AAEF,eAAO,MAAM,sBAAsB,u3EAyBlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,odAIpC,CAAC;AASF,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAIhE;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAI5E;AAsCD,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAGvE;AAyDD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,GAAE,eAA2B,GACnC,YAAY,EAAE,CAehB;AAED,MAAM,MAAM,WAAW,GACrB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,GAAE,eAA2B,GACnC,WAAW,CAwCb"}

package/dist/skills.js

@@ -54,7 +54,7 @@ Use exact addresses returned by discovery; never invent one. Search with 2–4 d
 One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the four \`connecta\` functions, and \`console.log\`.
 
 - What exists: \`connecta.search({})\` browses every catalog; add \`safety: "readOnly"\` for only calls the program can execute, and \`connector: "<id>"\` to browse one. This filters discovery results, not authority, and each match carries its \`address\` and annotations.
-- Exact schemas for known addresses: \`connecta.describe({ addresses: [...] })\`; \`format: "json"\` only for exact constraints.
+- Exact schemas for known addresses: \`connecta.describe({ address: "connector.tool" })\` for one or \`connecta.describe({ addresses: [...] })\` for many; \`format: "json"\` only for exact constraints.
 - Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\`, which is also how a program tells a policy refusal from a transient failure.
 - Search inside the run rather than searching first, and return only the reduction the answer needs — never raw payloads.
 - Only tools annotated \`readOnlyHint: true\` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.10.4";
+export declare const CONNECTA_VERSION = "0.10.6";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.10.4";
+export const CONNECTA_VERSION = "0.10.6";
 //# sourceMappingURL=version.js.map

package/documentation/code-mode.md

@@ -98,7 +98,8 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 
 1. **Expose each provider as a guest global** whose properties are its `fns`,
    called with the program's arguments and awaited. Connecta's provider carries
-   `search`, `describe`, `call`, `batch`, and `__callNamespace` — see point 3.
+   `search`, `describe`, `call`, `batch`, `emit`, and `__callNamespace` — see
+   point 3.
 2. **Evaluate `prelude` after the provider globals exist and before the
    program**, in a scope where those globals are reachable. It is host-authored
    trusted code, never model input, and skipping it is not an option: connecta's
@@ -127,6 +128,10 @@ Optionally implement `AdmittingExecutor` (`acquire()` returning a lease whose
 `execute` runs once) for bounded admission (`L7`) and `close()` for shutdown;
 connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise.
 
+Note what is *not* on this list: [emitted output](#emitted-output) asks
+nothing of an executor — `connecta.emit` is just another provider function
+(`M8`).
+
 ## The program
 
 **P1.** A program is one JavaScript `async` arrow-function expression. It is
@@ -240,9 +245,10 @@ means "read the schema" where `[]` would claim the tool takes no fields. The
 lists come from the same walk that renders the compact schema, so a top-level
 `$ref` resolves and an `allOf` composes rather than reporting an empty list
 beside a schema that plainly shows fields; an object with no properties is the
-one case where `[]` is the truth. This metadata is code-mode-only:
-`search_tools` never carries it, and `includeSchemaKeys: false` buys the bytes
-back.
+one case where `[]` is the truth. A truncated schema omits the corresponding
+key list rather than repeating a large partial inventory. `search_tools`
+carries the same metadata whenever schemas are requested. Code-mode callers
+can set `includeSchemaKeys: false` to buy the bytes back.
 
 **S3.** Discovery is bounded and the bounds throw rather than silently shrink: a
 `limit` outside 1–100 is `invalid_args`, and a page whose serialized form
@@ -253,6 +259,8 @@ ask for less. As with every failure, the *thrown* error carries only the message
 ### connecta.describe
 
 ```js
+const one = await connecta.describe({ address: "ci.get_run" });
+
 const { tools } = await connecta.describe({
   addresses: ["ci.get_run", "ci.get_job_logs"],  // ≤ 100
   format: "compact",                             // or "json"
@@ -304,6 +312,15 @@ than ten calls throws.
 error crosses the bridge as a bare message (`E1`), a batch of one is the supported
 way for a program to *decide* something about a failure rather than report it.
 
+### connecta.emit
+
+```js
+await connecta.emit({ type: "image", data: shot.data, mimeType: "image/png" });
+```
+
+The rich-output channel, delivered after the JSON envelope on success. Its
+clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
+
 ## Errors
 
 **E1.** There are four error channels, and only two of them are typed.
@@ -351,11 +368,12 @@ program may do about it.
 sentence. A program cannot recover credentials — only an operator can — so the
 right move is to stop and let the failure reach the model.
 
-**E4.** A read-only refusal is not a downstream failure. An unannotated,
-write-capable, or destructive tool is refused in the sandbox with
-`destructive_tool_requires_approval` and stays refused; the program returns and
-the model crosses `call_destructive_tool`, where the host can ask a human.
-Generated code cannot mint that capability.
+**E4.** An unannotated, write-capable, or destructive tool stays refused with
+`destructive_tool_requires_approval`; `nextAction` carries its canonical address
+to `call_destructive_tool`, plus the original arguments when they fit the
+512-byte echo budget — whole or not at all, since a clipped copy is a different
+call. The model's short `reason` for the human reviewer grants no authority,
+never goes downstream, and generated code cannot mint the capability.
 
 **E5.** Failures of the *execution*, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
@@ -374,11 +392,9 @@ exactly first, by containment second — so a program that *wraps* a failure's
 message in its own text still reports the underlying typed failure. Keeping the
 type beats keeping the prose.
 
-**E7.** `retryable` for `unknown_address`, `unknown_tool`,
-`ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false,
-never inferred from an address containing `503`, `429`, or `temporar`.
+**E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. Both the message and the derived `query` clamp the address to 512 UTF-8 bytes with a `…` marker: the address is caller-authored and lands in the message, the query, the text content, and `structuredContent`, so an invented 50 KB one would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake; a short one — the common case — is exact and untagged.
 
-**E8.** A remote MCP tool whose advertised schema rejects the call fails before provider dispatch with `invalid_args`, carrying bounded, value-free `{ path, code, expected }` findings and scoped search recovery. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
+**E8.** A remote MCP tool whose advertised schema rejects the call fails before provider dispatch with `invalid_args`, carrying bounded, value-free `{ path, code, expected }` findings and scoped search recovery keyed `function: "connecta.search"` like every other in-program miss. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
 
 ## Results and projection
 
@@ -420,12 +436,70 @@ on data nobody asked for.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call order and returned as a single `logs` string, capped at 4,000 characters with a truncation marker. Logs survive failure — they ride along with the error result, which is what makes them worth writing. How a non-string argument renders is not contract (`X4`).
 
-**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; omitted and `false` are byte-for-byte the ordinary response path.
+**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; a program that emitted adds `emitted: N` and its blocks (`M2`). Omitted, `false`, and emit-free are byte-for-byte the ordinary response path.
 
 **R7.** Timing separates admission, provider setup, total executor wall time, catalog work, and connector work. Catalog and connector values are cumulative, so parallel work can exceed executor wall time. Each used operation kind (`search`, `describe`, `call`, `batch`) gets one aggregate with count, failures, duration, returned serialized bytes, and catalog/connector time; batch adds only its total child count.
 
 **R8.** Diagnostics contain measurements and fixed operation names only: no addresses, arguments, results, code, credentials, logs, or raw errors. Result sizes are numbers, never previews. The collector exists only for the opted-in request; it is not activity, a session, or a stream.
 
+## Emitted output
+
+MCP-native output a return value cannot carry: base64 is not projectable, so a
+block that survives intake uncapped (`S5`) must not die at the `R2` exit
+guard. The argument and the refused alternatives live in the
+[design record](./rich-output-design.md) and `ethos.md`
+([#267](https://github.com/zackbart/connecta/issues/267),
+[#270](https://github.com/zackbart/connecta/issues/270)).
+
+**M1.** `connecta.emit(block)` accepts exactly one block: `{ type: "text",
+text }` or `{ type: "image" | "audio", data /* base64 */, mimeType }`, every
+field a string, no extra fields, no `annotations`, no `_meta`, no sugar forms.
+An invalid block throws catchably and nothing is accepted — rejected, not
+stripped. The refused types are pointers: a guest-minted `resource_link` URI
+is a lure a client may dereference.
+
+**M2.** Blocks collect on the host in emission order and are delivered only
+with a successful result, appended to `content` after the JSON envelope, which
+gains `emitted: N`. A program that never emits produces the byte-for-byte
+ordinary response (`R6`). `structuredContent` stays the envelope alone —
+emission is presentation, not a second data channel.
+
+**M3.** Return value and emission are independent: `R2` never measures emitted
+bytes, a truncated return does not suppress delivered blocks, and blocks do
+not shrink the return budget.
+
+**M4.** A failed program delivers no blocks. The error result reports
+`emittedDiscarded: N` when N > 0 — a field on the structured envelope, a
+trailing line on the plain-text paths — never silently.
+
+**M5.** Two budgets (`ConnectaConfig.execute.maxEmittedBytes` /
+`.maxEmittedBlocks`, defaults 4,000,000 serialized bytes and 32 blocks) fail
+loudly at the `emit` call, naming the budget and the room remaining; nothing
+is partially accepted and prior blocks stand. No `get_result` stash: the
+program learns while it can still choose differently. The byte default is a
+transport bound, not a context bound — emitted media reaches the model as
+media, not base64 text.
+
+**M6.** No provenance is claimed: every emitted block is program output,
+trusted exactly as much as the return value. Preservation is re-emission of
+the raw downstream block, so `S5`'s uncapped fallthrough is contract.
+
+**M7.** `emit` spends no host-call budget (`L4`); `M5`'s bounds are its only
+bounds.
+
+**M8.** Emission asks nothing of an executor: `emit` is a provider function,
+blocks cross the guest boundary once as an argument, and `ExecuteResult` is
+unchanged — `Executor` stays assignable from `@cloudflare/codemode`'s
+`DynamicWorkerExecutor`, and any executor that bridges provider calls gets
+emission for free.
+
+**M9.** Request-local and unstreamed: blocks exist only in the finished
+response, and `emit` resolving means "accepted," never "delivered."
+
+**M10.** Activity stays payload-free. `diagnostics: true` adds one `emitted`
+aggregate — count and serialized bytes, numbers only (`R8`), present only
+when something was emitted.
+
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -516,27 +590,34 @@ itself (`R2`, `R5`).
 
 ## Activity
 
-**V1.** One payload-free activity event per call that named a real connector,
-with `source: "execute_code"` — every dispatched call, plus every refusal
-connecta could attribute to a connector: a read-only refusal, an unknown tool on
-a known connector, an ambiguous shortcut, a connector whose catalog could not be
-loaded, a credential connecta could not supply, an exhausted host-call budget. A
-program that calls ten tools is ten events — as legible as ten `call_tool` calls,
-which is what makes moving work into the sandbox an optimization, not a
-blindfold.
+**V1.** One payload-free activity event per attempted call, with
+`source: "execute_code"` — every dispatched call plus every local refusal: a
+read-only refusal, an unknown tool, an ambiguous shortcut, an unloadable
+catalog, a missing credential, an exhausted host-call budget, an address no
+connector owns. Ten tools called is ten events, as legible as ten `call_tool`
+calls — which makes moving work into the sandbox an optimization, not a blindfold.
 
 **V2.** Each event carries `connectorId`, `toolName`, `address`, `source`,
 `outcome` (`success`, `error`, `timeout`, `cancelled`), `durationMs`,
-`attempts`, and `errorCode` when there was one — plus the request's id, actor,
-and server identity. It has nowhere to put arguments, results, program source,
-or raw error text, by construction. A failure the program *caught* is still
-recorded: the call happened. `address` is canonical (`A1`) for every call that
-resolved to a tool; for the refusals that never resolved to one it is the name the
-program used, which for a shortcut is the sanitized alias — the honest record of
-what was attempted.
-
-**V3.** A call whose connector does not exist — an unknown address — emits
-nothing. There is no connector to attribute it to.
+`attempts`, and `errorCode` when the call *failed* — plus request, actor, and
+server identity. Typed codes derive an optional `friction`: `tool_not_found`,
+`schema_retry`, `destructive_reroute`, or `auth_required`. The fifth class,
+`result_too_large`, cannot reach an `execute_code` event: it belongs to a
+`call_tool` result — or a `batch_call` child's — too large to return inline,
+and a program's own return is refused paging by design rather than truncated
+into friction. There is nowhere to put arguments, results, program source, or
+raw error text; a caught failure is still recorded. `address` is
+canonical (`A1`) where a tool resolved, otherwise the name the program used —
+for a shortcut its sanitized alias, the honest record of what was attempted.
+
+**V3.** A call whose connector does not exist is recorded at the address as
+written, *provided* it split into the two fields activity keeps — one with no
+interior dot records nothing. An invented id is the address mistake an operator
+most needs to see. But recording it as written puts caller-authored text in
+fields that are otherwise operator- and connector-authored, so `connectorId`
+and `toolName` clamp at 128 UTF-8 bytes (`address` at 257) with a `…` marker:
+payload-free *by construction* means the event has nowhere to put a payload,
+not merely that connecta declines to.
 
 **V4.** The execution itself emits no event. It has no address, and its one
 distinctive artifact is the program source, which is exactly what a payload-free
@@ -629,6 +710,10 @@ The middle three were places where the contract described behavior the code did
 not quite have. The code moved, because the described behavior is the one worth
 having.
 
+One surface was added since: [emitted output](#emitted-output) (`M1`–`M10`,
+[#270](https://github.com/zackbart/connecta/issues/270)) — additive by
+construction, with the byte-for-byte no-emit promise pinned by test.
+
 ## Verification
 
 Every clause has a test. `test/guest-contract-cases.ts` holds the case table,
@@ -678,8 +763,14 @@ the upstream `Executor` shape assignable.
 | `L5`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap) |
 | `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message) |
 | `L7` | `test/execute.test.ts`, `test/executor-admission.test.ts` |
-| `V1`, `V2` | `test/guest-api-contract.test.ts` (dispatched calls, and the four refusal classes that name a connector), `test/activity.test.ts` |
-| `V3`, `V4` | `test/guest-api-contract.test.ts` (no event without a connector) |
+| `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, and the identity clamp) |
+| `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
+| `M2`, `M3` | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path) |
+| `M4` | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths) |
+| `M5`, `M7` | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched) |
+| `M6`, `M9` | verdicts; `M1`'s strict typing and `M2`'s collect-then-deliver are their enforcement |
+| `M8` | two arms passing one case table, `test/codemode-compat.test.ts` |
+| `M10` | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |

package/documentation/meta-tools.md

@@ -55,8 +55,11 @@ or generated code; `safety: "approvalRequired"` finds the complementary set
 that must cross `call_destructive_tool`. Omitting `safety`, or setting it to
 `"all"`, preserves the complete configured catalog. This is only a discovery
 filter: it neither grants authority nor changes invocation admission.
-`includeSchemas: "compact"` adds each match's input and any
-declared output shape; matches also carry declared behavior annotations. When
+`includeSchemas: "compact"` adds each match's input and any declared output
+shape. Bounded plain-object schemas also expose `inputKeys`,
+`requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
+list rather than repeating a large partial inventory. Matches carry declared
+behavior annotations. When
 that shape is sufficient, call the returned address directly. Reserve schema
 expansion — `connecta.describe` in a program, `describe_tools` on the classic
 surface — for a search without schemas, an ambiguous compact shape, or exact
@@ -86,12 +89,24 @@ mode; they are not a duplicated Connecta object result. Newly stashed JSON and
 downstream content envelopes use compact serialization, so `get_result` byte
 offsets and totals refer to that exact compact text.
 
+A `call_tool` or `batch_call` truncation notice carries both the historical
+`resultId` and an exact
+`nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`. The handle
+is therefore directly actionable without copying an identifier out of prose;
+re-calling with `fields` remains the smaller alternative when projection is
+possible. Program results and oversized discovery responses carry no such
+route — paging a program's return value is a refused shape, because a program
+can shrink anything before it returns.
+
 `fields` keeps its historical flat `{ "<path>": value }` result when every
-requested dot-path resolves, except that an exact downstream `$connecta` field
-is always escaped under `data`. If any path misses—or that reserved name is
-selected—the result carries matches under `data` and reserves `$connecta` for a
+requested dot-path resolves. Dot notation traverses objects; append `[]` to an
+array field before continuing, as in `results[].id`. An exact downstream
+`$connecta` field is always escaped under `data`. If any path misses—or that
+reserved name is selected—the result carries matches under `data` and reserves `$connecta` for a
 `type: "field_projection"` recovery record naming each `unmatchedFields`
-entry. The discriminator means downstream fields named `data`, `projection`,
+entry. When a miss matches a declared array path except for `[]`, the record
+also carries the traversal hint. The discriminator means downstream fields
+named `data`, `projection`,
 or `$connecta` remain ordinary values nested under `data`, never apparent
 metadata. A declared output schema contributes a bounded `availableFields`
 list and a `schemaCoverage` verdict. Only a completely analyzed, closed schema
@@ -166,6 +181,71 @@ only through the same-origin, Clerk-operator credential route. After OAuth
 consent or an operator update, retry the original operation; a static update is
 read from the vault on the next call and needs no redeploy.
 
+## Routing recovery
+
+Predictable local refusals carry structured recovery on both result modes.
+An unknown connector suggests an unscoped discovery query derived from the
+attempted tool name; an unknown tool scopes the same query to the connector that
+answered. The suggested route follows the caller's own surface: `tool:
+"search_tools"` for a top-level call, `function: "connecta.search"` with the same
+arguments when the miss happened inside `execute_code`, which has no way to call
+a tool. A read path that reaches an unannotated, write-capable, or destructive
+tool returns `nextAction` for `call_destructive_tool` with the canonical
+address. Nothing is executed by these records.
+
+That route echoes the caller's own arguments back only while they fit a
+512-byte budget, and then whole — never clipped. An error envelope is not
+size-guarded the way a result is, so an unbounded echo would let a large
+argument object produce a refusal many times the deployment's result cap, on
+both `call_tool` and the `batch_call` envelope. Over budget, `args` is absent
+and the `purpose` says to re-send what was just sent: the agent already holds
+its own arguments, and half of them would describe a call nobody made.
+
+The address gets the same budget and the opposite rule: 512 bytes, clamped
+with a trailing `…` rather than dropped. It is caller-authored too — an
+invented one can be any length — and it reaches the error message *and* the
+recovery query, each of which lands in both the text content and
+`structuredContent`; unbounded, a 50 KB typo produced a 200 KB refusal under a
+1 KB result cap. Dropping it is not an option the way dropping arguments is:
+the address is the thing being corrected, a clipped one still identifies the
+mistake, and a short one — every real one — comes back exact and untagged.
+
+Shortcut ambiguity inside `execute_code` returns every colliding canonical
+address and points at `connecta.call`; the program or model must still choose
+which one matches the user's intent. `call_destructive_tool` accepts an optional
+`reason` of at most 500 characters for the host's human approval view. It is
+outer-call context only: Connecta neither treats it as authority nor passes it
+to the downstream connector, and an empty or whitespace-only one is read as no
+reason rather than as a reason to refuse the call.
+
+Activity carries an optional coarse `friction` class: `tool_not_found`,
+`schema_retry`, `destructive_reroute`, `auth_required`, or `result_too_large`.
+It is derived from the typed error code, except on the one call that has no
+error code to derive from: a `call_tool` result — or a `batch_call` child's —
+too large to return inline is friction for the agent while remaining
+`outcome: "success"`. That is the only source of `result_too_large` friction.
+An oversized *discovery* response and an oversized program return are shaped
+differently and produce none, and an `errorCode` is written only when the call
+actually failed. The category adds no arguments, results, search text,
+generated code, credentials, or raw errors.
+
+An address whose connector does not exist is recorded too, as written, provided
+it has the `<connectorId>.<toolName>` shape at all — a string that never split
+into the two fields activity keeps still records nothing. A hallucinated
+connector id is the most common address mistake, and an operator reading
+activity should see it; addresses are already a first-class activity field, so
+nothing new is retained.
+
+What *is* new is that those fields now hold caller-authored text, so the
+recording seam clamps them: `connectorId` and `toolName` at 128 UTF-8 bytes
+each, `address` at 257, with a `…` marker. Far past any real id or tool name,
+and far short of a 40 KB invented one. The clamp is structural rather than a
+policy the writer applies, because "payload-free by construction" has to mean
+the event type has nowhere to put a payload — a 40 KB connector id is a payload
+wearing an id's clothing. Clamped rather than skipped: the invented id is
+exactly what an operator needs to see, and its first 128 bytes say as much
+about the mistake as all 40,000 would.
+
 ## Argument recovery
 
 A remote MCP tool's advertised `inputSchema` is checked in the shared
@@ -177,9 +257,11 @@ JSON Pointer `path`, schema-keyword `code`, and expected shape. Submitted
 values are never copied into those findings.
 
 At most three findings are returned; `validation.truncated` says when more
-exist. `nextAction` points to `search_tools` scoped to the same connector and
-tool name when the compact schema is needed, while `retry` says to correct the
-listed arguments and reissue the original operation. A schema the local
+exist. `nextAction` points to discovery scoped to the same connector and tool
+name when the compact schema is needed — routed like any other miss, so a
+program is sent to `connecta.search` and a top-level call to `search_tools` —
+while `retry` says to correct the listed arguments and reissue the original
+operation. A schema the local
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.