@zackbart/connecta 0.40.0 → 0.42.0

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

@@ -0,0 +1,104 @@
+// The root graph calls the optional recorder, never the /activity implementation.
+import { Cause, Effect, Exit } from "effect";
+import { InvocationFailure } from "./invocation-failure.js";
+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, source) {
+    if (!context?.recordOperation)
+        return work;
+    return Effect.suspend(() => {
+        const started = performance.now();
+        const connectors = registry.listConnectors();
+        // Human operations stay owner-only, including discovery of private catalogs.
+        let personal = Boolean(context.principalActor);
+        try {
+            personal ||= connectors.some((connector) => connector.authScope === "personal" ||
+                !connector.staticTools ||
+                usesCallerIdentity(connector) ||
+                connector.describe?.().auth?.mode === "request");
+        }
+        catch {
+            personal = true;
+        }
+        return work.pipe(Effect.onExit((exit) => Effect.sync(() => {
+            const result = Exit.isSuccess(exit)
+                ? exit.value
+                : undefined;
+            const failed = Exit.isFailure(exit) || result?.isError === true;
+            const interrupted = Exit.isFailure(exit) && exit.cause.reasons.some(Cause.isInterruptReason);
+            const failure = Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined;
+            const errorCode = interrupted
+                ? "cancelled"
+                : classificationCode(Exit.isFailure(exit)
+                    ? failure instanceof InvocationFailure ||
+                        failure instanceof ExecutorAdmissionError ||
+                        failure instanceof DiscoveryPolicyError
+                        ? failure.code
+                        : classifyCallError(failure).code
+                    : result?.structuredContent?.error?.code);
+            try {
+                // Result pages already measure their payload. Other operations have no
+                // reusable measurement: never serialize discovery or media for telemetry.
+                const page = name === "result" && Exit.isSuccess(exit)
+                    ? exit.value
+                    : undefined;
+                const bytes = page?.structuredContent?.bytes ?? page?.bytes;
+                const resultBytes = typeof bytes === "number" && Number.isSafeInteger(bytes) && bytes >= 0 ? bytes : undefined;
+                context.recordOperation(context, {
+                    operation: {
+                        name,
+                        connectors: connectors.map((connector) => connector.id),
+                        personal,
+                        ...(counts ? { hostCalls: counts() } : {}),
+                    },
+                    ...(source ? { source } : {}),
+                    durationMs: performance.now() - started,
+                    resultBytes,
+                    outcome: !failed
+                        ? "success"
+                        : errorCode === "timeout"
+                            ? "timeout"
+                            : errorCode === "cancelled" || errorCode === "executor_cancelled"
+                                ? "cancelled"
+                                : "error",
+                    errorCode,
+                });
+            }
+            catch {
+                /* Optional recording cannot replace the operation's result. */
+            }
+        })));
+    });
+}
+const OPERATION_NAMES = new Set(["search", "describe", "result", "skill", "program"]);
+export function checkedActivityOperation(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const input = value;
+    if (!OPERATION_NAMES.has(input.name) ||
+        typeof input.personal !== "boolean" ||
+        !Array.isArray(input.connectors) ||
+        input.connectors.some((id) => typeof id !== "string" || !/^[a-zA-Z0-9_-]+$/.test(id)))
+        return undefined;
+    const counts = input.hostCalls;
+    if (counts &&
+        [counts.attempted, counts.admitted, counts.succeeded, counts.failed].some((n) => typeof n !== "number" || !Number.isSafeInteger(n) || n < 0))
+        return undefined;
+    return {
+        name: input.name,
+        connectors: [...new Set(input.connectors)],
+        personal: input.personal,
+        ...(counts
+            ? {
+                hostCalls: {
+                    attempted: counts.attempted,
+                    admitted: counts.admitted,
+                    succeeded: counts.succeeded,
+                    failed: counts.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

@@ -23,8 +23,15 @@ export declare function labelErrorClass(ctor: {
  * name is exactly one of those, else `DOMException`.
  */
 export declare function errorLabel(failure: unknown): string | undefined;
+interface IdentityLookupFact {
+    outcome: "timeout" | "rejected";
+    durationMs: number;
+    cold: boolean;
+    inFlight: number;
+}
 /** Facts connecta derived about a failure where it saw it. */
 export interface FailureFacts {
+    identityLookup?: IdentityLookupFact;
     /** Inbound refusal classification attached to its Response, never its body. */
     reason?: AuthDenialReason;
     step?: FailureStep;
@@ -64,6 +71,7 @@ export interface FailureSubject {
 declare const recordBrand: unique symbol;
 /** One failure as an operator may read it. Only `failureRecord` makes one. */
 export interface FailureRecord {
+    readonly identityLookup?: IdentityLookupFact;
     readonly [recordBrand]: true;
     readonly reason?: AuthDenialReason;
     readonly accessContext?: boolean;
@@ -110,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"]);
@@ -165,6 +166,20 @@ export function errorLabel(failure) {
     }
     return undefined;
 }
+function identityLookupFact(value) {
+    if (!value ||
+        (value.outcome !== "timeout" && value.outcome !== "rejected") ||
+        count(value.durationMs, 86_400_000) === undefined ||
+        typeof value.cold !== "boolean" ||
+        count(value.inFlight, 1_000) === undefined)
+        return undefined;
+    return {
+        outcome: value.outcome,
+        durationMs: Math.round(value.durationMs),
+        cold: value.cold,
+        inFlight: Math.round(value.inFlight),
+    };
+}
 function origin(value) {
     if (typeof value !== "string")
         return undefined;
@@ -190,6 +205,7 @@ function checkedFacts(facts) {
     return {
         ...defined("reason", member(facts.reason, AUTH_DENIAL_REASONS)),
         ...defined("step", member(facts.step, STEPS)),
+        ...defined("identityLookup", identityLookupFact(facts.identityLookup)),
         ...defined("origin", origin(facts.origin)),
         ...defined("httpStatus", httpStatus(facts.httpStatus)),
         ...defined("oauthError", member(facts.oauthError, OAUTH_ERROR_CODES)),