@zackbart/connecta 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to this package are documented here.
 
+## 0.30.0 — 2026-10-09
+
+Connecta 0.30.0 makes large results, sign-in and rich output dependable for agents, on both direct calls and programs. The six-tool surface from 0.29.0 stays. We measured the alternative, folding everything into `execute_code`, against it on Sonnet 5.5 and GPT-6-Luna (#765). The code-only surface scored lower and made a duplicate billable write, so it was not adopted.
+
+Default `call_tool` and `call_destructive_tool` results now put their data in `content` and no longer send `structuredContent` or advertise `outputSchema`. Clients that prefer structured content, Claude Code among them, previously saw only a `{"format":"json"}` stub. Read the format from `_meta["dev.connecta/format"]`. For a truncated result, parse the first line of the text as a JSON notice. `resultMode: "value"` keeps the full structured envelope.
+
+Programs no longer lose large data. A `connecta.call` result over the executor's inline cap is rebuilt from stash pages up to 1 MiB, and larger results come back as a handle for `connecta.result`. A program that returns more than 24,000 characters gets a pageable `resultId` in place of a truncated preview. If that run made a write, the notice says the write already ran. Paging checks the caller's connector grants on every page. Programs can forward images and other rich content with `connecta.emit(result)` or `result.content`, within the existing byte and block limits.
+
+Downstream-OAuth handoff links use compact, opaque tokens that agents copy intact; links issued before the upgrade keep working until they expire. Auth failures on direct calls, program calls and catalog search now carry the sign-in link or operator instructions themselves, so agents no longer need a separate `authorize_connector` step. URL elicitation is unchanged.
+
+Values submitted in JSON-Schema `writeOnly` argument fields are now treated like credentials. They are redacted from downstream result text, error text, program output and stored pages, with bounded work and memory. Values under 8 characters are replaced only where a structured field equals them, and prose containing them is withheld. Credential redaction of very large or deeply nested results no longer risks exhausting memory.
+
+Custom `KVStorage` adapters must honor the new `expiresAtMs` option on `set` and `compareAndSet` and declare `capabilities: { absoluteExpiry: true }`. Construction rejects adapters without that declaration. The built-in memory, SQLite and D1 drivers already comply. Stash capacity charges now use storage time and hold until orphaned chunks expire, so a skewed or failing host can no longer over-admit stashes. The new maintained Infisical provider lets deployments manage projects, folders and secrets with machine-identity Universal Auth and no hand-written connector.
+
+### Added
+
+- Add a maintained Infisical REST provider for machine-identity Universal Auth, projects, folders, and secret reads and writes. Tokens stay in memory and refresh before expiry, lists omit values by default, writes omit values and expose pending approvals, and credential-free OpenAPI checks cover every endpoint. Value-free results, including imports and approvals, return only validated identifiers and omit comments, descriptions, free-form names, reminder notes, and arbitrary nested objects. Project slugs are withheld because Infisical can derive them from free-text project names. Write recovery echoes omit secret values, secret comments, and folder descriptions without changing dispatched arguments. Comments are available only from explicit value reads. `metadataOmitted` reports withheld or unavailable metadata. This protects against careless human data entry on an honest server; adversarial encodings by a malicious server are out of scope. Known, accepted residual risk: environment slugs are returned as required routing identifiers. Infisical's UI derives them from environment names by default, so secrets entered in those names can appear in returned slugs. Operators must not put secrets in environment names or slugs. Secrets placed in identifiers or key names are out of scope. Submitted-value matching and request-secret registration are removed, preserving later program arguments and repeated writes with the same value. Rejected tokens never automatically resend writes; reconcile before an explicit retry. Existing `clientId`/`clientSecret` credentials work when the connector id is preserved. Core uncertainty and retry envelopes omit nested and composed `writeOnly` fields, withhold argument echoes when sensitivity cannot be resolved, and mark partial or withheld echoes with `argsRedacted: true`. Retry using the original arguments. Guarded base-URL validation refuses invalid configuration without quoting its value.
+- Add an eval-only code arm, explicit route/outcome grading, offline baseline regrading and a paired A/B report with a pre-registered correctness and write-safety decision rule. Both agent runners assert the selected tool list; Claude also supports Haiku 5.5.
+- Forward MCP rich content from programs with `connecta.emit(result)` or `result.content`, preserving native blocks and metadata within the existing paging and emission limits. Snapshot retained native blocks within byte, node, and depth limits before paging can yield so later connector mutations cannot change their content or bypass emission limits. Page oversized structured data before inspecting native presentation, and refuse cyclic or over-budget presentation without retaining it.
+
+### Changed
+
+- Auth failures on direct calls, program calls, and catalog search/describe now include the authorization URL or operator credential instructions that `authorize_connector` returns. Each call or program run reuses one handoff per connector, without forcing reauthorization. Programs can read typed recovery through `error.data` as well as `error.details`; URL elicitation is unchanged.
+- Separate the human product overview from agent task documentation. Route endpoint operation, deployment, integration, and repository maintenance through an agent index, preserve technical contracts and existing section links, and move the operator UI contract into its own guide.
+
+### Fixed
+
+- Read Vercel's complete public MCP inventory from its linked category references, with bounded credential-free fetching and explicit unavailable findings for incomplete documentation.
+  
+  Reconcile category URLs discovered across the entire index with published counts and category tool headings before comparing drift. Unrecognized formatting reports unavailable instead of silently omitting tools, and unused unrelated reference definitions do not block the inventory.
+  
+  Resolve relative category destinations before requiring a count on each category link, exclude CommonMark code examples, and require the tool's known category to reconcile before reporting a removal. Disappearing categories require review, while unrelated count prose does not block the check.
+- **Breaking:** Book each result stash reservation once with a finite deadline of booking time
+  plus a 30-second write budget plus the chunk TTL, normally 15 minutes. Stop the
+  write loop on timeout and return no paging ID. Absolute chunk and ledger expiry
+  prevents late or ambiguous writes from extending that bound. Custom KVStorage
+  adapters must honor the new `expiresAtMs` option on set and compareAndSet and
+  declare `capabilities: { absoluteExpiry: true }`; construction rejects legacy
+  adapters without that explicit opt-in. Rejected write responses retain the
+  original reservation because their dispatched operation may commit later.
+  Settlement and cleanup shorten or remove charges when possible; after failure
+  or exhausted retries, capacity may be over-held until the booked deadline.
+  Bound each cleanup/release or settlement path to 15 seconds, including storage
+  I/O, and abandon further work when its budget expires so stalled operations
+  cannot hang the caller after the write timeout.
+  Remove durable completion receipts and their recovery path.
+  State-file import and `migrate-state` report database failures with fixed
+  step descriptions, preventing SQLite trigger errors from printing imported
+  values (#726).
+- Serve identical eval code-arm usage guidance through text, structured content, resource aliases and guest skills. Require clean matching runtime and task/harness provenance before evaluating the registered A/B decision; explicit mismatch diagnostics mark decisions NON-COMPARABLE.
+- Require strict per-trial model, CLI, task and deadline provenance before the eval A/B decision. Count timeout, interruption and runner errors as failures regardless of cached status, report failure kinds per arm, and derive native code-arm skill manifests from the exact served guide bytes.
+- Clarify the cross-connector join eval to select the highest-MRR customer with an open bug, and accept value-mode retained-result notices in the result-paging grader while preserving same-ID paging and single-fetch checks.
+- **Breaking:** Keep default direct-call data and truncation previews visible in clients that prefer structured content. Successful `call_tool` and `call_destructive_tool` results with `resultMode` omitted or set to `"mcp"` now omit `structuredContent`, including its former `format` and paging fields. These tools also stop advertising `outputSchema`.
+  
+  Migrate clients to read result data from `content` and format from `_meta["dev.connecta/format"]` instead of `structuredContent.format`. For truncated default-mode results, parse the first line of the content text as a JSON notice to read `resultId`, `nextOffset`, and `nextAction`, then page with `connecta.result`. Clients that need a structured envelope can request `resultMode: "value"` and keep reading `structuredContent.format` and the paging notice in `structuredContent.data`. Remove assumptions that either direct-call tool advertises an `outputSchema`; use content handling or the value-mode envelope instead. Value-mode and error envelopes retain their complete JSON mirrors.
+- Require storage-side proof of expiry before pruning stash capacity charges, so an ahead caller clock cannot admit another stash while charged chunks remain readable.
+- Make stash charge deadline tests deterministic under runner load across memory, SQLite, and D1.
+- Page oversized call results inside programs through the existing result stash. Reconstruct bounded values across executors and return pageable handles for larger results, keeping completed writes successful and avoiding duplicate downstream calls. Preserve U+FEFF at result and page starts in program reconstruction and direct paging. Report unpageable oversized raw text containing unpaired UTF-16 surrogates without silently replacing its code units.
+- Issue compact downstream-OAuth handoff URLs with opaque, unpadded base64url tokens so agents can copy them intact. Preserve exact signature verification, all identity and lifetime checks, and pre-upgrade links until their original expiry. Authorization guidance now tells agents to copy the URL unchanged and request a fresh link when it is invalid or expired.
+- Stash oversized execute_code returns behind a pageable resultId, preserving the full redacted value without repeating completed writes. Share direct-call expiry, authority checks, page caps, and capacity limits; keep bounded truncation when paging is unavailable. Skill and catalog reads retain their grant dependencies through subsequent return stashes, including caught resolution failures and recovery metadata. Local guides follow connector visibility under exact-tool grants; downstream skills and resources retain whole-connector enforcement. Write warnings reflect only writes completed during the current run.
+- Count Claude eval runner cleanup after successful conversation completion as a normal exit in paired comparisons.
+  Accept numeric 143 or signal SIGTERM only after successful completion and a harness SIGTERM sent before any observed child exit.
+
+### Security
+
+- Redact submitted `writeOnly` argument values, including property names inside private objects and their encoded forms, from downstream results, errors, resource reads, connector usage guides, downstream skill files, program returns, logs, and emits before they reach agents, guest programs, or result paging storage. JSON results stay valid, with matching numbers and booleans replaced by a placeholder string, and nested JSON strings are decoded and checked. Short private values redact only equal structured fields and withhold prose that contains them, so identifiers and approval state remain; empty strings are exempt. Matching costs amortized constant work per scanned character regardless of how many values are registered, plus one budgeted confirmation per length where a long value's prefix appears; the matcher's memory, including at most 16 Ki runs of waiting confirmations per scanned text, is bounded across every credential and private value, and text that needs more work or runs is withheld. Redaction walks results iteratively and copies only what changes, so an oversized or deeply nested downstream result can no longer exhaust the heap or stack before paging, and one bounded work budget per redaction withholds only the affected field.
+
 ## 0.29.0 — 2026-10-08
 
 Connecta 0.29.0 adopts the MCP 2026-07-28 request envelope, binding client capabilities and client identity to each request. `server/discover` advertises the extensions served and private cache hints. Connecta-owned access, pool and deadline refusals return JSON-RPC errors; admission codes move to `-33001` and `-33002`. Modern clients must preserve the protocol-version and declared argument headers. `tools.listChanged` is false, and `subscriptions/listen` remains unsupported.

package/README.md

@@ -2,149 +2,144 @@
 
 ![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
-One MCP endpoint. The integrations you chose. Your agent reaches them by
-writing code instead of loading a thousand tool definitions.
+One connection between your agent and the services you choose.
+
+Connecta brings your MCP servers and HTTP APIs together behind one endpoint.
+Connect your agent once, then choose which integrations it can use. You run
+Connecta yourself, on your own machine or infrastructure.
 
 ## The mental model
 
-You ask your agent a question that touches a service — Linear, Stripe, an
-internal API, anything you have connected. Here is what happens:
+Ask your agent to find open issues, compare them with customer feedback, or
+prepare a report. Connecta gives it a small set of tools for finding and using
+the services you connected, without loading every service's tool definitions
+into the conversation.
+
+The agent writes a short program that runs in a sandbox beside those
+integrations. It can gather results, combine them, and return the parts that
+answer your question. Fifty issues can become a short list grouped by owner
+before the result reaches the conversation. The agent writes the code; you
+ask for the work.
+
+```mermaid
+flowchart LR
+    Agent["Your agent"] <-->|"One connection"| Connecta["Your Connecta deployment"]
+    Connecta <--> Work["Work tools<br/>Linear, GitHub, Notion"]
+    Connecta <--> Business["Business services<br/>Stripe, RevenueCat, Mixpanel"]
+    Connecta <--> Yours["Your other services<br/>Remote MCP servers and HTTP APIs"]
+
+    style Connecta fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
+```
+
+You choose which services to connect and who can use them. Your agent keeps
+the same connection as those services change.
 
-1. The agent talks to one endpoint, yours, and sees six tools. Always six,
-   no matter how many services sit behind it.
-2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
-   your integrations. The program can search for tools, call them, chain the
-   calls, and shape the result.
-3. Only the answer comes back into the agent's context — not raw pages of
-   API output.
-4. If the agent wants to change something — create, update, delete — it
-   can do that from a program in a `trusted` pool. A `read-only` pool
-   routes each write through `call_destructive_tool`. The host controls approval; trusted endpoints annotate `execute_code` as a
-   write. Pool trust defaults to `read-only`.
+## From a question to an answer
 
-Credentials never leave the server. The program never sees them, and neither
-does the agent.
+Say you ask, "Which open issues affect our highest-value customers?" Your agent
+can gather information from your issue tracker and customer records, combine
+it inside Connecta, and bring back a focused answer.
 
 ```mermaid
 flowchart TB
-    Client["Your MCP client<br/>Claude, Cursor, …"]
+    Question["You ask a question"] --> Plan["Your agent works out what to look up"]
+    Plan --> Gather["A program in Connecta gathers the relevant records"]
+    Gather --> Tracker["Open issues from your tracker"]
+    Gather --> Customers["Customer records from a connected service"]
+    Tracker --> Combine["The program matches, filters, and groups the results"]
+    Customers --> Combine
+    Combine --> Answer["Your agent explains the answer"]
+
+    style Combine fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
+    style Answer fill:#dcfce7,stroke:#15803d,color:#14532d
+```
 
-    subgraph Connecta["Connecta — one endpoint, six tools, your credentials"]
-        Sandbox["execute_code<br/>the agent's program runs here<br/>reads, plus writes<br/>in trusted pools"]
-        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
-    end
+The records are an example; the available information depends on the services
+and access you have configured. Processing results inside Connecta keeps the
+conversation focused on the answer.
 
-    Integrations["The integrations you chose<br/>Linear · Stripe · Notion · Vercel · your HTTP API · any MCP server"]
+## What you can do with it
 
-    Client -->|"one connection"| Sandbox
-    Client --> Explicit
-    Sandbox -->|"reads"| Integrations
-    Explicit -->|"writes"| Integrations
-```
+Connect hosted MCP services, add an internal HTTP API, and let the agent work
+across them in one task. Changing your connected services does not require
+changing the agent's connection. Your deployment decides which services and
+operations each caller can reach.
+
+Connecta includes maintained connections for <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Infisical, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, and Vercel<!-- providers:end -->.
+Each connection has its own setup guide.
+Notion, Vercel, and Cloudflare offer hosted MCP connections and selected HTTP
+API capabilities. You can also connect other remote MCP servers or define the
+operations you need from an HTTP API.
+
+Google Workspace connections use the account your deployment assigns to each
+signed-in person. A Workspace administrator authorizes them for your domain.
+Gmail reads mail and writes drafts, but does not send mail. Google Drive can
+read, write, and share files, but does not permanently delete them. Available
+operations and account access depend on the integration and your deployment.
+
+Large results need not fill the conversation. The agent can filter and
+summarize them in its program, or read a large result in smaller pieces.
 
-This is the kind of thing the agent writes, not you:
-
-```js
-async () => {
-  const { data: { nodes } } = await connecta.call("tracker.list_issues", { state: "started" });
-  const byOwner = {};
-  for (const issue of nodes) {
-    (byOwner[issue.assignee?.name ?? "unassigned"] ??= []).push(issue.identifier);
-  }
-  return byOwner;
-}
+## Writes, credentials, and access
+
+Connecta distinguishes reads from writes. By default, programs can read, and
+each change uses a separate visible tool call. Your agent's host controls
+whether it asks for approval. You can explicitly allow programs to make
+changes too; the host then sees the program tool as a write. This choice does
+not give a caller access to additional services.
+
+```mermaid
+flowchart TB
+    Change["Your agent wants to change something"] --> Choice{"Are programs allowed<br/>to make changes?"}
+    Choice -->|"Default: no"| Separate["A separate visible call for each change"]
+    Choice -->|"Explicit choice: yes"| Program["A program that can make changes"]
+    Separate --> Host["Your agent's host handles approval"]
+    Program --> Host
+    Host --> Access["Connecta checks the caller's access"]
+    Access --> Services["The connected service receives the change"]
+
+    style Host fill:#fef3c7,stroke:#b45309,color:#78350f
+    style Access fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:2px
 ```
 
-Fifty issues in, one small object out. Your context window notices.
+Connecta handles integration credentials on the server. Its sandbox does not
+receive them. Optional encrypted storage protects saved credentials. Connections can use
+shared credentials or a person's own account, with access rules set by the
+deployment owner. Permission to use a connection is separate from permission
+to manage its credentials.
 
-## What you can do with it
+People sign in through Clerk on Node or Cloudflare Access on Workers. Machine
+clients use tokens issued by your Connecta deployment. A deployment can serve
+several people within one tenant, each with the access you assign.
+
+## A place to see your connections
 
-- **Put every MCP server you use behind one connection.** Add or remove
-  services in a config file; your client never changes.
-- **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
-  generated tool sprawl is the problem, not the fix.
-- **Use maintained connections** for <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, and Vercel<!-- providers:end -->: known endpoints, auth defaults, and
-  vetted read/write classifications, imported one at a time.
-  Cloudflare, Notion, and Vercel each let the deployment choose their
-  hand-written API interface or official hosted MCP. Planning Center, Overflow,
-  Tithe.ly, Breeze, and Church Community Builder are hand-written over their
-  whole APIs, with every money-moving write behind approval. Gmail reads mail
-  and writes drafts — never sends — and Google Drive reads, writes, and shares
-  files — never deletes one for good — as each signed-in Workspace user through
-  domain-wide delegation, with no per-user consent step; Google Docs reads and
-  edits documents, and Google Sheets reads and writes spreadsheets, the same
-  way. Google Slides reads, creates, edits, and comments on each user's decks the
-  same way.
-  Google Forms reads and edits forms and reads their responses the same way.
-- **Let the agent work in code.** Search, chain, filter, join, and reduce
-  inside the sandbox instead of round-tripping every call through the model.
-- **Teach undeclared result shapes by using them.** Successful read-only calls
-  retain field names and broad types in bounded runtime memory, never scalar
-  values, so later programs can project a remote MCP result its provider never
-  documented.
-- **Keep large results usable.** Oversized direct calls return a bounded
-  preview with a handle for paging through the rest. For read-only work, the
-  notice also points the agent to reduce or search the result inside a
-  program. Discovery can show compact schemas, exact JSON Schema, or a
-  TypeScript signature to read while writing JavaScript.
-- **Keep writes deliberate.** The registry classifies tools as reads or writes.
-  Read-only pools route writes through `call_destructive_tool`; trusted pools
-  let programs write and annotate `execute_code` as a write. The host controls
-  approval. Exact deployment classification overrides beat provider review
-  and downstream annotations.
-- **Run it on Node or Cloudflare Workers.** The core is shared; each deployment
-  supplies its platform's executor and one store: a D1 database on Workers
-  (`@zackbart/connecta/d1`), a SQLite file on Node (`@zackbart/connecta/sqlite`).
-  The Node template also runs unchanged in Docker.
-
-Deployments explicitly compose optional features: `operatorUi()` from
-`@zackbart/connecta/ui`, `encryptedCredentialVault()` from `/credentials`,
-`activityHistory()` from `/activity`, and
-inbound authentication adapters from `/auth/*`. Omit a module and its implementation does no runtime work. Core
-keeps connector discovery, execution, invocation, and enforcement together.
-Both deployment shapes write configuration as `defineConfig((env) => …)`, with
-each optional module a type-checked expression the environment switches on.
-`createConnecta` validates it against one schema — an unknown option or an
-unusable value refuses to boot — and `connecta.describeConfig()` returns a
-secret-free snapshot of what the deployment runs with. With `operatorUi()` enabled,
-`GET /ui/api/config` returns that snapshot scoped to the caller, live connector
-facts, and the caller's grants and permissions. `CONNECTA_TOKEN=<bearer> connecta
-doctor --config --url https://connecta.example` prints only the scoped snapshot
-as JSON, using the same serializer. It does not run the diagnostic program.
-
-The optional UI has Overview, Connectors, Tools, Access, Activity and
-Config pages. Connector detail separates configuration, schemas, authentication,
-activity and diagnostics into tabs. Overview shows health, attention items and
-endpoint setup in a drawer; Config marks each snapshot value as default or
-configured. Catalog descriptions and schemas render as text. Activity filters
-stay in the URL and calls group by recorded request id. Authentication, history,
-and token controls use the signed-in person's existing permissions.
-Connector selection and access rules remain in deployment code.
-
-One deployment may serve several authenticated people inside the same tenant.
-Cloudflare Access supplies Worker identity; Node uses Clerk for human auth. Machine clients use connecta-issued `cta_`
-access tokens. Static bearer secrets are retired. Connecta owns no accounts or groups. Shared-credential administration and personal connection
-setup require separate explicit permissions, both denied by default. See
-[inbound auth](./documentation/auth.md#principals-visibility-and-operators).
-Clerk deployments enable `aud_claim_enabled` and use resource-bound JWT or
-opaque OAuth tokens by default. An explicit `allowedOAuthClientIds` list is a
-fallback for unbound tokens from dedicated clients. Clerk session
-tokens authenticate operator routes only; [Clerk auth](./documentation/auth.md#clerk-oauth-tokens-and-operator-sessions)
-describes endpoint audience validation and the configuration migration.
-
-Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
-service. The [principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md)
-state the goals and invariants; [decision records](https://github.com/zackbart/connecta/tree/main/decisions)
-explain past choices.
+The optional operator UI shows connected services, available tools, access,
+and configuration. Authorized people can connect accounts, manage credentials,
+and issue client tokens. Optional activity history shows who called what,
+when, and whether it worked, without recording arguments, results, or program
+code. The UI's controls follow the signed-in person's permissions.
+
+Your agent or developer changes the integrations and access rules in deployment
+code. The UI helps you inspect them and manage authentication.
+
+## Where it runs
+
+Run Connecta locally or on a server with Node, including in Docker, or host it
+on Cloudflare Workers. Both offer the same agent tools. Running programs on
+Workers requires Cloudflare's Workers Paid plan.
 
 ## Getting started
 
-Setup is written for an agent. Point yours at [`AGENTS.md`](https://github.com/zackbart/connecta/blob/main/AGENTS.md) and
-ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers the architecture, the six tools,
-code mode, and inbound auth if you want to go deeper. When upgrading an
-existing deployment, each [changelog](./CHANGELOG.md) release opens with what
-breaks and what a deployment can ignore.
+Give your agent the [agent documentation](./documentation/README.md) and ask it
+to set up Connecta with the integrations you want. Tell it where you want to
+run it and who should have access. The setup guides cover Node, Docker, and
+Cloudflare Workers, including connecting your agent client.
+
+<a id="existing-client-tokens"></a>
+
+For an existing deployment, ask your agent to follow the
+[upgrade guidance](./documentation/deploying.md#upgrade-an-existing-deployment).
 
 ## Status
 
@@ -152,13 +147,7 @@ Built for its author's deployments first and published openly. Breaking
 changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
 [security policy](./SECURITY.md).
 
-### Existing client tokens
-
-Upgrading from v0.23 does not require rotating managed `cta_…` tokens. Import
-`accessTokens` from `@zackbart/connecta/auth/access-tokens`, replace the old
-`accessTokens: true` with `accessTokens: accessTokens(storage)`, and keep the
-same persistent storage namespace and identity/tool/pool grant rules. Enable
-`identity.accessTokenManagement` only for the interactive operators who should
-manage tokens. Records written by v0.23 and later move with the store: a 0.28
-JSON state file migrates with `connecta migrate-state`, and a D1 table is
-read as is. See the package's `documentation/auth.md` for the migration.
+The [principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md)
+state the goals and tested rules. [Decision records](https://github.com/zackbart/connecta/tree/main/decisions)
+explain past choices. [GitHub issues](https://github.com/zackbart/connecta/issues)
+track planned work; a plan is not a shipped feature.

package/bin/connecta.mjs

@@ -276,7 +276,13 @@ async function migrateState() {
   }
   const [statePath, databasePath] = args.map((arg) => resolve(process.cwd(), arg));
   const { importStateFile, openSqlite } = await import(pathToFileURL(join(packageRoot, "dist", "sqlite.js")).href);
-  const database = openSqlite(databasePath);
+  let database;
+  try {
+    database = openSqlite(databasePath);
+  } catch {
+    throw new Error("State migration failed: could not open the SQLite database");
+  }
+  let closeFailed = false;
   try {
     const result = importStateFile(database, statePath);
     console.log(
@@ -284,8 +290,13 @@ async function migrateState() {
         ` (${result.kept} already present, ${result.expired} expired).`,
     );
   } finally {
-    database.close();
+    try {
+      database.close();
+    } catch {
+      closeFailed = true;
+    }
   }
+  if (closeFailed) throw new Error("State migration failed: could not close the SQLite database");
 }
 
 try {

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.29.0";
+export const CONNECTA_VERSION = "0.30.0";

package/dist/argument-redaction.js

@@ -0,0 +1,230 @@
+const PUBLIC = {};
+const OMIT = { omit: true };
+const OMITTED = Symbol("omitted argument");
+const MAX_DEPTH = 32;
+const MAX_SCHEMAS = 2048;
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sensitive(plan) {
+    return Object.keys(plan).length > 0;
+}
+function equal(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function item(plan, index) {
+    return plan.prefix?.[index] ?? plan.items ?? PUBLIC;
+}
+/** Combine restrictions from references, siblings, and allOf without losing array indices. */
+function merge(left, right) {
+    if (left.omit || right.omit)
+        return OMIT;
+    const names = new Set([...Object.keys(left.properties ?? {}), ...Object.keys(right.properties ?? {})]);
+    const properties = Object.fromEntries([...names]
+        .sort()
+        .map((name) => [
+        name,
+        merge(Object.hasOwn(left.properties ?? {}, name) ? left.properties[name] : PUBLIC, Object.hasOwn(right.properties ?? {}, name) ? right.properties[name] : PUBLIC),
+    ]));
+    const items = mergeItems(left.items ?? PUBLIC, right.items ?? PUBLIC);
+    const prefix = Array.from({ length: Math.max(left.prefix?.length ?? 0, right.prefix?.length ?? 0) }, (_, index) => mergeItems(item(left, index), item(right, index)));
+    // Equivalent plans compare equally even when one schema spells out public prefixes.
+    while (prefix.length && equal(prefix.at(-1), items))
+        prefix.pop();
+    return {
+        ...(names.size ? { properties } : {}),
+        ...(prefix.length ? { prefix } : {}),
+        ...(sensitive(items) ? { items } : {}),
+    };
+}
+function mergeItems(left, right) {
+    if (!sensitive(left))
+        return right;
+    if (!sensitive(right))
+        return left;
+    return merge(left, right);
+}
+/** Compile a bounded plan. Unknown sensitivity refuses the entire echo, never just a branch. */
+function compile(root, unionAlternatives = false) {
+    let visited = 0;
+    const active = new Set();
+    const unresolved = () => {
+        throw new Error("Unresolved argument sensitivity");
+    };
+    function reference(ref) {
+        if (typeof ref !== "string" || !ref.startsWith("#"))
+            return unresolved();
+        const pointer = decodeURIComponent(ref.slice(1));
+        if (pointer === "")
+            return root;
+        if (!pointer.startsWith("/"))
+            return unresolved();
+        let target = root;
+        for (const encoded of pointer.slice(1).split("/")) {
+            if (/~[^01]|~$/.test(encoded))
+                return unresolved();
+            const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+            if (target === null || typeof target !== "object" || !Object.hasOwn(target, key))
+                return unresolved();
+            target = target[key];
+        }
+        return target;
+    }
+    function walk(schema, depth) {
+        if (++visited > MAX_SCHEMAS || depth > MAX_DEPTH)
+            return unresolved();
+        if (typeof schema === "boolean")
+            return PUBLIC;
+        if (!object(schema) || active.has(schema))
+            return unresolved();
+        if (schema["writeOnly"] !== undefined && typeof schema["writeOnly"] !== "boolean")
+            return unresolved();
+        if (schema["writeOnly"] === true)
+            return OMIT;
+        if ((schema !== root && schema["$id"] !== undefined) ||
+            schema["$dynamicRef"] !== undefined ||
+            schema["$recursiveRef"] !== undefined)
+            return unresolved();
+        active.add(schema);
+        try {
+            let plan = PUBLIC;
+            const child = (value) => walk(value, depth + 1);
+            if (schema["$ref"] !== undefined)
+                plan = merge(plan, child(reference(schema["$ref"])));
+            if (schema["properties"] !== undefined) {
+                if (!object(schema["properties"]))
+                    return unresolved();
+                const properties = Object.entries(schema["properties"])
+                    .map(([name, value]) => [name, child(value)])
+                    .filter(([, value]) => sensitive(value))
+                    .sort(([a], [b]) => a.localeCompare(b));
+                plan = merge(plan, properties.length ? { properties: Object.fromEntries(properties) } : PUBLIC);
+            }
+            const prefixes = schema["prefixItems"] ?? (Array.isArray(schema["items"]) ? schema["items"] : undefined);
+            if (prefixes !== undefined && !Array.isArray(prefixes))
+                return unresolved();
+            if (schema["prefixItems"] !== undefined && Array.isArray(schema["items"]))
+                return unresolved();
+            const tail = Array.isArray(schema["items"]) ? schema["additionalItems"] : schema["items"];
+            const arrayPlan = {
+                ...(prefixes ? { prefix: prefixes.map(child) } : {}),
+                ...(tail !== undefined ? { items: child(tail) } : {}),
+            };
+            plan = merge(plan, arrayPlan);
+            for (const keyword of ["allOf", "oneOf", "anyOf"]) {
+                const branches = schema[keyword];
+                if (branches === undefined)
+                    continue;
+                if (!Array.isArray(branches) || !branches.length)
+                    return unresolved();
+                const plans = branches.map(child);
+                if (keyword === "allOf" || unionAlternatives)
+                    for (const branch of plans)
+                        plan = merge(plan, branch);
+                else {
+                    if (plans.some((branch) => !equal(branch, plans[0])))
+                        return unresolved();
+                    plan = merge(plan, plans[0]);
+                }
+            }
+            // These applicators need matching/evaluation rules we do not implement.
+            // Public-only schemas are harmless; sensitivity or an unresolved reference fails closed.
+            for (const keyword of [
+                "additionalProperties",
+                "unevaluatedProperties",
+                "unevaluatedItems",
+                "contains",
+                "not",
+                "if",
+                "then",
+                "else",
+            ])
+                if (schema[keyword] !== undefined && sensitive(child(schema[keyword])))
+                    return unresolved();
+            for (const keyword of ["patternProperties", "dependentSchemas", "dependencies"]) {
+                if (schema[keyword] === undefined)
+                    continue;
+                if (!object(schema[keyword]))
+                    return unresolved();
+                for (const value of Object.values(schema[keyword])) {
+                    if (keyword === "dependencies" && Array.isArray(value))
+                        continue;
+                    if (sensitive(child(value)))
+                        return unresolved();
+                }
+            }
+            return plan;
+        }
+        finally {
+            active.delete(schema);
+        }
+    }
+    return walk(root, 0);
+}
+/** Omit whole array values when private elements cannot be removed without shifting indices. */
+function apply(value, plan, mark, depth = 0) {
+    if (!sensitive(plan))
+        return value;
+    if (depth > MAX_DEPTH)
+        throw new Error("Argument redaction depth exceeded");
+    if (plan.omit) {
+        mark(value);
+        return OMITTED;
+    }
+    if (Array.isArray(value)) {
+        const values = value.map((entry, index) => apply(entry, item(plan, index), mark, depth + 1));
+        return values.includes(OMITTED) ? OMITTED : values;
+    }
+    if (!object(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([name, entry]) => {
+        const field = Object.hasOwn(plan.properties ?? {}, name) ? plan.properties[name] : PUBLIC;
+        const filtered = apply(entry, field, mark, depth + 1);
+        return filtered === OMITTED ? [] : [[name, filtered]];
+    }));
+}
+/** Output redaction protects the union of private fields across alternatives.
+ * Other sensitivity rules and unresolved-schema handling follow echo redaction. */
+export function visitPrivateCallArguments(args, schema, visit) {
+    // Public-only schemas need no sensitivity compilation, regardless of size.
+    // Iterative traversal visits each object once, including definitions and cycles.
+    const pending = [schema];
+    const seen = new Set();
+    let privateSchema = false;
+    while (pending.length) {
+        const value = pending.pop();
+        if (value === null || typeof value !== "object" || seen.has(value))
+            continue;
+        seen.add(value);
+        if (Object.hasOwn(value, "writeOnly") && value["writeOnly"] === true) {
+            privateSchema = true;
+            break;
+        }
+        for (const entry of Object.values(value))
+            pending.push(entry);
+    }
+    if (!privateSchema)
+        return;
+    try {
+        apply(args, compile(schema, true), visit);
+    }
+    catch {
+        // When a private annotation exists but its location cannot be resolved,
+        // treat every submitted value as private, just as the echo is withheld.
+        visit(args);
+    }
+}
+/** Internal schema filter; the single echo helper owns snapshotting and byte budgeting. */
+export function redactCallArguments(args, schema) {
+    try {
+        const plan = compile(schema);
+        let redacted = false;
+        const value = apply(args, plan, () => {
+            redacted = true;
+        });
+        return { ...(value !== OMITTED ? { value } : {}), redacted };
+    }
+    catch {
+        return { redacted: true };
+    }
+}