@zackbart/connecta 0.27.0 → 0.28.1

package/dist/providers/vercel.js

@@ -9,7 +9,7 @@
  * those rows with Vercel's published OpenAPI document at
  * https://openapi.vercel.sh/ without needing a credential.
  */
-import { api, defined } from "../connectors/api.js";
+import { apiConnector as api, defined } from "../connectors/api-connector.js";
 import { remoteMcp } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { guardedFetch, retryAfterMs, } from "../connectors/guarded-fetch.js";

package/dist/routes/mcp.js

@@ -4,9 +4,8 @@ import { notFoundResponse } from "../branding.js";
 import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError, } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
-import { registerResumeTool } from "../resumable.js";
 import { intersectAccess } from "../connector-access.js";
-import { instructionsFor } from "../skills.js";
+import { CONNECTA_INSTRUCTIONS } from "../skills.js";
 import { msg } from "../errors.js";
 import { detach } from "../runtime/run.js";
 import { authorize, loggableValue, mayManageConnector, validateAuthPermissions, } from "./shared.js";
@@ -218,19 +217,14 @@ function toolkitRetired(logger) {
         },
     });
 }
-function serveMcp(request, requestSignal, opts, baseUrl, actor, registry, canManageAuth, poolName, runtimeContext) {
-    // A paused run belongs to the endpoint it started on: resuming it through
-    // another pool's endpoint finds nothing, as another subject would.
-    const resumable = opts.resumable
-        ? { ...opts.resumable, pool: poolName ?? null, approval: opts.approval }
-        : undefined;
+function serveMcp(request, requestSignal, opts, baseUrl, actor, registry, canManageAuth, runtimeContext) {
     // Every McpServer the request builds is fresh and closes with its scope.
     // The modern handler tears its own down after the exchange; the legacy
     // transport never does, and neither may stay wired to an ended request.
     const servers = [];
     const createServer = () => {
         const server = new McpServer(opts.serverInfo, {
-            instructions: instructionsFor(resumable !== undefined),
+            instructions: CONNECTA_INSTRUCTIONS,
             cacheHints: {
                 "tools/list": {
                     ttlMs: 3_600_000,
@@ -274,7 +268,7 @@ function serveMcp(request, requestSignal, opts, baseUrl, actor, registry, canMan
                 : {}),
             approval: opts.approval,
         });
-        const runner = registerExecuteTool(server, registry, {
+        registerExecuteTool(server, registry, {
             baseUrl,
             executor: opts.executor,
             logger: opts.logger,
@@ -304,19 +298,9 @@ function serveMcp(request, requestSignal, opts, baseUrl, actor, registry, canMan
             ...(opts.watchdogMs !== undefined
                 ? { watchdogMs: opts.watchdogMs }
                 : {}),
-            resumable,
             approval: opts.approval,
             maxWrites: opts.maxWrites,
         });
-        // Always registered, so the surface is the same eight tools on every
-        // deployment; without resumable writes it answers that there is nothing
-        // to resume.
-        registerResumeTool(server, registry, {
-            runner,
-            settings: resumable,
-            ...(activity ? { activity } : {}),
-            requestSignal,
-        });
         servers.push(server);
         return server;
     };
@@ -527,7 +511,7 @@ export function createMcpRoute(opts) {
                 if (new URL(request.url).searchParams.has("toolkit")) {
                     return cors(toolkitRetired(opts.logger));
                 }
-                return cors(yield* serveMcp(localRequest, localAbort.signal, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, poolName, runtimeContext));
+                return cors(yield* serveMcp(localRequest, localAbort.signal, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, runtimeContext));
             });
             if (remainingMs === undefined)
                 return yield* handled;

package/dist/routes/oauth.js

@@ -102,6 +102,30 @@ export function routeOAuthCallback(context) {
         return Effect.succeed(null);
     return Effect.uninterruptible(Effect.promise(() => finishOAuthCallback(context)));
 }
+/**
+ * RFC 6749's error codes (sections 4.1.2.1 and 5.2) and RFC 8707's
+ * `invalid_target`. Only a code on this list is logged: the `code` an OAuth
+ * error carries is the provider's own text.
+ */
+const TOKEN_ERROR_CODES = new Set([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    "invalid_target",
+    "access_denied",
+    "server_error",
+    "temporarily_unavailable",
+]);
+/** ` with OAuth error <code>` for a known code; nothing for anything else. */
+function exchangeErrorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" && TOKEN_ERROR_CODES.has(code)
+        ? ` with OAuth error ${code}`
+        : "";
+}
 async function finishOAuthCallback(context) {
     const { path, url, baseUrl, opts } = context;
     const error = url.searchParams.get("error");
@@ -198,10 +222,12 @@ async function finishOAuthCallback(context) {
             return html("connected", opts, connector);
         }
         catch (err) {
-            // The page names the reason and nothing else; what the exchange threw can
-            // quote a token endpoint's body, so it goes only to the operator log.
+            // Neither the page nor the log repeats what the exchange threw: the SDK
+            // quotes the token endpoint's error_description or raw body, and a
+            // provider echoing a client_secret_post request puts the secret there.
             opts.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
-                `with 500: the authorization code exchange threw ${loggableValue(msg(err))}.`);
+                `with 500: the authorization code exchange failed${exchangeErrorCode(err)}. ` +
+                "Check the connector's client configuration and re-run authorization.");
             return html("exchange_failed", opts, connector);
         }
     }

package/dist/routes/shared.d.ts

@@ -41,14 +41,9 @@ export interface ServerOptions {
     hostCallTimeoutMs?: number | undefined;
     /** Hard ceiling on one execute_code run, outside the sandbox. Default 120_000. */
     watchdogMs?: number | undefined;
-    /** Resumable writes' settings; absent when they are off. */
-    resumable?: {
-        maxWrites: number;
-        ttlSeconds: number;
-    } | undefined;
     /** Config approval exemptions (`execute.approval`), resolved at construction. */
     approval?: ApprovalPolicy | undefined;
-    /** Writes one program may send (`execute.maxWrites`), exempt ones included. */
+    /** Exempt writes one program may send (`execute.maxWrites`). */
     maxWrites?: number | undefined;
     /** Required sandbox backing the execute_code meta-tool. */
     executor: Executor;

package/dist/server.js

@@ -52,10 +52,6 @@ export function createFetchHandler(opts) {
             ...(opts.executorName !== undefined
                 ? { executor: { name: opts.executorName } }
                 : {}),
-            // Whether a program's write pauses for resume_execution or fails E4.
-            // The tool is listed either way; this is the only place an operator
-            // can see which answer it gives (#565).
-            resumableWrites: opts.resumable !== undefined,
             // Counts only, from refreshes that already happened — the endpoint
             // asks no downstream anything, and `connecta doctor` reads it to
             // report a stale allowlist without a probe of its own (#343).

package/dist/skills.js

@@ -1,24 +1,17 @@
 import { boundedEchoText } from "./errors.js";
-const ROUTE = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar read results with a small sample before proceeding.";
+const ROUTE = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.";
 const RECOVERY = 'After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 /**
- * The MCP instructions of a deployment whose programs pause at writes. The
- * route sentence is its own, not ROUTE's: with writes in programs, "one known
- * write" is the only work left for call_destructive_tool, and an agent told
- * only that programs *may* write reads each write after a lookup as a known
- * one and sends them one prompt at a time.
+ * The always-loaded MCP `instructions` string. A program runs reads and the
+ * writes config exempts from approval; every other write is its own top-level
+ * call_destructive_tool, where the host's permission prompt is the approval.
  */
-export const CONNECTA_INSTRUCTIONS = `Choose a route before discovery. One known read: call_tool; one known write: call_destructive_tool. Everything else starts with execute_code to discover, call, and return the answer: unknown addresses, reduction, multiple or dependent calls, and writes that follow reads. Keep authorized batches in one program. Sample unfamiliar reads. Reduce a one-time write's full result there or page a direct call with get_result; never repeat it to recover output. Non-exempt program writes pause unsent; resume_execution with the returned token, address, and args approves the call and continues the program. Approval "tool" covers later same-address calls in this run; other approval-required writes need their own approval. ${RECOVERY}`;
-/**
- * The instructions of a deployment without resumable writes, whose programs
- * refuse every write: the routing it always had.
- */
-export const READ_ONLY_PROGRAM_INSTRUCTIONS = `${ROUTE} Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. ${RECOVERY}`;
+export const CONNECTA_INSTRUCTIONS = `${ROUTE} Only readOnlyHint: true tools and config-exempt writes run there. Keep catalog inspection and other unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. Never repeat a write to recover its output. ${RECOVERY}`;
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
-Eight tools: \`execute_code\`, \`resume_execution\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
+Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
 
 Follow the MCP instructions for routing. Read at most once for syntax or repair.
 
@@ -48,16 +41,14 @@ For top-level catalog inspection or approval-required discovery, omit \`limit\`
 - Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string.
 - Validate tabular headers, row arrays, and row widths before mapping them. Never let a header or partial row become data.
 
-Only explicitly \`readOnlyHint: true\` or config-exempt calls run unasked. With resumable writes, non-exempt approval-required calls pause unsent; \`resume_execution\` repeats the pending address, args, and token. Without them, use \`call_destructive_tool\` for writes. Keep each authorized batch in one resumable program, final post included. \`approval: "call"\` covers one write; \`approval: "tool"\` covers later same-address calls in this run. Other approval-required writes need approval. Replay requires the same call order. Sandbox code cannot widen host gates.
+Only explicitly \`readOnlyHint: true\` calls and writes the deployment's config exempts from approval run in a program. Any other write is refused before it is sent: send it through top-level \`call_destructive_tool\`, where the host asks. Sandbox code cannot widen host gates.
 
 ## Errors and repair
 
 Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Promise rejections retain these fields. Branch on fields, never prose. After a shared argument failure, repair one call before repeating it across other records. Do not retry \`retryable: false\`, and do not retry \`rate_limited\` immediately because portable code has no timer.
 
 - \`destructive_tool_requires_approval\`: stop and send the returned address through top-level \`call_destructive_tool\`.
-- \`execution_paused\`: the run already stopped at a write; let it end.
-- \`write_outcome_unknown\`: sent but unanswered, never re-sent; check the target.
-- \`execution_expired\`, \`_diverged\`, \`_interrupted\`: check \`writes\`, then rerun.
+- \`write_outcome_unknown\`: an exempt write was sent but unanswered and is never re-sent; check the target.
 - \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
 - Truncated direct call: page with \`get_result\`, never repeat a write. A program result has no page handle; reduce a read in a new program. After a write, check the target or report the gap.
 - Unknown addresses and tools carry scoped search recovery. Use it inside the current run. Do not invent an address.
@@ -72,8 +63,6 @@ The \`execute_code\` description states this deployment's host-call and write bu
 
 Portable code uses standard JavaScript builtins, \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch, process, timers, crypto, and WebSocket. Dynamic Workers must use only \`{ loader }\`; bindings, modules, or globalOutbound grant ambient authority. With loader only, environment maps are empty; node:fs/http/https are absent; outbound fetch, WebSocket, node:net, and node:tls are denied; DNS is unresolved. Runtime builtins remain through \`import()\` and \`process.getBuiltinModule()\`, including node:path and cloudflare:workers; this set can drift. Timers, process, crypto, WebSocket, and data: fetch remain. Avoid every runtime-only capability because QuickJS fails.
 
-\`Date.now()\` is the run's start and does not advance; \`Math.random()\` is seeded per run.
-
 ## Examples
 
 One read-only call at a known address:
@@ -113,10 +102,6 @@ Connector guides appear in \`skills({})\` and discovery with an exact \`guide\`
 `;
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
-/** The always-loaded MCP `instructions` string. */
-export function instructionsFor(resumableWrites) {
-    return resumableWrites ? CONNECTA_INSTRUCTIONS : READ_ONLY_PROGRAM_INSTRUCTIONS;
-}
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
     return connectors.some((connector) => connectorGuide(connector) !== undefined);

package/dist/tool-safety.d.ts

@@ -20,7 +20,7 @@ export interface ApprovalPolicy {
 }
 export declare const NO_EXEMPTIONS: ApprovalPolicy;
 /**
- * Whether a program may call this tool without pausing for approval.
+ * Whether a program may call this tool without asking for approval.
  *
  * Only a tool that is *not* explicitly read-only can be exempt — a read-only
  * tool needs no exemption, and reporting one would blur the two classes an

package/dist/tool-safety.js

@@ -14,7 +14,7 @@ export const NO_EXEMPTIONS = {
     tools: new Map(),
 };
 /**
- * Whether a program may call this tool without pausing for approval.
+ * Whether a program may call this tool without asking for approval.
  *
  * Only a tool that is *not* explicitly read-only can be exempt — a read-only
  * tool needs no exemption, and reporting one would blur the two classes an

package/dist/types.d.ts

@@ -253,8 +253,8 @@ export interface Connector {
     /**
      * This connector's own default for its tools that are not explicitly
      * read-only, inside `execute_code`: `"never"` lets a program call them
-     * without pausing for approval. Reserved for connectors connecta ships
-     * whose writes are cheap to undo (the planned artifacts connector, whose
+     * without asking for approval. Reserved for connectors connecta ships
+     * whose writes are cheap to undo (the artifacts connector, whose
      * every write is a new immutable version); a deployment's own connectors
      * leave it unset and exempt through `execute.approval`, which overrides
      * this either way. Never read from a downstream catalog — a server cannot

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.27.0";
+export declare const CONNECTA_VERSION = "0.28.1";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.27.0";
+export const CONNECTA_VERSION = "0.28.1";

package/documentation/architecture.md

@@ -21,8 +21,10 @@ health, and the per-connector call limiters. It is built once and lives as long
 as the isolate — on Workers a lazy module-scope singleton, which is why both
 deployment shapes construct it outside the request handler.
 
-An OAuth `remoteMcp()` connector also owns a runtime-local refresh completion
-gate (`src/auth/downstream-oauth.ts`). It coordinates credential mutation across
+An OAuth connector — `remoteMcp()`, or `api()` with a static grant
+(`src/auth/static-oauth.ts`, the same provider with its discovery and client
+answered from config) — also owns a runtime-local refresh completion gate
+(`src/auth/downstream-oauth.ts`). It coordinates credential mutation across
 concurrent request scopes while sharing no client, transport, or response, and
 never lets a follower cancel the owner. The subtle part is that a valid token
 response consumes the refresh token whether or not the owner survives to save it,
@@ -61,7 +63,7 @@ top to bottom.
 | 2 | MCP preflight | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth. |
 | 2 | Other `OPTIONS` | Auth metadata first, otherwise compatibility CORS preflight. |
 | 3 | `/.well-known/*` | Auth metadata, or 404. |
-| 4 | `/health` | Open and payload-free: health, executor, whether resumable writes are on, admission, and deployment metadata, with drift as stable short hashes. |
+| 4 | `/health` | Open and payload-free: health, executor, admission, and deployment metadata, with drift as stable short hashes. |
 | 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state and personal-ownership checked, independent of the UI. |
 | 6 | `/mcp`, `/mcp/<pool>` | Admission, then auth, then a request-local MCP server. An undeclared pool, a refusing grant, and a throwing grant are one identical 404; see [pools](./auth.md#pools). |
 | 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
@@ -94,7 +96,7 @@ An admitted non-preflight `/mcp` request then takes five steps in
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
-   404 — then register the eight meta-tools on a fresh `McpServer`
+   404 — then register the seven meta-tools on a fresh `McpServer`
    (`test/server.test.ts`, `test/code-first-surface.test.ts`).
 
 ## Layers below the meta-tools
@@ -109,7 +111,7 @@ or hands out, and a change usually belongs in exactly one of them:
 | `src/invocation.ts` | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows. |
 | `src/result-shapes.ts` | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none. |
-| `src/resumable.ts`, `src/run-journal.ts` | Resumable writes: a program's host-call numbering, the write gate that pauses it, the journal a paused run becomes, the replay `resume_execution` plays from it, and the claim and write-ahead marks that keep an approved write to at most one send. |
+| `src/exempt-writes.ts` | The writes a program may send, which config exempted from asking: the write budget's default, what a dispatched write's outcome says about whether it landed, and the tracking that lets one outlive the program without hiding an unknown outcome. Every other program write is refused before it reaches this. |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same two
 services, `CatalogService` and `InvocationService`. That is the point: a
@@ -222,12 +224,10 @@ successful call's preview and a paging-unavailable notice rather than a result i
 A second optional method, `compareAndSet(key, expected, next, options?)`, is an
 atomic claim: `null` means absent (expired counts) on the way in and delete on
 the way out. A successful write accepts the same optional `ttlSeconds` as
-`set`. Resumable writes require it: of two `resume_execution` calls racing
-for one paused run exactly one may win, and every write that run sends is
-marked on its header first, so a read and a write standing in for the claim
-could send an approved write twice. Omitted, `execute.resumableWrites` is on
-exactly when the store has it, and asking for it over a store without it
-refuses to construct. Downstream OAuth uses it where the store has it, so
+`set`. Artifacts require it, because every write commits by swapping a head,
+and so does issuing access tokens; a read and a write standing in for the
+claim would let two writers both win. Downstream OAuth uses it where the store
+has it, so
 resealing legacy plaintext and discarding a refused grant cannot overwrite a
 consent that landed in between, and falls back to a read and a write where it
 does not.
@@ -330,7 +330,7 @@ owner admitted to `set_refresh` is stored with the program. Every run rechecks
 that identity's current `connectorAccess` and pool grant, including continued
 access to `artifacts.set_refresh`, then intersects those grants with shared
 connectors. Revoking either grant stops later runs.
-Resumable writes and approval exemptions are off. A refused call fails the
+Approval exemptions are off, so a refresh writes nothing. A refused call fails the
 entire refresh even if its program catches the error. The head CAS claims one
 run per artifact; the data commit checks the claim ID and program version in
 the same CAS. The claim deadline starts before executor admission and aborts
@@ -483,7 +483,6 @@ would be another partition's.
 | Admission (`executor-admission.ts`, `call-admission.ts`) | Queued waiters are Deferreds settled by whoever removes them from the queue; a wait is one flat race of grant, Clock timeout, and signal. The uncontended path stays synchronous. Two controllers, as [#453](https://github.com/zackbart/connecta/issues/453) requires. |
 | One tool call (`invocation.ts`) | One fiber: resolution, the read-only and schema refusals, admission, and the downstream attempt sit under a single `withDeadlineEffect`, whose expiry interrupts the call wherever it is. The permit is an `acquireRelease`; the connector call is `Effect.tryPromise` over the unchanged `Connector`. |
 | `execute_code` (`execute.ts`) | One fiber whose Scope owns the run's signal and executor lease, so a result, a throw, the watchdog, and cancellation all release the lease and abort the signal the same way. The executor's `acquire()` and `execute()` stay Promises raced against the signal and `execute.watchdogMs`. Each guest host call is a fiber of its own. |
-| Resumable writes (`resumable.ts`) | A play's stop is a Deferred its write gate completes, raced against the executor like the watchdog; the gate for call n awaits the decision Deferreds of every lower-numbered call; header writes are one compare-and-set at a time on a per-play turn. A paused run holds nothing request-bound — its journal is data, and the next play is a new request's. |
 | Discovery (`catalog-service.ts`) | A request-scoped cache: one shared read per connector (`runtime/shared-read.ts`), settled by the read itself and carrying its own signal and the probe timeout whichever asker starts it. Each asker waits under its own deadline and signal, so one that times out or is cancelled fails alone, and the read is cancelled only once every asker has gone. Fan-out is `Effect.forEach` under the discovery concurrency. |
 | Registry (`registry.ts`) | Catalog persistence and the result stash are programs over `Storage`. A refresh flight is a Deferred its publishing request completes, bounded by its owner's deadline (the default probe timeout when it has none); persisted-catalog writes take per-connector turns, each a Deferred its own request completes. Same-request loads share one read the way discovery's do. |
 | Remote MCP (`connectors/remote-mcp.ts`) | Each request scope's state holds a Scope, each connection is a lease forked from it, and a connect in flight is a Deferred carrying the client it connected. Closing a session and the transport are each bounded to a second. |
@@ -589,9 +588,8 @@ cap. Effect can reject excess properties when both decoding and rendering use
 `onExcessProperty: "error"`; its default strips them. The generated schemas
 still differ from the exact meta-tool goldens, including record rendering and
 composed numeric bounds. A Schema replacement would need to preserve that
-contract, memoized rendering, and the raw-argument checks used by resumable
-writes. Both MCP SDK packages still depend on Zod, so changing our inputs alone
-does not remove Zod from an installation.
+contract and memoized rendering. Both MCP SDK packages still depend on Zod,
+so changing our inputs alone does not remove Zod from an installation.
 
 A one-endpoint `HttpApi` prototype adds 106,634 bytes gzip to `./ui` and 106,453
 to `./activity`. Even plain `HttpRouter` adds 45,324 to `./ui`, taking it to
@@ -631,7 +629,7 @@ src/
   skills.ts           MCP instructions, the usage skill, connector guides
   catalog-drift.ts    vetted manifests and the counts a refresh produces
   activity.ts         optional history factory and best-effort recorder
-  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth
+  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
   executors/          the QuickJS pool and child (Node only)
   node.ts             listen() + fileStorage re-export (Node only)
 ```

package/documentation/auth.md

@@ -305,7 +305,9 @@ or epoch does not open. Anything that fails to open — a tampered value, a
 rotated key — reads as absent: the connector reports `auth_required` and logs a
 warning. The flow bookkeeping stays plaintext: `state`, the pending URL,
 discovery metadata, and the generation. The callback route reads `state`
-directly, and none of it authenticates anything by itself.
+directly, and none of it authenticates anything by itself. An
+[`api()` OAuth connector](#downstream-oauth-on-api) seals its tokens and
+verifier the same way and stores no client at all.
 
 Plaintext left by an older release is read, then sealed where it lies through
 the same generation fence as any write, so an upgrade keeps the grant. Sealing
@@ -326,8 +328,8 @@ The operator's `POST /ui/oauth/<id>` takes a `mode` query parameter:
 
 | Request | What it does |
 | --- | --- |
-| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, the registered client, discovery, and any pending flow wiped, so the next flow registers a client again. |
-| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
+| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, discovery, and any pending flow wiped. A dynamically registered client may be carried into it ([below](#human-authentication-management)); one that is not carried is registered again. |
+| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes and still names the stored client; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
 | `DELETE /ui/oauth/<id>` | Disconnect: a disconnected epoch that passive reads never turn back into a consent flow. |
 
 Any other `mode`, or more than one, is a 400 before anything starts; the
@@ -592,9 +594,22 @@ the connector's URL, redirect URI, client metadata, auth scope, transport settin
 and owner partition still match. It drops the grant and one-shot flow state,
 selects the authorization server again, and re-seals the retained client under
 the replacement epoch key. A different issuer registers a new client. Disconnect
-and issuer-mismatch recovery discard it. The SDK has no client-validation
-exchange while constructing a fresh consent URL; a provider that revokes a
-retained client may refuse it only at consent or callback, after this request.
+and issuer-mismatch recovery discard it. A URL-based client is never carried:
+nothing was registered, and leaving it behind lets fresh metadata decide
+whether the server still accepts one. Neither is a client whose secret has
+expired.
+
+A carried client has to earn its next carry. Building a consent URL sends the
+provider nothing, so a restart cannot learn there that a provider has purged
+the client, and RFC 6749 forbids the provider from redirecting an unknown
+client back to the callback, so nothing arrives later either. Tokens in the
+epoch are the only proof the provider still knows it. A restart that follows
+a restart with no grant in between therefore registers again: a purged
+registration costs one refused consent, not a Restart that can never recover.
+A refusal connecta does hear is handled where it lands. A start whose refresh
+draws `invalid_client` drops the client and registers in that same start; a
+callback whose code exchange draws it drops the client, and Continue will not
+hand back the URL that named it.
 
 Credential and OAuth mutation require an admitted interactive human, connector
 visibility, the appropriate shared or personal permission, and an exact
@@ -636,8 +651,107 @@ existing dynamic registration flow. State validation, PKCE, issuer binding,
 encrypted token storage, refresh, and disconnect follow the same code paths.
 The metadata URL and scopes participate in the saved-client configuration
 binding, so restarting after either changes cannot reuse an old registration.
+A restart never carries the URL-based client itself, so a server that stops
+advertising support gets a registered client on the next restart.
 
 `scope` supplies space-separated default OAuth scopes through client metadata.
 A downstream challenge or protected-resource scope declaration takes precedence,
 and the SDK adds `offline_access` when advertised for refresh-token grants.
 Omitting both settings preserves the existing discovery and registration flow.
+
+## Downstream OAuth on `api()`
+
+Some APIs a deployment needs have no MCP server and take nothing but OAuth.
+Church Community Builder's REST API accepts only a three-legged grant, issues
+its clients by hand, and publishes no metadata to discover. `api()` takes a
+static authorization-code configuration for that shape:
+
+```ts
+api("church", {
+  authScope: "personal",
+  oauth: {
+    authorizationEndpoint: "https://login.example.com/oauth/authorize",
+    tokenEndpoint: "https://api.example.com/oauth/token",
+    clientId: env.CHURCH_CLIENT_ID,
+    clientSecret: env.CHURCH_CLIENT_SECRET,
+    scope: "people:read",
+    apiOrigins: ["https://api.example.com"],
+  },
+  tools: [{
+    name: "get_person",
+    description: "Read one person",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    handler: async ({ id }, ctx) => {
+      const response = await ctx.oauth!.fetch(
+        `https://api.example.com/people/${encodeURIComponent(id)}`,
+      );
+      return response.json();
+    },
+  }],
+});
+```
+
+Nothing is discovered, registered, or learned. Every URL is configuration, so
+the rule for [URLs a downstream advertises](#urls-a-downstream-advertises)
+has nothing to check, and the endpoints are checked once, at construction:
+HTTPS (HTTP only on loopback), no credentials, no fragment. PKCE with S256 is
+on unless `pkce: false`, which drops the challenge from the consent URL and
+the verifier from the exchange, for a server that refuses them.
+`authorizationParams` adds provider parameters but cannot restate the grant's
+own, and `tokenRequestHeaders` adds headers to the code exchange and every
+refresh — CCB's token endpoint wants its own `Accept` media type — but cannot
+set `Authorization`, `Content-Type`, `Content-Length`, `Cookie`, or `Host`. `tokenEndpointAuthMethod` defaults to `client_secret_basic` with a secret
+and `none` without; the mismatched pairings refuse to boot. A static server has
+no advertised issuer, so no RFC 9207 `iss` is demanded and no RFC 8707
+`resource` is sent. The grant is bound to the token endpoint instead:
+repointing it fences the old tokens behind a new epoch rather than sending
+them to the new server.
+
+**The client lives in deployment configuration, not a vault slot.** It is the
+deployment's identity at the provider — one per deployment, like Clerk's
+`secretKey` — while a vault slot belongs to an owner: on a personal connector
+every human would paste the deployment's secret into their own partition.
+Configuration also keeps it out of storage altogether. It is never written,
+sealed or otherwise, so a leaked store holds no client secret, Disconnect has
+nothing of it to delete, and Restart has no registration to carry forward.
+Read it from the environment or a Worker secret; an empty string, the usual
+unset variable, refuses to boot without quoting it.
+
+Handlers never see the grant. `ctx.oauth.fetch(url, init)` sends the calling
+owner's access token as `Authorization: Bearer` and does four things a
+hand-rolled header would not:
+
+- **It sends the token to `apiOrigins` and nowhere else.** A request to any
+  other origin is refused before it leaves, so an untrusted URL in a response
+  — a pagination link, a webhook target — cannot carry the token off.
+  Redirects come back unfollowed, and a handler cannot set `Authorization`
+  itself.
+- **A 401 earns exactly one recovery.** If another request has already
+  rotated a token in, that token is used; otherwise one refresh runs through
+  the same coordinator as `remoteMcp()`, coalesced across requests, with the
+  rotating refresh token persisted even if its owner is cancelled after the
+  answer arrives. The request is then replayed once, which is why a stream
+  body is refused.
+- **Failures land in the existing classes.** No grant, a second 401, or a
+  [dead refresh](#refresh-failures), whose refused tokens are deleted on the
+  spot, is `auth_required` and routes the agent to `authorize_connector`. An
+  authorization-server outage is a retryable `unavailable` that keeps the
+  grant. A second 401 is latched for the rest of the request scope, so a
+  program's next fifty calls do not spend fifty refreshes on it.
+- **It reads and writes nothing a handler can name.** Storage, sealing, and the
+  owner partition are the registry's, exactly as for `remoteMcp()`.
+
+Everything else is the `remoteMcp()` grant, unchanged: the epoch fence and its
+cleanup lineage, sealing under the vault key, shared and personal ownership,
+the callback route and its state and principal checks, `authorize_connector`,
+and the operator's Connect, Restart, and Disconnect. Status reports a stored
+grant as healthy without asking the downstream — failing at use is enough —
+and never starts authorization. One difference is deliberate: the first start
+publishes a modern epoch at once. The legacy generation exists so a grant from
+before epochs survives an upgrade, and an `api()` grant has no such past.
+
+`oauth` and `credential` are exclusive on one connector, so `auth_required`
+names one recovery. A provider that offers both a personal access token and
+OAuth, as Planning Center does, lets the deployment choose which to pass;
+handlers branch on whether `ctx.oauth` is present.