@zackbart/connecta 0.40.0 → 0.42.0

package/dist/result-preview.js

@@ -0,0 +1,210 @@
+/**
+ * Schema-aware views of direct reads past their cap, as pure functions of redacted
+ * text. Presentation only: the stash and what a program sees stay byte-identical
+ * to the full result, and everything shown here also appears in it, unchanged.
+ * Rules: documentation/meta-tools.md#previews-of-reads-over-the-cap.
+ */
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+/** Bytes of whole rows a view shows. */
+const ROW_BYTES = 1_500;
+/** One row can pass ROW_BYTES up to this, so a wide list still shows its shape. */
+const FIRST_ROW_BYTES = 3_000;
+/** Everything outside the list stays whole, or the read is not a list. */
+const REST_BYTES = 1_024;
+const TEXT_HEAD_BYTES = 1_200;
+const TEXT_TAIL_BYTES = 800;
+const MIN_ROWS = 3;
+const MAX_ROW_DEPTH = 3;
+const MAX_KEYS = 40;
+const MAX_KEY_CHARS = 64;
+/** Rows sampled for key names. */
+const KEY_SAMPLE_ROWS = 50;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const byteLength = (text) => enc.encode(text).length;
+/** The largest list of records within MAX_ROW_DEPTH keys of the root. */
+function dominantRows(root) {
+    let best;
+    const visit = (node, path) => {
+        if (Array.isArray(node)) {
+            if (node.length >= MIN_ROWS && node.every((row) => isRecord(row) || Array.isArray(row))) {
+                const bytes = byteLength(JSON.stringify(node));
+                if (!best || bytes > best.bytes)
+                    best = { path, rows: node, bytes };
+            }
+            return;
+        }
+        if (!isRecord(node) || path.length >= MAX_ROW_DEPTH)
+            return;
+        for (const key of Object.keys(node))
+            visit(node[key], [...path, key]);
+    };
+    visit(root, []);
+    return best;
+}
+function withRows(root, path, rows) {
+    if (!path.length)
+        return rows;
+    const [head, ...tail] = path;
+    const record = root;
+    // Computed keys define own properties, so a key named __proto__ stays data.
+    return { ...record, [head]: withRows(record[head], tail, rows) };
+}
+function rowKeys(rows) {
+    const keys = new Set();
+    for (const row of rows.slice(0, KEY_SAMPLE_ROWS)) {
+        if (!isRecord(row))
+            continue;
+        for (const key of Object.keys(row))
+            if (key.length <= MAX_KEY_CHARS)
+                keys.add(key);
+        if (keys.size >= MAX_KEYS)
+            break;
+    }
+    return [...keys].slice(0, MAX_KEYS);
+}
+/** JavaScript that reads `path` from a parsed value; a program runs it, so it must be exact. */
+function accessor(path) {
+    return path.map((key) => (/^[A-Za-z_$][\w$]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`)).join("");
+}
+function rowsPreview(parsed, total, cap) {
+    const found = dominantRows(parsed);
+    if (!found || found.bytes * 2 < total)
+        return undefined;
+    // The bytes outside the list; the ways it can be spelled do not change them.
+    const rest = byteLength(JSON.stringify(withRows(parsed, found.path, [])));
+    if (rest > REST_BYTES)
+        return undefined;
+    const firstRowBytes = Math.min(FIRST_ROW_BYTES, cap - rest);
+    const rowBytes = Math.min(ROW_BYTES, cap - rest);
+    const shown = [];
+    let used = 0;
+    for (const row of found.rows) {
+        const size = byteLength(JSON.stringify(row)) + 1;
+        if (used + size > (shown.length ? rowBytes : firstRowBytes))
+            break;
+        shown.push(row);
+        used += size;
+    }
+    const count = found.rows.length;
+    // An empty list would read as a list with no rows, and a whole one needs no sample.
+    if (!shown.length || shown.length === count)
+        return undefined;
+    const keys = rowKeys(found.rows);
+    const path = found.path.length ? accessor(found.path).replace(/^\./, "") : "(root)";
+    const body = JSON.stringify(withRows(parsed, found.path, shown));
+    if (byteLength(body) > cap)
+        return undefined;
+    return {
+        fields: { rows: { path, count, shown: shown.length, keys } },
+        body,
+        shown: `Sample only: ${shown.length === 1 ? "row 1" : `rows 1-${shown.length}`} of ${count} at ${path} follow, in the result's own shape, with every value outside the list; the other ${count - shown.length} are not shown.`,
+        noun: "rows",
+        reduce: `const rows = JSON.parse(text)${accessor(found.path)}; return { count: rows.length, rows: rows.slice(0, 5) };`,
+    };
+}
+function lineCount(text) {
+    let lines = 1;
+    for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1))
+        lines++;
+    return lines;
+}
+/** Whether a byte continues a UTF-8 character rather than starting one. */
+const continues = (byte) => byte !== undefined && (byte & 0xc0) === 0x80;
+function textPreview(text, reading, cap) {
+    const bytes = enc.encode(text);
+    if (bytes.length <= TEXT_HEAD_BYTES + TEXT_TAIL_BYTES)
+        return undefined;
+    const marker = (omitted) => `\n…[${omitted} bytes omitted]…\n`;
+    let headEnd = TEXT_HEAD_BYTES;
+    while (continues(bytes[headEnd]))
+        headEnd--;
+    let tailStart = bytes.length - TEXT_TAIL_BYTES;
+    while (continues(bytes[tailStart]))
+        tailStart++;
+    const shownBytes = headEnd + bytes.length - tailStart;
+    const body = `${dec.decode(bytes.subarray(0, headEnd))}${marker(tailStart - headEnd)}${dec.decode(bytes.subarray(tailStart))}`;
+    if (byteLength(body) > cap)
+        return undefined;
+    const lines = lineCount(text);
+    return {
+        fields: { text: { lines, shownBytes } },
+        body,
+        shown: `Sample only: the first ${headEnd} and last ${bytes.length - tailStart} bytes of ${lines} lines follow; the ${tailStart - headEnd} bytes between them are not shown.`,
+        noun: "text",
+        reduce: `const lines = ${reading}.split("\\n"); return { lines: lines.length, matches: lines.filter((line) => /error|fail/i.test(line)).map((line) => line.slice(0, 500)).slice(0, 40) };`,
+    };
+}
+/** Parts of a JSON number token whose exact value is the same however it is spelled. */
+function exactValue(token) {
+    const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(token);
+    if (!match)
+        return undefined;
+    const fraction = match[3] ?? "";
+    const digits = `${match[2]}${fraction}`;
+    let start = 0;
+    let end = digits.length;
+    while (digits[start] === "0")
+        start++;
+    while (end > start && digits[end - 1] === "0")
+        end--;
+    if (start === end)
+        return `${match[1]}0`;
+    return `${match[1]}${digits.slice(start, end)}e${Number(match[4] ?? 0) - fraction.length + digits.length - end}`;
+}
+/** Whether JSON.parse then JSON.stringify keeps this token's value, including its sign and range. */
+function keepsNumber(token) {
+    const printed = String(Number(token));
+    return printed === token || exactValue(printed) === exactValue(token);
+}
+/**
+ * Whether every number in text JSON.parse has already accepted survives parsing.
+ * Both a view and the offered program parse it, so one lossy number anywhere,
+ * inside or outside the rows, declines the view. Strings are skipped, not read.
+ */
+function keepsNumbers(json) {
+    let at = 0;
+    while (at < json.length) {
+        const code = json.charCodeAt(at);
+        if (code === 34) {
+            at++;
+            while (json.charCodeAt(at) !== 34)
+                at += json.charCodeAt(at) === 92 ? 2 : 1;
+            at++;
+        }
+        else if (code === 45 || (code >= 48 && code <= 57)) {
+            const start = at;
+            while (at < json.length && "+-.0123456789Ee".includes(json[at]))
+                at++;
+            if (!keepsNumber(json.slice(start, at)))
+                return false;
+        }
+        else
+            at++;
+    }
+    return true;
+}
+/**
+ * The view of a read past its cap, or undefined when its first bytes should stand:
+ * documents, scalars, shallow or deep lists a view would misstate, and numbers
+ * parsing would change.
+ *
+ * `format` is the result's own: an API connector's text arrives here as one
+ * JSON string, whose decoded text is what a person would call the result.
+ */
+export function previewResult(text, format, cap) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return textPreview(text, "text", cap);
+    }
+    if (typeof parsed === "string" && format === "text")
+        return textPreview(parsed, "JSON.parse(text)", cap);
+    if (typeof parsed !== "object" || parsed === null || !keepsNumbers(text))
+        return undefined;
+    return rowsPreview(parsed, byteLength(text), cap);
+}

