@zackbart/connecta 0.41.0 → 0.42.0

package/dist/native-recovery.js

@@ -20,11 +20,14 @@ export function nativeRecovery(result, wireName) {
             : { operator: "Check connector authentication in deployment configuration." };
     }
     else if (action?.tool === "call_tool" || action?.tool === "call_destructive_tool") {
+        const purpose = error.code === "destructive_tool_requires_approval"
+            ? "Nothing was sent. Refresh the host's tool list, then call this tool only if the write is still wanted; the host asks for approval."
+            : (action.purpose ?? "Retry the original native call.");
         error.nextAction = wireName
             ? {
                 tool: wireName,
                 arguments: action.arguments?.args ?? {},
-                purpose: `${action.purpose ?? "Retry the original native call."}${action.arguments?.argsRedacted ? " Resend the original arguments; sensitive fields were omitted." : ""}`,
+                purpose: `${purpose}${action.arguments?.argsRedacted ? " Resend the original arguments; sensitive fields were omitted." : ""}`,
             }
             : { host: "search", purpose: action.purpose };
     }

package/dist/native-tools.js

@@ -12,6 +12,7 @@ import { withAuthorizationHandoff } from "./authorization-handoff.js";
 import { classifyCallError } from "./errors.js";
 import { nativeRecovery } from "./native-recovery.js";
 import { CatalogService } from "./catalog-service.js";
+import { catalogStaleness } from "./catalog-freshness.js";
 import { jsonResult } from "./meta-tools.js";
 import { failureRecord, logFailure } from "./operator-record.js";
 /**
@@ -24,8 +25,19 @@ export const NATIVE_NAME_MAX = 48;
 const MAX_NATIVE_TOOLS = 1_000;
 /** Native `tools/list` cache hint. Shorter than the meta surface's hour: the list follows downstream catalogs. */
 export const NATIVE_TOOLS_LIST_TTL_MS = 300_000;
+/** The hint when a listing omits a connector or lists one stale: about when that connector is next asked. */
+export const NATIVE_DEGRADED_TOOLS_LIST_TTL_MS = 60_000;
 const HASH_CHARS = 6;
 const SEPARATOR = "__";
+/**
+ * What every write's name carries. It sits before the tool, because Eve displays
+ * a name's last `__` segment and a suffix there would show every write as "write".
+ */
+const WRITE_SEGMENT = `${SEPARATOR}WRITE${SEPARATOR}`;
+/** How every hashed read ends, and so what no write's name may end in. See {@link nativeToolName}. */
+const READ_HASH_TAIL = /_[0-9a-f]{6}$/;
+/** A hashed write keeps this much of its connector, leaving the rest of the budget to its tool. */
+const WRITE_CONNECTOR_HEAD = 24;
 /** No `__`, no leading `_`: the last `__` of a plain name is then always its separator. */
 const PLAIN_TOOL = /^[A-Za-z0-9-](?:[A-Za-z0-9-]|_(?!_))*$/;
 const NATIVE_NAME = new RegExp(`^[A-Za-z][A-Za-z0-9_-]{0,${NATIVE_NAME_MAX - 1}}$`);
