@zackbart/connecta 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,105 @@
 
 All notable changes to this package are documented here.
 
+## 0.31.0 — 2026-10-09
+
+Connecta 0.31.0 lets the auth mode choose how Stripe, Notion, Cloudflare and Vercel connect (#801). `auth: { type: "oauth" }` connects the vendor's hosted MCP server, OAuth only. A key connects Connecta's own REST connector with an operator-managed credential: Stripe `apiKey`, Notion `token`, Cloudflare `apiToken` or `globalApiKey`, and Vercel `token`. Each implementation is now complete on its own. This replaces the 0.29 split, in which the hosted server owned writes and the REST surface refused them, so a Cloudflare API token could not change a DNS record. Decision record 0005 explains the choice. Deployments that use none of these four providers need no changes.
+
+The timing comes from Stripe. Its hosted MCP server stops accepting `sk_` secret keys and untagged `rk_` restricted keys on 2026-10-31, so a deployment that sends one of those keys to `mcp.stripe.com` loses Stripe on that date. Upgrade before then. Stripe still documents agent-tagged restricted keys for its MCP server, but Connecta's hosted Stripe connection is now OAuth only, and every Stripe key, tagged or not, uses the REST connector. For these four providers, Connecta no longer sends a bearer key, literal header or operator credential to the hosted MCP server. Other hosted providers, such as RevenueCat, Mixpanel and GitHub, are unchanged.
+
+Every key connector serves the same four tools. `<vendor>_api_search` and `<vendor>_api_details` read an operation index compiled from the vendor's pinned OpenAPI document. `<vendor>_api_read` and `<vendor>_api_write` check each call's path and parameters against that index before sending it, and return `{ status, data, page? }`. The read tool admits GET plus reviewed read-only POSTs such as Stripe's invoice preview, Cloudflare analytics and Vercel observability queries. Each vendor keeps a few named tools. Stripe POST writes send the caller's `idempotencyKey`, or a generated one, as `Idempotency-Key` and return it; DELETE writes send none. When a deadline interrupts one of those POST writes, or its outcome is otherwise unknown, `uncertainCall.recovery` carries the generated key, or a caller-supplied key of at most 128 characters. A longer caller key is still sent to Stripe but not echoed there, since the caller already has it. Every Stripe request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the pinned index's version, whatever the account's default API version. Response shapes and accepted parameters follow that version, so check the fields programs rely on with `stripe_api_details`. Stripe's `connectedAccount` now works with an operator-managed key. `npm run providers:check` reports when a pinned index falls behind the vendor's live document.
+
+Most existing configurations of these providers need edits. `auth` is now required, with no default, and omitting it throws an error that lists the valid types. `surface` is removed from Notion, Vercel and Cloudflare, along with Cloudflare `authentication` and its `credential` override. Stripe loses literal `headers` auth and hosted `credential` auth. Cloudflare bearer-token auth to `mcp.cloudflare.com` is removed, so those deployments move to `apiToken` and its REST tools. A credential stored under the same connector id carries over; run its Test action after upgrading.
+
+Tool names change on the key paths. Cloudflare's `cloudflare_api_get` and `cloudflare_api_mutate` become `cloudflare_api_read` and `cloudflare_api_write`. `verify_api_token` and `verify_global_api_key` become `verify_credential`. Cloudflare's 23 hand-written reads give way to `cloudflare_api_read`, which returns unprojected results. Vercel's `vercel_api_get` and `vercel_api_mutate` become `vercel_api_read` and `vercel_api_write`, and `verify_project_domain`, `remove_project_domain` and `delete_deployment` are removed. Notion's token connector drops eight `integration_*` tools in favor of the generic ones. Stripe keeps its tool names with Connecta's contracts, but natural-language Sigma, metrics, docs search, the planner, reports and feedback exist only on the OAuth connection.
+
+Several exports are removed. Cloudflare loses `CloudflareApiOptions`, `CloudflareMcpOptions`, `CloudflareConnectionOptions` and `CloudflareAuthentication`, plus `CLOUDFLARE_DNS_RECORD_TYPES` and `CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`. Notion and Vercel lose their `ApiOptions`, `McpOptions` and `ConnectionOptions` types, and Stripe loses `StripeHeaderOptions`. Each `<Vendor>Options` is now a union of per-auth types, such as `StripeApiKeyOptions`, `NotionTokenOptions`, `VercelTokenOptions` and `CloudflareGlobalApiKeyOptions`.
+
+A Cloudflare Global API Key reaches every account and zone its user can reach. `auth: { type: "globalApiKey" }` therefore requires `pin: { accountIds, zoneIds }` unless the configuration states `unpinned: true`. It never writes `/user` or `/memberships`. Pins deny by default and also apply to GraphQL tags and list results. An operation that names no account or zone is refused unless it was reviewed as safe. Pins are optional for scoped API tokens. A Global API Key cannot reach R2.
+
+Every key connector applies one reviewed value-safety table. No REST tool response, success or error, returns a credential that grants access to the vendor or a third party, or a stored secret value. Operations that mint or hand out credentials are refused before they are sent. Stored secrets read as `"[redacted]"`. URLs that act as capabilities keep only their scheme and host, or lose their signing parameters. Reviewed operations withhold the vendor's error text unless their review keeps it. Results therefore lose fields they used to return. Stripe withholds client secrets, webhook signing secrets, Issuing card numbers and CVCs, and Checkout Session URLs other than those of guest payment sessions. Notion strips the signatures from pre-signed file URLs, so a returned file URL no longer downloads. Vercel returns `"[redacted]"` for environment values and header rule values. Cloudflare redacts Hyperdrive passwords, dispatch binding values and transform-rule header values. The guarantee assumes an honest vendor server and covers only the REST key connectors. Secrets that people type into free text, names or identifiers are out of scope. Hosted OAuth connections fall outside it: they return what the vendor's server returns, under Connecta's existing credential and `writeOnly` redaction.
+
+The four provider entries now carry both transports and a pinned index. Measured gzip, Stripe grows from 171 KB to 243 KB, Notion from 191 KB to 216 KB, Vercel from 190 KB to 231 KB and Cloudflare from 193 KB to 338 KB, all within their stated caps. Vercel admits only reviewed and approved MCP clients to its hosted server. If it refuses authorization for that reason, the deployment needs Vercel's approval or a token connector. Vercel's hosted connection now lists its four environment variable tools. The two that can return decrypted values are classified as writes. Cloudflare's hosted `execute` is always a write, so a read-only pool on a Cloudflare OAuth connector reaches only `search`. Use an API token for read-only API access. Agent evals against fake vendors for all four providers are planned. `documentation/provider-auth-migration.md` gives the step-by-step migration for each provider.
+
+### Changed
+
+- **Breaking:** `cloudflare()` now requires `auth`, which selects the implementation. `auth: { type: "oauth" }` connects Cloudflare's hosted MCP server (`search` and `execute`), OAuth only; bearer-token and credential auth to `mcp.cloudflare.com` are removed. `auth: { type: "apiToken" }` and `auth: { type: "globalApiKey" }` connect Connecta's own REST connector to the v4 API with an operator-managed credential: `cloudflare_api_search` and `cloudflare_api_details` read a pinned Cloudflare API index (3,336 operations, deprecated ones dropped), `cloudflare_api_read` (GET plus 47 reviewed read-only POSTs such as analytics, Analytics Engine and Log Explorer SQL, and KV bulk get) and `cloudflare_api_write` check every call against that index before sending it and return `{ status, data, page? }` with the envelope unwrapped, and the named tools are `verify_credential`, `list_accounts`, `list_zones`, `graphql_query` (read-only, refuses mutations), and `cloudflare_api_upload`. `accountId` and `zoneId` fill path placeholders; `pin: { accountIds, zoneIds }` restricts every call by default deny (an operation naming no account or zone is refused unless reviewed safe), including GraphQL tags and list results, and is required for a Global API Key unless `unpinned: true`. A reviewed value-safety table derived from the pinned spec gives every credential-bearing operation a verdict: credential producers (API tokens, Access service tokens, R2 temporary credentials, signing keys, direct-upload URLs, and more) and payment secrets are refused, stored and embedded secrets and environment and plain-text binding values are redacted on every method and tool, and operations that take or return credentials withhold vendor error text; URL Scanner captures are refused; a pinned connector's GraphQL documents hold one query and only fragments it uses, and a key-name, typed-secret, and URL-credential heuristic backs it up; a Global API Key never writes `/user` or `/memberships`. `surface`, `authentication`, `credential` overrides, the API-token mutation refusals, `verify_api_token`, `verify_global_api_key` (now `verify_credential`), `cloudflare_api_get`, `cloudflare_api_mutate`, the 23 hand-written reads from `get_zone` and `list_dns_records` to `list_pages_domains` (use `cloudflare_api_read`), `CLOUDFLARE_DNS_RECORD_TYPES`, `CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`, and the `CloudflareApiOptions`, `CloudflareMcpOptions`, `CloudflareConnectionOptions`, and `CloudflareAuthentication` types are removed. See the provider auth migration guide.
+- Record that the auth mode selects the provider implementation: OAuth uses the vendor's hosted MCP and keys use a Connecta REST connector, superseding the hosted MCP ownership rule for Stripe, Vercel, Cloudflare and Notion (decision record 0005). Each provider's change is its own entry.
+- **Breaking:** `notion()` now requires `auth`, which selects the implementation, and `surface` is removed. `auth: { type: "oauth" }` connects Notion's hosted MCP server as the signed-in user, OAuth only, with the same reviewed catalog. `auth: { type: "token" }` connects Connecta's REST connector to `api.notion.com` as an internal integration with an operator-managed token: `notion_api_search`, `notion_api_details`, `notion_api_read`, and `notion_api_write` reach every operation in a pinned Notion API index (with the sent `Notion-Version` pinned to it), check each call against it before sending, admit Notion's read-only POST queries on the read tool, and return `{ status, data, page? }`, where `page.in: "body"` marks a body-borne cursor, `page.path` names a view query's continuation, and `hasMore` without `next` marks a cursorless cut-off such as meeting notes' limit. The token connector keeps `integration_search`, `integration_get_page`, `integration_get_page_content`, `integration_get_data_source_schema`, `integration_query_data_source`, `integration_create_page`, and `integration_append_blocks` (which now also takes `checklist`); `integration_get_page_property`, `integration_get_database`, `integration_list_users`, `integration_get_self`, `integration_list_comments`, `integration_update_page_properties`, `integration_trash_page`, and `integration_add_comment` are removed in favor of the generic tools. Notion's OAuth token endpoints and multipart file sends are refused. Notion's reconciliation table is retired. `npm run providers:spec` accepts `options.versionHeader` for documents that carry their API version in a header parameter. See the provider auth migration guide.
+- **Breaking:** `stripe()` now requires `auth`, which selects the implementation. `auth: { type: "oauth" }` connects Stripe's hosted MCP server exactly as before, OAuth only. `auth: { type: "apiKey" }` with `mode` (and optional `connectedAccount`) connects Connecta's own REST connector to `api.stripe.com` with an operator-managed secret or restricted key: `stripe_api_search` and `stripe_api_details` read a pinned Stripe API index, `stripe_api_read` and `stripe_api_write` check every call against that index before sending it, form-encode v1 bodies, send v2 bodies as JSON, send `Stripe-Version: 2026-09-30.endive` (the pinned index's version) on every v1 and v2 request whatever the account's default API version, so response shapes and accepted parameters follow it (check them with `stripe_api_details`), return `{ status, data, page? }` with optional `select`, and on every POST write send the caller's `idempotencyKey` or a generated one as `Idempotency-Key` and return it (DELETE sends none); `get_stripe_account_info` and `get_balance_summary` are named reads. A key whose prefix contradicts `mode` is refused before any request, and `connectedAccount` now works with an operator-managed key. Literal `headers` and hosted `credential` auth are removed; omitting `auth` is refused with the valid types. Providers gain the `"dual"` kind, `variants()` accepts a nested discriminant such as `["auth", "type"]`, the operator UI shows whether a provider connector uses hosted MCP or REST, and `npm run providers:spec` compiles pinned OpenAPI documents into operation indexes that `check:providers-generated` checks offline and `providers:check` compares with the live document. A POST write's key also reaches the caller when the response body is lost or the call deadline interrupts it: `write_outcome_unknown` now carries `uncertainCall.recovery` with the generated key, or a caller-supplied key of at most 128 characters (a longer caller key is still sent to Stripe but not echoed, since the caller already has it). See the provider auth migration guide.
+- **Breaking:** `vercel()` now requires `auth`, which selects the implementation, and `surface` is removed. `auth: { type: "oauth" }` connects Vercel's hosted MCP server as before, OAuth only; it now also lists `filter_project_envs`, `get_project_env`, `create_project_env`, and `edit_project_env`, with the two value-returning reads reviewed as writes. `auth: { type: "token" }` with optional `teamId` and `baseUrl` connects Connecta's own REST connector to `api.vercel.com` with an operator-managed access token, complete on its own: `vercel_api_search` and `vercel_api_details` read Vercel's OpenAPI document pinned by content hash, `vercel_api_read` (GET plus reviewed read-only POSTs such as `POST /v2/observability/query`) and `vercel_api_write` check every call against that index before sending it, apply the default team to operations that accept one (`teamId: null` for the personal account), and return `{ status, data, page? }` with `until` or `cursor` pagination. Named tools are `list_teams`, the value-safe environment variable tools, `get_deployment_build_logs`, `get_runtime_logs` (bounded by `waitMs` and `maxRows`), and `vercel_api_upload` for octet-stream operations. Value safety follows a reviewed per-operation table derived from the pinned spec (`scripts/value-safety.mjs` flags every operation whose response may carry a credential or secret value; a test fails on any without a verdict): credential minting, Connect authorization, project transfer requests, decrypted environment values, Global Config items and tokens, a domain move-out, KMS signing, and domain transfer codes are refused; environment values, protection-bypass secrets, deploy hook URLs, drain and webhook headers, signing secrets, and destination URLs beyond their origin, external route and redirect destinations beyond their origin, the args and values of every header, cookie, and query rule (route transforms and conditions, firewall conditions), team invite codes, synced Global Config items, and URL credentials are redacted on every path; a key-name heuristic covers the rest; and secret-family failures carry fixed messages. The 0.29 ownership refusals, reconciliation tables, `vercel_api_get`, `vercel_api_mutate`, `verify_project_domain`, `remove_project_domain`, `delete_deployment`, and the no-op `defaultPageSize` option are removed. See the provider auth migration guide.
+
+### Security
+
+- **Breaking:** Every key connector (Stripe, Notion, Cloudflare, Vercel) now applies one reviewed value-safety mechanism: one detector over each pinned spec (the union of the former Cloudflare and Vercel detectors), one per-vendor table of `refuse`, `redact`, and `safe` verdicts, one redaction engine on every result, and one error policy. Stripe refuses operations that hand out a credential (ephemeral keys, Terminal connection tokens and onboarding links, v1 and v2 account links, login links, account, customer, and billing portal sessions, file link creation, Financial Connections session creation, and the meter event session), refuses Issuing `number` and `cvc` expansions on every Issuing path, and redacts client secrets, webhook and event destination signing secrets, Apps secret payloads, app-install authorization codes, Terminal Wi-Fi passwords, forwarded header values, and Issuing card numbers and CVCs; webhook, file link, and pre-signed import URLs keep only their origin. Resource rules keyed on Stripe's `object` apply these wherever an object appears (expansions, lists, events and their `previous_attributes`). Identity verification URLs are unchanged; a Checkout Session's URL is returned whole only for a provably guest payment session (no `customer`, `customer_account`, customer creation, or saved payment method options) and otherwise keeps only its origin. Notion withholds the signature parameters of pre-signed file URLs and refuses its OAuth endpoints through the table. Cloudflare's review grows by 259 operations, newly redacting Hyperdrive passwords, RealtimeKit storage credentials, transform-rule header values, dispatch binding values, and webhook destinations beyond their origin. Vercel replaces environment values with `"[redacted]"` instead of dropping them, and redacts audit-event invite codes, integration drain headers, and route header values. Where the former engines differed the stricter rule holds: a credential-named field loses its whole value, and every reviewed operation (or one whose request takes a credential-named field) withholds the vendor's error text unless its review keeps it. `providers:spec` (now run under tsx) checks every reviewed path against the pinned response schema. `RestVendor.valueSafety` is required and the `redact` hook is removed; Cloudflare's generated index no longer carries `secrets`. See the provider auth migration guide.
+
+## 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,147 @@
 
 ![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.
+Stripe, Notion, Cloudflare, and Vercel use their hosted MCP servers when you
+sign in with OAuth, and Connecta's own API connections when you use an API key,
+a Cloudflare API token or Global API Key, a Notion integration token, or a
+Vercel access token. 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.
+
+## 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.
 
-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;
-}
+```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
+
+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.
 
-- **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.
+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 +150,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.31.0";