@zackbart/connecta 0.25.0 → 0.26.1

package/AGENTS.md

@@ -4,12 +4,13 @@ This is the canonical instruction file for coding agents. `CLAUDE.md` is a
 symlink to this file so every agent works from the same conventions.
 
 A single MCP endpoint aggregating downstream connectors (remote MCP servers and
-plain HTTP APIs) behind seven meta-tools, `execute_code` among them. Every
+plain HTTP APIs) behind eight meta-tools, `execute_code` among them. Every
 deployment configures an executor, and agents reach connectors by writing
 JavaScript against it. One fetch-native core on Effect behind a Promise API,
-running on both Node and Cloudflare Workers. Two `planned` decisions change
-that picture — resumable writes with an eighth tool, and an artifacts module —
-and until they ship, the code and the guides describe what exists.
+running on both Node and Cloudflare Workers. A program's write pauses until
+`resume_execution` repeats it. One `planned` decision changes that picture — an
+artifacts module — and until it ships, the code and the guides describe what
+exists.
 
 - **[`ethos.md`](./ethos.md) is the constitution.** It states what connecta is
   and isn't, and its decisions table carries a verdict for every shape already
@@ -73,7 +74,7 @@ pins the generated deployment to the CLI package's exact version, restores the
 template `.gitignore` and the `CLAUDE.md` symlink, and refuses to merge into an
 existing path.
 `connecta doctor` verifies a running deployment's health, executor, and exact
-seven-tool surface. The template carries its own `Dockerfile` and
+eight-tool surface. The template carries its own `Dockerfile` and
 `docker-compose.yml`, so the generated project is the container: setup changes
 must keep the root README, the template (source, container files, and README),
 and the `scripts/check-package.mjs` smoke — which builds and runs that

package/CHANGELOG.md

@@ -2,6 +2,393 @@
 
 All notable changes to this package are documented here.
 
