@zackbart/connecta 0.24.4 → 0.26.0

package/documentation/meta-tools.md

@@ -2,34 +2,43 @@
 
 Connecta keeps one small tool surface in model context and resolves downstream
 tools behind it. `search_tools` finds addresses, the call tools enforce safety
-annotations, `execute_code` runs read-only work as a program, and `get_result`
-pages bounded results.
+annotations, `execute_code` runs work as a program that pauses at each write
+until `resume_execution` approves it, and `get_result` pages bounded results.
 
 This guide is the contract an MCP client sees. The in-program `connecta.*` API
 those tools imply belongs to [code mode](./code-mode.md); inbound identity and
 credential administration belong to [auth](./auth.md).
 
-## The seven tools
+## The eight tools
 
-Every deployment requires an executor, so `tools/list` is exactly seven. No
-configuration adds an eighth or removes one.
+Every deployment requires an executor, so `tools/list` is exactly eight. No
+configuration adds a ninth or removes one — not even turning resumable writes
+off, which changes what `resume_execution` answers and nothing about whether it
+is listed, so a client's cached tool list never depends on the storage behind
+the deployment. `execute_code` keeps its read-only hint although its programs
+may now reach writes, because no write runs there: a program stops before
+sending one, and the write runs only inside the destructive-annotated
+`resume_execution` that repeats it ([code mode](./code-mode.md#pausing-and-resuming)).
 
 | Tool | Arguments | Returns |
 | --- | --- | --- |
-| `execute_code` | `code`, `diagnostics?` | the program's reduced return value, plus a `diagnostics` block when asked |
-| `search_tools` | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json"` | `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`, plus `queryAnalysis` on a partial or failed search |
+| `execute_code` | `code`, `diagnostics?` | the program's reduced return value, plus a `diagnostics` block when asked; or, when it reached a write, `{ paused: { address, args, token, expiresAt, nextAction, hint } }` |
+| `resume_execution` | `token`, `address`, `args`, `approval?: "call" \| "tool"`, `reason?` | what `execute_code` would have returned had the write been approved: the result, the next pause, or a typed failure |
+| `search_tools` | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json" \| "typescript"` | `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`, plus `queryAnalysis` on a partial or failed search |
 | `call_tool` | `address`, `args?`, `resultMode?: "mcp" \| "value"`, `timeoutMs?`, `diagnostics?` | the downstream result, bounded as [result representation](#result-representation) describes |
 | `call_destructive_tool` | the same, plus `reason?` | the same |
 | `authorize_connector` | `connector`, `force?` | the class-specific handoff in [authorization recovery](#authorization-recovery) |
-| `get_result` | `id`, `offset?`, `maxBytes?` | `{ offset, nextOffset?, totalBytes, text }` |
+| `get_result` | `id`, `offset?`, `maxBytes?` | a one-line JSON header `{ resultId, offset, bytes, totalBytes, hasMore, nextAction? }`, a newline, then the page as raw text ([paging](#paging-with-get_result)) |
 | `skills` | `name?` | the listing when `name` is absent, that skill's markdown when it is present |
 
 `limit` defaults to 8 and is capped at 100, as is one `connecta.describe` batch.
 `get_result.offset` is a whole number of bytes ≥ 0 defaulting to 0 and
-`maxBytes` a whole number ≥ 1 defaulting to the deployment result cap — itself
-50,000 bytes unless `calls.maxResultBytes` or a per-connector override says
-otherwise. Both are validated rather than clamped: a bad value is an input
-error. `reason` is at most 500 characters of context for the host's human
+`maxBytes` a whole number ≥ 1 that defaults to, and is clamped to, the inline
+cap of the call that stashed the result — 24,000 bytes unless
+`calls.maxResultBytes` or a per-connector override says otherwise
+([why 24,000](#truncated-direct-call-results)). A value outside those domains is
+an input error; a valid `maxBytes` above the cap is an upper bound, not an
+error ([why](#paging-with-get_result)). `reason` is at most 500 characters of context for the host's human
 approval view; Connecta neither treats it as authority nor sends it downstream,
 and an empty or whitespace-only one reads as no reason rather than as grounds to
 refuse a consequential call.
@@ -43,9 +52,13 @@ credentials, logs, or raw error text.
 
 Connecta's own tools carry the annotations it demands of downstream tools:
 read-only hints on all but `authorize_connector`, which mutates stored auth
-state, and `call_destructive_tool`. Otherwise a host that gates on annotations
-would prompt for every search, and a connecta aggregated behind another connecta
-would be refused by its own policy.
+state, and the two that send writes, `call_destructive_tool` and
+`resume_execution`, both destructive. Otherwise a host that gates on
+annotations would prompt for every search, and a connecta aggregated behind
+another connecta would be refused by its own policy. `resume_execution` is
+where the prompt belongs: its arguments are the exact write, so the human
+approves what will be sent rather than a program that might send anything.
+Its `reason`, like `call_destructive_tool`'s, is dropped before anything runs.
 
 ## Routing between the call surfaces
 
@@ -61,12 +74,21 @@ as a small sample for inspection before continuing in another call, which avoids
 repeated guesses at text formats and collection roots without restoring a
 mandatory discovery-only round trip.
 
-That covers read-only work, because that is the only work a program can do.
-Anything unannotated, write-capable, or destructive is inadmissible inside the
-sandbox, so multi-step destructive work discovers at the top level and runs each
-step through `call_destructive_tool`, where the host can put the question to a
-human. Telling an agent never to search at the top level for multiple calls
-would close the only route that work has.
+Writes take the same route. A program that reaches a tool not explicitly
+annotated read-only stops before sending it — unless the deployment's config
+exempts that tool, and then it runs unasked — and returns the exact call with a
+token; `resume_execution` repeating it is the approval, and the program
+replays from a journal to send it and carry on — to its answer, or to its next
+write. So "close the stale issues and post a summary" is one program and a few
+approvals, not one program and thirty-one top-level calls, and the program's
+reasoning survives between them. `approval: "tool"` covers the rest of the
+run's calls to that tool, so thirty closes cost one prompt. One known write
+still goes straight to `call_destructive_tool`, and top-level discovery stays
+for catalog inspection. On a deployment without resumable writes (storage
+without `compareAndSet`), a program cannot write at all: the call fails
+`destructive_tool_requires_approval`, multi-step writes discover at the top
+level and run each step through `call_destructive_tool`, and the MCP
+instructions say so.
 
 The three discovery routes use deliberately different envelopes. These are their
 smallest successful one-tool shapes:
@@ -104,9 +126,9 @@ discovery. Both take the same arguments.
 | --- | --- |
 | `query` | two to four action/object terms; empty or whitespace-only browses |
 | `connector` | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous |
-| `safety` | `"readOnly"` for what generated code may call, `"approvalRequired"` for the complementary set that must cross `call_destructive_tool`, omitted or `"all"` for the complete configured catalog |
+| `safety` | `"readOnly"` for what runs unasked, `"approvalRequired"` for the complementary set that pauses a program or crosses `call_destructive_tool`, omitted or `"all"` for the complete configured catalog. A config-exempt write stays `"approvalRequired"` and its row says `approval: "exempt"`: a program calls it without pausing, and `call_tool` still refuses it ([code mode](./code-mode.md#pausing-and-resuming) `W12`) |
 | `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small |
-| `includeSchemas` | `"compact"` for the rendered routing view, `"json"` for the exact schema |
+| `includeSchemas` | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures)) |
 | `fullDescriptions` | unabridged tool purposes, at the obvious cost |
 
 Neither `connector` nor `safety` grants authority or changes invocation
@@ -141,6 +163,44 @@ act on is the flag: any cap sets `inputSchemaTruncated` or
 `outputSchemaTruncated`, and that means repeat with `includeSchemas: "json"`, or
 describe, when the exact constraints matter.
 
+### TypeScript signatures
+
+`includeSchemas: "typescript"` replaces both schema fields with one
+`signature`: the function `connecta.call(address, args)` resolves to, written
+as a TypeScript type because agents write code against types more reliably
+than against JSON Schema ([executor](https://github.com/UsefulSoftwareCo/executor)'s
+discovery made the same bet).
+
+```ts
+(args: { team: string; limit?: number /* <= 250 */ }) => Promise<unknown>
+(args?: {}) => Promise<{ accounts: { stripe_context: string; livemode: boolean; name?: string }[] }>
+(args: { team: string }) => Promise</* observed, not declared */ { cursor?: string; issues?: { id?: string }[] }>
+```
+
+It is something to read, not something that runs: programs stay JavaScript,
+and the refusal of erasable TypeScript in `execute_code` stands
+([ethos](../ethos.md#decisions)). The output half is the provider's declared
+schema, else an `S9` observation that opens with the
+`/* observed, not declared */` marker and keeps the `outputSchemaSource`
+field, else `unknown` — runtime evidence never reads as a contract, even when
+the signature is lifted out of its entry. A tool without parameters takes
+`args?: {}`.
+
+The walk, byte budgets, and truncation flags are compact's, each half
+separately, and search, describe, and every discovery route share them, so the
+same tool renders the same signature from `search_tools` and `connecta.search`.
+What changes is the dialect: `number` for `integer`, `;` between members,
+quoted non-identifier keys, `| null` for OpenAPI `nullable` and type lists,
+index signatures for schema-valued `additionalProperties`,
+`Record<string, unknown>` for an open object with no declared properties, and
+JSDoc for property prose where describe keeps it. Both dialects parenthesize a
+union or intersection before an array suffix, `(A | B)[]`.
+Where compact would print a bare definition name or raw JSON, the signature
+prints `unknown` with a marker and sets the flag: `/* recursive */` for a
+`$ref` cycle, `/* unresolved */` for a missing target, `/* truncated */` past
+depth four or an exhausted budget. `inputKeys` and friends come from the
+declared schema exactly as they do for compact.
+
 ## Connector guides and skills
 
 A connector may attach a deployment-owned guide as markdown, keeping the
@@ -202,7 +262,8 @@ text block carrying its compact JSON and then applies the same content size
 guard, which preserves structured-only results including `null`, arrays, and
 scalars. An existing text mirror stays unchanged; Connecta adds no second copy.
 Newly stashed JSON and downstream content envelopes use compact serialization,
-so `get_result` offsets and totals describe that exact compact text.
+and a lone text block stashes as its own text, so `get_result` offsets and
+totals describe exactly that text.
 
 | Bound | Value |
 | --- | --- |
@@ -244,30 +305,124 @@ original UTF-8 text, not the envelope. A supplied offset inside a character
 moves back to its start; page ends also align to character boundaries, and a
 page smaller than one character widens just enough to make progress.
 
-A successfully stashed `call_tool` truncation notice carries both the historical
-`resultId` and an exact
-`nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`, so the handle
-is actionable without copying an identifier out of prose. 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.
-
-A refused or failed stash write cannot undo a downstream success. Both call tools
-then return a truncated preview where one is usable, with a paging-unavailable
-notice and no `resultId` or paging action; an envelope carrying non-text blocks
-gets the notice alone, because the head of a half-written base64 image helps
-nobody. Activity records success, and the operator logger receives a fixed
-warning naming the connector and tool without storage error prose. For read-only
-work, reduce the result inside `execute_code` — repeating an approved write is
-not a way to recover its output. Other result-processing failures use a fixed
-`result_processing_failed` message and are never retryable.
-
 A per-call `timeoutMs` covers catalog resolution, admission, and connector
 execution under one deadline. The admission queue's own timeout may expire
 sooner but cannot extend the call deadline. Result processing happens after that
 deadline ends, because a completed downstream call must not turn into a
 retryable timeout while Connecta prepares its response.
 
+### Truncated direct-call results
+
+A `call_tool` or `call_destructive_tool` result over its cap — the connector's
+`maxResultBytes`, else `calls.maxResultBytes`, else 24,000 bytes — comes back
+as one text block. Its first line is the truncation notice, one line of compact
+JSON; everything after the first newline is the preview:
+
+```text
+{"truncated":true,"resultId":"…","totalBytes":161420,"hint":"This write already ran: do not call it again to see its result. Bytes 0-24000 of 161420 follow; page the rest with get_result using nextAction.","nextAction":{"tool":"get_result","arguments":{"id":"…","offset":24000}}}
+{"ts":"2026-09-16T21:31:11.759Z","actor":"sam.ortiz@example.com",…
+```
+
+The notice leads because clients cut oversized results from the end, and a
+notice at the tail is the part they drop. Claude Code (measured on 2.1.280, from
+its bundled source and with `claude -p` against a probe server) passes an MCP
+result through untouched while its text blocks total at most 50,000 characters.
+One character more and it replaces the whole result with a pointer to a spill
+file plus the first 2,000 characters of `JSON.stringify(content, null, 2)`,
+whatever `MAX_MCP_OUTPUT_TOKENS` says. Once the characters exceed twice
+`MAX_MCP_OUTPUT_TOKENS` (25,000 by default, so again 50,000) it also counts real
+tokens against that limit, and a result over it arrives as an error carrying no
+content at all — no preview, no notice. The old layout — a
+50,000-byte preview, then the notice — crossed the first line every time, so an
+agent without file tools never saw the handle; in the eval's write task two of
+three models re-ran a billable export three times trying to read its result.
+
+The default cap sits under both lines with room to spare. Preview plus notice
+stays under 25,000 bytes, which is under 50,000 characters for any text, because
+a character is at least one UTF-8 byte, and under 25,000 tokens for any text,
+because a token covers at least one byte. A `get_result` page obeys the same
+cap, and 24,000 matches the program result boundary in
+[code mode](./code-mode.md). A deployment whose
+clients take more can raise the cap, and one whose clients take less can lower
+it, per connector if need be; a result between 24,000 and 50,000 bytes that
+used to arrive whole now pages. A client that spills rather than rejects keeps
+the notice whatever its threshold, since the notice is the first few hundred
+characters. One that rejects outright — Claude Code with
+`MAX_MCP_OUTPUT_TOKENS` set below 12,500 — needs a cap under twice its limit.
+
+The preview is the head of what `get_result` pages, cut on a character
+boundary, so `nextAction.arguments.offset` continues exactly where it stops. A
+lone text block — including the one synthesized from `structuredContent` — is
+measured, stashed, previewed, and paged as its text: wrapping it in a content
+envelope added nothing but a second layer of JSON escaping, so a JSON payload
+used to preview as `[{"type":"text","text":"{\"ts\":…` and every page carried
+the escaping twice. Several text blocks keep the serialized envelope as the one
+string measured, stashed, and paged, because their boundaries live there; they
+preview as their text joined by newlines, and their next action starts at
+offset 0. A content array carrying non-text blocks returns the notice alone,
+because the head of a half-written base64 image helps nobody. In value mode the
+notice is `data` itself, with no preview and a next action at offset 0.
+
+The hint says what to do next. For a call not explicitly annotated read-only it
+opens with “This write already ran: do not call it again to see its result.”
+The approved write happened; repeating it to look again is how one export
+becomes three. For an explicitly read-only call, repeating is the better route,
+so the hint offers it first: to find something specific, repeat the read inside
+`execute_code` with `connecta.call` and filter or search the result there; to
+read it in full, page with `get_result`. Inside a program the inline cap does
+not apply to a host call's result, only to what the program returns (`L6` in
+[code mode](./code-mode.md) bounds a host call far higher), so the reduction
+sees the whole result at once. When the hint named paging alone, the eval's
+weakest model read a 185 KB CI log in 24,000-byte pages, skipped the range
+holding the real failure, and named the flaky test near the top; before the
+notice was visible, it had reduced the log in a program and found the failure.
+`nextAction` stays the page handle for either kind of call, because paging is
+the one next step connecta can spell out exactly, while a reduction is a
+program the agent has to write. `resultId` stays beside the exact `nextAction`,
+so the handle is actionable without copying an identifier out of prose.
+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.
+
+### Paging with get_result
+
+A page is the truncated result's shape again: one text block whose first line
+is a JSON header and whose remainder is the page, raw.
+
+```text
+{"resultId":"…","offset":24000,"bytes":24000,"totalBytes":161420,"hasMore":true,"nextAction":{"tool":"get_result","arguments":{"id":"…","offset":48000}}}
+{"ts":"2026-09-17T23:42:55.357Z","actor":"noor.haddad@example.com",…
+```
+
+`bytes` is what this page returned; `hasMore` is false on the last page, which
+carries no `nextAction`. The page is the stashed text as-is — a lone text
+block's own text, a value's compact JSON, several blocks' serialized content
+array — and never a JSON string holding it. Pages used to arrive as
+`{ offset, nextOffset?, totalBytes, text }`, which escaped every quote and
+newline in the page: a second layer over JSON payloads that made them hard to
+read and swelled a 20,000-byte page of JSON lines to 25,000 characters or more.
+
+`maxBytes` is an upper bound clamped to the inline cap of the call that stashed
+the result — the connector's override when it had one, recorded in the stash
+entry — and a clamped request is answered, not refused, with `bytes` saying how
+much came back. Clients cut an oversized page exactly as they cut the original
+result. In the eval, agents that could finally see the handle asked for pages of
+50,000 bytes and more, and Claude Code rejected every one of those answers
+outright, leaving an agent that had just been told not to repeat a write with
+nothing to read. So no response to a truncated call or to a page request
+exceeds the cap plus a header of a few hundred bytes. Value mode's unpageable
+preview is cut short enough that its JSON escaping still fits. Entries stashed
+before the cap was recorded page at the deployment cap.
+
+A refused or failed stash write cannot undo a downstream success. Both call tools
+then return the same layout with a paging-unavailable notice and no `resultId`
+or paging action — the notice first, then the preview where one is usable, and
+for a write the same warning not to repeat it. Activity records success, and
+the operator logger receives a fixed warning naming the connector and tool
+without storage error prose. For read-only work, reduce the result inside
+`execute_code` — repeating an approved write is not a way to recover its output. Other result-processing failures use a fixed
+`result_processing_failed` message and are never retryable.
+
 ## Lexical discovery
 
 `search_tools` tokenizes tool names and descriptions at punctuation and
@@ -378,9 +533,10 @@ attempted tool name; an unknown tool scopes the same query to the connector that
 answered. The suggested route follows the route the caller took:
 `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
+way to call a tool. `call_tool` reaching an unannotated, write-capable, or
 destructive tool returns `nextAction` for `call_destructive_tool` with the
-canonical address. Nothing is executed by these records.
+canonical address; inside a program the same call pauses, and the pause result
+names `resume_execution` instead. Nothing is executed by these records.
 
 `connecta.describe` keeps its failures inline instead, so one miss cannot
 discard the other schemas; each failed entry carries a human `error`, typed

package/ethos.md

@@ -4,92 +4,91 @@ Connecta’s scope, refusals, and invariants. Contradictions require a design de
 
 ## What this is
 
-- **One MCP endpoint.** Agents reach configured connectors through JavaScript
-  and seven meta-tools. Every deployment requires an executor.
-- **Config-as-code.** One tenant and connector set; identities receive
-  config-derived views. Maintained providers, `remoteMcp()`, and `api()` obey
-  the same connector contract.
-- **Safe by default.** Only explicitly read-only tools run inside a program.
-  Others cross `call_destructive_tool`; the host owns human approval.
-- **One fetch-native core.** Web APIs support Node and Workers. Platform code
-  and optional features use explicit subpath imports.
+- **One MCP endpoint.** Agents reach configured connectors through JavaScript,
+  a required executor, and eight meta-tools.
+- **Config-as-code.** One tenant and connector set; identities get
+  config-derived views. Maintained providers, `remoteMcp()`, and `api()` share
+  one connector contract.
+- **Safe by default.** Programs run only read-only or config-exempt tools
+  unasked; others pause for `resume_execution` or cross
+  `call_destructive_tool`. The host owns approval.
+- **One fetch-native core.** Web APIs on Node and Workers; platform code and
+  optional features behind explicit subpaths; Effect inside, Promises outside.
 - **Human auth management.** Optional pages show status and payload-free history.
   Explicit permissions allow credential changes and OAuth. Capabilities stay in code.
 
 ## What this isn't
 
-No runtime registration, admin-editable capabilities, policy engine, approvals,
-or pauses. No schema ingestion, accounts, groups, protocol sessions, or server
-push. Inbound providers own identity; personal state remains within one tenant.
-Credentials fail at use, without background probes. Breaking changes remain
-acceptable; version numbers signal change, not stability.
+No runtime registration, admin-editable capabilities, or policy engine; config
+may only exempt a tool from asking. No schema ingestion, accounts, or groups;
+personal state remains within one tenant. Breaking changes remain acceptable;
+version numbers signal change, not stability.
 
 ## Decisions
 
 Revisiting a verdict requires a new argument. Accepted designs live in
-subsystem guides and the CHANGELOG.
+subsystem guides and the CHANGELOG; `planned` ones bind review before either
+carries them.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
-| OpenAPI / GraphQL ingestion | refused | the disease is a tool nobody chose — a document authored it; hand-written literals, even through a shared factory, are still authorship |
+| OpenAPI / GraphQL ingestion | refused | the disease is a document-authored tool nobody chose; hand-written literals, even through a shared factory, are still authorship |
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
-| Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
+| Approvals and pauses | accepted | a program pauses host-side at its first unapproved write until the destructive-annotated `resume_execution` repeats it; an expiring journal replays it, never re-sending unknown outcomes ([#565](https://github.com/zackbart/connecta/issues/565)) |
+| Approval exemptions | accepted | config-only, program-only, never read-only elsewhere ([#566](https://github.com/zackbart/connecta/issues/566)) |
 | Runtime connector registration | refused | config-as-code is the security model |
-| Optional deployment modules | accepted | explicit imports and typed config slots select UI, activity history, credential vault, and inbound auth; discovery, execution, invocation, and enforcement stay in core |
-| Generic plugin lifecycle or marketplace | refused | modules organize deployment code; runtime installation and discovery add no required behavior |
-| Connecta-issued access tokens | removed | inbound identity providers own client authentication; configured bearer auth remains an optional adapter |
-| Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
+| Artifacts module | accepted | a built-in connector for team-only sandboxed pages over stored JSON; immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) |
+| Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Connecta-issued access tokens | removed | inbound providers authenticate clients; bearer auth stays an optional adapter |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
-| Protocol sessions & server push | refused | stateless per request |
-| Resources & prompts aggregation | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Elicitation passthrough | refused | no route through a stateless aggregator |
+| Resources, prompts, and downstream MCP Apps templates | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Protocol sessions, server push, elicitation passthrough | refused | stateless per request; elicitation has no route |
 | Repository formatter | refused | style is authored, not enforced |
-| Host-side projection of program results | refused | a program projects; a heuristic drops fields invisibly ([#223](https://github.com/zackbart/connecta/issues/223)) |
-| `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove ([#223](https://github.com/zackbart/connecta/issues/223)) |
+| Host-side projection or paging of program results | refused | a program projects: heuristics drop fields invisibly, paging rewards unprojected returns ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Widening the `Executor` result contract | refused | `{ result, error?, logs? }` is the `@cloudflare/codemode` parity guarantee ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Erasable TypeScript in `execute_code` | refused | 24 MB dependency in the core, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
-| Guest-minted `resource` / `resource_link` blocks | refused | a program can never mint a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Erasable TypeScript in `execute_code` | refused | a 24 MB core dependency, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
+| Guest-minted `resource` / `resource_link` blocks | refused | no program mints a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Provenance tracking for emitted content | refused | everything a program emits is program output ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Result sampling on the catalog surface | refused | sampling is execution and cannot ride a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
+| Result sampling on the catalog surface | refused | sampling is execution, not a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
-| Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
+| Effect as the core effect system | accepted | lifetimes held the bugs: the rewrite closed leaked permits, hung waits, and cross-request races. Overturns [#470](https://github.com/zackbart/connecta/issues/470) |
+| Shared bounded queue under both admission controllers | refused | built: −17 lines bought a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
 | MCP Apps rendering and `connecta.ui` | removed | clients render returned data |
 | Connector shortcut globals | removed | canonical addresses need no sanitization |
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
-| Connector HTTP routes | removed | deployments own custom routes |
-| Caller-selected toolkits | removed | config derives every view; config-declared, grant-gated pools at `/mcp/<pool>` are not caller-selected ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
+| Connector HTTP routes | removed | deployments own custom routes; the operator UI's artifact viewer is the exception |
+| Caller-selected toolkits | removed | config derives every view, grant-gated `/mcp/<pool>` pools included ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
-| Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
-| Stabilized workflows | gated | needs programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
+| Per-result lexical query coverage | removed | failed a precommitted response-bytes gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
+| Stabilized workflows | accepted | only as artifact refresh: deployment-triggered read-only programs, shared credentials ([#225](https://github.com/zackbart/connecta/issues/225), [#564](https://github.com/zackbart/connecta/issues/564)) |
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
-| Downstream MCP Apps template passthrough | refused | clients own presentation; Connecta serves tools and data |
 | Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
 | Program UI tool calls | removed | duplicated calls without improving retrieval ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants
 
-Tests beside subsystem documentation enforce these invariants. Breaking one
-requires a design decision.
+Tests beside subsystem documentation enforce these; breaking one requires a
+design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
-- **Only explicitly read-only work runs inside the sandbox.** Everything else crosses `call_destructive_tool`.
-- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it.
-- **A downstream catalog is complete or it is a failure.** A partial catalog is never cached, persisted, or served.
+- **Only explicitly read-only or config-exempt work runs unasked in the sandbox.** Others pause or cross `call_destructive_tool`.
+- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it; a paused journal is data, not a request.
+- **A downstream catalog is complete or it is a failure.** A partial one is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
 - **An observed shape is never a declaration.** Names and broad types only, labeled, and gone behind any declared schema.
-- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
-- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
-- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Human routes manage auth, never capability.** Visibility grants use, not credential administration. Shared and personal auth mutations require separate config-derived permissions, both denied by default. Activity has its own read permission.
-- **Omitted modules do no work.** Core imports no UI bundle, encrypted vault implementation, activity implementation, or bearer adapter. OAuth callbacks remain available without UI.
-- **Status reads do not start authorization.** OAuth starts through an explicit authorized action; loading the UI never creates a consent flow.
+- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector (and principal, for personal auth), rendered by nothing.
+- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin or `effect/testing`.
+- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath; Effect is the one hard dependency, named by no published type.
+- **Human routes manage auth, never capability.** Visibility grants use, not administration. Auth mutations need separate config-derived permissions, denied by default; activity reads its own. Artifact viewing respects connector grants and cannot invoke tools.
+- **Omitted modules do no work.** Core imports no UI bundle, vault, activity, artifacts, or bearer implementation. OAuth callbacks work without UI.
+- **Status reads do not start authorization.** Only an explicit authorized action starts OAuth, never a page load.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/examples/worker/AGENTS.md

@@ -37,6 +37,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
   A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
   tokens are removed. UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
+- Brand the operator UI in `operatorUi({ branding })`: product and owner names,
+  description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
+  `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
+  rather than leaving the default. The commented block above
+  `ui: operatorUi()` in `src/index.ts` shows the shape; README "UI and
+  encrypted credentials" covers the rest.
 - After configuration changes, typecheck: inside the connecta repository that
   is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and