@@ -49,28 +61,82 @@ const shortHashNative = /* @__PURE__ */ registerAuth(shortHash, function (text)
 function connectorPart(connectorId) {
     return /^[a-z]/.test(connectorId) ? connectorId : `C${connectorId}`;
 }
+/** The classification a wire name is bound to. A name never changes what it is bound to. */
+function boundClassification(name) {
+    return name.includes(WRITE_SEGMENT) && !READ_HASH_TAIL.test(name) ? "write" : "read";
+}
 /**
- * A pure function of the connector id and downstream tool name, so it is
- * stable across catalog refreshes: `<connector>__<tool>` when that is exact,
- * legal and short, otherwise its head plus a six-hex SHA-256 suffix of the
- * original pair.
+ * A pure function of the connector id, downstream tool name and classification,
+ * so it is stable across catalog refreshes until the classification changes. A
+ * read is `<connector>__<tool>` when that is exact, legal and short, otherwise its
+ * head plus `_` and a six-hex SHA-256 of the original pair. A write is
+ * `<connector>__WRITE__<tool>` under the same conditions and when that does not end
+ * like a hashed read, otherwise a connector head, the marker, a tool head, `_w` and
+ * the same hash.
+ *
+ * No read's name is ever a write's, including a name a host cached before writes
+ * had their own, because a read's name has not changed. A read can carry the marker
+ * only when hashed: connector ids have no uppercase, so `WRITE` and the `__` after
+ * it would fall inside the tool, and a plain tool has no `__`. Every hashed read
+ * ends in `_` and six hex digits. Every write carries the marker and never ends so.
  */
-export function nativeToolName(connectorId, toolName) {
-    return runEdge(nativeToolNameNative(connectorId, toolName));
+export function nativeToolName(connectorId, toolName, classification) {
+    return runEdge(nativeToolNameNative(connectorId, toolName, classification));
 }
-const nativeToolNameNative = /* @__PURE__ */ registerAuth(nativeToolName, function (connectorId, toolName) {
+const nativeToolNameNative = /* @__PURE__ */ registerAuth(nativeToolName, function (connectorId, toolName, classification) {
     return authFlow(function* () {
+        const connector = connectorPart(connectorId);
         const tool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
-        const plain = `${connectorPart(connectorId)}${SEPARATOR}${tool}`;
-        if (tool === toolName && PLAIN_TOOL.test(tool) && plain.length <= NATIVE_NAME_MAX)
+        const write = classification === "write";
+        const plain = `${connector}${write ? WRITE_SEGMENT : SEPARATOR}${tool}`;
+        if (tool === toolName &&
+            PLAIN_TOOL.test(tool) &&
+            plain.length <= NATIVE_NAME_MAX &&
+            !(write && READ_HASH_TAIL.test(plain)))
             return plain;
-        const head = plain.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "");
-        return `${head}_${yield* upwardStep(authCall(shortHash, [`${connectorId}.${toolName}`]))}`;
+        const hash = yield* upwardStep(authCall(shortHash, [`${connectorId}.${toolName}`]));
+        if (write) {
+            const owner = connector.slice(0, WRITE_CONNECTOR_HEAD);
+            const suffix = `_w${hash}`;
+            const room = NATIVE_NAME_MAX - suffix.length - owner.length - WRITE_SEGMENT.length;
+            return `${owner}${WRITE_SEGMENT}${tool.slice(0, room).replace(/_+$/, "")}${suffix}`;
+        }
+        return `${plain.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "")}_${hash}`;
     });
 });
-/** Read or write, from the served classification only. */
-function annotationsFor(tool) {
-    return tool.classification === "read"
+/**
+ * Whether any tool of a connector could hold a name: every shape in
+ * {@link nativeToolName}, including truncated connector prefixes.
+ */
+function couldClaim(connector, name) {
+    const part = connectorPart(connector.id);
+    const prefix = `${part}${SEPARATOR}`;
+    // A hashed name can truncate even the connector prefix, and strips trailing
+    // underscores from its head. Such a name is exactly `${head}_` + six hex digits.
+    const head = prefix.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "");
+    return (name.startsWith(prefix) ||
+        // A hashed write keeps only the head of a long connector id.
+        name.startsWith(`${part.slice(0, WRITE_CONNECTOR_HEAD)}${WRITE_SEGMENT}`) ||
+        (name.length === head.length + 1 + HASH_CHARS &&
+            name.startsWith(`${head}_`) &&
+            /^[0-9a-f]+$/.test(name.slice(-HASH_CHARS))));
+}
+/**
+ * The name recovery should give: what the refusing verdict selects, because a
+ * catalog can change between resolving a name and invoking it.
+ */
+function recoveryName(result, called, names) {
+    const error = result?.structuredContent?.error;
+    const route = error?.code === "destructive_tool_requires_approval" ? "call_destructive_tool" : error?.nextAction?.tool;
+    return route === "call_destructive_tool" ? names.write : route === "call_tool" ? names.read : called;
+}
+/**
+ * Read or write, from the served classification only. A stale listing cannot
+ * vouch for a read: the connector may have reclassified the tool since, so it
+ * fails closed (INV-1). The call's own verdict comes from a live catalog.
+ */
+function annotationsFor(tool, stale) {
+    return tool.classification === "read" && !stale
         ? { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
         : { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
 }
@@ -160,10 +226,13 @@ export class NativeSurface {
     /**
      * Every listable native tool. A connector whose catalog fails is omitted
      * whole, never partially, with an operator warning; two tools claiming one
-     * name are both omitted and stay reachable by address in execute_code.
+     * name are both omitted and stay reachable by address in execute_code. A tool
+     * claims its read and write names alike, whichever it is now, so a collision
+     * does not come and go with a classification and a name cached under the other
+     * classification still finds its tool.
      */
-    claims(connectors = this.registry.listConnectors()) {
-        return runEdge(authOwnMethod(NativeSurface.prototype, this, "claims", [connectors]));
+    claims(connectors = this.registry.listConnectors(), allowStale = false) {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "claims", [connectors, allowStale]));
     }
     list() {
         return runEdge(authOwnMethod(NativeSurface.prototype, this, "list", []));
@@ -176,7 +245,11 @@ export class NativeSurface {
     resolve(name) {
         return runEdge(authOwnMethod(NativeSurface.prototype, this, "resolve", [name]));
     }
-    /** A native call: the existing route its current verdict selects. */
+    /**
+     * A native call: the existing route the name is bound to, never one chosen from
+     * the current verdict. A read name takes the read route, which refuses a current
+     * write before dispatch, so a host's replay of a cached read cannot reach a write.
+     */
     call(name, args, request) {
         return runEdge(authOwnMethod(NativeSurface.prototype, this, "call", [name, args, request]));
     }
@@ -185,11 +258,25 @@ export class NativeSurface {
             ...(entry?.tool.title ? { title: entry.tool.title } : {}),
             ...(entry ? { description: describe(entry, this.options.executeCode, guideName) } : {}),
             inputSchema: passThroughSchema(entry?.tool.inputSchema),
-            ...(entry ? { annotations: annotationsFor(entry.tool) } : {}),
-            ...(entry ? { _meta: { "dev.connecta/address": `${entry.connector.id}.${entry.tool.name}` } } : {}),
+            ...(entry ? { annotations: annotationsFor(entry.tool, entry.stale !== undefined) } : {}),
+            ...(entry
+                ? {
+                    _meta: {
+                        "dev.connecta/address": `${entry.connector.id}.${entry.tool.name}`,
+                        ...(entry.stale
+                            ? {
+                                "dev.connecta/stale": {
+                                    code: entry.stale.code,
+                                    ageMs: entry.stale.ageMs,
+                                    ...(entry.stale.retryAfterMs === undefined ? {} : { retryAfterMs: entry.stale.retryAfterMs }),
+                                },
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
         }, authMethod((args, request) => Effect.gen({ self: this }, function* () {
-            const result = yield* authInvoke(this, "call", [name, args ?? {}, request]);
-            return nativeRecovery(result, name);
+            return yield* authInvoke(this, "call", [name, args ?? {}, request]);
         })));
     }
     /**
@@ -266,14 +353,15 @@ export class NativeSurface {
                         error: yield* upwardStep(authCall(withAuthorizationHandoff, [self.options.requestScope, error])),
                     });
                     result.isError = true;
-                    return result;
+                    return nativeRecovery(result, name);
                 }
                 const address = `${target.entry.connector.id}.${target.entry.tool.name}`;
-                return yield* upwardStep(authInvoke(self.options, "route", [
-                    target.entry.tool.classification === "read" ? "call_tool" : "call_destructive_tool",
+                const result = yield* upwardStep(authInvoke(self.options, "route", [
+                    boundClassification(name) === "read" ? "call_tool" : "call_destructive_tool",
                     { address, args },
                     request,
                 ]));
+                return nativeRecovery(result, recoveryName(result, name, target.entry.names));
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, NativeSurface.prototype.call);
         registerAuthMethod(NativeSurface.prototype, "resolve", function (name) {
@@ -282,19 +370,20 @@ export class NativeSurface {
                 requestScope: this.options.requestScope,
                 signal: this.options.requestSignal,
             }, () => authFlow(function* () {
-                const prefixed = self.registry.listConnectors().filter((connector) => {
-                    const prefix = `${connectorPart(connector.id)}${SEPARATOR}`;
-                    // A hashed name can truncate even the connector prefix, and strips
-                    // trailing underscores from its head. Include every possible claimant.
-                    const head = prefix.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "");
-                    // A hashed name carries a stripped head only as exactly `${head}_` + six hex digits.
-                    return (name.startsWith(prefix) ||
-                        (name.length === head.length + 1 + HASH_CHARS &&
-                            name.startsWith(`${head}_`) &&
-                            /^[0-9a-f]+$/.test(name.slice(-HASH_CHARS))));
-                });
-                const { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", [prefixed]));
-                const found = byName.get(name);
+                const possible = (...names) => self.registry.listConnectors().filter((connector) => names.some((held) => couldClaim(connector, held)));
+                const prefixed = possible(name);
+                let { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", [prefixed]));
+                let found = byName.get(name);
+                if (found) {
+                    // A tool that loses either name loses both, as listing omits it, so the
+                    // other name's claimants decide this one too. One step is enough: only a
+                    // tool sharing one of these two names can take them from this tool.
+                    const every = possible(found.names.read, found.names.write);
+                    if (every.length > prefixed.length) {
+                        ({ loaded, byName } = yield* upwardStep(authInvoke(self, "claims", [every])));
+                        found = byName.get(name);
+                    }
+                }
                 if (found === null)
                     return { kind: "ambiguous" };
                 // An unavailable possible claimant cannot prove uniqueness.
@@ -310,8 +399,10 @@ export class NativeSurface {
                 requestScope: this.options.requestScope,
                 signal: this.options.requestSignal,
             }, () => authFlow(function* () {
-                const { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", []));
+                const { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", [undefined, true]));
                 for (const entry of loaded) {
+                    if ("tools" in entry && catalogStaleness(entry.tools))
+                        self.options.staleCatalogs.push(entry.connector.id);
                     // Validate the whole connector before registering any of its tools.
                     const tool = "tools" in entry
                         ? entry.tools.find((tool) => tool.inputSchema !== undefined && !nativeInputSchema(tool.inputSchema))
@@ -321,32 +412,56 @@ export class NativeSurface {
                     self.options.catalogErrors.push(entry.connector.id);
                     logFailure(self.options.logger, "native catalog unavailable", failureRecord({ connector: entry.connector.id, ...(tool ? { tool } : {}) }, "error" in entry ? entry.error : undefined));
                 }
-                return [...byName.values()].filter((entry) => entry !== null &&
+                if (self.options.catalogErrors.length || self.options.staleCatalogs.length)
+                    self.options.onDegradedListing?.();
+                return [...byName].flatMap(([name, entry]) => entry !== null &&
+                    entry.name === name &&
                     !self.options.catalogErrors.includes(entry.connector.id) &&
-                    (!(self.options.readOnly || entry.connector.readOnly) || entry.tool.classification === "read"));
+                    (!(self.options.readOnly || entry.connector.readOnly) || entry.tool.classification === "read")
+                    ? [entry]
+                    : []);
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, NativeSurface.prototype.list);
-        registerAuthMethod(NativeSurface.prototype, "claims", function (connectors) {
+        registerAuthMethod(NativeSurface.prototype, "claims", function (connectors, allowStale = false) {
             const self = this;
             return duringViewEffect({
                 requestScope: this.options.requestScope,
                 signal: this.options.requestSignal,
             }, () => authFlow(function* () {
-                const loaded = yield* upwardStep(authInvoke(self.catalog, "listCatalogs", [true, connectors ?? self.registry.listConnectors()]));
-                const byName = new Map();
+                const loaded = yield* upwardStep(authInvoke(self.catalog, "listCatalogs", [true, connectors ?? self.registry.listConnectors(), allowStale]));
+                const claimed = [];
+                const claimants = new Map();
                 for (const entry of loaded) {
                     if (!("tools" in entry))
                         continue;
                     for (const tool of entry.tools) {
-                        const name = yield* upwardStep(authCall(nativeToolName, [entry.connector.id, tool.name]));
-                        if (byName.has(name)) {
-                            byName.set(name, null);
-                            logFailure(self.options.logger, "native name collision", failureRecord({ connector: entry.connector.id, tool }));
-                        }
-                        else
-                            byName.set(name, { name, connector: entry.connector, tool });
+                        const read = yield* upwardStep(authCall(nativeToolName, [entry.connector.id, tool.name, "read"]));
+                        const write = yield* upwardStep(authCall(nativeToolName, [entry.connector.id, tool.name, "write"]));
+                        const name = tool.classification === "read" ? read : write;
+                        const stale = catalogStaleness(entry.tools);
+                        claimed.push({
+                            names: [read, write],
+                            claim: {
+                                name,
+                                names: { read, write },
+                                connector: entry.connector,
+                                tool,
+                                ...(stale ? { stale } : {}),
+                            },
+                        });
+                        for (const held of [read, write])
+                            claimants.set(held, (claimants.get(held) ?? 0) + 1);
                     }
                 }
+                const byName = new Map();
+                for (const { names, claim } of claimed) {
+                    // A tool that loses either name loses both: it is omitted, not half listed.
+                    const collides = names.some((name) => claimants.get(name) > 1);
+                    if (collides)
+                        logFailure(self.options.logger, "native name collision", failureRecord({ connector: claim.connector.id, tool: claim.tool }));
+                    for (const name of names)
+                        byName.set(name, collides ? null : claim);
+                }
                 return { loaded, byName };
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, NativeSurface.prototype.claims);

package/dist/node.js

@@ -114,6 +114,8 @@ export function listen(connecta, portOrOptions) {
     const activeResponses = new Map();
     let shuttingDown = false;
     const server = createServer((req, res) => {
+        // Before the body: a client's timer has been running through its upload too.
+        const requestArrivedAt = Date.now();
         awaitingRequest.delete(req.socket);
         const socket = req.socket;
         activeResponses.set(socket, (activeResponses.get(socket) ?? 0) + 1);
@@ -196,7 +198,7 @@ export function listen(connecta, portOrOptions) {
                     res.end("Payload Too Large");
                     return;
                 }
-                const response = await connecta.fetch(request, undefined, ctx);
+                const response = await connecta.fetch(request, undefined, { ...ctx, requestArrivedAt });
                 await writeResponse(res, response);
             }
             catch (error) {

package/dist/oauth-handoff.js

@@ -4,6 +4,9 @@ import { authCall, authInvoke, authFlow, authStorage, registerAuth } from "./aut
 import { runEdge } from "./runtime/run.js";
 import { oauthConnectKeys } from "./storage/keys.js";
 const HANDOFF_TTL_MS = 15 * 60_000;
+// A flow can issue a link until its ten-minute retry state ends, and that link lives
+// fifteen more, so a reset's record outlives every link that could repeat it.
+const FLOW_RESET_EXPIRY = { ttlSeconds: 30 * 60 };
 const INTERACTIVE_OAUTH_REQUIRED = "An interactive provider (Clerk or Cloudflare Access) is required to connect OAuth connectors.";
 // Length-prefixed fields avoid JSON keys and escaping without reserving any
 // character in an identity. This is an opaque wire encoding, not encryption.
@@ -16,7 +19,7 @@ function encodeHandoff(h) {
         h.expiresAt.toString(36),
         h.nonce,
         h.force ? "1" : "0",
-        h.after ?? "",
+        h.flow ?? "",
     ]
         .map((field) => `${field.length}:${field}`)
         .join("");
@@ -36,7 +39,7 @@ function decodeHandoff(value) {
         fields.push(value.slice(offset, offset + length));
         offset += length;
     }
-    const [connector, owner, principal, origin, expiry, nonce, force, after] = fields;
+    const [connector, owner, principal, origin, expiry, nonce, force, flow] = fields;
     if (fields.length !== 8 || offset !== value.length || !/^[0-9a-z]+$/.test(expiry) || !/^[01]$/.test(force))
         throw new Error("Invalid handoff fields");
     return {
@@ -47,7 +50,7 @@ function decodeHandoff(value) {
         expiresAt: parseInt(expiry, 36),
         nonce: nonce,
         force: force === "1",
-        ...(after ? { after } : {}),
+        ...(flow ? { flow } : {}),
     };
 }
 function encodeSegment(value) {
@@ -89,10 +92,10 @@ const oauthConnectUrlNative = /* @__PURE__ */ registerAuth(oauthConnectUrl, func
         ]))).url;
     });
 });
-export function oauthConnectLink(opts, baseUrl, connectorId, principal, force = false, opaque = false, after) {
-    return runEdge(oauthConnectLinkNative(opts, baseUrl, connectorId, principal, force, opaque, after));
+export function oauthConnectLink(opts, baseUrl, connectorId, principal, force = false, opaque = false, flow) {
+    return runEdge(oauthConnectLinkNative(opts, baseUrl, connectorId, principal, force, opaque, flow));
 }
-const oauthConnectLinkNative = /* @__PURE__ */ registerAuth(oauthConnectLink, function (opts, baseUrl, connectorId, principal, force = false, opaque = false, after) {
+const oauthConnectLinkNative = /* @__PURE__ */ registerAuth(oauthConnectLink, function (opts, baseUrl, connectorId, principal, force = false, opaque = false, flow) {
     return authFlow(function* () {
         const unavailable = oauthConnectUnavailable(opts);
         if (unavailable)
@@ -108,7 +111,7 @@ const oauthConnectLinkNative = /* @__PURE__ */ registerAuth(oauthConnectLink, fu
             expiresAt: Date.now() + HANDOFF_TTL_MS,
             nonce: crypto.randomUUID(),
             force,
-            ...(after ? { after } : {}),
+            ...(flow ? { flow } : {}),
         };
         const vault = opts.config.vault;
         if (opaque && (!vault.seal || !vault.open))
@@ -126,32 +129,14 @@ const oauthConnectLinkNative = /* @__PURE__ */ registerAuth(oauthConnectLink, fu
     });
 });
 /** A claim precedes OAuth reset; only a completed start can prove recovery. */
-export function oauthConnectLinkProgress(opts, baseUrl, id, nonce) {
-    return runEdge(oauthConnectLinkProgressNative(opts, baseUrl, id, nonce));
+export function oauthConnectLinkStarted(opts, baseUrl, id, nonce) {
+    return runEdge(oauthConnectLinkStartedNative(opts, baseUrl, id, nonce));
 }
-const oauthConnectLinkProgressNative = /* @__PURE__ */ registerAuth(oauthConnectLinkProgress, function (opts, baseUrl, id, nonce) {
+const oauthConnectLinkStartedNative = /* @__PURE__ */ registerAuth(oauthConnectLinkStarted, function (opts, baseUrl, id, nonce) {
     return authFlow(function* () {
-        const stage = yield* upwardStep(authStorage(opts.registry.contextFor(id, baseUrl).storage, "get", [
+        return ((yield* upwardStep(authStorage(opts.registry.contextFor(id, baseUrl).storage, "get", [
             oauthConnectKeys.used(nonce),
-        ]));
-        return stage === "used" ? "claimed" : stage === "started" || stage === "failed" ? stage : undefined;
-    });
-});
-/** Make outstanding flow links single-use refusals before a completion check. */
-export function closeOAuthConnectLinks(opts, baseUrl, id, nonces) {
-    return runEdge(closeOAuthConnectLinksNative(opts, baseUrl, id, nonces));
-}
-const closeOAuthConnectLinksNative = /* @__PURE__ */ registerAuth(closeOAuthConnectLinks, function (opts, baseUrl, id, nonces) {
-    return authFlow(function* () {
-        const storage = opts.registry.contextFor(id, baseUrl).storage;
-        for (const nonce of nonces) {
-            yield* upwardStep(authStorage(storage, "compareAndSet", [
-                oauthConnectKeys.used(nonce),
-                null,
-                "closed",
-                { ttlSeconds: HANDOFF_TTL_MS / 1000 },
-            ]));
-        }
+        ]))) === "started");
     });
 });
 /** Consuming a round prevents replay from creating sibling retry lineages. */
@@ -206,6 +191,9 @@ const verifyOAuthHandoffNative = /* @__PURE__ */ registerAuth(verifyOAuthHandoff
                         atob(payload.slice(3)),
                     ]))
                     : atob(payload));
+                // A retired predecessor binding: nothing here can honor it, so it must not be ignored.
+                if ("after" in h)
+                    return null;
             }
             const connector = opts.registry.getConnector(connectorId);
             if (!connector ||
@@ -221,8 +209,8 @@ const verifyOAuthHandoffNative = /* @__PURE__ */ registerAuth(verifyOAuthHandoff
                 !h.nonce ||
                 typeof h.force !== "boolean")
                 return null;
-            if (h.after !== undefined &&
-                (typeof h.after !== "string" || !/^[a-f0-9-]{36}$/.test(h.after) || h.after === h.nonce || h.force))
+            if (h.flow !== undefined &&
+                (typeof h.flow !== "string" || !/^[a-f0-9-]{36}$/.test(h.flow) || h.flow === h.nonce || !h.force))
                 return null;
             if (yield* upwardStep(authStorage(opts.registry.contextFor(connectorId, baseUrl).storage, "get", [
                 oauthConnectKeys.used(h.nonce),
@@ -235,21 +223,34 @@ const verifyOAuthHandoffNative = /* @__PURE__ */ registerAuth(verifyOAuthHandoff
         }
     });
 });
-/** Claim only after browser identity and permissions pass, before starting OAuth. */
-export function consumeOAuthConnectLink(opts, handoff) {
-    return runEdge(consumeOAuthConnectLinkNative(opts, handoff));
+/**
+ * Claim only after browser identity and permissions pass, before starting OAuth.
+ * A forced flow resets once, whichever of its links arrives first. A later visitor
+ * continues that attempt, waits on it without spending its link, or, once it has
+ * failed, takes over the reset.
+ */
+export function claimOAuthConnectStart(opts, handoff) {
+    return runEdge(claimOAuthConnectStartNative(opts, handoff));
 }
-const consumeOAuthConnectLinkNative = /* @__PURE__ */ registerAuth(consumeOAuthConnectLink, function (opts, handoff) {
+const claimOAuthConnectStartNative = /* @__PURE__ */ registerAuth(claimOAuthConnectStart, function (opts, handoff) {
     return authFlow(function* () {
         if (handoff.expiresAt <= Date.now())
-            return false;
+            return "refused";
         const storage = opts.registry.contextFor(handoff.connector, handoff.origin).storage;
-        if (handoff.after &&
-            (yield* upwardStep(authStorage(storage, "get", [oauthConnectKeys.used(handoff.after)]))) !==
-                "started")
-            return false;
+        const reset = handoff.force ? oauthConnectKeys.reset(handoff.flow ?? handoff.nonce) : undefined;
+        const prior = reset ? yield* upwardStep(authStorage(storage, "get", [reset])) : "started";
+        if (prior === "used")
+            return "pending";
+        const claiming = prior !== "started";
+        if (claiming &&
+            !(yield* upwardStep(authStorage(storage, "compareAndSet", [reset, prior, "used", FLOW_RESET_EXPIRY]))))
+            return "pending";
         const expiry = { ttlSeconds: Math.max(1, Math.ceil((handoff.expiresAt - Date.now()) / 1000)) };
-        return yield* upwardStep(authStorage(storage, "compareAndSet", [oauthConnectKeys.used(handoff.nonce), null, "used", expiry]));
+        if (yield* upwardStep(authStorage(storage, "compareAndSet", [oauthConnectKeys.used(handoff.nonce), null, "used", expiry])))
+            return claiming ? "reset" : "continue";
+        if (claiming)
+            yield* upwardStep(authStorage(storage, "compareAndSet", [reset, "used", prior, FLOW_RESET_EXPIRY]));
+        return "refused";
     });
 });
 /** Terminal marker only after the start and every tracked reset have settled. */
@@ -258,9 +259,18 @@ export function finishOAuthConnectStart(opts, handoff, outcome) {
 }
 const finishOAuthConnectStartNative = /* @__PURE__ */ registerAuth(finishOAuthConnectStart, function (opts, handoff, outcome) {
     return authFlow(function* () {
+        const storage = opts.registry.contextFor(handoff.connector, handoff.origin).storage;
+        // Settled first, and whatever the link's expiry: a finished link proves its flow's
+        // reset finished, and only the visitor who claimed a reset can find it still claimed.
+        if (handoff.force)
+            yield* upwardStep(authStorage(storage, "compareAndSet", [
+                oauthConnectKeys.reset(handoff.flow ?? handoff.nonce),
+                "used",
+                outcome,
+                FLOW_RESET_EXPIRY,
+            ]));
         if (handoff.expiresAt <= Date.now())
             return false;
-        const storage = opts.registry.contextFor(handoff.connector, handoff.origin).storage;
         const expiry = { ttlSeconds: Math.max(1, Math.ceil((handoff.expiresAt - Date.now()) / 1000)) };
         return yield* upwardStep(authStorage(storage, "compareAndSet", [oauthConnectKeys.used(handoff.nonce), "used", outcome, expiry]));
     });

package/dist/operation-activity.js

@@ -5,7 +5,7 @@ import { ExecutorAdmissionError } from "./executor-admission.js";
 import { DiscoveryPolicyError } from "./catalog-service.js";
 import { classificationCode, classifyCallError } from "./errors.js";
 import { usesCallerIdentity } from "./connector-caller.js";
-export function operationActivity(context, registry, name, work, counts) {
+export function operationActivity(context, registry, name, work, counts, source) {
     if (!context?.recordOperation)
         return work;
     return Effect.suspend(() => {
@@ -53,6 +53,7 @@ export function operationActivity(context, registry, name, work, counts) {
                         personal,
                         ...(counts ? { hostCalls: counts() } : {}),
                     },
+                    ...(source ? { source } : {}),
                     durationMs: performance.now() - started,
                     resultBytes,
                     outcome: !failed

package/dist/operation-vocabulary.js

@@ -193,6 +193,12 @@ export function registerConnectorVocabulary(connector, declarations) {
     if (entries.length)
         connectors.set(connector, new Map(entries));
 }
+/** Give a connector that delegates to an api() connector the vocabulary its hatch registered there. */
+export function carryConnectorVocabulary(source, target) {
+    const registered = connectors.get(source);
+    if (registered)
+        connectors.set(target, registered);
+}
 /**
  * Read tools whose operation vocabulary matches every query word, and the
  * fully determined reads among those operations, each through a visible read

package/dist/operator-record.d.ts

@@ -118,7 +118,7 @@ export declare function failureRecord(subject: FailureSubject, failure?: unknown
  * The events an operator log reports failures as. Closed: a new one is a
  * reviewed line here, never a string assembled at the call site.
  */
-export type FailureEvent = "Authentication admission refused" | "Cloudflare Access verification unavailable" | "operator_refused" | "Authentication released after its pending work became unreachable" | "negotiation cache read failed" | "negotiation cache write failed" | "discovery health read failed" | "discovery health write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "credential verification record failed" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "native catalog unavailable" | "native name collision" | "native tools/list refused a pool over the 1,000-tool native cap" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+export type FailureEvent = "Authentication admission refused" | "Cloudflare Access verification unavailable" | "operator_refused" | "Authentication released after its pending work became unreachable" | "negotiation cache read failed" | "negotiation cache write failed" | "discovery health read failed" | "discovery health write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog chunk cleanup failed" | "catalog fence failed" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "credential verification record failed" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "native catalog unavailable" | "native name collision" | "native tools/list refused a pool over the 1,000-tool native cap" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
 /**
  * Log one failure as `[connecta] <event>` and its record. A record
  * `failureRecord` did not build is replaced, whatever its shape, by a fixed

package/dist/operator-record.js

@@ -47,6 +47,7 @@ const SOURCES = new Set([
     "call_destructive_tool",
     "batch_call",
     "execute_code",
+    "execute_read_code",
     "resume_execution",
 ]);
 const MODES = new Set(["continue", "restart"]);