+## Unreleased
+
+## 0.26.1 — 2026-09-26
+
+This patch fixes slow OAuth restarts, unbounded downstream authorization waits,
+and operator pages that signed people out after a temporary load failure.
+Connect now opens consent in one click, and browser-facing pages share the
+configured theme. Agent guidance preserves one-time write results and keeps
+an authorized batch in one resumable program. Approval defaults and the eight
+MCP tools are unchanged. No configuration or storage migration is required;
+deployments without the operator UI can ignore the page changes. OAuth starts
+abort downstream work after 30 seconds, but uncancellable storage resets and
+cleanup must finish before the response. Restart reuses a matching client
+registration; a revoked client may still fail at consent or callback and need
+another restart. The Node template now pins 0.26.1.
+
+### Added
+
+- **Continue or restart an operator OAuth start.** `POST /ui/oauth/<id>`
+  takes `?mode=continue` or `?mode=restart`. `restart`, still the default
+  when `mode` is absent, creates a new epoch and clears the grant and
+  discovery while retaining a matching issuer-bound client registration. `continue` hands back the pending
+  authorization URL when it was written in the last ten minutes. Otherwise it
+  starts a flow in the current epoch, reusing a stored registration when one
+  exists. A first connection still registers dynamically. A disconnected
+  connector resets first. A response with a URL now carries `reused`. A continue that reused a
+  URL or found the connection healthy leaves the cached catalog alone. Any
+  other `mode` is a 400. After a `publicUrl` change, continue keeps a client
+  registered for the old callback, which the authorization server refuses;
+  restart recovers. `ConnectorStatus` gains the optional
+  `authorizationReused`, set by `remoteMcp()`'s `startAuth`.
+
+### Changed
+
+- **Pending authorization URLs expire for reuse.** A non-forced `startAuth`,
+  including `authorize_connector` without `force`, reissues a pending URL only
+  when it is under ten minutes old. The pending URL's envelope now records its
+  write time, which older readers ignore. A URL written before this release,
+  or under a pre-epoch generation, starts a fresh flow instead.
+- **OAuth cleanup deletes run concurrently.** A restart's epoch cleanup,
+  `clearPending`, and `invalidateCredentials("all")` keep up to six deletes
+  in flight, the Workers limit on simultaneous connections. Every delete is
+  still attempted, and a falsy rejection now counts as a failure. A retired
+  epoch's manifest is still removed only after all of its values. Catalog
+  invalidation deletes the root and its chunks together under the registry's
+  chunk I/O bound, so a failed root delete no longer skips the chunks.
+
+- Every page connecta renders for a person now shares one token layer and one
+  layout: the operator shell, the OAuth callback, a browser's 404, and the
+  artifact frame follow `branding.theme` and light or dark. The OAuth callback
+  names the outcome in its heading with a status mark, names the connector by
+  title only after the state check, uses `branding.productName` in its copy,
+  and folds the agent fix prompt under "Details for the operator". Refusals
+  stay byte-identical across connectors and paths.
+- A request whose `Accept` names `text/html` gets a themed 404 page; every
+  other client keeps the plain `Not Found` body.
+- Markdown artifacts take the deployment's resolved scheme and tokens instead
+  of the OS palette, and drop an opening `# Heading` that only repeats the
+  title the viewer already shows. The frame waits on the viewer's surface with
+  a loading line, and says so if the page never arrives.
+- Without the operator UI, callback and 404 pages no longer link the default
+  `/favicon.svg`, which only the UI serves.
+- The operator UI starts OAuth in one click. Connect opens the provider's
+  page in a new tab straight away and asks the server to continue a pending
+  authorization rather than restart it; only Reconnect on a healthy
+  connection restarts, behind an in-page confirm. A tab returning to the page
+  quietly re-reads the status of connectors waiting on authorization.
+- Operator UI notices appear in the card that caused them, in fixed
+  sentences rather than the route's error text; problems fixed by authorizing
+  or adding a credential are warnings rather than errors, with one primary
+  action per row. Activity and artifact states, the confirm dialogs, the
+  mobile masthead, and the vocabulary shown to people (outcomes, actors,
+  timestamps) now read the same across pages and use `branding.productName`.
+
+### Fixed
+
+- Operator OAuth starts now abort downstream discovery and registration after
+  30 seconds or browser cancellation, with a fixed timeout response. Every
+  reset already started by the request, including issuer-mismatch recovery,
+  drains before catalog invalidation and response so a delayed generation
+  write cannot replace a later flow. These uncancellable storage waits can
+  exceed the deadline. Disconnect still finishes after browser cancellation.
+- Forced OAuth restarts reuse registrations bound to the issuer, redirect URI,
+  client metadata, connector settings, and owner partition. Credentials are
+  re-sealed for the replacement epoch, and fresh discovery detects issuer
+  changes. Disconnect and issuer-mismatch recovery discard the registration.
+  The SDK cannot detect a revoked client while constructing a consent URL;
+  a callback refusal clears it so the next restart can register again.
+- Agent sampling advice now applies to reads. For a one-time write, agents
+  reduce the full result in the program or page a direct-call result through
+  `get_result`, without repeating the write to recover discarded output.
+- Authorized batches stay in one resumable program. Guidance explains how
+  tool-scoped approval covers repeated calls to one address while other
+  approval-required writes retain their own approvals. The call-scoped
+  default and host enforcement are unchanged.
+- **A restart's cleanup no longer grows with every earlier restart.** Each
+  OAuth restart re-deleted every epoch the connector had ever retired, one key
+  at a time, and restart 1,001 failed forever with a full cleanup backlog. A
+  restart now deletes the epoch it retires, retries any of the eight most
+  recent epochs whose cleanup failed (their manifest outlives their values),
+  and sweeps at most 16 epochs retired more than 24 hours ago, dropping each
+  from the lineage only when all of its keys are gone. A Disconnect that
+  reported a failed cleanup still deletes the old grant when retried. The
+  cleanup work stays bounded independently of earlier resets. Residue a late
+  writer leaves in a younger epoch stays unreadable behind the fence until the
+  sweep reaches it. A late writer whose cleanup fails in an epoch already
+  listed now restarts that epoch's grace. The accepted assumption is that no
+  request holds a retired epoch for a day. The lineage records retirement
+  times in a sibling record older releases ignore, and its cap rises to 5,000
+  epochs. A connector stuck at the old 1,000 wall restarts the day it
+  upgrades. Rolling back is clean unless a lineage has grown past 1,000. See
+  [auth](./documentation/auth.md#starting-restarting-and-retiring-an-oauth-epoch).
+- A failed or unreachable `/ui/data` no longer signs the operator out. Only a
+  401 or 403 on that read returns to the token gate; anything else keeps the
+  page and offers Retry. A connector whose details fail to load says whether
+  the session, the browser's connection, or the downstream service is at
+  fault, and only the last offers the fix prompt.
+
+## 0.26.0 — 2026-09-25
+
+Programs can now write with host approval. When a program reaches a tool that
+is not explicitly read-only, it pauses before the call and returns the exact
+address, arguments, and a token. The new eighth MCP tool,
+`resume_execution`, repeats that call to show the host the real write and
+replays the program from its journal without resending an uncertain outcome.
+`tools/list` now has eight tools on every deployment, so client allowlists and
+`connecta doctor` installations pinned to 0.25 need updating. Resumable
+writes turn on by default when storage supports `compareAndSet` (memory, file,
+or the Worker example's D1 adapter); a program write that previously failed
+now pauses. Cloudflare KV cannot make that claim atomically, so resumable
+writes stay off there. Set `execute.resumableWrites: false` to silence its
+startup warning. Program clocks and randomness are pinned for replay.
+
+Artifacts arrive as an optional module with versioned JSON documents, a
+sandboxed viewer and library, and scheduled refresh of one data document from
+a read-only program. A deployment supplies a Node timer or Worker cron;
+connecta starts no background job. Stored pages use the operator sign-in,
+and a dedicated artifact origin may require signing in again because browser
+storage belongs to one origin. Page scripts run with an opaque origin and no
+network by default; only explicitly allowlisted script, style, and font
+origins may load. Artifact version and configuration writes are approval-exempt inside
+programs by default; deployment config can restore the approval prompt.
+`run_refresh` requires host approval and is excluded from that exemption.
+Deployments that omit the module need no
+artifact storage, R2 bucket, cron, browser binding, or second domain.
+
+Before upgrading a Worker deployment that uses D1 activity, add the
+`approval` column shown below. Every admitted `/mcp` request, on Node and
+Workers, has a five-minute total lifetime by default; set
+`admission.requests.maxDurationMs` above any longer authorized request. The
+Worker example also enables `enable_request_signal` for live disconnects.
+To add artifacts to that example, use CAS-capable D1
+storage, optionally R2 for bodies, and explicitly configure any CDN origins.
+The Node template now pins 0.26.0 and shows the optional artifact timer.
+`ConnectorCallErrorCode` gains `conflict` for stale artifact edits, while an
+identity can opt into reviewed exact tool grants that remain visible only while
+the loaded catalog classifies them read-only. The operator UI no longer
+returns downstream OAuth or credential-test text in notices; callers that
+read those route messages must use the fixed outcome and consult server logs
+for diagnostics.
+
+### Added
+
+- **Guarded read-only identity grants (#601).** A deployment may put
+  `{ tool: "connector.tool", requireReadOnly: true }` in
+  `identity.connectorAccess`. The reviewed exact address stays visible only
+  while its loaded catalog explicitly says read-only without a contradictory
+  destructive hint. A reclassified tool disappears from discovery and every
+  call path, including `call_destructive_tool` and approval-exempt programs;
+  new names are never added automatically. Existing string grants keep their
+  additive meaning, and a pool can still only narrow the identity's view.
+  A stale catalog or a dishonest downstream annotation remains a trust limit.
+
+- **Resumable writes and `resume_execution` (#565).** A program's call to a
+  tool that is not explicitly read-only pauses the run before anything is
+  sent and returns `{ paused: { address, args, token, expiresAt, nextAction,
+  hint } }`. `resume_execution` — always listed, annotated destructive — must
+  repeat the address and args exactly (`approval_mismatch` otherwise, before
+  anything is claimed); it claims the run by compare-and-set and replays the
+  program from a journal in the caller's result storage, answering every
+  earlier host call from its record — no catalog, permit, connector, or
+  activity — and sending the approved write once. `approval: "tool"` approves
+  the rest of the run's calls to that tool. Each live write is marked on the
+  run's header before it is sent, so racing or crashed resumes never send it
+  twice. A write sent but never answered — or answered with anything short
+  of a refusal or the downstream tool's own error — stops the run as
+  `write_outcome_unknown`, even beside a concurrent pause, and is never sent
+  again; a program that stops matching its journal fails
+  `execution_diverged`; a resumed play that sent writes and then ended without
+  pausing (a sandbox failure, a lapsed claim) fails `execution_interrupted`
+  rather than replaying reads it never journaled. Every error from a resumed
+  play carries `writes` counts, and once a write landed or may have, its
+  advice is to check those before re-running rather than a plain re-run; a
+  run that sent writes keeps those counts past its deadline. Every paused-run
+  storage call has a deadline (the host-call deadline, at least 5 s), so
+  storage that stops answering fails the run rather than holding it. A paused
+  run survives a restart and expires `execute.pausedRunTtlSeconds` (default 1,800) after its
+  first pause; `execute.maxWrites` (default 10) caps a run's writes on top of
+  the host-call budget. `execute.resumableWrites` defaults to whether the
+  storage has `compareAndSet`; `true` without it refuses to construct.
+  `/health` reports `resumableWrites`, and `connecta doctor` expects the eight
+  tools and says when resumable writes are off. See code mode "Pausing and
+  resuming" (`W1`–`W11`, `X12`).
+- **Config approval exemptions (#566).** `execute.approval` maps connector ids
+  and `connector.tool` addresses to `"never"` or `"ask"`: a program calls an
+  exempt write without pausing, while it still spends the write budget, is
+  journaled, and records activity. The address wins over the connector entry,
+  which wins over a connector's own `approval: "never"` default — reserved for
+  connectors connecta ships, such as the artifacts connector — so
+  `"ask"` switches such a default off. It works with resumable writes off
+  too, where an exempt write the program leaves unawaited still finishes
+  before the run ends, and one with an unknown outcome is the result. Exempt is never read-only: discovery keeps the tool approval-required
+  and marks its row `approval: "exempt"`, `call_tool` still refuses it, and no
+  downstream annotation can grant it. An unknown connector id, or an `api()`
+  address its tools do not include, refuses to construct. The operator UI's
+  per-tool badge gains its third state, "exempt from approval".
+- **Activity for pauses and approvals.** `ActivityOutcome` gains `paused` and
+  `approved`, both with zero attempts; `ActivityCallSource` gains
+  `resume_execution`; `ToolCallActivityEvent` gains an optional `approval`
+  (`"call"` or `"tool"`), set only on an approval. All three are enums — the
+  approved arguments are never recorded. The Worker example's D1 activity
+  store writes an `approval` column; add it with
+  `ALTER TABLE tool_call_activity ADD COLUMN approval TEXT;` before deploying
+  the updated adapter. The operator activity page labels both outcomes and
+  says what an approval covered.
+- **Artifact storage and validation, at `@zackbart/connecta/artifacts`
+  (#562).** `kvArtifactStore(storage, { blobs?, prefix? })` keeps artifacts
+  in any `KVStorage` with `compareAndSet` and `list` — one head record per
+  artifact, swapped by compare-and-set, with every earlier version immutable
+  beside it and bodies content-addressed — and refuses Cloudflare Workers KV
+  at construction, because a write that cannot compare-and-set its head can
+  lose a teammate's edit. `validateArtifact({ kind, source, documents? })` is
+  the static check every save runs: one `id="artifact-root"`, no frames,
+  plugins, forms, or `<base>`, external scripts only from explicitly
+  allowlisted origins, and no relative or unapproved network resource URLs,
+  with a line number and a fix in every message. The Worker example gains
+  `r2-artifact-blobs.ts` for keeping bodies
+  in R2 beside a D1 store. The subpath adds no dependency and no Effect.
+- **The built-in artifacts connector (#562, #564).** `createConnecta({ artifacts:
+  artifacts({ store }) })` appends an `artifacts` connector with five reads —
+  `list_artifacts`, `get_artifact`, `get_document`, `validate_artifact`, and
+  `get_refresh` — and nine writes: `create_artifact`, `update_artifact`, `patch_artifact` (exact
+  find/replace, every edit matching once or nothing changes),
+  `set_documents` (plural and atomic), `rollback_artifact`,
+  `archive_artifact`, `restore_artifact`, `set_refresh`, and `run_refresh`.
+  Version-changing writes name their expected base, and every write records
+  its actor from the request's authorization. The connector skips approval, except for `run_refresh`,
+  inside `execute_code` through its own `approval:
+  "never"` — `execute.approval: { artifacts: "ask" }` turns that off — while
+  still spending the write budget and recording activity; `call_tool` still
+  refuses it. The connector serves a publishing guide as
+  `connector:artifacts`, required before the first write. An optional
+  `renderCheck` hook receives the exact frame document and CSP a viewer will
+  load and can refuse a write; without one, static validation is the floor.
+  The module needs `publicUrl`, and a configured connector named `artifacts`
+  refuses to construct.
+- **Artifact library and sandboxed viewer (#563).** `/artifacts` lists pages;
+  `/artifacts/<id>` opens one after the same inbound sign-in as the operator
+  UI. A viewer snapshot pins exact view and document versions. Page HTML runs
+  in an opaque-origin frame with no fetch or worker access. A deployment may
+  allow exact CDN origins for scripts, styles, and fonts; none are allowed by
+  default. With `artifactOrigin`, the main host redirects artifact paths and
+  the dedicated host serves no MCP or operator routes. A browser bearer stored
+  on the main origin must be entered again on the artifact origin; the redirect
+  carries no credential.
+- **Scheduled artifact refresh (#564).** `set_refresh` attaches a versioned
+  program for one data document on a manual, daily, or weekly schedule;
+  `run_refresh` triggers it now, and `get_refresh` reports freshness and a
+  bounded run history. The module's `runDue()` is called by the deployment's
+  Node timer or Worker cron, never by a core background loop. Runs use only
+  shared connectors' explicitly read-only tools within the setter's current
+  identity and pool grants, and stop if publishing permission is revoked.
+  Connector approval exemptions cannot permit a scheduled write. Runs claim
+  the artifact by compare-and-set and validate returned JSON, including any
+  configured render check, before publishing a new document version. A failure keeps the last good value and marks the page
+  stale without rendering raw failure text in the library or viewer. Each tick
+  starts at most ten due pages; the Node template and Worker example show the
+  optional wiring.
+- **`conflict` (#562).** A new `ConnectorCallErrorCode` for a write whose base
+  someone else already moved past, never retryable as-is, with an optional
+  bounded `current` map (at most 20 whole-number entries) on
+  `ConnectorCallError` and `CallErrorDetails` saying where things stand. A
+  program reads it as `err.details.current`; a top-level call returns it in
+  the structured error. A write refused with `conflict` inside a program is a
+  known failure (`W9`), not an unknown outcome.
+
+### Changed
+
+- **`execute_code` asks for a zero-argument program (#602).** Its guidance now
+  shows `async () => { ... }`, with `connecta` supplied as the sandbox global.
+  Passing `connecta` as an arrow parameter shadows that global and fails; the
+  accepted source forms and execution rules have not changed.
+- **Worker resource setup has an optional Alchemy guide (#567).** It covers
+  account resources and adoption while keeping the Worker script, domains,
+  Browser Rendering, and cron deployment with Wrangler until Alchemy's
+  script-upload path is shown to preserve `ctx.access`. Alchemy is not a
+  connecta dependency or a second deployment template.
+- **`execute_code` source intake (#576).** Programs over 64 KiB of UTF-8
+  source fail before executor admission. The host recovers one fenced async
+  arrow even when prose surrounds it, a default-exported arrow, or a named
+  async function declaration, so Node and Workers receive the same program.
+- **Eight tools, and instructions that follow the mode.** `tools/list` adds
+  `resume_execution` everywhere. With resumable writes on, the MCP
+  instructions say programs may write and pause, the `execute_code`
+  description advertises the write budget and drops `safety: "readOnly"` from
+  its search example (a program looking for a write would not find it), and
+  the `usage` skill gains the pause, resume, and unknown-outcome guidance;
+  without them, the instructions and description read as they did in 0.25.
+- **The operator UI's "needs approval" badge reads "asks for approval"**, and
+  the tool legend says a program pauses for `resume_execution` while a direct
+  call crosses `call_destructive_tool`.
+- **A program's clock and randomness are pinned (code mode `P6`).**
+  `Date.now()`, `new Date()`, and `Date()` inside `execute_code` return the
+  instant the run started and do not advance, and `Math.random()` is an sfc32
+  stream seeded per run from the host's CSPRNG; on a Dynamic Worker,
+  `crypto.getRandomValues`, `crypto.randomUUID`, and `performance.now()` follow
+  the same pin. The replacements are locked like `Error`. Resumable writes
+  (#565) replay a paused program from the top, and a program that branched on
+  a moving clock or an unseeded draw could not be replayed; pinning every run
+  means none behaves differently for having paused. A program that timed its
+  own work now measures zero — `diagnostics: true` measures from the host.
+
+### Fixed
+
+- **Request admission recovers after missing Worker cleanup (#595).** An
+  admitted `/mcp` request now has a configurable total lifetime, five minutes
+  by default, covering auth, tools, and response delivery. Its own timer aborts
+  live work, including connector calls. If workerd ends it without running
+  JavaScript cleanup, the next request or a queued request's timer reclaims
+  only the expired permit. An orphaned queued request cannot strand its next
+  permit indefinitely, and late cleanup cannot release a successor's permit.
+  The Worker example enables `enable_request_signal` for prompt live disconnect
+  cleanup.
+
+- **Legacy MCP handshake close (#572).** A client that leaves while the older
+  protocol handshake is still initializing no longer leaves the SDK's
+  `notifications/initialized` promise rejected without a handler. Successful
+  handshakes still send the notification.
+
+- **Operator notices no longer render downstream error text**
+  ([#568](https://github.com/zackbart/connecta/issues/568)). The OAuth
+  connect/disconnect notice and the credential Test result showed whatever the
+  server sent back, and that text can come from a token endpoint's error body or
+  a provider's refusal, either of which can quote the secret it was sent. Each
+  notice now says a fixed sentence chosen by outcome, with the fix prompt for
+  that outcome, and the page never renders a route's words there even if an
+  older server sends them. The routes log the downstream's text instead — a
+  failed OAuth action or credential test at `warn`, a passing test's message at
+  `info` — and never record it in activity. A `CredentialTestResult.message` is
+  now log-only, and a Test refused because nothing usable is stored carries the
+  same `credential_required` or `credential_mismatch` problem the Connections
+  page shows.
+
+- **Compact schemas group an array's union element.** The `compact` format,
+  the default for `search_tools` and `connecta.search`, rendered an array of a
+  union as `{ op: "replace" } | { op: "append" }[]`, which reads as one
+  operation or an array of the other; Linear `save_issue`'s `patch` was one
+  such array. A union, intersection, enum, or type list used as an array
+  element, a tuple's rest included, now renders parenthesized, as
+  `({ op: "replace" } | { op: "append" })[]`, matching the `typescript`
+  format. The renderer records which shapes it rendered at operator level
+  rather than rescanning its text, so a pipe in a literal, a constraint, or
+  property prose adds no parentheses, and every other shape renders byte for
+  byte as before (#569).
+
+- **A catalog refresh whose connector ignores abort held every later reader.**
+  A refresh flight lived until its connector settled, so a `listTools` that
+  ignored its signal kept the flight open until the catalog was invalidated,
+  and every reader that joined it timed out in turn while the connector stayed
+  unlisted. A flight is now bounded by its owner's deadline, or by the default
+  30-second probe timeout for an owner with none. Past it, readers still
+  waiting and readers arriving later make a fresh attempt, and a late result
+  from the abandoned flight is neither cached nor persisted, so it cannot
+  overwrite the fresh one. Abandonment logs a warning
+  ([#570](https://github.com/zackbart/connecta/issues/570)).
+- **A joined catalog read ended on its starter's deadline.** Readers of one
+  catalog in a request share one read, and that read ran under whichever
+  reader started it. A short-deadline `connecta.call` that started it failed a
+  concurrent `connecta.search` with the call's timeout, and a search cancelled
+  by its client cancelled a read others were still waiting on. The shared read
+  now carries its own signal and the probe timeout. Each reader waits under its
+  own deadline and cancellation, one that leaves fails alone, and the read is
+  cancelled only when every reader has gone. It is still one downstream read
+  per connector per request. The registry's cross-request refresh no longer
+  hands its owner's cancellation to joiners, which make a fresh attempt instead
+  ([#571](https://github.com/zackbart/connecta/issues/571)).
+
 ## 0.25.0 — 2026-09-23
 
 The Effect core is the release. Admission, deadlines, invocation,

package/README.md

@@ -10,16 +10,19 @@ writing code instead of loading a thousand tool definitions.
 You ask your agent a question that touches a service — Linear, Stripe, an
 internal API, anything you have connected. Here is what happens:
 
-1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+1. The agent talks to one endpoint, yours, and sees eight tools. Always eight,
    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
-   cannot do that from a program. It makes one explicit call, and your MCP
-   client can put that call in front of you first.
+4. If the program wants to change something — create, update, delete — it
+   stops right there, before anything is sent, and hands the agent the exact
+   write. The agent repeats it through `resume_execution`, which your MCP
+   client can put in front of you first. Approve it and the program picks up
+   where it stopped, without re-reading what it already read. A single write
+   can also go straight through `call_destructive_tool`.
 
 Credentials never leave the server. The program never sees them, and neither
 does the agent.
@@ -28,9 +31,9 @@ does the agent.
 flowchart TB
     Client["Your MCP client<br/>Claude, Cursor, …"]
 
-    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
-        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools only"]
-        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
+    subgraph Connecta["Connecta — one endpoint, eight tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>reads run, writes pause"]
+        Explicit["resume_execution · call_destructive_tool<br/>the exact write, visible<br/>your client can ask you first"]
     end
 
     Integrations["The integrations you chose<br/>Linear · Stripe · Notion · Vercel · your HTTP API · any MCP server"]
@@ -38,6 +41,7 @@ flowchart TB
     Client -->|"one connection"| Sandbox
     Client --> Explicit
     Sandbox -->|"reads"| Integrations
+    Sandbox -.->|"paused write"| Explicit
     Explicit -->|"writes"| Integrations
 ```
 
@@ -73,22 +77,35 @@ Fifty issues in, one small object out. Your context window notices.
   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 writes deliberate.** Only tools marked read-only run in a program.
-  Everything else is a separate, visible call your client can gate.
-- **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,
-  from the same small deployment file.
+- **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.** Only tools marked read-only run in a program
+  unasked. Any other call pauses the program with the exact write, and it
+  runs only once `resume_execution` repeats it — a visible call your client
+  can gate. A paused run is a journal in storage, not a held program, so it
+  survives a restart; it expires, and a write whose outcome is unknown is
+  never sent twice. Config — and only config — can exempt a cheap,
+  reversible write from asking, per tool or per connector.
+- **Run it on Node or Cloudflare Workers.** The core is shared; each deployment
+  supplies its platform's executor and storage. 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
+`activityHistory()` from `/activity`, `artifacts()` from `/artifacts`, 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.
 
 The optional UI shows each person's connections and effective permissions.
 Authentication controls live inside each connection, with optional activity
 history. The configured connection list loads before downstream checks finish;
 a slow provider does not hold up the page. Connector selection and access rules
-remain in deployment code.
+remain in deployment code. It also explains which tools can run in programs or
+need approval, offers a fixed repair prompt for classified failures, and shows
+client setup commands for the endpoints the signed-in person can use.
 
 One deployment may serve several authenticated people inside the same tenant.
 Cloudflare Access supplies Worker identity; Node can use Clerk or the optional
@@ -105,7 +122,7 @@ and why.
 
 Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers the architecture, the seven tools,
+[documentation](./documentation/) covers the architecture, the eight 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.

package/SECURITY.md

@@ -16,8 +16,9 @@ CI blocks moderate, high, and critical production dependency advisories. Lower
 findings are reviewed for reachability and recorded when an upstream package has
 not yet released a compatible fix.
 
-The MCP TypeScript SDK 2.x packages are exact-pinned. The split client and
-server packages no longer install Hono or `@hono/node-server`, so the temporary
-root-project override used with SDK 1.x is gone. A dependency bump must pass
-both `npm run release:check` and the Node/Workers runtime suites before the pin
-moves.
+The MCP TypeScript SDK 2.x packages and Effect are exact-pinned. Effect is the
+runtime core, and its unstable modules can break in a minor release, so its pin
+moves in a dedicated upgrade. The split client and server packages no longer
+install Hono or `@hono/node-server`, so the temporary root-project override
+used with SDK 1.x is gone. A dependency bump must pass `npm run release:check`
+and the Node/Workers runtime suites before a pin moves.

package/bin/connecta.mjs

@@ -249,6 +249,7 @@ async function doctor() {
     "call_tool",
     "execute_code",
     "get_result",
+    "resume_execution",
     "search_tools",
     "skills",
   ];
@@ -301,7 +302,10 @@ async function doctor() {
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
       `${executorName ? `${executorName} executed` : "code executed"}, ` +
-      "prescribed seven-tool surface" +
+      "prescribed eight-tool surface" +
+      // resume_execution is listed either way; whether programs can write is
+      // what an operator cannot tell from the tool list, so say when not.
+      (health.resumableWrites === false ? ", resumable writes off" : "") +
       (drifted.length > 0
         ? `, catalog drift on ${drifted.length} connector(s).`
         : "."),

package/dist/activity.d.ts

@@ -1,7 +1,9 @@
 import type { ActivityModule } from "./module-contracts.js";
 import type { CatalogDriftCounts, Logger } from "./types.js";
-export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code";
-export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled";
+export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
+export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
+/** How much one `resume_execution` approved: this call, or this tool for the run. */
+export type ActivityApproval = "call" | "tool";
 export type AgentFriction = "tool_not_found" | "schema_retry" | "destructive_reroute" | "auth_required" | "result_too_large";
 export { agentFrictionForCode } from "./activity-friction.js";
 /**
@@ -47,6 +49,11 @@ export interface ToolCallActivityEvent {
      * agent while remaining an `outcome: "success"` call with no error code.
      */
     friction?: AgentFriction;
+    /**
+     * Set only on an `approved` event: the scope the approval covered. An enum,
+     * like everything else here — the approved arguments are never recorded.
+     */
+    approval?: ActivityApproval;
     serverName: string;
     serverVersion: string;
     deploymentId?: string;
@@ -142,7 +149,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction">;
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode" | "friction" | "approval">;
 /**
  * Best-effort by design: activity storage can never change a tool result.
  * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics

package/dist/activity.js

@@ -49,9 +49,18 @@ export function recordToolActivity(context, input) {
         source: input.source,
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
-        attempts: Math.max(1, Math.trunc(input.attempts)),
+        // A pause and an approval reach nothing downstream, so they are the two
+        // events that honestly carry zero attempts. Every other outcome keeps its
+        // floor of one, as it always has.
+        attempts: input.outcome === "paused" || input.outcome === "approved"
+            ? 0
+            : Math.max(1, Math.trunc(input.attempts)),
         ...(input.errorCode ? { errorCode: input.errorCode } : {}),
         ...(friction ? { friction } : {}),
+        ...(input.outcome === "approved" &&
+            (input.approval === "call" || input.approval === "tool")
+            ? { approval: input.approval }
+            : {}),
         serverName: context.serverInfo.name,
         serverVersion: context.serverInfo.version,
         ...(context.deploymentId