@zackbart/connecta 0.26.0 → 0.26.1

package/dist/routes/oauth-management.js

@@ -1,8 +1,29 @@
 import { Effect, Result } from "effect";
+import { drainOAuthStartResets } from "../auth/oauth-start-reset.js";
 import { closeScope } from "../runtime/connector-scope.js";
+import { withDeadlineEffect } from "../runtime/run.js";
 import { isSafeHttpUrl } from "../ui.js";
 import { authorizedPerson, refuse, serveOperator, visibleRegistry, } from "./operator.js";
 import { mayManageConnector, isSameOrigin, msg, privateJson, } from "./shared.js";
+/** Bounds the start and its handoff; invalidation and scope close finish after it. */
+const OAUTH_START_TIMEOUT_MS = 30_000;
+/**
+ * How a POST starts authorization, from its `mode` query parameter:
+ * `restart` (the default) resets the connector to a fresh epoch — wiping the
+ * grant, the client registration, and discovery — before starting over;
+ * `continue` hands back a recent pending authorization URL when one exists
+ * and otherwise starts a flow in the current epoch, keeping the stored
+ * registration. `null` is a malformed request.
+ */
+function startMode(url) {
+    const modes = url.searchParams.getAll("mode");
+    if (modes.length === 0)
+        return "restart";
+    const [mode] = modes;
+    return modes.length === 1 && (mode === "continue" || mode === "restart")
+        ? mode
+        : null;
+}
 function oauthManagementRequest(context, connectorId) {
     const { request, baseUrl, defer, opts } = context;
     return Effect.gen(function* () {
@@ -27,35 +48,65 @@ function oauthManagementRequest(context, connectorId) {
         if (!disconnecting && request.method !== "POST") {
             return yield* refuse("method not allowed", 405);
         }
-        const ctx = registry.contextFor(connectorId, baseUrl, {});
+        const mode = disconnecting ? undefined : startMode(context.url);
+        if (mode === null) {
+            return yield* refuse('mode must be "continue" or "restart"', 400);
+        }
+        let ctx;
         // The connector scope this request opened ends with it, however it ends.
-        yield* Effect.addFinalizer(() => closeScope(connector, ctx, defer));
-        const operation = yield* Effect.result(Effect.tryPromise({
+        yield* Effect.addFinalizer(() => ctx ? closeScope(connector, ctx, defer) : Effect.void);
+        const timeoutError = new Error("OAuth authorization start timed out");
+        const operation = yield* Effect.result(withDeadlineEffect((signal) => Effect.tryPromise({
             try: async () => {
+                ctx = registry.contextFor(connectorId, baseUrl, {}, { signal });
                 if (disconnecting) {
                     await disconnectAuth(ctx);
                     return undefined;
                 }
-                const started = await startAuth(ctx, { force: true });
+                const started = await startAuth(ctx, { force: mode === "restart" });
+                if (signal.aborted)
+                    throw signal.reason;
                 if (started.authorizationUrl) {
                     await registry.bindOAuthHandoff(connectorId, started.authorizationUrl);
                 }
                 return started;
             },
             catch: (error) => error,
+        }), {
+            // A disconnect deliberately ignores both browser cancellation and
+            // this start deadline so its reset reaches invalidation.
+            ...(disconnecting ? {} : { timeoutMs: OAUTH_START_TIMEOUT_MS }),
+            ...(disconnecting ? {} : { signal: request.signal }),
+            timeoutError,
         }));
-        // The old grant and its cached catalog are invalid after either operation,
-        // including a partially failed physical cleanup whose epoch fence succeeded.
-        const invalidated = yield* Effect.result(Effect.tryPromise({
-            try: () => registry.invalidateStored(connectorId),
-            catch: (error) => error,
-        }));
+        const opened = ctx;
+        if (Result.isFailure(operation) && opened) {
+            // Storage has no abort contract. If a reset's generation write is still
+            // pending, answering now would let it publish over a newer flow.
+            yield* Effect.promise(() => drainOAuthStartResets(opened.requestScope ?? opened));
+        }
+        // A disconnect or a restart invalidates the old grant and its cached
+        // catalog, even when a partially failed physical cleanup left its epoch
+        // fence standing. So does a continued start that had to begin a new flow:
+        // the grant it found was missing or refused. A continued start that
+        // reused a pending URL or found the connection healthy changed nothing,
+        // so the catalog stays. (A continue does reset a disconnected connector,
+        // but the disconnect already invalidated that catalog.)
+        const started = Result.isSuccess(operation) ? operation.success : undefined;
+        const reused = mode === "continue" && started?.authorizationReused === true;
+        const unchanged = mode === "continue" && (reused || started?.state === "ok");
+        const invalidated = unchanged
+            ? Result.succeed(undefined)
+            : yield* Effect.result(Effect.tryPromise({
+                try: () => registry.invalidateStored(connectorId),
+                catch: (error) => error,
+            }));
         // Every failure below answers in the route's own fixed words. A hook's
         // rejection and a status message can quote a token endpoint's error body
         // or a provider's refusal, either of which can quote the secret it was
         // sent, so that text goes to the deployment's log and nowhere else.
         const failed = (detail, fixed, status) => {
-            opts.logger.warn(`[connecta] connector "${connectorId}" OAuth ${disconnecting ? "disconnect" : "restart"} failed: ${detail}`);
+            opts.logger.warn(`[connecta] connector "${connectorId}" OAuth ${disconnecting ? "disconnect" : mode} failed: ${detail}`);
             return refuse(fixed, status);
         };
         const couldNot = disconnecting
@@ -64,6 +115,9 @@ function oauthManagementRequest(context, connectorId) {
         // A Result, not a caught value, decides whether it failed: a hook that
         // rejects with no reason at all still failed.
         if (Result.isFailure(operation)) {
+            if (operation.failure === timeoutError) {
+                return yield* failed(`start exceeded ${OAUTH_START_TIMEOUT_MS} ms`, "OAuth authorization start timed out", 504);
+            }
             return yield* failed(msg(operation.failure), couldNot, 400);
         }
         if (Result.isFailure(invalidated)) {
@@ -92,7 +146,7 @@ function oauthManagementRequest(context, connectorId) {
         // stopped shipping, and the state and the link are the whole answer.
         return privateJson({
             state: result.state,
-            ...(authorizationUrl ? { authorizationUrl } : {}),
+            ...(authorizationUrl ? { authorizationUrl, reused } : {}),
         });
     }).pipe(Effect.scoped);
 }

package/dist/routes/oauth.js

@@ -1,92 +1,59 @@
 import { Effect } from "effect";
 import { oauthValueStorageKey } from "../auth/downstream-oauth.js";
-import { resolveBranding } from "../branding.js";
+import { escapeHtml, renderPage, resolveBranding, STATUS_ICONS } from "../branding.js";
 import { oauthCallbackOutcome, providerErrorReason, } from "../oauth-callback-outcome.js";
 import { authorizeUiIdentity, mayManageConnector, validateAuthPermissions, loggableValue, msg, } from "./shared.js";
-function escapeHtml(value) {
-    return value
-        .replaceAll("&", "&")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;");
-}
+const TONE_MARKS = {
+    ok: { className: " ok", icon: STATUS_ICONS.ok, label: "Connected" },
+    declined: { className: "", icon: STATUS_ICONS.declined, label: "Not connected" },
+    problem: { className: " danger", icon: STATUS_ICONS.problem, label: "Not connected" },
+};
 /**
- * The callback's one page. It renders a reason from a closed set and that
- * reason's fixed copy, so nothing the request carried — the provider's `error`
- * parameter, an exchange failure's message — can reach the body. Escaping
- * stays anyway: branding and the configured connector id are still strings.
+ * The callback's one page, in the shared layout. It renders a reason from a
+ * closed set and that reason's fixed copy, so nothing the request carried —
+ * the provider's `error` parameter, an exchange failure's message — can reach
+ * the body. The connector's title appears only when `connector` is passed,
+ * which the route does only after the state check, and `oauthCallbackOutcome`
+ * gates it by reason again; every refusal before that point is the same bytes
+ * for every connector id and path. Escaping stays anyway: branding and a
+ * configured title are still strings.
+ *
+ * The fix prompt is for whoever runs the deployment, and the person reading
+ * this page is often a teammate finishing personal auth, so it sits folded
+ * under a quiet disclosure rather than in the message.
  */
-function html(reason, branding, hasUi = false, connectorId) {
-    const outcome = oauthCallbackOutcome(reason, connectorId);
-    const brand = resolveBranding(branding);
-    const title = brand.pageTitle;
-    const owner = brand.ownerName
-        ? brand.ownerUrl
-            ? `<a class="brand" href="${escapeHtml(brand.ownerUrl)}">${escapeHtml(brand.ownerName)}</a>`
-            : `<span class="brand">${escapeHtml(brand.ownerName)}</span>`
-        : brand.productUrl
-            ? `<a class="brand" href="${escapeHtml(brand.productUrl)}">${escapeHtml(brand.productName)}</a>`
-            : `<span class="brand">${escapeHtml(brand.productName)}</span>`;
-    const product = brand.ownerName
-        ? brand.productUrl
-            ? `<a class="product" href="${escapeHtml(brand.productUrl)}">${escapeHtml(brand.productName)}</a>`
-            : `<span class="product">${escapeHtml(brand.productName)}</span>`
+function html(reason, opts, connector) {
+    const brand = resolveBranding(opts.branding);
+    const outcome = oauthCallbackOutcome(reason, connector, brand.productName);
+    const mark = TONE_MARKS[outcome.tone];
+    const uiMounted = Boolean(opts.ui);
+    const home = uiMounted
+        ? `<div class="status-actions"><a class="btn${outcome.tone === "ok" ? "" : " primary"}" href="/">Return to ${escapeHtml(brand.productName)}</a></div>`
+        : "";
+    const details = outcome.fixPrompt
+        ? `<details class="status-details">
+      <summary>Details for the operator</summary>
+      <p>If this keeps happening, send this to whoever runs ${escapeHtml(brand.productName)}. It is written for a coding agent working on the deployment and carries nothing from the provider's response.</p>
+      <pre>${escapeHtml(outcome.fixPrompt)}</pre>
+    </details>`
         : "";
-    return new Response(`<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<meta name="theme-color" content="${escapeHtml(brand.themeColor)}">
-<link rel="icon" href="${escapeHtml(brand.faviconHref)}" type="image/svg+xml">
-<link rel="shortcut icon" href="/favicon.ico">
-<title>${escapeHtml(title)}</title>
-<style>
-  * { border-radius: 0; box-sizing: border-box; }
-  html { color: #000; background: #fff; font: 16px/1.5 "Helvetica Neue",
-    Helvetica, Arial, sans-serif; -webkit-font-smoothing: antialiased; }
-  body { margin: 0; min-height: 100vh; }
-  ::selection { color: #fff; background: #000; }
-  .shell { margin: 0 auto; max-width: 70rem; padding: 1rem; }
-  .grid { display: grid; gap: 1rem 1.5rem;
-    grid-template-columns: repeat(3, minmax(0, 1fr)); }
-  .brand { font-weight: 500; grid-column: 1; text-decoration: none; }
-  .product { grid-column: 2 / -1; }
-  main { margin-top: 5rem; }
-  h1, p { font: inherit; margin: 0; }
-  h1 { grid-column: 1; }
-  .copy { grid-column: 2 / -1; max-width: 34em; }
-  .copy > * + * { margin-top: 1.5rem; }
-  a { color: inherit; text-decoration: underline; text-decoration-thickness: 1.5px;
-    text-underline-offset: .22em; }
-  a:hover { text-decoration-color: transparent; }
-  a:focus-visible, summary:focus-visible { outline: 1px solid #000; outline-offset: 2px; }
-  summary { cursor: pointer; }
-  pre { font: 13px/1.5 ui-monospace, Menlo, Consolas, monospace; margin: .75rem 0 0;
-    padding: .75rem; white-space: pre-wrap; border: 1px solid #000; user-select: all; }
-  @media (max-width: 36.99rem) {
-    .grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-    .product { grid-column: 2; }
-    main { margin-top: 3rem; }
-    h1, .copy { grid-column: 1 / -1; }
-  }
-</style>
-</head>
-<body>
-  <header class="shell grid">
-    ${owner}
-    ${product}
-  </header>
-  <main class="shell grid" data-oauth-callback="${outcome.reason}">
-    <h1>Connection status</h1>
-    <div class="copy">
-      <p>${escapeHtml(outcome.message)}</p>
-      ${outcome.fixPrompt ? `<details><summary>Fix prompt for a coding agent</summary><pre>${escapeHtml(outcome.fixPrompt)}</pre></details>` : ""}
-      ${hasUi ? `<p><a href="/">Return to ${escapeHtml(brand.productName)}</a></p>` : ""}
+    const body = `<main class="page shell" data-oauth-callback="${outcome.reason}">
+  <section class="status-page">
+    <div class="status-head">
+      <span class="status-mark${mark.className}" aria-hidden="true">${mark.icon}</span>
+      <p class="status-label${mark.className}">${mark.label}</p>
     </div>
-  </main>
-</body>
-</html>`, { status: outcome.status, headers: { "Content-Type": "text/html; charset=utf-8" } });
+    <h1>${escapeHtml(outcome.heading)}</h1>
+    <p class="status-copy">${escapeHtml(outcome.message)}</p>
+    ${home}
+    ${details}
+  </section>
+</main>`;
+    return new Response(renderPage(opts.branding, {
+        title: `${outcome.heading} — ${brand.pageTitle}`,
+        uiMounted,
+        body,
+    }), { status: outcome.status, headers: { "Content-Type": "text/html; charset=utf-8" } });
 }
 /**
  * Pay the storage read a real downstream-OAuth refusal pays, on the refusal
@@ -138,10 +105,10 @@ async function finishOAuthCallback(context) {
     const { path, url, baseUrl, opts } = context;
     const error = url.searchParams.get("error");
     if (error)
-        return html(providerErrorReason(error), opts.branding, Boolean(opts.ui));
+        return html(providerErrorReason(error), opts);
     const code = url.searchParams.get("code");
     if (!code)
-        return html("invalid_callback", opts.branding, Boolean(opts.ui));
+        return html("invalid_callback", opts);
     const id = path.slice("/oauth/callback/".length);
     const state = url.searchParams.get("state");
     const callbackTarget = await opts.registry.oauthCallbackView(id, state);
@@ -155,7 +122,7 @@ async function finishOAuthCallback(context) {
     const connectorContext = callbackRegistry
         ? callbackRegistry.contextFor(id, baseUrl)
         : opts.registry.contextFor(id, baseUrl);
-    const refused = () => html("invalid_callback", opts.branding, Boolean(opts.ui));
+    const refused = () => html("invalid_callback", opts);
     if (!connector || !connector.finishAuth) {
         await equalizeRefusalCost(connectorContext);
         return refused();
@@ -220,19 +187,19 @@ async function finishOAuthCallback(context) {
             opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
                 `${loggableValue(id)} with 500: its principal handoff could not be ` +
                 `consumed (${loggableValue(msg(err))}). No authorization code was exchanged.`);
-            return html("handoff_failed", opts.branding, Boolean(opts.ui), id);
+            return html("handoff_failed", opts, connector);
         }
     }
     try {
         await connector.finishAuth(code, connectorContext, url.searchParams);
         await callbackRegistry.invalidateStored(id);
-        return html("connected", opts.branding, Boolean(opts.ui), id);
+        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.
         opts.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
             `with 500: the authorization code exchange threw ${loggableValue(msg(err))}.`);
-        return html("exchange_failed", opts.branding, Boolean(opts.ui), id);
+        return html("exchange_failed", opts, connector);
     }
 }

package/dist/routes/ui.js

@@ -95,9 +95,15 @@ export async function routeUi(context) {
         // An artifact shell frames the sandboxed page from its own origin and
         // nothing else; Connections stays on the deployment's public origin.
         const homeUrl = opts.publicUrl ? new URL("/", opts.publicUrl).toString() : "/";
+        // The artifact host serves no favicon, so a shell there takes its icons
+        // from the public origin, as the 404 does; on the main host they stay
+        // root-relative.
+        const onArtifactHost = Boolean(opts.artifactOrigin) &&
+            url.origin === new URL(opts.artifactOrigin).origin;
+        const iconOrigin = onArtifactHost ? opts.publicUrl : undefined;
         return new Response(request.method === "HEAD"
             ? null
-            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage, { homeUrl }), {
+            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage, { homeUrl, iconOrigin }), {
             status: 200,
             headers: {
                 "Content-Type": "text/html; charset=utf-8",

package/dist/server.js

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { notFoundResponse } from "./branding.js";
 import { aggregateCallAdmissionSnapshots } from "./call-admission.js";
 import { isAdmittingExecutor } from "./executor-admission.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
@@ -107,7 +108,7 @@ export function createFetchHandler(opts) {
             const response = yield* metadata(request, baseUrl);
             if (response)
                 return response;
-            return new Response("Not Found", { status: 404 });
+            return notFoundResponse(request, opts);
         }
         if (path === "/health")
             return yield* Effect.promise(health);
@@ -117,7 +118,7 @@ export function createFetchHandler(opts) {
         const mcp = yield* routeMcp.handle(context);
         if (mcp)
             return mcp;
-        return new Response("Not Found", { status: 404 });
+        return notFoundResponse(request, opts);
     });
     const serve = (request, runtimeContext) => Effect.suspend(() => {
         const url = new URL(request.url);
@@ -127,15 +128,16 @@ export function createFetchHandler(opts) {
             ? runtimeContext.waitUntil.bind(runtimeContext)
             : undefined;
         // The artifact hostname has no MCP, health, OAuth, or operator routes.
-        // Dispatch before MCP origin checks so even a hostile /mcp is a plain 404.
+        // Dispatch before MCP origin checks so even a hostile /mcp gets the same
+        // 404 as any other unserved path.
         if (opts.artifactOrigin && url.origin === new URL(opts.artifactOrigin).origin) {
             if (!isArtifactPath(path) || !opts.ui || !opts.artifactsModule) {
-                return Effect.succeed(withSecurityHeaders(new Response("Not Found", { status: 404 }), url, path));
+                return Effect.succeed(withSecurityHeaders(notFoundResponse(request, opts), url, path));
             }
             const context = {
                 request, url, path, baseUrl: opts.artifactOrigin, opts, defer, runtimeContext,
             };
-            return Effect.map(Effect.promise(() => opts.ui.handle(context)), response => withSecurityHeaders(response ?? new Response("Not Found", { status: 404 }), url, path));
+            return Effect.map(Effect.promise(() => opts.ui.handle(context)), response => withSecurityHeaders(response ?? notFoundResponse(request, opts), url, path));
         }
         if (opts.artifactOrigin && isArtifactPath(path) && opts.ui && opts.artifactsModule) {
             const target = new URL(opts.artifactOrigin);

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

@@ -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
@@ -98,13 +98,6 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         ...detailOptions,
     }));
 }
-function escapeHtmlAttr(value) {
-    return value
-        .replaceAll("&", "&")
-        .replaceAll('"', """)
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;");
-}
 function jsonForInlineScript(value) {
     return JSON.stringify(value)
         .replaceAll("<", "\\u003c")
@@ -145,71 +138,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,9 +176,8 @@ 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")
@@ -252,7 +209,7 @@ 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 routes = [
                 ...(context.opts.credentialVault ? [routeCredentials] : []),

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