package/dist/result-seal.js

@@ -0,0 +1,168 @@
+// A program's retained results are unreadable to any other request by default. Chunk 0,
+// which holds the header a reader needs, stays in this memory-only ledger while the run
+// lasts, so every way a run can end leaves nothing a reader can open unless sealing wrote
+// that chunk. Sealing waits until the run can no longer add to its secret set, and only
+// then writes the headers of entries that pass that set. Stored bytes never change, so an
+// offset issued for an entry stays valid. A reclaimed transfer leaves this ledger first and
+// gets no header. Sealing costs no extra writes, and reads stored bytes back only for
+// entries the set grew past.
+import { Duration, Effect } from "effect";
+import { authStorage } from "./auth/native.js";
+import { PendingWork } from "./runtime/request-scope.js";
+import { withDeadlineEffect } from "./runtime/run.js";
+import { resultKeys } from "./storage/keys.js";
+// A BOM is payload here, as it is on every page of the same bytes.
+const dec = new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
+export const RESULT_ENVELOPE_V4 = "connecta-result-v4:";
+/** Stored for an entry sealing did not publish, so its id can say why. Its binding and no bytes. */
+const RESULT_REFUSED_V4 = "connecta-result-refused-v4:";
+const SEAL_CONCURRENCY = 8;
+/** Kept back from sealing's time for the markers and cleanup of unpublished entries. */
+const REFUSAL_RESERVE_MS = 1000;
+const envelope = (entry) => `${RESULT_ENVELOPE_V4}${entry.binding}:${entry.total}:${entry.chunkBytes}:${entry.cap}:${entry.first}`;
+/** One run's unsealed results. It lives and dies with the run's request (INV-7). */
+export class HeldResults {
+    secrets;
+    credentialReads;
+    entries = new Map();
+    hostCalls = new PendingWork();
+    closed = false;
+    constructor(secrets, 
+    /** The request's credential reads, which outlast the host calls that started them. */
+    credentialReads) {
+        this.secrets = secrets;
+        this.credentialReads = credentialReads;
+    }
+    /** False once sealing began: a late entry would never become readable, and a late host call never starts. */
+    accepts() {
+        return !this.closed;
+    }
+    add(entry) {
+        if (this.closed)
+            return false;
+        this.entries.set(entry.id, entry);
+        return true;
+    }
+    /** Forget an entry whose stash is being given back, so sealing never writes its header.
+     * False once sealing began, when the entry is no longer this ledger's to give up. */
+    discard(id) {
+        return !this.closed && this.entries.delete(id);
+    }
+    /** Chunk 0 as storage will hold it, for paging inside the run that stashed it. */
+    stored(id) {
+        const entry = this.entries.get(id);
+        return entry && envelope(entry);
+    }
+    /** A guest host call; sealing waits for it to settle. */
+    track(work) {
+        const done = this.hostCalls.begin();
+        void work.then(done, done);
+    }
+    /** Stop accepting work and hand over what the run retained. */
+    close() {
+        this.closed = true;
+        const entries = [...this.entries.values()];
+        this.entries.clear();
+        return entries;
+    }
+    /** Succeeds once nothing the run started can add to the secret set. */
+    settled = Effect.suspend(() => this.hostCalls.idle).pipe(Effect.andThen(Effect.suspend(() => this.credentialReads.idle)), Effect.repeat({ until: () => !this.hostCalls.pending && !this.credentialReads.pending }), Effect.asVoid);
+}
+function bytesOf(encoded, total) {
+    const bytes = new Uint8Array(total);
+    let at = 0;
+    for (const part of encoded) {
+        const binary = atob(part);
+        for (let index = 0; index < binary.length; index++)
+            bytes[at++] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+/** The checks a result takes on its way into the stash, repeated over the whole stored value.
+ * Structured redaction joins text blocks, so a form split across two of them is found. */
+function passesSet(secrets, text, format) {
+    if (format === "json") {
+        try {
+            if (secrets.changes(JSON.parse(text)))
+                return false;
+        }
+        catch {
+            // A value JSON renders as text, such as `undefined`, takes the text check alone.
+        }
+    }
+    return secrets.text(text) === text;
+}
+const SEALED = { refused: 0, refusedWrite: false };
+/**
+ * Publish what can be published. Never fails. Nothing is published until the run's work
+ * has settled, and anything still pending when the budget ends leaves every entry
+ * unpublished, which is the refusal. Markers only improve what a later page is told, so
+ * a failed marker, a timeout or a cancellation changes nothing a reader can get.
+ */
+export function sealHeldResults(held, storage, 
+/** The absolute time the run's response must be on its way. */
+answerBy, signal) {
+    return Effect.suspend(() => {
+        const secrets = held.secrets;
+        const entries = held.close();
+        if (entries.length === 0)
+            return Effect.succeed(SEALED);
+        const published = new Set();
+        const key = (entry, index) => resultKeys.chunk(entry.id, index);
+        const passes = (entry) => Effect.gen(function* () {
+            const parts = [entry.first];
+            for (let index = 1; index < entry.chunks; index++) {
+                const chunk = yield* authStorage(storage, "get", [key(entry, index)]);
+                // Expired or evicted under a held header: nothing left to check, so nothing to offer.
+                if (chunk === null)
+                    return false;
+                parts.push(chunk);
+            }
+            const text = dec.decode(bytesOf(parts, entry.total));
+            return passesSet(secrets, text, entry.format);
+        });
+        const seal = Effect.gen(function* () {
+            yield* held.settled;
+            const stable = secrets.revision;
+            yield* Effect.forEach(entries, (entry) => Effect.gen(function* () {
+                if (entry.passed !== stable && (entry.binary || !(yield* passes(entry))))
+                    return;
+                // Nothing the run started is left, so this holds. If it ever fails, stop.
+                if (secrets.revision !== stable)
+                    return;
+                yield* authStorage(storage, "set", [key(entry, 0), envelope(entry), { expiresAtMs: entry.expiresAtMs }]);
+                published.add(entry);
+            }).pipe(Effect.ignore), { concurrency: SEAL_CONCURRENCY, discard: true });
+        });
+        // A header write that commits after its timeout can replace a marker, so a marker is no
+        // publication fence. That write only ever carries bytes this seal already checked.
+        const refuse = (entry) => Effect.gen(function* () {
+            yield* authStorage(storage, "set", [
+                key(entry, 0),
+                `${RESULT_REFUSED_V4}${entry.binding}:`,
+                { expiresAtMs: entry.expiresAtMs },
+            ]);
+            for (let index = 1; index < entry.chunks; index++) {
+                yield* authStorage(storage, "delete", [key(entry, index)]);
+            }
+        }).pipe(Effect.ignore);
+        const remainingMs = Math.max(1, answerBy - Date.now());
+        const reserveMs = Math.min(REFUSAL_RESERVE_MS, Math.floor(remainingMs / 4));
+        return withDeadlineEffect(() => seal, {
+            timeoutMs: Math.max(1, remainingMs - reserveMs),
+            ...(signal ? { signal } : {}),
+            timeoutError: new Error("Sealing ran out of time."),
+        }).pipe(Effect.ignore, Effect.flatMap(() => {
+            const refused = entries.filter((entry) => !published.has(entry));
+            const outcome = refused.length
+                ? { refused: refused.length, refusedWrite: refused.some((entry) => entry.write) }
+                : SEALED;
+            if (refused.length === 0 || signal?.aborted)
+                return Effect.succeed(outcome);
+            return Effect.forEach(refused, refuse, { concurrency: SEAL_CONCURRENCY, discard: true }).pipe(Effect.timeoutOrElse({
+                duration: Duration.millis(Math.max(1, answerBy - Date.now())),
+                orElse: () => Effect.void,
+            }), Effect.as(outcome));
+        }));
+    });
+}

package/dist/route-names.js

@@ -0,0 +1,53 @@
+/**
+ * `meta`: the six meta-tools. `read-route`: those plus `execute_read_code`, which
+ * then takes read follow-ups, so they cost no write approval. `code`: in-program
+ * wording, selected only by the eval code arm. `native` and `native-code`: native
+ * pools without and with `execute_code`.
+ */
+const NAMES = {
+    meta: Object.freeze({
+        search: "search_tools",
+        read: "call_tool",
+        write: "call_destructive_tool",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    "read-route": Object.freeze({
+        search: "search_tools",
+        read: "call_tool",
+        write: "call_destructive_tool",
+        program: "execute_read_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    code: Object.freeze({
+        search: "connecta.search inside execute_code",
+        read: "connecta.call inside execute_code",
+        write: "connecta.call inside execute_code",
+        program: "execute_code",
+        authorize: "authorize_connector",
+        skills: "skills",
+    }),
+    native: Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "your host's tool search",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+    "native-code": Object.freeze({
+        search: "your host's tool search",
+        read: "the original native tool",
+        write: "the original native tool",
+        program: "execute_code",
+        authorize: "the returned authorization handoff",
+        skills: "skills",
+    }),
+};
+/** The meta surface's names: the default wherever no other surface applies. */
+export const META_ROUTES = NAMES.meta;
+export function routeNames(surface) {
+    return NAMES[surface];
+}

package/dist/routes/activity-context.js

@@ -8,6 +8,7 @@ export function operatorActivityContext(context, authz) {
     return {
         sink: activity.store,
         recordTool: activity.recordTool,
+        recordOperation: activity.recordOperation,
         actor: authz.actor,
         ...(principal
             ? { principalActor: { kind: authz.actor.kind, id: principal.id, namespace: principal.namespace } }

package/dist/routes/activity-disclosure.js

@@ -1,3 +1,4 @@
+import { checkedActivityOperation } from "../operation-activity.js";
 import { recordedToolName } from "../operator-record.js";
 /** A recorded tool is shown only when its name passes the record grammar and its endpoint granted it. */
 function activityToolVisible(access, event) {
@@ -15,6 +16,31 @@ function activityToolVisible(access, event) {
  * pool that is no longer declared is withheld.
  */
 export function activityEventVisible(context, authz, registry, event) {
+    const pool = event.pool !== undefined ? context.opts.pools.get(event.pool) : undefined;
+    if (event.pool !== undefined && !pool)
+        return false;
+    const access = pool ? pool.access : { connectorIds: "all" };
+    if (event.kind === "operation") {
+        const operation = checkedActivityOperation(event.operation);
+        if (!operation ||
+            event.toolName !== operation.name ||
+            event.connectorId !== (operation.connectors.length === 1 ? operation.connectors[0] : "$operation"))
+            return false;
+        const ownerOnly = operation.personal ||
+            event.actorBasis === "principal" ||
+            operation.connectors.some((id) => registry.getConnector(id)?.authScope === "personal");
+        if (ownerOnly) {
+            const owner = authz.identity.principal;
+            if (!owner ||
+                event.actorBasis !== "principal" ||
+                event.actor.id !== owner.id ||
+                event.actor.namespace !== owner.namespace)
+                return false;
+        }
+        return operation.connectors.every((id) => registry.canReadConnectorSkills(id) &&
+            (access.connectorIds === "all" || access.connectorIds.includes(id)) &&
+            !access.toolAccess?.has(id));
+    }
     const connector = registry.getConnector(event.connectorId);
     if (!connector)
         return false;
@@ -26,10 +52,6 @@ export function activityEventVisible(context, authz, registry, event) {
             event.actor.namespace !== owner.namespace)
             return false;
     }
-    const pool = event.pool !== undefined ? context.opts.pools.get(event.pool) : undefined;
-    if (event.pool !== undefined && !pool)
-        return false;
-    const access = pool ? pool.access : { connectorIds: "all" };
     if (access.connectorIds !== "all" && !access.connectorIds.includes(event.connectorId))
         return false;
     // Connector-wide counts reveal tools outside an address-only grant.

package/dist/routes/activity.js

@@ -27,12 +27,13 @@ function enrichActivityActorLabels(page, auth) {
                 ...(event.actor.namespace ? { namespace: event.actor.namespace } : {}),
             };
             // Re-check stored client facts, including custom readers and old rows.
-            const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, pool: _pool, actorBasis: _actorBasis, ...record } = event;
+            const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, operation: _operation, friction: suppliedFriction, pool: _pool, actorBasis: _actorBasis, ...record } = event;
             const packageVersion = activityPackageVersion(suppliedPackageVersion);
             const clientName = activityClientFact(suppliedName, "name");
             const clientVersion = activityClientFact(suppliedVersion, "version");
             return {
                 ...record,
+                ...(event.kind !== "operation" && suppliedFriction !== undefined ? { friction: suppliedFriction } : {}),
                 ...activityBehaviorFacts(event),
                 ...(packageVersion !== undefined ? { packageVersion } : {}),
                 ...(clientName !== undefined ? { clientName } : {}),

package/dist/routes/connect.js

@@ -5,7 +5,7 @@ import { escapeHtml, renderPage } from "../branding.js";
 import { htmlSecurityHeaders } from "../html-security.js";
 import { closeConnectorScope } from "../connector-scope.js";
 import { drainOAuthStartResets } from "../auth/oauth-start-reset.js";
-import { finishOAuthConnectStart, consumeOAuthConnectLink, oauthConnectUnavailable, verifyOAuthHandoff, } from "../oauth-handoff.js";
+import { finishOAuthConnectStart, claimOAuthConnectStart, oauthConnectUnavailable, verifyOAuthHandoff, } from "../oauth-handoff.js";
 import { failureRecord, logFailure } from "../operator-record.js";
 import { runEdge, withDeadlineEffect } from "../runtime/run.js";
 import { admitsMaintainer, authorizeUiIdentity, mayManageConnector, privateJson, withSessionCookies, } from "./shared.js";
@@ -66,6 +66,9 @@ export function routeConnect(context) {
 async function connect(context) {
     const { opts, request, baseUrl, runtimeContext } = context;
     const refuse = (error, status = 403) => privateJson({ error }, { status });
+    const invalidLink = () => refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+    // Spends nothing, so this same link works once the other visit settles.
+    const starting = () => refuse("This connection is starting in another visit. Reload this page in a moment. If this stays, start a new connection request.", 409);
     if (request.method !== "GET")
         return privateJson({ error: "method not allowed" }, { status: 405, headers: { Allow: "GET" } });
     const unavailable = oauthConnectUnavailable(opts);
@@ -74,7 +77,7 @@ async function connect(context) {
     const id = context.path.slice("/connect/".length);
     const handoff = await verifyOAuthHandoff(opts, baseUrl, id, context.url.searchParams.get("h"));
     if (!handoff)
-        return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+        return invalidLink();
     const authPage = () => {
         const target = new URL(`/connectors/${id}`, baseUrl);
         target.searchParams.set("h", context.url.searchParams.get("h"));
@@ -124,10 +127,11 @@ async function connect(context) {
         }
         if (target.origin !== new URL(baseUrl).origin || target.username || target.password)
             return refuse("Credential management URL is unavailable", 503);
-        if (!(await consumeOAuthConnectLink(opts, handoff)))
-            return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
-        if (!(await finishOAuthConnectStart(opts, handoff, "started")))
-            return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+        const claim = await claimOAuthConnectStart(opts, handoff);
+        if (claim === "pending")
+            return starting();
+        if (claim === "refused" || !(await finishOAuthConnectStart(opts, handoff, "started")))
+            return invalidLink();
         // Credential entry stays in the authenticated operator UI on this origin.
         return withSessionCookies(new Response(null, {
             status: 302,
@@ -149,16 +153,20 @@ async function connect(context) {
     const timeoutError = new ConnectorCallError("timeout", "OAuth authorization start timed out");
     let claimed = false;
     try {
-        if (!(await consumeOAuthConnectLink(opts, handoff)))
-            return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+        const claim = await claimOAuthConnectStart(opts, handoff);
+        if (claim === "pending")
+            return starting();
+        if (claim === "refused")
+            return invalidLink();
         claimed = true;
+        const force = claim === "reset";
         const status = await runEdge(withDeadlineEffect((signal) => Effect.tryPromise({
             try: async () => {
                 ctx = registry.contextFor(id, baseUrl, scope, {
                     signal,
                     ...(context.defer ? { defer: context.defer } : {}),
                 });
-                const started = await connector.startAuth(ctx, { force: handoff.force });
+                const started = await connector.startAuth(ctx, { force });
                 if (signal.aborted)
                     throw signal.reason;
                 if (started.authorizationUrl) {
@@ -181,11 +189,11 @@ async function connect(context) {
             catch: (error) => error,
         }), { timeoutMs: START_TIMEOUT_MS, signal: request.signal, timeoutError }));
         await drainOAuthStartResets(scope);
-        if (handoff.force || (!status.authorizationReused && status.state !== "ok"))
+        if (force || (!status.authorizationReused && status.state !== "ok"))
             await registry.invalidateStored(id);
         if (status.state === "ok") {
             if (!(await finishOAuthConnectStart(opts, handoff, "started")))
-                return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+                return invalidLink();
             return withSessionCookies(new Response("This connector is already connected.", { headers: { "Cache-Control": "no-store" } }), authz.sessionCookies);
         }
         if (status.state !== "auth_required" || !status.authorizationUrl) {
@@ -194,7 +202,7 @@ async function connect(context) {
             // state only, since a plugin's `startAuth` returns whatever it likes.
             logFailure(opts.config.logger, "OAuth start failed", failureRecord({
                 connector: id,
-                mode: handoff.force ? "restart" : "continue",
+                mode: force ? "restart" : "continue",
                 state: status.state,
             }));
             return refuse(status.state === "auth_required"
@@ -205,7 +213,7 @@ async function connect(context) {
         if (!["https:", "http:"].includes(target.protocol) || target.username || target.password)
             return refuse("OAuth authorization returned no safe URL", 502);
         if (!(await finishOAuthConnectStart(opts, handoff, "started")))
-            return refuse("Invalid or expired connection link. Request a new link from connecta.", 400);
+            return invalidLink();
         return withSessionCookies(new Response(null, { status: 302, headers: { Location: target.href, "Cache-Control": "no-store" } }), authz.sessionCookies);
     }
     catch (error) {