@zackbart/connecta 0.29.0 → 0.31.0

package/dist/config-schema.d.ts

@@ -25,9 +25,13 @@ type AnyField = Field<any, any, boolean>;
 export type Shape = {
     readonly [key: string]: AnyField;
 };
-/** A discriminated union of closed objects: `cases[value[key]]`, else `cases[otherwise]`. */
+/**
+ * A discriminated union of closed objects: `cases[value[key[0]][key[1]]…]`,
+ * else `cases[otherwise]`. Each case is the whole object's shape, including
+ * the nested objects on the key path.
+ */
 interface Variants {
-    readonly key: string;
+    readonly key: readonly string[];
     readonly cases: Readonly<Record<string, Shape>>;
     readonly otherwise?: string;
 }
@@ -116,13 +120,16 @@ export declare function instance<F extends AnyField>(field: F): F & {
 };
 /**
  * A closed object whose allowed keys depend on a discriminant, such as
- * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * `remoteMcp({ auth: { type: "headers", headers } })`. The discriminant may
+ * be nested: `variants(["auth", "type"], cases)` selects the whole options
+ * shape from `options.auth.type`, so `{ auth: { type: "apiKey" }, mode }` and
+ * `{ auth: { type: "oauth" } }` accept different top-level keys. An omitted
  * discriminant selects `otherwise` when given; an omitted one without it, an
- * unrecognized one, or a value that is not an object throws with its path and
- * the valid values, so no union falls through to "no case". Only the walk
- * reads variants; the factory validates the remaining values itself.
+ * unrecognized one, or a value on the path that is not an object throws with
+ * its path and the valid values, so no union falls through to "no case". Only
+ * the walk reads variants; the factory validates the remaining values itself.
  */
