@zackbart/connecta 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -4,6 +4,122 @@ All notable changes to this package are documented here.
 
 ## Unreleased
 
+## 0.26.1 — 2026-09-26
+
+This patch fixes slow OAuth restarts, unbounded downstream authorization waits,
+and operator pages that signed people out after a temporary load failure.
+Connect now opens consent in one click, and browser-facing pages share the
+configured theme. Agent guidance preserves one-time write results and keeps
+an authorized batch in one resumable program. Approval defaults and the eight
+MCP tools are unchanged. No configuration or storage migration is required;
+deployments without the operator UI can ignore the page changes. OAuth starts
+abort downstream work after 30 seconds, but uncancellable storage resets and
+cleanup must finish before the response. Restart reuses a matching client
+registration; a revoked client may still fail at consent or callback and need
+another restart. The Node template now pins 0.26.1.
+
+### Added
+
+- **Continue or restart an operator OAuth start.** `POST /ui/oauth/<id>`
+  takes `?mode=continue` or `?mode=restart`. `restart`, still the default
+  when `mode` is absent, creates a new epoch and clears the grant and
+  discovery while retaining a matching issuer-bound client registration. `continue` hands back the pending
+  authorization URL when it was written in the last ten minutes. Otherwise it
+  starts a flow in the current epoch, reusing a stored registration when one
+  exists. A first connection still registers dynamically. A disconnected
+  connector resets first. A response with a URL now carries `reused`. A continue that reused a
+  URL or found the connection healthy leaves the cached catalog alone. Any
+  other `mode` is a 400. After a `publicUrl` change, continue keeps a client
+  registered for the old callback, which the authorization server refuses;
+  restart recovers. `ConnectorStatus` gains the optional
+  `authorizationReused`, set by `remoteMcp()`'s `startAuth`.
+
+### Changed
+
+- **Pending authorization URLs expire for reuse.** A non-forced `startAuth`,
+  including `authorize_connector` without `force`, reissues a pending URL only
+  when it is under ten minutes old. The pending URL's envelope now records its
+  write time, which older readers ignore. A URL written before this release,
+  or under a pre-epoch generation, starts a fresh flow instead.
+- **OAuth cleanup deletes run concurrently.** A restart's epoch cleanup,
+  `clearPending`, and `invalidateCredentials("all")` keep up to six deletes
+  in flight, the Workers limit on simultaneous connections. Every delete is
+  still attempted, and a falsy rejection now counts as a failure. A retired
+  epoch's manifest is still removed only after all of its values. Catalog
+  invalidation deletes the root and its chunks together under the registry's
+  chunk I/O bound, so a failed root delete no longer skips the chunks.
+
+- Every page connecta renders for a person now shares one token layer and one
+  layout: the operator shell, the OAuth callback, a browser's 404, and the
+  artifact frame follow `branding.theme` and light or dark. The OAuth callback
+  names the outcome in its heading with a status mark, names the connector by
+  title only after the state check, uses `branding.productName` in its copy,
+  and folds the agent fix prompt under "Details for the operator". Refusals
+  stay byte-identical across connectors and paths.
+- A request whose `Accept` names `text/html` gets a themed 404 page; every
+  other client keeps the plain `Not Found` body.
+- Markdown artifacts take the deployment's resolved scheme and tokens instead
+  of the OS palette, and drop an opening `# Heading` that only repeats the
+  title the viewer already shows. The frame waits on the viewer's surface with
+  a loading line, and says so if the page never arrives.
+- Without the operator UI, callback and 404 pages no longer link the default
+  `/favicon.svg`, which only the UI serves.
+- The operator UI starts OAuth in one click. Connect opens the provider's
+  page in a new tab straight away and asks the server to continue a pending
+  authorization rather than restart it; only Reconnect on a healthy
+  connection restarts, behind an in-page confirm. A tab returning to the page
+  quietly re-reads the status of connectors waiting on authorization.
+- Operator UI notices appear in the card that caused them, in fixed
+  sentences rather than the route's error text; problems fixed by authorizing
+  or adding a credential are warnings rather than errors, with one primary
+  action per row. Activity and artifact states, the confirm dialogs, the
+  mobile masthead, and the vocabulary shown to people (outcomes, actors,
+  timestamps) now read the same across pages and use `branding.productName`.
+
+### Fixed
+
+- Operator OAuth starts now abort downstream discovery and registration after
+  30 seconds or browser cancellation, with a fixed timeout response. Every
+  reset already started by the request, including issuer-mismatch recovery,
+  drains before catalog invalidation and response so a delayed generation
+  write cannot replace a later flow. These uncancellable storage waits can
+  exceed the deadline. Disconnect still finishes after browser cancellation.
+- Forced OAuth restarts reuse registrations bound to the issuer, redirect URI,
+  client metadata, connector settings, and owner partition. Credentials are
+  re-sealed for the replacement epoch, and fresh discovery detects issuer
+  changes. Disconnect and issuer-mismatch recovery discard the registration.
+  The SDK cannot detect a revoked client while constructing a consent URL;
+  a callback refusal clears it so the next restart can register again.
+- Agent sampling advice now applies to reads. For a one-time write, agents
+  reduce the full result in the program or page a direct-call result through
+  `get_result`, without repeating the write to recover discarded output.
+- Authorized batches stay in one resumable program. Guidance explains how
+  tool-scoped approval covers repeated calls to one address while other
+  approval-required writes retain their own approvals. The call-scoped
+  default and host enforcement are unchanged.
+- **A restart's cleanup no longer grows with every earlier restart.** Each
+  OAuth restart re-deleted every epoch the connector had ever retired, one key
+  at a time, and restart 1,001 failed forever with a full cleanup backlog. A
+  restart now deletes the epoch it retires, retries any of the eight most
+  recent epochs whose cleanup failed (their manifest outlives their values),
+  and sweeps at most 16 epochs retired more than 24 hours ago, dropping each
+  from the lineage only when all of its keys are gone. A Disconnect that
+  reported a failed cleanup still deletes the old grant when retried. The
+  cleanup work stays bounded independently of earlier resets. Residue a late
+  writer leaves in a younger epoch stays unreadable behind the fence until the
+  sweep reaches it. A late writer whose cleanup fails in an epoch already
+  listed now restarts that epoch's grace. The accepted assumption is that no
+  request holds a retired epoch for a day. The lineage records retirement
+  times in a sibling record older releases ignore, and its cap rises to 5,000
+  epochs. A connector stuck at the old 1,000 wall restarts the day it
+  upgrades. Rolling back is clean unless a lineage has grown past 1,000. See
+  [auth](./documentation/auth.md#starting-restarting-and-retiring-an-oauth-epoch).
+- A failed or unreachable `/ui/data` no longer signs the operator out. Only a
+  401 or 403 on that read returns to the token gate; anything else keeps the
+  page and offers Retry. A connector whose details fail to load says whether
+  the session, the browser's connection, or the downstream service is at
+  fault, and only the last offers the fix prompt.
+
 ## 0.26.0 — 2026-09-25
 
 Programs can now write with host approval. When a program reaches a tool that

package/dist/artifacts/document.js

@@ -42,19 +42,23 @@ const DEFINE_GLOBAL = '(()=>{const f=(o)=>{if(o!==null&&typeof o==="object"){for
 /**
  * The complete document a viewer or render check loads. `data` maps document
  * names to their stored, script-safe JSON text, which is spliced in as-is.
+ *
+ * `theme` reaches a Markdown page only, whose styling is connecta's own. An
+ * HTML page is the author's, down to its colors, and is never restyled; the
+ * frame around it is what follows the deployment's scheme.
  */
 export function buildFrameDocument(input) {
     let page = input.source;
     if (input.kind === "markdown") {
         try {
-            page = markdownPage(input.source, input.global.title);
+            page = markdownPage(input.source, input.global.title, input.theme);
         }
         catch (error) {
             if (!(error instanceof MarkdownNestingError))
                 throw error;
             // Old or externally populated stores may hold a page that today's
             // validator would reject. Render fixed text instead of throwing here.
-            page = markdownPage("This page has too many nested block quotes or lists to display.", input.global.title);
+            page = markdownPage("This page has too many nested block quotes or lists to display.", input.global.title, input.theme);
         }
     }
     const meta = scriptSafeJson(input.global);

package/dist/artifacts/markdown.js

@@ -13,6 +13,8 @@
 // of text, a delimiter that found no closer is never searched for again, and
 // nesting stops at a fixed depth. A megabyte of `[[[[` or `**` renders in
 // linear time, because this runs on every page view.
+import { resolveTheme, schemeAttribute, themeCss, } from "../branding.js";
+import { TOKENS_CSS } from "../page-styles.js";
 const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === '"' ? "&quot;" : "&#39;");
 const PUNCTUATION = /^[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]$/;
 const MAX_INLINE_DEPTH = 8;
@@ -430,20 +432,47 @@ export function renderMarkdown(source) {
         .map((line) => line.replace(/^\t+/, (tabs) => "    ".repeat(tabs.length)));
     return blocks(lines);
 }
-const MARKDOWN_STYLE = ":root{color-scheme:light dark}body{margin:0;font:16px/1.6 system-ui,-apple-system,'Segoe UI',sans-serif;" +
-    "color:#1f2328;background:#fff}main{max-width:820px;margin:0 auto;padding:40px 24px}" +
+/**
+ * Every color, font, and radius comes from the shared tokens, so a Markdown
+ * page reads as part of the viewer around it: the deployment's accent and
+ * fonts, and the palette of the scheme the page was given rather than whatever
+ * the OS prefers. The background is the frame's `--surface`, so the page sits
+ * flush in its card instead of painting a second one.
+ */
+const MARKDOWN_STYLE = "body{margin:0;font:16px/1.6 var(--sans);color:var(--text);background:var(--surface)}" +
+    "main{max-width:820px;margin:0 auto;padding:32px 24px}main>:first-child{margin-top:0}" +
     "h1,h2,h3,h4{line-height:1.25;margin:1.6em 0 .6em}h1{font-size:2em}h2{font-size:1.5em}" +
-    "a{color:#0969da}code{font:0.9em ui-monospace,SFMono-Regular,Menlo,monospace;background:#f3f4f6;padding:.1em .3em;border-radius:4px}" +
-    "pre{overflow:auto;padding:16px;background:#f3f4f6;border-radius:8px}pre code{background:none;padding:0}" +
-    "blockquote{margin:0;padding:0 1em;color:#59636e;border-left:4px solid #d1d9e0}" +
-    "table{border-collapse:collapse;display:block;overflow:auto}th,td{padding:6px 12px;border:1px solid #d1d9e0}" +
-    "img{max-width:100%}hr{border:0;border-top:1px solid #d1d9e0}" +
-    "@media (prefers-color-scheme:dark){body{color:#e6edf3;background:#0d1117}a{color:#4493f8}" +
-    "code,pre{background:#161b22}blockquote{color:#9198a1;border-color:#3d444d}th,td,hr{border-color:#3d444d}}";
-/** A complete page for a Markdown artifact: the rendered body in `<main id="artifact-root">`. */
-export function markdownPage(source, title) {
-    return (`<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    "a{color:var(--link)}code{font:.9em var(--mono);background:var(--surface-2);padding:.1em .3em;border-radius:4px}" +
+    "pre{overflow:auto;padding:16px;background:var(--surface-2);border-radius:calc(var(--radius) - 2px)}pre code{background:none;padding:0}" +
+    "blockquote{margin:0;padding:0 1em;color:var(--muted);border-left:4px solid var(--border-strong)}" +
+    "table{border-collapse:collapse;display:block;overflow:auto}th,td{padding:6px 12px;border:1px solid var(--border-strong)}" +
+    "th{background:var(--surface-2)}img{max-width:100%}hr{border:0;border-top:1px solid var(--border)}";
+const collapse = (text) => text.replace(/\s+/g, " ").trim().toLowerCase();
+/**
+ * The source without a leading `# Heading` that only repeats the title. The
+ * viewer shows the title as the page's heading directly above the frame, so a
+ * page opening with the same words would say them twice. Any other opening
+ * heading is the author's and stays.
+ */
+function withoutRepeatedTitle(source, title) {
+    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const first = lines.findIndex((line) => line.trim() !== "");
+    const heading = first < 0 ? undefined : HEADING.exec(lines[first] ?? "");
+    if (heading?.[1] !== "#" || !collapse(title) || collapse(heading[2] ?? "") !== collapse(title)) {
+        return source;
+    }
+    return lines.slice(first + 1).join("\n");
+}
+/**
+ * A complete page for a Markdown artifact: the rendered body in
+ * `<main id="artifact-root">`. `theme` is the deployment's resolved theme; the
+ * viewer passes it so a pinned scheme and the operator's tokens reach the
+ * frame. Without one the page follows the OS scheme with default tokens.
+ */
+export function markdownPage(source, title, theme) {
+    const resolved = theme ?? resolveTheme();
+    return (`<!doctype html><html lang="en"${schemeAttribute(resolved)}><head><meta charset="utf-8">` +
         `<meta name="viewport" content="width=device-width,initial-scale=1">` +
-        `<title>${escapeHtml(title)}</title><style>${MARKDOWN_STYLE}</style></head>` +
-        `<body><main id="artifact-root">\n${renderMarkdown(source)}\n</main></body></html>`);
+        `<title>${escapeHtml(title)}</title><style>${TOKENS_CSS}${themeCss(resolved)}${MARKDOWN_STYLE}</style></head>` +
+        `<body><main id="artifact-root">\n${renderMarkdown(withoutRepeatedTitle(source, title))}\n</main></body></html>`);
 }

package/dist/artifacts/routes.js

@@ -11,6 +11,8 @@
 // could call — and the fetch directives leave it no network.
 import { resolveActorLabels, actorKey } from "../routes/actor-labels.js";
 import { authorize, mayViewArtifacts, privateJson, validateAuthPermissions, } from "../routes/shared.js";
+import { resolveBranding, schemeAttribute, themeCss } from "../branding.js";
+import { TOKENS_CSS } from "../page-styles.js";
 import { buildFrameDocument, frameCsp } from "./document.js";
 import { scriptSafeJson } from "./json.js";
 import { freshnessOf } from "./refresh.js";
@@ -20,19 +22,38 @@ const MAX_QUERY_CHARS = 200;
 const MAX_PINS = 32;
 const PIN = /^([A-Za-z_][A-Za-z0-9_]{0,63}):(\d{1,9})$/;
 const notFound = () => privateJson({ error: "not found" }, { status: 404 });
-/** The frame's bootstrap: wait for exactly one document from the parent, then become it. */
-function frameBootstrap(expectedOrigin) {
+/** How long the frame waits for its document before saying it did not come. */
+const FRAME_STALL_MS = 15_000;
+/**
+ * The frame's bootstrap: wait for exactly one document from the parent, then
+ * become it.
+ *
+ * Until the document arrives the frame shows one quiet line on the viewer's
+ * own surface, in the deployment's scheme and tokens, instead of a blank white
+ * box; if the handshake never completes, the line says so. None of it is page
+ * data — the scheme and tokens are deployment configuration — and all of it is
+ * gone the moment `document.open` replaces this document with the page.
+ */
+function frameBootstrap(expectedOrigin, theme) {
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"></head><body>
+<html lang="en"${schemeAttribute(theme)}><head><meta charset="utf-8"><meta name="referrer" content="no-referrer">
+<style>${TOKENS_CSS}${themeCss(theme)}html{background:var(--surface)}body{color:var(--muted);font:.875rem/1.5 var(--sans);margin:0;padding:1.25rem 1.5rem}</style>
+</head><body>
+<p id="frame-status" role="status">Loading page…</p>
 <script>
 (() => {
   const expected = ${scriptSafeJson(expectedOrigin)};
   if (window.parent === window) return;
+  const status = document.getElementById("frame-status");
+  const stalled = setTimeout(() => {
+    status.textContent = "This page did not load. Reload to try again.";
+  }, ${FRAME_STALL_MS});
   const receive = (event) => {
     if (event.source !== window.parent || event.origin !== expected) return;
     const message = event.data;
     if (!message || message.type !== "document" || typeof message.html !== "string") return;
     window.removeEventListener("message", receive);
+    clearTimeout(stalled);
     document.open();
     document.write(message.html);
     document.close();
@@ -152,6 +173,7 @@ export function artifactRoutes(options) {
             document: buildFrameDocument({
                 kind: page.head.kind,
                 source: page.source,
+                theme: resolveBranding(context.opts.branding).theme,
                 global: {
                     id,
                     title: page.head.title,
@@ -169,7 +191,8 @@ export function artifactRoutes(options) {
         if (path === "/artifacts/_frame") {
             if (!read)
                 return privateJson({ error: "method not allowed" }, { status: 405 });
-            return new Response(request.method === "HEAD" ? null : frameBootstrap(new URL(context.baseUrl).origin), {
+            const bootstrap = frameBootstrap(new URL(context.baseUrl).origin, resolveBranding(context.opts.branding).theme);
+            return new Response(request.method === "HEAD" ? null : bootstrap, {
                 headers: {
                     "Content-Type": "text/html; charset=utf-8",
                     "Content-Security-Policy": csp,

package/dist/artifacts/validate.js

@@ -215,6 +215,7 @@ export function checkView(input, context) {
     if (kind === "markdown") {
         let rendered;
         try {
+            // The served page also carries themeCss (≤~0.5 KB), which FRAME_OVERHEAD_BYTES absorbs.
             rendered = utf8Bytes(markdownPage(source, input.title ?? "")) + input.dataBytes + FRAME_OVERHEAD_BYTES;
         }
         catch (error) {