@zackbart/connecta 0.26.0 → 0.26.2

package/dist/skills.js

@@ -1,5 +1,5 @@
 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 result shapes 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. Inspect unfamiliar read results with a small sample before proceeding.";
 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
@@ -8,7 +8,7 @@ const RECOVERY = 'After auth_required use authorize_connector. After a truncated
  * only that programs *may* write reads each write after a lookup as a known
  * one and sends them one prompt at a time.
  */
-export const CONNECTA_INSTRUCTIONS = `Choose a route before discovery. A known-address read needs only 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, loops, joins, branches, and writes that follow reads. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. A program's call to a tool not annotated readOnlyHint: true pauses unsent; resume_execution with the returned token, address, and args approves it and continues the program (approval "tool" covers that tool for the run). Keep catalog inspection top level with search_tools. ${RECOVERY}`;
+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.
@@ -35,7 +35,7 @@ The minimum guest API is:
 
 ## Discover and select
 
-Search and call in one run when schemas suffice. For unfamiliar result formats, return a small sample and continue; do not guess a parser. Use 2–4 distinctive action/object terms; search distinct operations separately.
+Search and call in one run when schemas suffice. Sample unfamiliar reads. Reduce a one-time write's full result here or page a direct call with get_result; never repeat the write to recover output. Search distinct operations separately with 2–4 distinctive action/object terms.
 
 For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 8), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An \`outputSchemaSource: "observed"\` shape is a hint, not a contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
@@ -43,12 +43,12 @@ For top-level catalog inspection or approval-required discovery, omit \`limit\`
 - Use \`includeSchemas: "json"\` for programmatic schema inspection; compact schemas are text, not objects with \`.properties\`. Check connectorTitle for the account/environment, then address, purpose, annotations, inputs, and outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
-- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe. If a result shape is unclear, return a small sample for inspection before continuing.
+- Reduce through available output keys. An observed key is a hint; later results may differ. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe.
 - Match provider identifiers and names exactly after resolving them from source data or a connector guide. A broad regular expression that merely finds a plausible value is not identity resolution.
 - 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 tools explicitly annotated \`readOnlyHint: true\` are reachable unasked. Where the MCP instructions say programs pause, any other call pauses unsent and \`execute_code\` returns \`paused\` with the write and a token; repeat all three unchanged in top-level \`resume_execution\` to approve (\`approval: "tool"\` covers that tool for the run). Replay reruns the program against a journal: make the same calls in the same order. The catalog, credential, admission, and approval gates run below the sandbox; code cannot widen its authority.
+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.
 
 ## Errors and repair
 
@@ -59,7 +59,7 @@ Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`detail
 - \`write_outcome_unknown\`: sent but unanswered, never re-sent; check the target.
 - \`execution_expired\`, \`_diverged\`, \`_interrupted\`: check \`writes\`, then rerun.
 - \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
-- A truncated direct-call result: follow its \`get_result\` action. A truncated program result has no page handle; filter, map, or slice inside a new program.
+- 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.
 
 For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. Every call makes one attempt; use the returned error classification and retry hint to decide whether to reissue. \`diagnostics: true\` adds timing.

package/dist/types.d.ts

@@ -217,6 +217,11 @@ export interface ConnectorStatus {
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
     authorizationUrl?: string;
+    /**
+     * Set by a non-forced `startAuth` that handed back a still-recent pending
+     * authorization URL instead of starting a new flow. Absent otherwise.
+     */
+    authorizationReused?: boolean;
     message?: string;
     /**
      * Drift observed the last time this connector served a catalog refresh *in

package/dist/ui.d.ts

@@ -7,7 +7,7 @@ import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, Connector, ConnectorStatus, ToolDef, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
-export type OperatorPage = "connections" | "activity" | "artifacts" | "artifact";
+export type OperatorPage = "tokens" | "connections" | "activity" | "artifacts" | "artifact";
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
 /**
@@ -52,6 +52,11 @@ export declare function buildUiData(registry: RegistryView, baseUrl: string, ser
 export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage, options?: {
     /** Where the Connections page lives, when this shell is on another origin. */
     homeUrl?: string;
+    /**
+     * The origin that serves `/favicon.*`, when this shell is on another one:
+     * an artifact host answers those paths with 404. See `PageLayout.iconOrigin`.
+     */
+    iconOrigin?: string | undefined;
 }): string;
 /** Mount the connection UI without enabling any storage or activity module. */
 export declare function operatorUi(options?: {

package/dist/ui.js

@@ -6,7 +6,7 @@ import { runEdge } from "./runtime/run.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { resolveBranding, isSafeHttpsUrl, themeCss } from "./branding.js";
+import { escapeHtml, isSafeHttpsUrl, notFoundResponse, renderPage, resolveBranding, } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 /**
  * A JS string literal safe to inline in a script element. Escaping `/` keeps
@@ -17,6 +17,7 @@ function stringForInlineScript(value) {
 }
 const OPERATOR_PAGE_LABELS = {
     connections: "Connections",
+    tokens: "Access tokens",
     activity: "Activity",
     artifacts: "Artifacts",
     artifact: "Artifact",
@@ -24,6 +25,8 @@ const OPERATOR_PAGE_LABELS = {
 /** `/artifacts/<id>` and its snapshots, `/artifacts/<id>/v/<version>`. */
 const ARTIFACT_PAGE = /^\/artifacts\/[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?(?:\/v\/\d{1,9})?$/;
 export function operatorPageForPath(path) {
+    if (path === "/tokens")
+        return "tokens";
     if (path === "/")
         return "connections";
     if (path === "/activity")
@@ -98,13 +101,6 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         ...detailOptions,
     }));
 }
-function escapeHtmlAttr(value) {
-    return value
-        .replaceAll("&", "&amp;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;");
-}
 function jsonForInlineScript(value) {
     return JSON.stringify(value)
         .replaceAll("<", "\\u003c")
@@ -145,71 +141,36 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
         }
         : (uiAuth ?? { kind: "bearer" });
     const brand = resolveBranding(branding);
-    const title = operatorPageTitle(page, brand.pageTitle);
     // When an operator shell ships a nonce-based CSP, every script it emits must
     // carry that nonce to run; without a nonce the markup is unchanged.
     const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
-    // Top-left corner. With an owner set it reads "<owner> <product>"; without
-    // one the product label stands alone. Either half links out when the
-    // matching URL is configured.
-    const owner = brand.ownerName
-        ? brand.ownerUrl
-            ? `<a class="brand navlink" href="${escapeHtmlAttr(brand.ownerUrl)}">${escapeHtmlAttr(brand.ownerName)}</a>`
-            : `<span class="brand">${escapeHtmlAttr(brand.ownerName)}</span>`
-        : brand.productUrl
-            ? `<a class="brand navlink" href="${escapeHtmlAttr(brand.productUrl)}">${escapeHtmlAttr(brand.productName)}</a>`
-            : `<span class="brand">${escapeHtmlAttr(brand.productName)}</span>`;
-    const product = brand.ownerName
-        ? brand.productUrl
-            ? `<a class="product navlink" href="${escapeHtmlAttr(brand.productUrl)}">${escapeHtmlAttr(brand.productName)}</a>`
-            : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
-        : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtml(clerk.publishableKey)}" src="${escapeHtml(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
-    // A pinned scheme is an attribute, not a stylesheet edit: the dark palette
-    // keys off `html[data-scheme]`, so "system" leaves the attribute off and the
-    // media query decides.
-    const schemeAttr = brand.theme.colorScheme === "system"
-        ? ""
-        : ` data-scheme="${brand.theme.colorScheme}"`;
-    return `<!doctype html>
-<html lang="en"${schemeAttr}>
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="theme-color" content="${escapeHtmlAttr(brand.themeColor)}">
-<meta name="description" content="${escapeHtmlAttr(brand.description)}">
-<link rel="icon" href="${escapeHtmlAttr(brand.faviconHref)}" type="image/svg+xml">
-<link rel="shortcut icon" href="/favicon.ico">
-<title>${escapeHtmlAttr(title)}</title>
-${clerkScript}
-<style>${OPERATOR_UI_CSS}${themeCss(brand.theme)}</style>
-</head>
-<body>
-<a class="skip-link" href="#operatorContent">Skip to operator page</a>
-<header class="masthead shell">
-  <div class="masthead-inner">
-    <div class="mast-nav">
-      ${owner}
-      ${product}
-    </div>
-    <div id="operatorNav"></div>
-  </div>
-</header>
-
+    // The shared layout owns the head, scheme, theme, and masthead; the shell
+    // adds its own bundle (which already imports the shared tokens), the nav
+    // mount, and the app.
+    return renderPage(branding, {
+        title: operatorPageTitle(page, brand.pageTitle),
+        uiMounted: true,
+        iconOrigin: options.iconOrigin,
+        styles: OPERATOR_UI_CSS,
+        head: clerkScript,
+        skipTo: { id: "operatorContent", label: "Skip to operator page" },
+        mastheadEnd: '<div id="operatorNav"></div>',
+        body: `
 <main id="operatorContent" class="page shell" tabindex="-1">
   <div class="lead">
     <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
     <div class="lead-copy">
-      <p>${escapeHtmlAttr(brand.description)}</p>
+      <p>${escapeHtml(brand.description)}</p>
       <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
       does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>
     </div>
   </div>
 </main>
-
-<script${nonceAttr}>
+`,
+        tail: `<script${nonceAttr}>
 const AUTH = ${jsonForInlineScript(auth)};
 const MCP_URL = ${jsonForInlineScript(mcpUrl)};
 const INITIAL_PAGE = ${jsonForInlineScript(page)};
@@ -218,12 +179,11 @@ const TITLE_SUFFIX = ${jsonForInlineScript(brand.pageTitle)};
 const PRODUCT_NAME = ${stringForInlineScript(brand.productName)};
 const PRODUCT_DESCRIPTION = ${stringForInlineScript(brand.description)};
 const PRODUCT_OPERATOR_LABEL = ${stringForInlineScript(brand.productName + " operator")};
-${OPERATOR_UI_SCRIPT}</script>
-</body>
-</html>`;
+${OPERATOR_UI_SCRIPT}</script>`,
+    });
 }
 function ownsOperatorPath(reserved, path) {
-    if (path === "/activity")
+    if (path === "/activity" || path === "/tokens")
         return true;
     return reserved.some((pattern) => pattern.endsWith("/*")
         ? path.startsWith(pattern.slice(0, -1))
@@ -252,8 +212,11 @@ export function operatorUi(options = {}) {
                 // The pages' JSON API and the sandboxed frame; the module owns both,
                 // and this bundle imports none of it.
                 return (await artifacts?.handle(context)) ??
-                    new Response("Not Found", { status: 404 });
+                    notFoundResponse(context.request, context.opts);
             }
+            const tokenResponse = await context.opts.accessTokens?.handle(context);
+            if (tokenResponse)
+                return tokenResponse;
             const routes = [
                 ...(context.opts.credentialVault ? [routeCredentials] : []),
                 routeOAuthManagement,

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.26.0";
+export declare const CONNECTA_VERSION = "0.26.2";

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.26.0";
+export const CONNECTA_VERSION = "0.26.2";

package/documentation/architecture.md

@@ -287,14 +287,24 @@ answers only `{ ok }`), log its text, and the page picks a sentence by outcome
 without ever rendering what the server sent. Credential handoff URLs exist only while the UI is
 mounted; OAuth callbacks never need it.
 
-Its appearance is one token layer. `src/operator-ui/browser.css` resolves every
-color, radius, and font through a custom property and mixes the rest from those
-with `color-mix`, so `branding.theme` only has to append a `:root` block after
-that stylesheet. The five tokens it accepts are gated in `src/branding.ts`, each
-by a narrow syntactic check: deployment config reaches a `<style>` element here,
-and an unvalidated value would be CSS injection. The dark palette is the same
-tokens under `prefers-color-scheme`; `colorScheme` pins one with a `data-scheme`
-attribute on the page.
+Its appearance is one token layer, and it is not the UI's alone: every page
+connecta shows a person — the operator shell, the OAuth callback, a browser's
+404, the artifact frame and Markdown pages — reads it. `src/operator-ui/tokens.css`
+resolves every color, radius, and font through a custom property and mixes the
+rest from those with `color-mix`; `page.css` holds the base typography and the
+primitives (shell, masthead, buttons, badges, messages, the one-message status
+page). The UI's `browser.css` imports both, and the build writes the same CSS,
+minified, into `src/page-styles.ts`, a module of two strings that core imports
+without the UI bundle, so an OAuth callback still renders with the UI omitted.
+`renderPage` in `src/branding.ts` is the one layout: head, favicon (the default
+is linked only when the UI serves it), `data-scheme`, the tokens with the theme
+after them, and the masthead. So `branding.theme` only has to append a `:root`
+block after the stylesheet. The five tokens it accepts are gated in
+`src/branding.ts`, each by a narrow syntactic check: deployment config reaches a
+`<style>` element here, and an unvalidated value would be CSS injection. The
+dark palette is the same tokens under `prefers-color-scheme`; `colorScheme` pins
+one with a `data-scheme` attribute on the page, and the artifact viewer passes
+the same attribute into a Markdown page, never into authored HTML.
 
 The artifacts module — `artifacts()` from `/artifacts`, implemented in
 `src/artifacts/` — is the one module that contributes a connector. Core
@@ -604,6 +614,6 @@ compiling and configuring the real thing.
   connector limiters, then the executor, then the Connecta's runtime; Node's `listen()` calls it on
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
-  invalid admission rule, the removed `accessTokens` option, a missing executor:
+  invalid admission rule, the old boolean `accessTokens` option, a missing executor:
   all refuse to boot (`test/config.test.ts`, `test/registry.test.ts`). Starting
   in the wrong shape is worse than not starting.

package/documentation/auth.md

@@ -7,7 +7,7 @@ static bearers are checked first, then other providers in configuration order.
 An `InboundAuth` provider's `authorize(request, baseUrl, runtimeContext)`
 returns either `{ ok: true, userId?, subjectId?, principal? }` or a refusal
 carrying its own `Response`, so the provider owns its challenge. Connecta
-issues no tokens of its own and serves no token-management routes.
+issues managed client tokens only when the optional `accessTokens` module is configured.
 
 The bearer adapter challenges with `WWW-Authenticate: Bearer` and deliberately
 omits `resource_metadata`: its credential is configured out of band, so it has no
@@ -16,6 +16,67 @@ or the edge own OAuth discovery. An open deployment with any connector warns at
 construction — including API connectors carrying static auth headers, and with
 sharper wording for credential and OAuth connectors.
 
+## Managed client tokens and upgrading from v0.23
+
+Import `accessTokens` from `@zackbart/connecta/auth/access-tokens` and pass its
+module to `createConnecta`. It installs its inbound adapter and, beside `ui`,
+the Access tokens page and `/ui/access-tokens` lifecycle routes. Omitting the
+module loads none of its implementation and serves none of those routes.
+
+```ts
+import { accessTokens } from "@zackbart/connecta/auth/access-tokens";
+
+createConnecta({
+  storage,
+  accessTokens: accessTokens(storage),
+  auth: clerkAuth({ publishableKey, secretKey }),
+  ui: operatorUi(),
+  identity: {
+    connectorAccess, // Keep the existing principal and token-id grant rules.
+    accessTokenManagement: ({ principal }) =>
+      principal?.namespace === "clerk:your-existing-namespace" &&
+      principal.id === "your-operator-id",
+  },
+  connectors,
+  executor,
+});
+```
+
+For a v0.23 deployment, replace the old `accessTokens: true` or options object
+with `accessTokens: accessTokens(storage)`, using **the same storage and key
+namespace**. Keep the existing `access-token:v1:record:*` and
+`access-token:v1:lookup:*` records. Their unrevoked `cta_…` secrets keep working;
+no secret recovery, rewrite, or client rotation is needed. Preserve the existing
+identity namespaces and connector/pool grant callbacks too. Storage compatibility
+does not translate deployment configuration or invent replacement grants.
+
+The adapter preserves `access_token` actor ids, the
+`connecta:access-tokens:v1` activity namespace, friendly names, and any stored
+principal. A token without a principal stays unbound. Every request evaluates
+current identity/tool/pool grants; a token never becomes an interactive operator.
+Names are labels, never permissions. New UI-issued tokens belong to the issuing
+human's principal, and any explicitly permitted token manager can list, rename,
+or revoke deployment tokens. Static and managed bearers cannot manage tokens or
+connection credentials. Operators need an interactive auth provider.
+
+Storage must implement `list`. Existing-token verification, rename, and revoke
+also work on older adapters without `compareAndSet`; **new issuance requires
+atomic `compareAndSet`**, because counting records before writing admits too many
+concurrent creates. Active capacity defaults to 100, configurable with
+`accessTokens(storage, { maxActive: 200 })`, up to 1,000. A durable reservation
+counts before a secret is written. An interrupted create can consume capacity
+without returning a token; it is never automatically retried or released after
+an uncertain write. Avoid creating new tokens through old-version instances once
+new-version issuance has started, since those instances do not honor reservations.
+
+Secrets contain 256 random bits and only their SHA-256 digests persist. Creation
+returns the secret once; list and rename never return it. Revocation removes its
+lookup before updating metadata, and authorization has no token cache. A strongly
+consistent store makes revocation effective on the next authorization; an
+eventually consistent backend retains its own propagation delay. Requests already
+admitted are not recalled. Management writes require an exact same-origin Origin,
+and responses are private and non-cacheable.
+
 ## Origins
 
 `allowedOrigins?: readonly string[] | "*"` bounds which browsers may speak to
@@ -250,6 +311,87 @@ means authorizing again. A vault without the optional `seal`/`open` members
 keeps these values plaintext and draws a startup warning. Without any vault,
 nothing changes: the state is plaintext, as it always was.
 
+## Starting, restarting, and retiring an OAuth epoch
+
+Every downstream OAuth value lives under an **epoch**, the value of
+`oauth:generation`. A restart or disconnect publishes a new one before it
+deletes anything, and a write from a flow that captured an older epoch lands
+in that epoch's own key namespace, where no reader looks. The fence is what
+keeps a retired grant out of use; deleting the old keys is hygiene on top.
+
+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. |
+| `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
+management permission, visibility, and principal checks are the same for
+both modes, and a personal connector continues only the caller's own flow.
+A 200 answers `{ state, authorizationUrl?, reused? }`, with `reused` present
+beside every URL: `true` when an earlier start's URL came back unchanged. A
+continue that reused a URL or found the connection healthy changed nothing,
+so it leaves the cached catalog alone; every other start invalidates it. The
+ten minutes are `PENDING_AUTHORIZATION_MAX_AGE_MS`. Connecta never expires
+its own half of a URL, but authorization servers expire theirs, and a fresh
+start that keeps the registration costs one authorization request. A URL
+stored without a write time — by an earlier release, or by a connector never
+reset since epochs arrived — is stale by definition. `authorize_connector`
+without `force` follows the same rule.
+
+Continue trusts the stored registration, which carries the `redirect_uris`
+it was registered with. After a `publicUrl` change the authorization server
+refuses that client's new callback at consent. Restart registers a client
+for the current URL and recovers.
+
+A restart cannot know which retired epochs a late write reached, so it
+publishes a **cleanup lineage** under the new epoch before activating it:
+the retired epochs, as the same plain list of names every release reads, and
+beside it a record of when each retired. A published lineage is never
+rewritten. A stale writer whose own cleanup fails appends to the live
+lineage, and a restart that rewrote the list it had read could drop that
+append. An epoch leaves the lineage only by being left out of its
+successor's.
+
+A restart does the same storage work however many came before it. After the
+fence it deletes the one epoch it retired: six values, then that epoch's own
+lineage records. An epoch's manifest outlives its values only when their
+deletion failed, so the restart also reads the manifests of the eight most
+recently retired epochs (`RETRY_PROBES`) and cleans up again any that still
+have one. A Disconnect or Restart that reported a failed cleanup therefore
+deletes the old grant when the operator retries it. Before publishing, it
+sweeps up to 16 epochs retired more than `CLEANUP_GRACE_MS` (24 hours) ago,
+oldest first, and leaves out only those whose values and records were all
+deleted. A failed sweep is carried and tried again later, and never fails
+the restart. Any other epoch inside its grace is not deleted again. A late write into it is unreadable behind the fence,
+and the late writer deletes it itself. If that delete fails, the writer
+records the epoch again as retired at that moment, appending it or, when it
+is already listed, moving only its time. A restart that swept it re-reads the
+lineage before publishing and keeps it. Whatever remains is swept once the
+grace has passed. Two such writers racing can lose one time update, which
+leaves the earlier time; a time missing altogether reads as retired at the
+moment of the restart that reads it, which only lengthens a grace.
+
+**The assumption:** no request holds a retired epoch for a day. The writers
+that can land late are OAuth flows, refreshes, and readers whose Workers KV
+replica still serves the old generation for a minute or more; none of them
+run that long. If it fails, only a writer that dies between its write and
+its own cleanup leaves residue no restart tracks, and that residue is never
+readable.
+
+The lineage holds at most 5,000 epochs, the ones retired within the last day
+plus any the sweep has not reached. A restart that would exceed that is
+refused before the fence moves, which takes more than 4,000 restarts of one
+connector in a day on top of the 1,000 an earlier release allowed. A
+connector that reached that release's 1,000 wall restarts again the day it
+upgrades, and its old entries drain 16 per restart a day later. An older
+release ignores the times, so a rollback still restarts unless a lineage has
+grown past its own 1,000 cap. Deletes run six at a time, the Workers limit
+on simultaneous connections, and catalog invalidation deletes its chunks
+concurrently under the registry's chunk I/O bound.
+
 ## Refresh failures
 
 A failed token refresh means one of two things, and connecta decides which
@@ -328,7 +470,7 @@ from caller input.
 interactive human, the one default here that is open, because a single-operator
 deployment would otherwise be locked out of its own event stream. Team
 deployments should set it. There is no general administrator role and no
-token-management authority.
+implicit token-management authority. `identity.accessTokenManagement` is a separate boolean permission, false by default, evaluated only for interactive humans. Lifecycle routes also require a stable principal.
 
 ```ts
 createConnecta({
@@ -429,6 +571,28 @@ instead of a base64 stack on every route.
 
 ## Human authentication management
 
+An operator's OAuth Connect or Restart request gives the start and its handoff
+30 seconds. The request's abort signal and that deadline reach downstream OAuth
+fetches, including metadata discovery and dynamic registration. If the deadline
+expires, the route returns `504` with `OAuth authorization start timed out` after
+an already-started reset finishes. Storage has no cancellation contract: its
+generation write must drain before a response, or it could publish an old epoch
+over a newer flow. Catalog invalidation and connector scope close also finish
+outside the deadline. Those storage and cleanup waits can extend the click past
+30 seconds; the bound is on downstream work, where a hung authorization server
+was the failure. The OAuth provider checks its signal before writing and removes
+a cancelled value write that finishes late. An operator Disconnect keeps its
+existing commit-through behavior even if the browser leaves.
+
+Restart retains a dynamically registered client only when its stored issuer and
+the connector's URL, redirect URI, client metadata, auth scope, transport settings,
+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.
+
 Credential and OAuth mutation require an admitted interactive human, connector
 visibility, the appropriate shared or personal permission, and an exact
 same-origin `Origin` for browser requests. A configured MCP bearer never becomes

package/documentation/code-mode.md

@@ -504,13 +504,11 @@ provider prose remains `connector_call_failed`.
 
 ## Results and projection
 
-**R1 (verdict: projection stays explicit).** A program's return value reaches
-the model unchanged except for the size guard in `R2`. Connecta does not
-summarize, reshape, or field-select it, and there is no automatic projection
-mode: the measured byte win came from *program-authored* projection, while a
-host heuristic would drop deliberately returned fields invisibly. Helpers earn
-their way in only if [#222](https://github.com/zackbart/connecta/issues/222)
-shows programs failing to project on their own.
+**R1 (verdict: projection stays explicit).** A program's return reaches the model
+unchanged except for `R2`'s size guard. Connecta does not summarize or select
+fields. Program-authored projection saved bytes; host heuristics could drop
+deliberately returned fields. Helpers need [#222](https://github.com/zackbart/connecta/issues/222)
+evidence that programs fail to project.
 
 **R2.** The boundary is 24,000 serialized characters (~6k tokens). A value over
 it is replaced by exactly one envelope:
@@ -528,15 +526,16 @@ The envelope is itself bounded as serialized, so `totalChars` is always the true
 size of what the program returned and truncation happens exactly once no matter
 how many hops the value takes.
 
-**R3.** Truncation is a *successful* result, not an error: the program ran, and
-the honest report is that its answer was too large. The fix is a program that
-returns less, which is why the envelope says so.
+**R3.** Truncation is a *successful* result: the program ran but returned too
+much. Run a program that returns less; that is why the envelope says so.
 
-**R4 (verdict: no result paging for programs).** A truncated program result
-carries no `get_result` handle, unlike `call_tool`. `get_result` exists so a
-model can page a *downstream payload* it could not shrink; a program can shrink
-anything, so paging its result would reward the behavior code mode exists to
-remove.
+**R4 (verdict: no result paging for programs).** Program results have no
+`get_result` handle. A program can shrink its return; paging would reward
+unprojected data.
+
+For non-repeatable writes, inspect and reduce the full result before return,
+or page a direct `call_destructive_tool` result with `get_result`. Sampling a
+program result may discard the only copy.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call
 order and returned as one `logs` string, capped at 4,000 characters with a
@@ -833,6 +832,7 @@ live. `emit` is not journaled; only the completing play delivers.
 **W7.** `approval: "call"`, the default, covers that one write; `"tool"` covers
 every later call to that canonical address for the run. Approvals live in the
 header, a retry's replacing one that sent nothing; nothing else grants one.
+Keep an authorized batch in one program; use tool scope for repeated calls to that address, while other addresses still need their own approval.
 
 **W8.** A replay fails `execution_diverged`, never replayed again, when (a) a
 call has no record before the approved write is repeated, (b) the program

package/documentation/meta-tools.md

@@ -69,10 +69,14 @@ an earlier result, or several operations. A program keeps discovery, calls, and
 reduction together when the schemas and result shapes suffice, and gives each
 distinct operation its own short `connecta.search` query. That is cheaper than it
 looks: discovery inside the program returns no candidate schema to the model and
-costs no round trip. One exception — an unfamiliar provider result may come back
-as a small sample for inspection before continuing in another call, which avoids
+costs no round trip. One exception — an unfamiliar read result may come back as
+a small sample for inspection before continuing in another call, which avoids
 repeated guesses at text formats and collection roots without restoring a
-mandatory discovery-only round trip.
+mandatory discovery-only round trip. A one-time write can return the only copy
+of its result. Inspect and reduce the full value before a program returns, or
+use a direct `call_destructive_tool` result and page it with `get_result` after
+the write runs once. A program return has no page handle; sampling or slicing
+a write's output there can discard the answer.
 
 Writes take the same route. A program that reaches a tool not explicitly
 annotated read-only stops before sending it — unless the deployment's config
@@ -81,8 +85,11 @@ token; `resume_execution` repeating it is the approval, and the program
 replays from a journal to send it and carry on — to its answer, or to its next
 write. So "close the stale issues and post a summary" is one program and a few
 approvals, not one program and thirty-one top-level calls, and the program's
-reasoning survives between them. `approval: "tool"` covers the rest of the
-run's calls to that tool, so thirty closes cost one prompt. One known write
+reasoning survives between them. Keep the entire authorized batch in that
+program, including its final post. The default `approval: "call"` covers only
+the pending write. Choosing `approval: "tool"` when the batch repeats an
+address covers later calls to that tool in this run, so thirty closes cost one
+prompt; the summary post still needs its own approval. One known write
 still goes straight to `call_destructive_tool`, and top-level discovery stays
 for catalog inspection. On a deployment without resumable writes (storage
 without `compareAndSet`), a program cannot write at all: the call fails

package/ethos.md

@@ -40,7 +40,7 @@ carries them.
 | Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
 | Artifacts module | accepted | a built-in connector for team-only sandboxed pages over stored JSON; immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) |
 | Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
-| Connecta-issued access tokens | removed | inbound providers authenticate clients; bearer auth stays an optional adapter |
+| Connecta-issued access tokens | accepted | optional /auth/access-tokens preserves v0.23 secrets; config owns grants, interactive management needs explicit permission ([#619](https://github.com/zackbart/connecta/issues/619)) |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
 | Resources, prompts, and downstream MCP Apps templates | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Protocol sessions, server push, elicitation passthrough | refused | stateless per request; elicitation has no route |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of eight meta-tools.",
@@ -114,6 +114,10 @@
     "./artifacts": {
       "types": "./dist/artifacts.d.ts",
       "import": "./dist/artifacts.js"
+    },
+    "./auth/access-tokens": {
+      "types": "./dist/access-tokens.d.ts",
+      "import": "./dist/access-tokens.js"
     }
   },
   "scripts": {