@zackbart/connecta 0.34.0 → 0.35.0

package/dist/connectors/api-connector.js

@@ -1,12 +1,23 @@
+import { Effect, Exit } from "effect";
+import { registerConnectorVocabulary } from "../operation-vocabulary.js";
+import { causeError, runEdge } from "../runtime/run.js";
+import { credentialProbe } from "../runtime/credential-probe.js";
+import { ContinuationBinding, serviceFor, setViewService, settleOnClose, duringViewEffect } from "../runtime/call.js";
+import { registerCallEntry, toolEntry } from "../runtime/call-entry.js";
 import { ConnectorCallError, networkErrorCode, unavailableCallError, WithheldTextError } from "../errors.js";
 import { attachFailureFacts, carryFailureFacts, errorLabel } from "../operator-record.js";
-import { compileValidator, validateCatalogToolInput } from "../validate.js";
+import { compileValidator, normalizeToolInput, validateCatalogToolInput } from "../validate.js";
 import { array, assertKnownOptions, instance, keys, optionsOf, strings } from "../config-schema.js";
 import { describedEndpoint, describedOrigin, describedTools } from "../described.js";
-import { CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
+import { READ_ONLY, CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
 import { assertStaticToolNames } from "../tool-name.js";
 import { registerInvocationAuth } from "../invocation-auth.js";
 import { redactCatalog, redactSentSecrets, sentSecretsFetch, trackCredentialReads } from "../sent-secrets.js";
+import { callClassification } from "../call-classification.js";
+import { classifyTool } from "../tool-safety.js";
+import { closeProviderCall, enterProviderBoundary, inLogicalCall, knownProviderFailure, nestedProviderRequests, providerBoundary, providerCallContext, providerFetch, providerRequests, tracksRequests, } from "../provider-call.js";
+import { providerCallFailure, providerCallResult } from "../write-outcome.js";
+import { deriveContext } from "../derived-context.js";
 export function defined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
 }
@@ -41,6 +52,7 @@ function checkToolContract(id, tool) {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export const API_OPTIONS = optionsOf()({
     ...keys("title", "description", "authScope", "maxResultBytes", "testCredential", "testCredentials", "validateArgs"),
+    readOnly: READ_ONLY,
     callAdmission: CALL_ADMISSION,
     usageGuide: USAGE_GUIDE,
     credential: CREDENTIAL,
@@ -90,6 +102,8 @@ function describedApiAuth(opts) {
  */
 export function apiConnector(id, opts, oauth) {
     opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    if (opts.readOnly !== undefined)
+        READ_ONLY.parse(opts.readOnly, `Connector(${JSON.stringify(id)}).readOnly`);
     if (opts.callAdmission !== undefined)
         CALL_ADMISSION.parse(opts.callAdmission, `api(${JSON.stringify(id)}).callAdmission`);
     assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
@@ -124,35 +138,67 @@ export function apiConnector(id, opts, oauth) {
         ...defined({
             description: opts.description,
             authScope: opts.authScope,
+            readOnly: opts.readOnly,
             maxResultBytes: opts.maxResultBytes,
             callAdmission: opts.callAdmission,
             usageGuide: opts.usageGuide,
             credential: opts.credential,
-            testCredential: opts.testCredential,
-            testCredentials: opts.testCredentials,
+            testCredential: opts.testCredential
+                ? (value, ctx) => credentialProbe(ctx, { value }, (view) => settleOnClose(view, () => opts.testCredential(value, view)))
+                : undefined,
+            testCredentials: opts.testCredentials
+                ? (values, ctx) => credentialProbe(ctx, values, (view) => settleOnClose(view, () => opts.testCredentials(values, view)))
+                : undefined,
         }),
         ...(oauth
             ? {
-                status: oauth.status,
-                startAuth: oauth.startAuth,
-                disconnectAuth: oauth.disconnectAuth,
-                verifyState: oauth.verifyState,
-                verifyCallbackIssuer: oauth.verifyCallbackIssuer,
-                consumeAuthError: oauth.consumeAuthError,
-                finishAuth: oauth.finishAuth,
+                status: (ctx) => settleOnClose(ctx, () => oauth.status(ctx)),
+                startAuth: (ctx, options) => settleOnClose(ctx, () => oauth.startAuth(ctx, options)),
+                disconnectAuth: (ctx) => settleOnClose(ctx, () => oauth.disconnectAuth(ctx)),
+                // Callback work belongs to its request, including the route's
+                // uninterruptible exchange, rather than any resource call.
+                verifyState: (state, ctx) => settleOnClose(ctx, () => oauth.verifyState(state, ctx), true),
+                verifyCallbackIssuer: (issuer, ctx) => settleOnClose(ctx, () => oauth.verifyCallbackIssuer(issuer, ctx), true),
+                consumeAuthError: (ctx) => settleOnClose(ctx, () => oauth.consumeAuthError(ctx), true),
+                finishAuth: (code, ctx, callbackParams) => settleOnClose(ctx, () => oauth.finishAuth(code, ctx, callbackParams), true),
             }
             : {}),
         staticTools: defs,
         async listTools(ctx) {
-            return redactCatalog(ctx, defs);
+            return settleOnClose(ctx, async () => redactCatalog(ctx, defs));
         },
-        async callTool(name, args, ctx) {
-            trackCredentialReads(ctx);
-            const tool = byName.get(name);
-            if (!tool) {
-                throw new Error(`Unknown tool "${name}" on connector "${id}"`);
-            }
-            const input = args ?? {};
+        callTool: (name, args, ctx, options) => runEdge(core(name, args, ctx, options)),
+    };
+    const core = (name, args, ctx) => Effect.gen(function* () {
+        trackCredentialReads(ctx);
+        enterProviderBoundary(ctx, connector);
+        const tool = byName.get(name);
+        // Refusals before the handler runs are known failures: nothing was sent.
+        if (!tool) {
+            throw knownProviderFailure(new Error(`Unknown tool "${name}" on connector "${id}"`));
+        }
+        // `await` (not a bare promise return) so a handler that throws before
+        // its first await never sits handler-less for the thenable-adoption
+        // microtask — workerd and vitest both report that gap as an unhandled
+        // rejection even though the caller catches the failure.
+        // Derived, never mutated: the registry's context stays as it was, and
+        // the call state beside it (caller, admission permit, recovery facts,
+        // sent secrets) resolves through the handler's copy. The grant sends a
+        // write once: the registry's classification of this call decides, else
+        // the rule the registry would apply to the tool (INV-1).
+        const write = (callClassification(ctx) ?? classifyTool(tool)) === "write";
+        const callCtx = providerCallContext(ctx, providerRequests(ctx) ? classifyTool(tool) : write ? "write" : "read");
+        const handlerCtx = deriveContext(callCtx, {
+            fetch: providerFetch(callCtx, opts.title ?? id, false, sentSecretsFetch(ctx)),
+            ...(oauth ? { oauth: oauth.access(callCtx, { write }) } : {}),
+        });
+        setViewService(handlerCtx, ContinuationBinding, {
+            connection: serviceFor(ctx, ContinuationBinding)?.connection || id,
+            principal: serviceFor(ctx, ContinuationBinding)?.principal ?? null,
+        });
+        let handlerStarted = false;
+        const handled = yield* Effect.exit(Effect.gen(function* () {
+            const input = normalizeToolInput(args ?? {});
             if (validateArgs && tool.inputSchema) {
                 const invalid = validateCatalogToolInput(tool.inputSchema, input, {
                     address: `${id}.${name}`,
@@ -163,54 +209,98 @@ export function apiConnector(id, opts, oauth) {
                     failClosed: true,
                 }, { connector: id, tool });
                 if (invalid)
-                    throw invalid;
+                    throw knownProviderFailure(invalid);
             }
-            // `await` (not a bare promise return) so a handler that throws before
-            // its first await never sits handler-less for the thenable-adoption
-            // microtask — workerd and vitest both report that gap as an unhandled
-            // rejection even though the caller catches the failure.
-            // Preserve the registry's context identity: private caller/provenance
-            // markers belong to it, as does the grant its accessor reaches.
-            const handlerCtx = Object.assign(ctx, {
-                fetch: sentSecretsFetch(ctx),
-                ...(oauth ? { oauth: oauth.access(ctx) } : {}),
-            });
-            try {
-                return redactSentSecrets(ctx, await tool.handler(input, handlerCtx));
+            handlerStarted = true;
+            // The opaque handler may await a helper, swallow its rejection, or
+            // wait elsewhere. Its boundary remains call-owned; auxiliary helpers
+            // retain their separate request ownership. Ledger settlement below
+            // must see the close reason before this call's Promise rejects.
+            const native = toolEntry(tool);
+            return yield* native
+                ? duringViewEffect(callCtx, () => native(input, handlerCtx))
+                : Effect.tryPromise({
+                    // Custom handlers retain their Promise revocation bridge and
+                    // synchronous entry, including their helpers' fact ordering.
+                    try: () => settleOnClose(callCtx, () => Promise.resolve(tool.handler(input, handlerCtx))),
+                    catch: (error) => error,
+                });
+        }));
+        if (Exit.isFailure(handled)) {
+            const error = causeError(handled.cause, callCtx.signal);
+            // Settled before anything is decided or reported: a request that has
+            // not left by now (a sibling awaiting its credential) never will.
+            closeProviderCall(callCtx);
+            if (!handlerStarted) {
+                throw knownProviderFailure(error instanceof ConnectorCallError
+                    ? error
+                    : new ConnectorCallError("invalid_args", `Cannot validate arguments for "${id}.${name}": its inputSchema could not be evaluated`));
             }
-            catch (error) {
-                // The request's own abort reason, by identity, is the caller's.
-                if (ctx.signal?.aborted === true && error === ctx.signal.reason)
+            // A handler owns its destinations. ctx.baseUrl is Connecta's inbound
+            // URL, so it must never masquerade as the failed downstream host.
+            const settle = (failure) => redactSentSecrets(ctx, providerCallFailure(handlerCtx, { title: opts.title ?? id }, failure, {
+                dispatched: true,
+                fallback: write ? "write" : "read",
+                finalize: true,
+                // Only a declared provider's ledger can see every request.
+                untracked: !tracksRequests(connector),
+            }));
+            // The request's own abort reason, by identity, is the caller's. The
+            // invocation reports it for its logical call; any other write's is
+            // settled like any other failure: it may have left.
+            if (ctx.signal?.aborted === true && error === ctx.signal.reason) {
+                if (!write || inLogicalCall(ctx))
                     throw error;
-                // A handler owns its destinations. ctx.baseUrl is Connecta's inbound
-                // URL, so it must never masquerade as the failed downstream host.
-                if (error instanceof ConnectorCallError)
-                    throw redactSentSecrets(ctx, error);
-                if (!networkErrorCode(error)) {
-                    // Anything else is a runtime's, parser's, or stream's account of
-                    // what the handler read (a JSON parser quotes the reply it choked
-                    // on; a body stream rejects with whatever the runtime says), so it
-                    // is told in connecta's words, classified as the original would
-                    // have been, and rebuilt without its cause or nested errors. A
-                    // handler that means the agent to read its words throws a
-                    // ConnectorCallError. No host is named: connecta does not know
-                    // which destination the handler read.
-                    const kind = errorLabel(error);
-                    throw attachFailureFacts(carryFailureFacts(error, new WithheldTextError(`Connector "${id}" tool "${name}" handler failed` +
-                        `${kind ? ` (${kind})` : ""}. Its text is withheld because it ` +
-                        "can quote what the downstream sent.", error)), { step: "handler" });
-                }
-                throw unavailableCallError(error, undefined, undefined, ctx.signal);
+                throw settle(error);
             }
-        },
-    };
+            if (error instanceof ConnectorCallError)
+                throw settle(error);
+            if (!networkErrorCode(error)) {
+                // Anything else is a runtime's, parser's, or stream's account of
+                // what the handler read (a JSON parser quotes the reply it choked
+                // on; a body stream rejects with whatever the runtime says), so it
+                // is told in connecta's words, classified as the original would
+                // have been, and rebuilt without its cause or nested errors. A
+                // handler that means the agent to read its words throws a
+                // ConnectorCallError. No host is named: connecta does not know
+                // which destination the handler read.
+                const kind = errorLabel(error);
+                throw settle(attachFailureFacts(carryFailureFacts(error, new WithheldTextError(`Connector "${id}" tool "${name}" handler failed` +
+                    `${kind ? ` (${kind})` : ""}. Its text is withheld because it ` +
+                    "can quote what the downstream sent.", error)), { step: "handler" }));
+            }
+            // A handler is opaque: by the time its fetch failed it may already
+            // have sent the write, so no network code proves a write unsent.
+            const unreachable = unavailableCallError(error, undefined, undefined, ctx.signal);
+            // A raw handler with no tracked requests remains opaque, as before.
+            // Once guarded requests exist, its own or a nested api() boundary's,
+            // the ledgers supply the dispatch proof.
+            if (providerRequests(handlerCtx)?.length || nestedProviderRequests(handlerCtx).length)
+                throw settle(unreachable);
+            throw providerCallFailure(ctx, { title: opts.title ?? id }, unreachable, {
+                dispatched: true,
+                fallback: classifyTool(tool),
+            });
+        }
+        closeProviderCall(callCtx);
+        // A write an undeclared 401 left unknown fails however its handler returned.
+        const unknown = providerCallResult(handlerCtx, write ? "write" : "read");
+        if (unknown)
+            throw redactSentSecrets(ctx, unknown);
+        return redactSentSecrets(ctx, handled.value);
+    }).pipe(Effect.catchDefect((error) => Effect.fail(error)));
+    // This boundary's identity in a logical call, fixed now: this object with
+    // this function, never whatever the property or a copy holds by then.
+    providerBoundary(connector);
+    registerCallEntry(connector, core);
     if (oauth)
         registerInvocationAuth(connector, async (ctx) => {
             // The built-in static OAuth status only reads the stored grant. It never
             // refreshes, invokes a handler, or sends a downstream request.
-            if ((await oauth.status(ctx)).state === "auth_required") {
+            if ((await settleOnClose(ctx, () => oauth.status(ctx))).state === "auth_required") {
                 throw new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization. Call authorize_connector.`);
             }
         });
+    registerConnectorVocabulary(connector, opts.tools);
     return connector;
 }

package/dist/connectors/guarded-fetch.d.ts

@@ -1,3 +1,5 @@
+export { retryAfterMs } from "../http-policy.js";
+import { type ProviderRequest } from "../provider-call.js";
 import type { ConnectorContext } from "../types.js";
 /** The methods a hand-written provider surface actually uses. */
 type GuardedMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -43,6 +45,18 @@ export interface GuardedRequest {
      * up front: the ceiling still bounds what is read, never what is sent.
      */
     prefixOnly?: boolean;
+    /** Trusted per-operation evidence (e.g. Breeze writes use GET); otherwise the tool's verdict applies. */
+    classification?: "read" | "write";
+    /** Provider-declared request that cannot perform the logical resource write. */
+    auxiliary?: boolean;
+    /**
+     * Replay proof for direct transport users: the genuine, legal idempotency
+     * key its vendor honors that this request carries (among `visibleHeaders`),
+     * set only then. An operation hint (a PUT, a content address) is never
+     * this proof. Never overrides a served write, and recorded on the logical
+     * call so key-reuse advice can name it (`keyProtectsCall`).
+     */
+    idempotencyKey?: string;
 }
 /**
  * One downstream response, read under the connector's byte ceiling.
@@ -84,8 +98,6 @@ interface GuardedResponse {
         truncated: boolean;
     }>;
 }
-/** Parse delta-seconds or an HTTP-date into a non-negative wait window. */
-export declare function retryAfterMs(headers: Headers): number | undefined;
 /**
  * Turn one response into the provider's own result, or throw the provider's
  * own typed failure. This is where status codes acquire meaning, and it is
@@ -95,9 +107,11 @@ type GuardedResponseMapper<T> = (response: GuardedResponse, ctx: ConnectorContex
 export interface GuardedFetchOptions {
     /**
      * Provider name as it appears in normalized failure prose — "Cloudflare",
-     * "Notion". Used for messages only; it is never parsed.
+     * "Vercel". Used for messages only; it is never parsed.
      */
     provider: string;
+    /** Provider-declared auth/metadata work that cannot perform the logical write. */
+    auxiliary?: boolean;
     /**
      * Absolute base URL. Its origin and path prefix are the confinement: every
      * request resolves beneath it or is refused.
@@ -133,29 +147,49 @@ export interface GuardedFetchOptions {
      * authentication, so a refused request never resolves a credential.
      */
     admit?: (url: URL, request: GuardedRequest) => void;
+    /**
+     * Reviewed vendor evidence that the vendor authenticates a request before
+     * it acts on it. Without it, a write answered 401 has an unknown outcome:
+     * a server may act on a request before it rejects the credential. With it,
+     * a 401 that `matches` is that write's refusal. Declare it only where the
+     * vendor's documentation says so, cite that documentation in `evidence` and
+     * in the provider's evidence review, and keep `matches` narrow. Of the
+     * maintained providers only Stripe declares it. Checked at construction.
+     */
+    authBeforeExecution?: AuthBeforeExecution;
 }
-/** Sends one already-guarded request on behalf of one call's context. */
-type GuardedFetcher = (url: string, init: RequestInit, ctx: ConnectorContext) => Promise<Response>;
 /**
- * The transport half of a guarded connector that authenticates through its
- * own `api()` OAuth grant: no header of the helper's making, and every request
- * sent through `ctx.oauth.fetch`, which adds the calling owner's bearer token,
- * refuses any origin outside the grant's `apiOrigins`, and spends one
- * coordinated refresh and one replay on a 401 before answering
- * `auth_required`. Spread it into the options:
- * `guardedFetch({ provider, baseUrl, maxResponseBytes, ...oauthBearer(provider) })`.
- *
- * Confinement still happens here first, so a request reaches the grant only
- * once it is provably beneath `baseUrl`; the grant's origin check is the second
- * fence, not the only one.
+ * A trusted per-vendor review: types cannot verify what a vendor does, so the
+ * reviewer checks the cited documentation and the predicate against it.
  */
+interface AuthBeforeExecution {
+    /** The vendor's documented guarantee: its URL and what it says. Never empty. */
+    evidence: string;
+    /**
+     * Whether this raw 401 is one the evidence covers, from its status and
+     * headers and the request's method and provider-relative path only: never a
+     * mapped code or prose.
+     */
+    matches: (answer: {
+        status: 401;
+        headers: Headers;
+        method: string;
+        path: string;
+    }) => boolean;
+}
+/** Sends one already-guarded request on behalf of one call's context. */
+type GuardedFetcher = (url: string, init: RequestInit, ctx: ConnectorContext) => Promise<Response>;
 export declare function oauthBearer(provider: string): Pick<GuardedFetchOptions, "authenticate" | "fetch">;
 /** Send one guarded request and map its response with provider knowledge. */
 export type GuardedTransport = <T>(request: GuardedRequest, ctx: ConnectorContext, map: GuardedResponseMapper<T>) => Promise<T>;
+/**
+ * Test-only legacy response lookup for renewal-provenance fixtures outside
+ * the kit. Production renewal uses the kit ledger. Undefined for other objects.
+ */
+export declare function answeredRequest(response: object): ProviderRequest | undefined;
 /**
  * Build the transport a connector sends every request through. `maxResponseBytes`
  * is required rather than defaulted: what counts as an absurd response is a fact
  * about the API, not about HTTP.
  */
 export declare function guardedFetch(options: GuardedFetchOptions): GuardedTransport;
-export {};