-export declare function variants(key: string, cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
+export declare function variants(key: string | readonly string[], cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
 /**
  * A closed object for the unknown-key walk only: each named key may hold
  * anything, which its factory validates. For the options of a built-in

package/dist/config-schema.js

@@ -183,16 +183,22 @@ export function instance(field) {
 }
 /**
  * A closed object whose allowed keys depend on a discriminant, such as
- * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * `remoteMcp({ auth: { type: "headers", headers } })`. The discriminant may
+ * be nested: `variants(["auth", "type"], cases)` selects the whole options
+ * shape from `options.auth.type`, so `{ auth: { type: "apiKey" }, mode }` and
+ * `{ auth: { type: "oauth" } }` accept different top-level keys. An omitted
  * discriminant selects `otherwise` when given; an omitted one without it, an
- * unrecognized one, or a value that is not an object throws with its path and
- * the valid values, so no union falls through to "no case". Only the walk
- * reads variants; the factory validates the remaining values itself.
+ * unrecognized one, or a value on the path that is not an object throws with
+ * its path and the valid values, so no union falls through to "no case". Only
+ * the walk reads variants; the factory validates the remaining values itself.
  */
 export function variants(key, cases, otherwise) {
+    const path = typeof key === "string" ? [key] : [...key];
+    if (path.length === 0)
+        throw new Error("variants() requires a discriminant key.");
     return {
         ...opaque(),
-        variants: { key, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
+        variants: { key: path, cases, ...(otherwise !== undefined ? { otherwise } : {}) },
     };
 }
 /**
@@ -309,14 +315,27 @@ function inspectRecord(value, path, field) {
  * is never echoed.
  */
 function selectShape(inspected, path, variants) {
-    const at = `${path}.${variants.key}`;
+    const at = `${path}.${variants.key.join(".")}`;
     const valid = Object.keys(variants.cases)
         .map((name) => JSON.stringify(name))
         .join(", ");
-    const descriptor = inspected.own.find(([key]) => key === variants.key)?.[1];
-    if (descriptor && isAccessor(descriptor))
-        fail(`${at} must be a plain value, not a getter or setter.`);
-    const discriminant = descriptor?.value;
+    // Walk the key path one plain object at a time, reading descriptors only.
+    let holder = inspected;
+    let discriminant;
+    for (const [depth, key] of variants.key.entries()) {
+        const step = `${path}.${variants.key.slice(0, depth + 1).join(".")}`;
+        const descriptor = holder.own.find(([own]) => own === key)?.[1];
+        if (descriptor && isAccessor(descriptor))
+            fail(`${step} must be a plain value, not a getter or setter.`);
+        discriminant = descriptor?.value;
+        if (depth === variants.key.length - 1 || discriminant === undefined)
+            break;
+        if (typeof discriminant !== "object" || discriminant === null || isArrayAt(discriminant, step)) {
+            fail(`${step} must be an object.`);
+        }
+        holder = inspectRecord(discriminant, step, OPAQUE);
+        discriminant = undefined;
+    }
     if (discriminant === undefined) {
         if (variants.otherwise !== undefined)
             return variants.cases[variants.otherwise];

package/dist/config.d.ts

@@ -252,6 +252,8 @@ declare const connectaConfig: {
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
      * `@zackbart/connecta/sqlite` on Node. Defaults to memoryStorage(), which
      * forgets everything on restart.
+     * Custom adapters must declare `capabilities.absoluteExpiry: true` and honor
+     * `expiresAtMs` on set and compareAndSet; older adapters fail construction.
      */
     storage: import("./config-schema.js").Field<KVStorage, KVStorage, true>;
     /**

package/dist/config.js

@@ -291,6 +291,8 @@ const connectaConfig = {
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
      * `@zackbart/connecta/sqlite` on Node. Defaults to memoryStorage(), which
      * forgets everything on restart.
+     * Custom adapters must declare `capabilities.absoluteExpiry: true` and honor
+     * `expiresAtMs` on set and compareAndSet; older adapters fail construction.
      */
     storage: opaque({
         // Every subsystem relies on the atomic claim and enumeration, so storage
@@ -299,13 +301,16 @@ const connectaConfig = {
         // adapter, which could never offer either guarantee.
         check: (value, path) => {
             const missing = STORAGE_METHODS.filter((method) => !hasMethods(value, [method]));
-            if (missing.length === 0)
-                return;
-            throw new ConfigError(`${path} must implement ${missing.join(" and ")}. ` +
-                "Use d1Storage(env.CONNECTA_DB) from @zackbart/connecta/d1 on Workers, " +
-                "sqliteStorage(path) from @zackbart/connecta/sqlite on Node, or " +
-                "memoryStorage() in tests. Workers KV is not supported: it is eventually " +
-                "consistent and cannot compare-and-set.");
+            if (missing.length > 0)
+                throw new ConfigError(`${path} must implement ${missing.join(" and ")}. ` +
+                    "Use d1Storage(env.CONNECTA_DB) from @zackbart/connecta/d1 on Workers, " +
+                    "sqliteStorage(path) from @zackbart/connecta/sqlite on Node, or " +
+                    "memoryStorage() in tests. Workers KV is not supported: it is eventually " +
+                    "consistent and cannot compare-and-set.");
+            if (!isObject(value) || !isObject(value.capabilities) || value.capabilities.absoluteExpiry !== true) {
+                throw new ConfigError(`${path} must declare capabilities.absoluteExpiry: true and honor expiresAtMs on set and compareAndSet. ` +
+                    "Upgrade the storage adapter before declaring this capability.");
+            }
         },
         resolve: (value) => value ?? memoryStorage(),
     }),

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

@@ -1,6 +1,6 @@
 import type { ConnectorContext } from "../types.js";
 /** The methods a hand-written provider surface actually uses. */
-type GuardedMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type GuardedMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface GuardedRequest {
     method: GuardedMethod;
     /**
@@ -21,6 +21,14 @@ export interface GuardedRequest {
      * shadow it.
      */
     headers?: Record<string, string | undefined>;
+    /**
+     * Headers whose values the tool returns to its caller by contract, such as
+     * an idempotency key. They are added after the request's sent secrets are
+     * registered, so a name like `Idempotency-Key` does not mark the value a
+     * credential and redact it from the result that must carry it. They may not
+     * collide with any other header.
+     */
+    visibleHeaders?: Record<string, string>;
     /** JSON request body. Serialized here, with the `Content-Type` to match. */
     body?: unknown;
     /**

package/dist/connectors/guarded-fetch.js

@@ -70,17 +70,17 @@ function confinementBase(provider, baseUrl) {
         base = new URL(baseUrl);
     }
     catch {
-        throw new Error(`${provider} baseUrl must be an absolute URL: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must be an absolute URL.`);
     }
     const loopback = base.hostname === "localhost" || base.hostname === "127.0.0.1" || base.hostname === "[::1]";
     if (base.protocol !== "https:" && !(base.protocol === "http:" && loopback)) {
-        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double): ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double).`);
     }
     if (base.username || base.password) {
         throw new Error(`${provider} baseUrl must not embed URL credentials; authentication belongs in headers.`);
     }
     if (base.search || base.hash) {
-        throw new Error(`${provider} baseUrl must not carry a query or fragment: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must not carry a query or fragment.`);
     }
     return base;
 }
@@ -343,6 +343,13 @@ export function guardedFetch(options) {
                 ...(ctx.signal ? { signal: ctx.signal } : {}),
             };
             sentSecretsFor(ctx).request(url, init);
+            for (const [name, value] of Object.entries(request.visibleHeaders ?? {})) {
+                const shadow = hasHeader(headers, name);
+                if (shadow) {
+                    throw new ConnectorCallError("invalid_args", `A ${provider} request sets the ${shadow} header twice.`);
+                }
+                headers[name] = value;
+            }
             response = await send(url.toString(), init, ctx);
         }
         catch (cause) {
@@ -356,8 +363,13 @@ export function guardedFetch(options) {
         }
         const declared = Number(response.headers.get("content-length"));
         // A prefix read takes only what it was asked for, so a long body is not
-        // a reason to refuse it; the ceiling still bounds what is read.
-        if (Number.isFinite(declared) && declared > limit && !(request.prefixOnly && response.ok)) {
+        // a reason to refuse it; the ceiling still bounds what is read. A HEAD
+        // response has no body: its Content-Length describes the GET
+        // representation, which is exactly what a HEAD asks about.
+        if (Number.isFinite(declared) &&
+            declared > limit &&
+            request.method !== "HEAD" &&
+            !(request.prefixOnly && response.ok)) {
             await response.body?.cancel().catch(() => { });
             throw oversized(provider, limit, `a declared ${declared} bytes`);
         }

package/dist/connectors/negotiation-cache.js

@@ -31,7 +31,7 @@ export async function storeNegotiation(ctx, digest, prior) {
         return;
     assertDownstreamOutputSafe(ctx.requestScope ?? ctx, prior);
     // DiscoverResult instructions, metadata and capability keys can echo auth.
-    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redact(prior);
+    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redactCredentials(prior);
     if (clean.kind === "modern" && !isSpecType.DiscoverResult(clean.discover))
         return;
     try {

package/dist/downstream-input-context.js

@@ -18,6 +18,15 @@ export function bindDownstreamContinuation(scope, target) {
 export function clearDownstreamContinuation(scope) {
     continuations.delete(scope);
 }
+/** The invocation's schema-filtered snapshot, never raw continuation arguments. */
+export function recordDownstreamArgumentEcho(scope, echo) {
+    const continuation = continuations.get(scope);
+    if (continuation)
+        continuation.argumentEcho = echo;
+}
+export function downstreamArgumentEcho(scope) {
+    return continuations.get(scope)?.argumentEcho ?? {};
+}
 export function downstreamWriteContinuation(scope) {
     return continuations.get(scope)?.write === true;
 }

package/dist/downstream-input.js

@@ -1,9 +1,9 @@
 import { inputRequired, specTypeSchemas, ProtocolError, INVALID_PARAMS, CLIENT_CAPABILITIES_META_KEY, PROTOCOL_VERSION_META_KEY, } from "@modelcontextprotocol/server";
-import { ConnectorCallError, echoedCallArgs } from "./errors.js";
-import { redactAgentOutput, sentSecretsForRequest } from "./sent-secrets.js";
+import { ConnectorCallError } from "./errors.js";
+import { sentSecretsForRequest } from "./sent-secrets.js";
 import { inputRetryKeys } from "./storage/keys.js";
 import { REQUEST_STATE_TTL_MS, MAX_INPUT_ROUNDS, invalidRequestState, requestDigest, stateObject, } from "./request-state.js";
-import { bindDownstreamCapabilities, downstreamInputCapabilities, bindDownstreamContinuation, clearDownstreamContinuation, assertNoPrivateStateEchoes, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
+import { bindDownstreamCapabilities, downstreamInputCapabilities, bindDownstreamContinuation, clearDownstreamContinuation, downstreamArgumentEcho, assertNoPrivateStateEchoes, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
 const MAX_PAYLOAD_BYTES = 64 * 1024;
 export const MAX_RELAY_STATE_CHARS = 128 * 1024;
 const MAX_REQUESTS = 16;
@@ -67,7 +67,7 @@ export async function captureDownstreamInput(scope, connector, address, raw, sec
                     url.password ||
                     [...params.url].some((char) => char.charCodeAt(0) <= 0x20 || char.charCodeAt(0) === 0x7f) ||
                     secrets.containsUrl(params.url) ||
-                    redactAgentOutput(secrets, params.url) !== params.url)
+                    secrets.redact(params.url) !== params.url)
                     return invalidInput();
             }
             catch {
@@ -84,7 +84,7 @@ export async function captureDownstreamInput(scope, connector, address, raw, sec
                 return invalidInput();
             // A schema controls the accepted answer. Refuse redaction changes rather
             // than asking the host to submit different field names or enum values.
-            if (redactAgentOutput(secrets, parsed.value.requestedSchema) !== parsed.value.requestedSchema)
+            if (secrets.redact(parsed.value.requestedSchema) !== parsed.value.requestedSchema)
                 return invalidInput();
             inputRequests[namespace(connector, index)] = inputRequired.elicit({
                 message: `Downstream ${connector}: ${parsed.value.message}`,
@@ -237,7 +237,7 @@ export class DownstreamElicitation {
                 return result;
             // The nonce is spent even when the downstream failure would normally
             // allow a retry. Preserve write reconciliation and auth prerequisites.
-            const echoed = echoedCallArgs(args.args);
+            const echoed = downstreamArgumentEcho(this.options.requestScope);
             const structuredContent = {
                 ...result.structuredContent,
                 error: {
@@ -249,9 +249,11 @@ export class DownstreamElicitation {
                                 tool: state.tool,
                                 arguments: { address: state.address, ...echoed },
                                 purpose: "Re-issue the original direct call without requestState or inputResponses to start a fresh input round. Do not resend this continuation." +
-                                    (args.args !== undefined && !("args" in echoed)
-                                        ? " Use the exact arguments you sent; they exceed the echo budget."
-                                        : ""),
+                                    (echoed.argsRedacted
+                                        ? " Re-send the original arguments; sensitive fields are omitted."
+                                        : args.args !== undefined && !("args" in echoed)
+                                            ? " Use the exact arguments you sent; they could not be echoed safely."
+                                            : ""),
                             },
                         }
                         : {}),
@@ -314,8 +316,8 @@ export class DownstreamElicitation {
         if (requestState.length > MAX_RELAY_STATE_CHARS)
             return failure("input_required_limit", "The sealed downstream state exceeds 128 KiB.");
         // Opaque echoes and mutable schemas/URLs were refused during capture.
-        // Prompt messages take the same #736 agent boundary as ordinary outputs.
-        return redactAgentOutput(sentSecretsForRequest(scope), inputRequired({
+        // Downstream prompt messages are prose under the payload rules.
+        return sentSecretsForRequest(scope).redact(inputRequired({
             ...(Object.keys(pending.inputRequests).length ? { inputRequests: pending.inputRequests } : {}),
             requestState,
         }));

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutorAdmissionErrorCode } from "./executor-admission.js";
+import type { JsonSchema } from "./types.js";
 /**
  * Machine-readable classification of a failed connector tool call.
  *
@@ -77,14 +78,14 @@ export declare const MAX_ARGUMENT_VALIDATION_ISSUES = 3;
  */
 export declare function boundedEchoText(value: string, maxBytes?: number): string;
 /**
- * `{ args }` when the caller's arguments fit the shared echo budget,
- * `{}` when they do not. All or nothing: a clipped echo would be a *different*
- * call than the one that was refused, and the routes this feeds end at a human
- * approving one. Unserializable arguments are treated the same way as oversized
- * ones — there is nothing honest to put in the field.
+ * Snapshot the caller's arguments after bounded schema-aware writeOnly omission,
+ * then apply the shared byte budget without clipping. Unresolved sensitivity
+ * omits the entire echo. argsRedacted marks partial or withheld arguments as
+ * reconciliation context; any retry must use the caller's original arguments.
  */
-export declare function echoedCallArgs(args: unknown): {
+export declare function echoedCallArgs(args: unknown, schema?: JsonSchema): {
     args?: unknown;
+    argsRedacted?: true;
 };
 /** Optional transport diagnostics; never a URL path or raw runtime message. */
 interface UnavailableDetails {
@@ -182,8 +183,25 @@ export declare class ConnectorCallError extends Error {
         current?: Readonly<Record<string, number>>;
     });
 }
+/** Secret-free payload returned by authorize_connector and auth failures. */
+export interface AuthorizationHandoff {
+    connector: string;
+    recovery: AuthRecoveryMode;
+    message?: string;
+    status?: "auth_required";
+    authorizationUrl?: string;
+    operatorUrl?: string;
+    instructions?: string;
+    credential?: {
+        label: string;
+        fields: {
+            name: string;
+            guidance?: string;
+        }[];
+    };
+}
 /** The `error` object surfaced in value-mode call results and rejected promises. */
-export interface CallErrorDetails {
+export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
     /** Sanitized transport diagnostics, absent when the runtime supplies none. */
     details?: UnavailableDetails;
     code: string;
@@ -224,12 +242,13 @@ export interface CallErrorDetails {
         arguments: {
             address: string;
             /**
-             * The caller's own arguments, echoed only when they fit
-             * the shared echo budget — and then whole, never clipped. Absent
-             * means "re-send exactly what you sent": a half-copied argument object
-             * routed into a human approval prompt would describe a call nobody made.
+             * A schema-filtered snapshot within the shared byte budget, never
+             * clipped. With argsRedacted, this is partial reconciliation context.
+             * If absent or redacted, retry only with the original arguments.
              */
             args?: unknown;
+            /** Sensitive fields were omitted, or sensitivity could not be resolved. */
+            argsRedacted?: true;
         };
         purpose: string;
     } | {
@@ -253,11 +272,18 @@ export interface CallErrorDetails {
     };
     /** Configured connectors in this request's registry view only. */
     configuredConnectors?: string[];
-    /** Agent-only uncertain write, never copied to an operator record. */
+    /**
+     * Agent-only uncertain write, never copied to an operator record. argsRedacted
+     * marks partial or withheld schema-filtered arguments; argsOmitted means args
+     * is absent. Reconciliation and any explicit retry require the original input.
+     */
     uncertainCall?: {
         address: string;
         args?: unknown;
         argsOmitted?: true;
+        argsRedacted?: true;
+        /** Facts the connector recorded before dispatch, such as a generated `idempotencyKey`. */
+        recovery?: Readonly<Record<string, string>>;
     };
     /** Explicit retry guidance; recovery never retries or mutates by itself. */
     retry?: string;

package/dist/errors.js

@@ -1,5 +1,6 @@
 // Typed failure contract for connector tool calls. Web-API only — no node:
 // imports here.
+import { redactCallArguments } from "./argument-redaction.js";
 const CLASSIFICATION_CODE_TABLE = {
     timeout: true,
     auth_required: true,
@@ -116,25 +117,34 @@ export function boundedEchoText(value, maxBytes = MAX_ECHOED_BYTES) {
     return `${echoDecoder.decode(bytes.slice(0, end))}…`;
 }
 /**
- * `{ args }` when the caller's arguments fit the shared echo budget,
- * `{}` when they do not. All or nothing: a clipped echo would be a *different*
- * call than the one that was refused, and the routes this feeds end at a human
- * approving one. Unserializable arguments are treated the same way as oversized
- * ones — there is nothing honest to put in the field.
+ * Snapshot the caller's arguments after bounded schema-aware writeOnly omission,
+ * then apply the shared byte budget without clipping. Unresolved sensitivity
+ * omits the entire echo. argsRedacted marks partial or withheld arguments as
+ * reconciliation context; any retry must use the caller's original arguments.
  */
-export function echoedCallArgs(args) {
+export function echoedCallArgs(args, schema) {
     if (args === undefined)
         return {};
     let text;
+    let redacted = false;
     try {
-        text = JSON.stringify(args);
+        const filtered = schema ? redactCallArguments(args, schema) : { value: args, redacted: false };
+        redacted = filtered.redacted;
+        if (!("value" in filtered))
+            return { argsRedacted: true };
+        const safeArgs = filtered.value;
+        text = JSON.stringify(safeArgs);
     }
     catch {
-        return {};
+        return redacted ? { argsRedacted: true } : {};
     }
     if (text === undefined)
         return {};
-    return echoEncoder.encode(text).length <= MAX_ECHOED_BYTES ? { args: JSON.parse(text) } : {};
+    return echoEncoder.encode(text).length <= MAX_ECHOED_BYTES
+        ? { args: JSON.parse(text), ...(redacted ? { argsRedacted: true } : {}) }
+        : redacted
+            ? { argsRedacted: true }
+            : {};
 }
 function boundedValidation(details) {
     if (!details)