@zackbart/connecta 0.34.1 → 0.35.0

package/dist/authorization-handoff.js

@@ -1,111 +1,185 @@
+import { upwardStep } from "./upward.js";
+import { authCall, authInvoke, authFlow, registerAuth } from "./auth/native.js";
+import { Context, Deferred, Effect, Scheduler } from "effect";
+import { forkRequest, fromSignal, runEdge } from "./runtime/run.js";
+import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { boundedEchoText } from "./errors.js";
-function oauthFollowUp(connectorId) {
-    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
+// A write whose outcome is unknown is never told to retry after recovery: it
+// re-reads its target first (INV-9). Each handoff keeps that variant beside
+// it, since one handoff per connector serves every call in a request.
+const RECONCILE = "re-read the target of the write that failed to check whether it took effect before any fresh call";
+const afterUnknownWrite = new WeakMap();
+function outcomeAware(build) {
+    const handoff = build(false);
+    afterUnknownWrite.set(handoff, build(true));
+    return handoff;
+}
+function oauthFollowUp(connectorId, unknownWrite) {
+    return `Then ${unknownWrite ? RECONCILE : "retry the original call"}; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
 }
 /** Shared with explicit authorization; errors never request a forced restart. */
-export async function authorizationHandoff(registry, baseUrl, requestScope, opts, args) {
-    const connector = registry.getConnector(args.connector);
-    if (!connector) {
-        throw new Error(`Unknown connector "${boundedEchoText(args.connector)}"`);
-    }
-    if (!connector.startAuth) {
-        if (!connector.credential) {
+export function authorizationHandoff(registry, baseUrl, requestScope, opts, args) {
+    return runEdge(authorizationHandoffNative(registry, baseUrl, requestScope, opts, args));
+}
+const authorizationHandoffNative = /* @__PURE__ */ registerAuth(authorizationHandoff, function (registry, baseUrl, requestScope, opts, args) {
+    return authFlow(function* () {
+        const connector = registry.getConnector(args.connector);
+        if (!connector) {
+            throw new Error(`Unknown connector "${boundedEchoText(args.connector)}"`);
+        }
+        if (!connector.startAuth) {
+            if (!connector.credential) {
+                return outcomeAware((unknownWrite) => ({
+                    connector: connector.id,
+                    recovery: "unavailable",
+                    message: `Connector "${connector.id}" declares neither downstream OAuth ` +
+                        "nor an operator-managed credential slot. Update the connector " +
+                        `or deployment configuration${unknownWrite ? `, then ${RECONCILE}` : " before retrying"}.`,
+                }));
+            }
+            const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
+            if (!ctx.credential || !opts.credentialHandoffUrl) {
+                return {
+                    connector: connector.id,
+                    recovery: "unavailable",
+                    message: "Credential recovery needs both a vault and the optional UI. Configure " +
+                        "vault and ui in deployment code, then call " +
+                        "authorize_connector again.",
+                };
+            }
+            const fields = connector.credential.fields?.map((field) => ({
+                name: field.name,
+                guidance: field.description ?? field.label,
+            })) ?? [
+                {
+                    name: "value",
+                    guidance: connector.credential.description ?? connector.credential.label,
+                },
+            ];
+            const operatorUrl = opts.credentialHandoffUrl;
+            const label = connector.credential.label;
+            return outcomeAware((unknownWrite) => ({
+                connector: connector.id,
+                recovery: "operator_config",
+                credential: { label, fields },
+                operatorUrl,
+                instructions: "Have the operator open operatorUrl, set and test the credential, " +
+                    `then ${unknownWrite ? RECONCILE : "retry the original call"}. No redeploy is needed. ` +
+                    (connector.authScope === "personal"
+                        ? "Credential mutation requires the signed-in principal who owns this connection."
+                        : "Shared credential mutation requires a signed-in human with access to this connector."),
+            }));
+        }
+        if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
             return {
                 connector: connector.id,
                 recovery: "unavailable",
-                message: `Connector "${connector.id}" declares neither downstream OAuth ` +
-                    "nor an operator-managed credential slot. Update the connector " +
-                    "or deployment configuration before retrying.",
+                message: opts.oauthConnectUnavailable ??
+                    "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
             };
-        }
-        const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
-        if (!ctx.credential || !opts.credentialHandoffUrl) {
+        if (!opts.canManageAuth?.(connector.id))
             return {
                 connector: connector.id,
                 recovery: "unavailable",
-                message: "Credential recovery needs both a vault and the optional UI. Configure " +
-                    "vault and ui in deployment code, then call " +
-                    "authorize_connector again.",
+                message: "Your identity is not permitted to manage authentication for this connection.",
             };
-        }
-        const fields = connector.credential.fields?.map((field) => ({
-            name: field.name,
-            guidance: field.description ?? field.label,
-        })) ?? [
-            {
-                name: "value",
-                guidance: connector.credential.description ?? connector.credential.label,
-            },
-        ];
-        return {
+        const authorizationUrl = yield* upwardStep(authInvoke(opts, "oauthConnectUrl", [connector.id, args.force]));
+        return outcomeAware((unknownWrite) => ({
             connector: connector.id,
-            recovery: "operator_config",
-            credential: {
-                label: connector.credential.label,
-                fields,
-            },
-            operatorUrl: opts.credentialHandoffUrl,
-            instructions: "Have the operator open operatorUrl, set and test the credential, " +
-                "then retry the original call. No redeploy is needed. " +
-                (connector.authScope === "personal"
-                    ? "Credential mutation requires the signed-in principal who owns this connection."
-                    : "Shared credential mutation requires a signed-in human with access to this connector."),
-        };
-    }
-    if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
-        return {
-            connector: connector.id,
-            recovery: "unavailable",
-            message: opts.oauthConnectUnavailable ??
-                "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
-        };
-    if (!opts.canManageAuth?.(connector.id))
-        return {
-            connector: connector.id,
-            recovery: "unavailable",
-            message: "Your identity is not permitted to manage authentication for this connection.",
-        };
-    return {
-        connector: connector.id,
-        recovery: "oauth",
-        status: "auth_required",
-        authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
-        instructions: "Copy authorizationUrl exactly as returned; do not decode or re-encode it. Open it in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
-            oauthFollowUp(connector.id),
-    };
+            recovery: "oauth",
+            status: "auth_required",
+            authorizationUrl,
+            instructions: "Copy authorizationUrl exactly as returned; do not decode or re-encode it. Open it in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
+                oauthFollowUp(connector.id, unknownWrite),
+        }));
+    });
+});
+export function authorizeConnector(...args) {
+    return runEdge(authorizeConnectorNative(...args));
 }
-const requests = new WeakMap();
+const authorizeConnectorNative = /* @__PURE__ */ registerAuth(authorizeConnector, function (...args) {
+    return authFlow(function* () {
+        const [registry, baseUrl, requestScope, , input] = args;
+        const handoff = yield* upwardStep(authCall(authorizationHandoff, [...args]));
+        const connector = registry.getConnector(input.connector);
+        if (connector.startAuth || !connector.credential)
+            return handoff;
+        const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
+        try {
+            const values = yield* upwardStep(authCall(ctx.credential?.getAll, [], ctx.credential));
+            const fields = connector.credential.fields?.map((field) => field.name) ?? ["value"];
+            if (values && fields.every((field) => typeof values[field] === "string" && values[field].length > 0)) {
+                // A later HTTP request cannot know whether a previous call rejected this
+                // key. Keep its recovery fields and state the condition, without probing.
+                return {
+                    ...handoff,
+                    recovery: "ready",
+                    message: "This connector's credential is configured. If a call to it just failed with an authentication or operator-configuration error, give this handoff to the operator; otherwise proceed with the call." +
+                        (handoff.message ? ` If recovery is needed: ${handoff.message}` : ""),
+                };
+            }
+        }
+        catch {
+            // An unreadable or declaration-mismatched slot needs operator repair.
+        }
+        return handoff;
+    });
+});
 /** Retain the admitted route's factory when program utilities share its scope. */
 export function bindAuthorizationHandoffs(scope, create) {
-    if (!requests.has(scope))
-        requests.set(scope, { create, enabled: true, handoffs: new Map() });
+    const retained = requestOwner(scope).retained;
+    retained.handoffs ??= { create, enabled: true, handoffs: new Map() };
 }
 export function enableAuthorizationHandoffs(scope, enabled) {
-    const request = requests.get(scope);
+    const request = requestOwner(scope).retained.handoffs;
     if (request)
         request.enabled = enabled;
 }
-/** One promise per connector also bounds concurrent errors in a program. */
-export async function withAuthorizationHandoff(scope, error) {
-    const request = requests.get(scope);
-    if (!request?.enabled ||
-        !error.nextAction ||
-        !("tool" in error.nextAction) ||
-        error.nextAction.tool !== "authorize_connector")
-        return error;
-    const connector = error.nextAction.arguments.connector;
-    let handoff = request.handoffs.get(connector);
-    if (!handoff) {
-        handoff = request.create(connector);
-        request.handoffs.set(connector, handoff);
-    }
-    try {
-        const value = await handoff;
-        return { ...error, ...value, message: error.message, ...(value.message ? { instructions: value.message } : {}) };
-    }
-    catch {
-        // A signing/configuration failure cannot replace the original call failure
-        // or leak an arbitrary vault exception into the recovery envelope.
-        return error;
-    }
+/** One request-owned producer per connector bounds concurrent errors in a program. */
+export function withAuthorizationHandoff(scope, error) {
+    return runEdge(withAuthorizationHandoffNative(scope, error));
+}
+export function withAuthorizationHandoffEffect(scope, error) {
+    return Effect.gen(function* () {
+        const owner = requestOwner(scope);
+        const request = owner.retained.handoffs;
+        if (!owner.open ||
+            !request ||
+            !error.nextAction ||
+            !("tool" in error.nextAction) ||
+            error.nextAction.tool !== "authorize_connector" ||
+            !request.enabled)
+            return error;
+        const connector = error.nextAction.arguments.connector;
+        const handoff = yield* Effect.uninterruptibleMask(() => Effect.gen(function* () {
+            const existing = request.handoffs.get(connector);
+            if (existing)
+                return existing;
+            const outcome = Deferred.makeUnsafe();
+            const answer = Deferred.await(outcome);
+            request.handoffs.set(connector, answer);
+            const scheduler = yield* Scheduler.Scheduler;
+            // Only canonical request ownership and the scheduler enter the producer.
+            // A waiting call's budget, credentials and cancellation cannot own it.
+            const services = Context.make(RequestScope, owner).pipe(Context.add(Scheduler.Scheduler, scheduler));
+            yield* forkRequest(Effect.interruptible(Effect.raceFirst(authCall(request.create, [connector]), fromSignal(owner.controller.signal))).pipe(Effect.setContext(services), Effect.onExit((exit) => Effect.sync(() => {
+                Deferred.doneUnsafe(outcome, exit);
+            }))), owner.scope);
+            return answer;
+        }));
+        return yield* handoff.pipe(Effect.map((shared) => {
+            if (!owner.open)
+                return error;
+            const value = (error.writeOutcome === "unknown" && afterUnknownWrite.get(shared)) || shared;
+            return {
+                ...error,
+                ...value,
+                message: error.message,
+                ...(value.message ? { instructions: value.message } : {}),
+            };
+        }), 
+        // A signing/configuration failure cannot replace the original failure.
+        Effect.catch(() => Effect.succeed(error)));
+    });
 }
+const withAuthorizationHandoffNative = /* @__PURE__ */ registerAuth(withAuthorizationHandoff, withAuthorizationHandoffEffect);

package/dist/call-admission-context.js

@@ -1,15 +1,8 @@
+import { Budget, callScopeKnown, chargeView, recordedService, setViewService } from "./runtime/call.js";
 import { chargeCallBudget } from "./runtime/call-admission.js";
-import { runEdge } from "./runtime/run.js";
-const permits = new WeakMap();
 export function attachCallAdmission(ctx, permit) {
-    permits.set(ctx, permit);
+    setViewService(ctx, Budget, { charge: chargeCallBudget(permit, ctx.signal) });
 }
-/**
- * Charge one sequential auxiliary request using the enclosing concurrency slot.
- * Await before dispatch and propagate refusal. Contexts outside an invocation
- * have no registry policy to charge.
- */
 export function chargeConnectorCall(ctx) {
-    const permit = permits.get(ctx);
-    return permit ? runEdge(chargeCallBudget(permit, ctx.signal)) : Promise.resolve();
+    return recordedService(ctx, Budget) || callScopeKnown(ctx) ? chargeView(ctx) : Promise.resolve();
 }

package/dist/call-admission.js

@@ -3,6 +3,7 @@ import { CALL_ADMISSION } from "./provider.js";
 import { ConnectorCallError } from "./errors.js";
 import { provideCallAdmissionProgram, provideCallBudgetCharge, startCallAdmission } from "./runtime/call-admission.js";
 import { fromSignal, runEdge } from "./runtime/run.js";
+import { keepErrorName } from "./redaction-identity.js";
 const DEFAULT_MAX_QUEUE_SIZE = 32;
 const DEFAULT_QUEUE_TIMEOUT_MS = 5_000;
 const DEFAULT_RETRY_AFTER_MS = 1_000;
@@ -23,6 +24,7 @@ export class CallAdmissionError extends ConnectorCallError {
         this.name = "CallAdmissionError";
     }
 }
+keepErrorName(CallAdmissionError, "CallAdmissionError");
 export function isCallAdmissionError(error) {
     return error instanceof CallAdmissionError;
 }

package/dist/call-classification.js

@@ -0,0 +1,9 @@
+// The served verdict comes from invocation, never a handler argument or method.
+import { Classification, ServedClassification, recordedService, setViewService } from "./runtime/call.js";
+export function attachCallClassification(ctx, classification) {
+    setViewService(ctx, Classification, classification);
+    setViewService(ctx, ServedClassification, classification);
+}
+export function callClassification(ctx) {
+    return recordedService(ctx, ServedClassification);
+}

package/dist/call-recovery.js

@@ -1,17 +1,23 @@
+// Recovery facts a connector records before it dispatches a write, such as an
+// idempotency key it will send. When the invocation deadline interrupts the
+// call, the connector's own failure never arrives, so the invocation reads
+// these facts from its own record and returns them with
+// `write_outcome_unknown` (`uncertainCall.recovery`). They are agent-only,
+// like the rest of `uncertainCall`, and never reach an operator record.
+import { Context, Effect } from "effect";
+import { Recovery, serviceFor, setViewService } from "./runtime/call.js";
 const MAX_FACTS = 4;
 const MAX_TEXT = 128;
 // Shared with the REST write schema so every accepted key survives recovery.
 export const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
 const NAME = /^[A-Za-z][A-Za-z0-9]*$/;
-const facts = new WeakMap();
-/**
- * Record facts that let the caller reconcile or safely retry this call's
- * write. Bounded: at most four string facts with short camelCase names; a fact
- * outside the bound is dropped rather than truncated. Idempotency keys allow
- * 255 characters to match the REST write schema; other values allow 128.
- */
-export function recordRecovery(ctx, recovery) {
-    const kept = { ...facts.get(ctx) };
+class RecordedRecovery extends Context.Service()("connecta/call/RecordedRecovery") {
+}
+export function recoveryRecord() {
+    return {};
+}
+export function recordRecoveryFacts(record, recovery) {
+    const kept = { ...record.facts };
     for (const [name, value] of Object.entries(recovery)) {
         if (Object.keys(kept).length >= MAX_FACTS && !Object.hasOwn(kept, name))
             break;
@@ -20,10 +26,23 @@ export function recordRecovery(ctx, recovery) {
             continue;
         kept[name] = value;
     }
-    facts.set(ctx, Object.freeze(kept));
+    record.facts = Object.freeze(kept);
+}
+function recordFor(ctx) {
+    let record = serviceFor(ctx, RecordedRecovery);
+    if (!record) {
+        record = recoveryRecord();
+        setViewService(ctx, RecordedRecovery, record);
+        const recordNow = (facts) => recordRecoveryFacts(record, facts);
+        setViewService(ctx, Recovery, { recordNow, record: (facts) => Effect.sync(() => recordNow(facts)) });
+    }
+    return record;
+}
+export function recordRecovery(ctx, facts) {
+    if (!serviceFor(ctx, Recovery))
+        recordFor(ctx);
+    serviceFor(ctx, Recovery)?.recordNow?.(facts);
 }
-/** The facts a connector recorded on this call's context, if any. */
 export function recoveryFor(ctx) {
-    const recorded = ctx ? facts.get(ctx) : undefined;
-    return recorded && Object.keys(recorded).length > 0 ? recorded : undefined;
+    return ctx ? serviceFor(ctx, RecordedRecovery)?.facts : undefined;
 }

package/dist/canonical-json.js

@@ -0,0 +1,8 @@
+/** Canonical JSON for internal claims: sorted object keys, preserved array order and JSON values. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.keys(item)
+            .sort()
+            .map((key) => [key, item[key]]))
+        : item);
+}