@zackbart/connecta 0.28.1 → 0.30.0

package/dist/downstream-input.js

@@ -0,0 +1,325 @@
+import { inputRequired, specTypeSchemas, ProtocolError, INVALID_PARAMS, CLIENT_CAPABILITIES_META_KEY, PROTOCOL_VERSION_META_KEY, } from "@modelcontextprotocol/server";
+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, 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;
+const PURPOSE = "connecta:downstream-input:v1";
+const pendingInputs = new WeakMap();
+const modernRequests = new WeakSet();
+function withinBudget(value) {
+    try {
+        return new TextEncoder().encode(JSON.stringify(value)).byteLength <= MAX_PAYLOAD_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+function namespace(connector, index) {
+    return `downstream/${connector}/${index}`;
+}
+function invalidInput() {
+    throw new ConnectorCallError("input_required_invalid", "The downstream returned malformed or unsafe input requests.");
+}
+/** Capture opaque state before any result redaction or unwrapping can alter it. */
+export async function captureDownstreamInput(scope, connector, address, raw, secrets) {
+    if (!withinBudget(raw))
+        throw new ConnectorCallError("input_required_limit", "The downstream input payload exceeds 64 KiB.");
+    if (!stateObject(raw) ||
+        (raw.requestState !== undefined && typeof raw.requestState !== "string") ||
+        (raw.inputRequests !== undefined && !stateObject(raw.inputRequests)) ||
+        (raw.requestState === undefined && raw.inputRequests === undefined))
+        return invalidInput();
+    const entries = Object.entries(raw.inputRequests ?? {});
+    if (!entries.length && raw.requestState === undefined)
+        return invalidInput();
+    if (entries.length > MAX_REQUESTS)
+        throw new ConnectorCallError("input_required_limit", "The downstream requested more than 16 inputs.");
+    const inputRequests = Object.create(null);
+    const inputs = Object.create(null);
+    const elicitation = downstreamInputCapabilities(scope).elicitation;
+    for (const [index, [key, request]] of entries.entries()) {
+        if (!key || key.length > 256 || !stateObject(request))
+            return invalidInput();
+        if (request.method !== "elicitation/create") {
+            throw new ConnectorCallError("input_required_unsupported", "Connecta relays downstream form and URL elicitation only.");
+        }
+        if (!stateObject(request.params))
+            return invalidInput();
+        const params = request.params;
+        const mode = params.mode ?? "form";
+        if (mode !== "form" && mode !== "url")
+            return invalidInput();
+        if (!elicitation?.[mode])
+            throw new ConnectorCallError("input_required_unsupported", "The client did not declare support for the downstream elicitation kind.");
+        if (mode === "url") {
+            if (typeof params.message !== "string" || typeof params.url !== "string")
+                return invalidInput();
+            try {
+                const url = new URL(params.url);
+                // An opaque downstream nonce is retained. Credentials are never put
+                // in browser URLs; refusal preserves semantics instead of rewriting it.
+                if (url.protocol !== "https:" ||
+                    url.username ||
+                    url.password ||
+                    [...params.url].some((char) => char.charCodeAt(0) <= 0x20 || char.charCodeAt(0) === 0x7f) ||
+                    secrets.containsUrl(params.url) ||
+                    secrets.redact(params.url) !== params.url)
+                    return invalidInput();
+            }
+            catch {
+                return invalidInput();
+            }
+            inputRequests[namespace(connector, index)] = inputRequired.elicitUrl({
+                message: `Downstream ${connector}: ${params.message}`,
+                url: params.url,
+            });
+        }
+        else {
+            const parsed = await specTypeSchemas.ElicitRequestFormParams["~standard"].validate(params);
+            if (parsed.issues)
+                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 (secrets.redact(parsed.value.requestedSchema) !== parsed.value.requestedSchema)
+                return invalidInput();
+            inputRequests[namespace(connector, index)] = inputRequired.elicit({
+                message: `Downstream ${connector}: ${parsed.value.message}`,
+                requestedSchema: parsed.value.requestedSchema,
+            });
+        }
+        inputs[namespace(connector, index)] = { key, mode };
+    }
+    // Opaque state is private even when a downstream echoes it in a prompt,
+    // URL, or schema. Keep the continuation intact and refuse the public prompt.
+    assertDownstreamOutputSafe(scope, inputRequests);
+    assertNoPrivateStateEchoes(inputRequests, raw.requestState !== undefined ? [raw.requestState] : []);
+    if (pendingInputs.has(scope))
+        return invalidInput();
+    pendingInputs.set(scope, {
+        connector,
+        address,
+        ...(raw.requestState !== undefined ? { requestState: raw.requestState } : {}),
+        inputRequests,
+        inputs,
+    });
+}
+function failure(code, message) {
+    const structuredContent = { ok: false, error: { code, message, retryable: false } };
+    return { content: [{ type: "text", text: JSON.stringify(structuredContent) }], structuredContent, isError: true };
+}
+/** MCP-only continuation coordination. No downstream prompt enters operator records. */
+export class DownstreamElicitation {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    bind(context) {
+        const envelope = context.mcpReq.envelope;
+        const declared = envelope?.[CLIENT_CAPABILITIES_META_KEY];
+        const elicitation = stateObject(declared) ? declared.elicitation : undefined;
+        const modern = envelope?.[PROTOCOL_VERSION_META_KEY] === "2026-07-28";
+        if (modern)
+            modernRequests.add(this.options.requestScope);
+        else
+            modernRequests.delete(this.options.requestScope);
+        bindDownstreamCapabilities(this.options.requestScope, modern && stateObject(elicitation)
+            ? {
+                elicitation: {
+                    ...(stateObject(elicitation.form) || Object.keys(elicitation).length === 0 ? { form: {} } : {}),
+                    ...(stateObject(elicitation.url) ? { url: {} } : {}),
+                },
+            }
+            : {});
+    }
+    async verify(wrapper, context) {
+        const { vault, registry, principal, endpoint } = this.options;
+        if (!vault?.open ||
+            !principal ||
+            typeof wrapper.connector !== "string" ||
+            !registry.getConnector(wrapper.connector) ||
+            typeof wrapper.sealed !== "string" ||
+            wrapper.sealed.length > MAX_RELAY_STATE_CHARS)
+            return invalidRequestState();
+        let state;
+        try {
+            state = JSON.parse(await vault.open(wrapper.connector, PURPOSE, wrapper.sealed));
+        }
+        catch {
+            return invalidRequestState();
+        }
+        if (!stateObject(state) ||
+            state.version !== 2 ||
+            state.kind !== "downstream" ||
+            state.principal !== principal ||
+            state.endpoint !== endpoint ||
+            state.connector !== wrapper.connector ||
+            typeof state.address !== "string" ||
+            typeof state.target !== "string" ||
+            !state.target.startsWith(`${state.connector}.`) ||
+            !["call_tool", "call_destructive_tool"].includes(String(state.tool)) ||
+            typeof state.digest !== "string" ||
+            !/^[a-f0-9]{64}$/.test(state.digest) ||
+            !Number.isSafeInteger(state.expiresAt) ||
+            state.expiresAt <= Date.now() ||
+            state.expiresAt > Date.now() + REQUEST_STATE_TTL_MS ||
+            !Number.isInteger(state.round) ||
+            state.round < 1 ||
+            state.round > MAX_INPUT_ROUNDS ||
+            typeof state.nonce !== "string" ||
+            !/^[a-f0-9-]{36}$/.test(state.nonce) ||
+            (state.requestState !== undefined && typeof state.requestState !== "string") ||
+            !Array.isArray(state.previousStates) ||
+            state.previousStates.length >= state.round ||
+            !state.previousStates.every((value) => typeof value === "string") ||
+            !withinBudget([...state.previousStates, ...(state.requestState !== undefined ? [state.requestState] : [])]) ||
+            !stateObject(state.inputs) ||
+            Object.keys(state.inputs).length > MAX_REQUESTS ||
+            !Object.entries(state.inputs).every(([wireKey, binding], index) => wireKey === namespace(wrapper.connector, index) &&
+                stateObject(binding) &&
+                typeof binding.key === "string" &&
+                binding.key.length > 0 &&
+                binding.key.length <= 256 &&
+                (binding.mode === "url" || binding.mode === "form")) ||
+            context.mcpReq.method !== "tools/call" ||
+            context.http?.req?.headers.get("Mcp-Name") !== state.tool)
+            return invalidRequestState();
+        return state;
+    }
+    async resume(state, tool, args, context, operation) {
+        if (state.tool !== tool || state.address !== args.address || state.digest !== (await requestDigest(tool, args)))
+            return failure("invalid_request_state", "Invalid or expired requestState");
+        const responses = Object.create(null);
+        const elicitation = downstreamInputCapabilities(this.options.requestScope).elicitation;
+        for (const [wireKey, { key, mode }] of Object.entries(state.inputs)) {
+            if (!elicitation?.[mode])
+                return failure("input_required_unsupported", "The client did not declare support for this continuation's input kind.");
+            const response = context.mcpReq.inputResponses?.[wireKey];
+            if (response === undefined)
+                continue;
+            const parsed = await specTypeSchemas.ElicitResult["~standard"].validate(response);
+            if (parsed.issues)
+                throw new ProtocolError(INVALID_PARAMS, "Invalid downstream input response", {
+                    reason: "invalid_input_response",
+                });
+            // URL acknowledgements and decline/cancel never carry form data.
+            responses[key] =
+                mode === "url" || parsed.value.action !== "accept" ? { action: parsed.value.action } : parsed.value;
+        }
+        if (!withinBudget(responses))
+            throw new ProtocolError(INVALID_PARAMS, "Input responses exceed 64 KiB", { reason: "invalid_input_response" });
+        const storage = this.options.registry.contextFor(state.connector, this.options.endpoint, this.options.requestScope).storage;
+        // Claim before any downstream dispatch, including decline/cancel. A failed
+        // or ambiguous continuation must not leave a reusable write permission.
+        if (!(await storage.compareAndSet(inputRetryKeys.used(state.nonce), null, "used", {
+            ttlSeconds: REQUEST_STATE_TTL_MS / 1000,
+        })))
+            return invalidRequestState();
+        bindDownstreamContinuation(this.options.requestScope, {
+            connector: state.connector,
+            address: state.target,
+            write: state.tool === "call_destructive_tool",
+            privateStates: [...state.previousStates, ...(state.requestState !== undefined ? [state.requestState] : [])],
+            input: {
+                ...(state.requestState !== undefined ? { requestState: state.requestState } : {}),
+                inputResponses: responses,
+            },
+        });
+        try {
+            const result = await this.finish(tool, args, context, await operation(), state);
+            if (!result.isError || !stateObject(result.structuredContent))
+                return result;
+            const error = result.structuredContent.error;
+            if (!stateObject(error))
+                return result;
+            // The nonce is spent even when the downstream failure would normally
+            // allow a retry. Preserve write reconciliation and auth prerequisites.
+            const echoed = downstreamArgumentEcho(this.options.requestScope);
+            const structuredContent = {
+                ...result.structuredContent,
+                error: {
+                    ...error,
+                    retryable: false,
+                    ...(state.tool === "call_tool" && error.nextAction === undefined && error.retry === undefined
+                        ? {
+                            nextAction: {
+                                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." +
+                                    (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."
+                                            : ""),
+                            },
+                        }
+                        : {}),
+                },
+            };
+            return { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+        }
+        finally {
+            clearDownstreamContinuation(this.options.requestScope);
+        }
+    }
+    async finish(tool, args, context, result, previous) {
+        const scope = this.options.requestScope;
+        const pending = pendingInputs.get(scope);
+        pendingInputs.delete(scope);
+        if (!pending)
+            return result;
+        const { vault, principal, endpoint } = this.options;
+        if (!modernRequests.has(scope) ||
+            !vault?.requestStateKey ||
+            !vault.seal ||
+            !vault.open ||
+            !principal ||
+            !["call_tool", "call_destructive_tool"].includes(tool))
+            return failure("input_required_unsupported", "Downstream input requires an authenticated direct call and a sealing vault.");
+        if ((previous?.round ?? 0) >= MAX_INPUT_ROUNDS)
+            return failure("input_required_round_limit", "The downstream still requires input after three rounds. Start a new direct request.");
+        const previousStates = [
+            ...new Set([
+                ...(previous?.previousStates ?? []),
+                ...(previous?.requestState !== undefined ? [previous.requestState] : []),
+            ]),
+        ].filter((value) => value !== pending.requestState);
+        if (!withinBudget([...previousStates, ...(pending.requestState !== undefined ? [pending.requestState] : [])])) {
+            return failure("input_required_limit", "The downstream private state history exceeds 64 KiB.");
+        }
+        const state = {
+            version: 2,
+            kind: "downstream",
+            principal,
+            endpoint,
+            connector: pending.connector,
+            address: String(args.address),
+            target: pending.address,
+            tool: tool,
+            digest: await requestDigest(tool, args),
+            round: (previous?.round ?? 0) + 1,
+            expiresAt: previous?.expiresAt ?? Date.now() + REQUEST_STATE_TTL_MS,
+            nonce: crypto.randomUUID(),
+            ...(pending.requestState !== undefined ? { requestState: pending.requestState } : {}),
+            previousStates,
+            inputs: pending.inputs,
+        };
+        const requestState = await this.options.mint({
+            version: 2,
+            kind: "downstream",
+            connector: pending.connector,
+            sealed: await vault.seal(pending.connector, PURPOSE, JSON.stringify(state)),
+        }, context);
+        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.
+        // 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,3 +1,5 @@
+import type { ExecutorAdmissionErrorCode } from "./executor-admission.js";
+import type { JsonSchema } from "./types.js";
 /**
  * Machine-readable classification of a failed connector tool call.
  *
@@ -5,7 +7,7 @@
  * naming a cause — the rule provider conventions call H11, defined in
  * `test/provider-conventions.test.ts`.
  */
-export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
+export type ConnectorCallErrorCode = "timeout" | "auth_required" | "downstream_oauth_required" | "oauth_revocation_failed" | "provider_permission_denied" | "rate_limited" | "unavailable" | "invalid_args"
 /**
  * Provider-owned absence: the caller re-addresses rather than waiting,
  * re-authorizing, or repairing arguments, and a program looping over ids can
@@ -22,7 +24,18 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited
  * change, and retries with the base `current` reports — repeating the same
  * call can never succeed, and waiting will not help either.
  */
- | "conflict" | "input_required_unsupported" | "connector_call_failed";
+ | "conflict" | "resource_template_ambiguous" | "resource_match_budget_exceeded" | "input_required_unsupported" | "input_required_invalid" | "input_required_limit" | "connector_call_failed";
+/**
+ * Every classification code connecta assigns: a connector's typed codes, the
+ * executor's admission codes, and the refusals connecta frames itself.
+ * Operator records and activity rows carry a code only when it is one of
+ * these (INV-6), so a code forwarded from a downstream is never recorded.
+ * Adding a member fails typecheck until {@link CLASSIFICATION_CODE_TABLE}
+ * lists it.
+ */
+export type ClassificationCode = ConnectorCallErrorCode | ExecutorAdmissionErrorCode | "cancelled" | "unknown_address" | "unknown_tool" | "ambiguous_tool_alias" | "catalog_lookup_failed" | "result_too_large" | "destructive_tool_requires_approval" | "auth_replay_refused" | "write_outcome_unknown" | "result_processing_failed" | "budget_exceeded" | "executor_failed" | "program_error";
+/** `value` when it is a code connecta assigns, else undefined. */
+export declare function classificationCode(value: unknown): ClassificationCode | undefined;
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */
@@ -37,6 +50,26 @@ export interface ArgumentValidationDetails {
     /** More findings existed but were omitted from the bounded response. */
     truncated?: true;
 }
+/** Agent-only facts from the published schema, never operator record fields. */
+export interface ArgumentRepairDetails {
+    acceptedKeys?: string[];
+    issues: Array<{
+        path: string;
+        receivedType: string;
+        acceptedKeys?: string[];
+        enumValues?: unknown[];
+        bounds?: Record<string, number>;
+    }>;
+    conditionalRequirements?: Array<{
+        path: string;
+        condition: unknown;
+        required: string[];
+    }>;
+    /** Synthesized from the schema and checked by the same validator. */
+    example?: unknown;
+    exampleUnavailable?: string;
+    truncated?: true;
+}
 export declare const MAX_ARGUMENT_VALIDATION_ISSUES = 3;
 /**
  * Clamp a string to a UTF-8 byte budget, appending `…` when it clipped.
@@ -45,33 +78,72 @@ 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 {
+    /** Guest program diagnostics; returned to the agent, never operator records. */
+    name?: string;
+    line?: number | null;
+    hint?: string;
+    /** Host-measured call deadline diagnostics; operation may contain caller text. */
+    operation?: string;
+    stage?: string;
+    elapsedMs?: number;
+    deadlineMs?: number;
     /** HTTP(S) origin only, at most 253 UTF-8 bytes. */
     host?: string;
     /** Validated network errno or `timeout`, at most 32 bytes. */
     code?: string;
 }
+/** The network errnos `networkErrorCode` reports, and `timeout`. */
+export declare const NETWORK_ERROR_CODES: ReadonlySet<string>;
 /** Runtime fields only: provider prose cannot supply an errno or a deadline. */
 export declare function networkErrorCode(error: unknown): string | undefined;
-/** Use at a fetch boundary where the destination and transport failure are known. */
-export declare function unavailableCallError(cause: unknown, host?: string, message?: string): ConnectorCallError;
-/** Agent-visible recovery class attached only to `auth_required` failures. */
+/**
+ * Use at a fetch boundary where the destination and transport failure are
+ * known. The runtime's error is read for its errno and dropped, never kept as
+ * `cause`: its message and cause chain can quote the URL, headers, or body of
+ * the request that failed, and a logger that renders an error renders its
+ * cause. The origin and errno in `details` are what survives.
+ *
+ * The one failure kept is the request's own abort reason, when that is what
+ * the fetch rejected with: the caller wrote it, not the downstream, and it is
+ * how a cancelled request tells its reason from a network failure.
+ */
+export declare function unavailableCallError(failure: unknown, host?: string, message?: string, signal?: AbortSignal): ConnectorCallError;
+/**
+ * A failure told in connecta's words because the original's text came from a
+ * downstream or authorization server, which can echo what the request carried
+ * or plant whatever it likes. There is no `cause`: the original is dropped
+ * whole, never masked.
+ *
+ * It is classified exactly as the original would have been. That verdict is
+ * read from the original once, here, and kept as two flags, so withholding
+ * the text moves no failure between `timeout`, retryable, and the caller's
+ * fallback code. Never wrap a `ConnectorCallError`: it already speaks in
+ * connecta's words and carries its own code.
+ */
+export declare class WithheldTextError extends Error {
+    /** The original read as a timeout. */
+    readonly timeout: boolean;
+    readonly retryable: boolean;
+    constructor(message: string, original: unknown);
+}
+/** Agent-visible recovery class for downstream credential failures. */
 export type AuthRecoveryMode = "oauth" | "operator_config" | "unavailable";
 /**
  * Throw from `Connector.callTool` (or anything beneath it) to classify a
- * failure exactly. Untyped errors fall back to a message-text heuristic, so a
- * connector whose legitimate error text mentions "timeout" is misread as a
- * retryable timeout — this class is the escape hatch. `retryable` defaults per
+ * failure exactly. Untyped errors are non-retryable unless a runtime errno
+ * or abort identifies a transport failure. This class supplies the connector's
+ * reviewed verdict. `retryable` defaults per
  * code (timeout, rate_limited, and unavailable retry; the rest do not) and may
  * be overridden.
  *
@@ -93,6 +165,7 @@ export declare class ConnectorCallError extends Error {
     readonly retryAfterMs: number | undefined;
     /** Bounded schema findings for `invalid_args`; never submitted values. */
     readonly validation: ArgumentValidationDetails | undefined;
+    readonly repair: ArgumentRepairDetails | undefined;
     /** Sanitized transport diagnostics for `unavailable` only. */
     readonly details: UnavailableDetails | undefined;
     /**
@@ -105,12 +178,30 @@ export declare class ConnectorCallError extends Error {
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
+        repair?: ArgumentRepairDetails;
         details?: UnavailableDetails;
         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;
@@ -120,6 +211,7 @@ export interface CallErrorDetails {
     retryAfterMs?: number;
     /** Bounded input-schema findings; paths and expectations, never values. */
     validation?: ArgumentValidationDetails;
+    repair?: ArgumentRepairDetails;
     /** On a `conflict`: where each thing the write touched stands now. */
     current?: Readonly<Record<string, number>>;
     /** Connector whose failed operation needs recovery. */
@@ -128,6 +220,8 @@ export interface CallErrorDetails {
     operation?: string;
     /** Which safe recovery path `authorize_connector` will return. */
     recovery?: AuthRecoveryMode;
+    /** An auth failure followed a write's downstream send. Reconcile before retry. */
+    reconciliationRequired?: true;
     /** The single model-facing entry point for every credential class. */
     nextAction?: {
         tool: "authorize_connector";
@@ -144,16 +238,17 @@ export interface CallErrorDetails {
         };
         purpose: string;
     } | {
-        tool: "call_destructive_tool";
+        tool: "call_tool" | "call_destructive_tool";
         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;
     } | {
@@ -175,19 +270,25 @@ export interface CallErrorDetails {
         addresses: string[];
         purpose: string;
     };
+    /** Configured connectors in this request's registry view only. */
+    configuredConnectors?: string[];
+    /**
+     * 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;
+    };
     /** Explicit retry guidance; recovery never retries or mutates by itself. */
     retry?: string;
 }
-/**
- * Details for a failure connecta itself framed — an address it could not
- * resolve, a tool it refuses to run — rather than one a connector threw.
- */
-export declare function framingError(code: string, message: string): CallErrorDetails;
-/**
- * Classify a value thrown by a connector call. A `ConnectorCallError` is
- * authoritative; anything else falls back to the historical message-text
- * heuristic.
- */
-export declare function classifyCallError(err: unknown, fallbackCode?: string): CallErrorDetails;
+/** Retryability of connecta framing depends only on its code. */
+export declare function framingError(code: ClassificationCode, message: string): CallErrorDetails;
+/** Typed connector verdicts and runtime facts only. Prose never changes a verdict. */
+export declare function classifyCallError(err: unknown, fallbackCode?: ClassificationCode): CallErrorDetails;
 export declare function msg(err: unknown): string;
 export {};