@zackbart/connecta 0.28.1 → 0.30.0

package/dist/invocation-auth.js

@@ -0,0 +1,69 @@
+import { vettedSchemaDigest } from "./catalog-drift.js";
+// Only built-in factories register local credential checks. This hook is not
+// part of Connector, and a replacement callTool cannot inherit its proof.
+const checks = new WeakMap();
+export function registerInvocationAuth(connector, check) {
+    checks.set(connector, { callTool: connector.callTool, check });
+}
+/** Local credential resolution only, before entering any connector call. */
+export async function resolveInvocationAuth(connector, ctx) {
+    const entry = checks.get(connector);
+    if (entry?.callTool === connector.callTool)
+        await entry.check(ctx);
+}
+const requests = new WeakMap();
+function requestFor(scope) {
+    let facts = requests.get(scope);
+    if (!facts) {
+        facts = { entered: [], authFailures: new Map(), retryReads: new Map() };
+        requests.set(scope, facts);
+    }
+    return facts;
+}
+/** Bind the verdict, annotation facts and schemas used for this call. */
+export async function classificationDigest(definition) {
+    try {
+        const schema = await vettedSchemaDigest(definition);
+        const annotations = Object.entries(definition.annotations ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const bytes = new TextEncoder().encode(JSON.stringify({ classification: definition.classification, annotations, schema }));
+        return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    catch {
+        // A digest refusal blocks recovery, not an ordinary call.
+        return "";
+    }
+}
+/** Called by the host immediately before callTool, using its private scope. */
+export function recordCallEntry(scope, call, definition) {
+    // Snapshot synchronously. Recovery hashes this private copy only when it
+    // needs a replay binding, without changing ordinary admission or completion.
+    requestFor(scope).entered.push({ ...call, definition: structuredClone(definition) });
+}
+export function bindReplayReads(scope, reads) {
+    requestFor(scope).retryReads = new Map(reads.map((read) => [read.address, read.digest]));
+}
+export function replayClassificationDigest(scope, address) {
+    return requestFor(scope).retryReads.get(address);
+}
+/** Eligibility comes from invocation control flow, never error fields. */
+export function recordAuthFailure(scope, connector, eligible) {
+    const failures = requestFor(scope).authFailures;
+    failures.set(connector, eligible && failures.get(connector) !== false);
+}
+export async function authRecoveryFacts(scope, connector) {
+    const facts = requestFor(scope);
+    const writeEntered = facts.entered.some((call) => call.classification === "write");
+    const reads = new Map();
+    let unsafeEntered = writeEntered;
+    for (const call of facts.entered) {
+        const digest = await classificationDigest(call.definition);
+        unsafeEntered ||= !call.fresh || !digest || (reads.has(call.address) && reads.get(call.address) !== digest);
+        reads.set(call.address, digest);
+    }
+    return {
+        writeEntered,
+        unsafeEntered,
+        eligible: !unsafeEntered && facts.authFailures.get(connector) === true,
+        reads: [...reads].map(([address, digest]) => ({ address, digest })),
+    };
+}

package/dist/invocation.js

@@ -1,11 +1,17 @@
+import { withAuthorizationHandoff } from "./authorization-handoff.js";
+import { hasControlCharacters } from "./tool-name.js";
+import { surfaceAllowsTool } from "./tool-safety.js";
 import { Cause, Effect, Exit } from "effect";
-import { isCallAdmissionError, } from "./call-admission.js";
-import { boundedEchoText, classifyCallError, ConnectorCallError, echoedCallArgs, framingError, } from "./errors.js";
-import { unwrapMcpResult } from "./mcp-result.js";
+import { isCallAdmissionError } from "./call-admission.js";
+import { boundedEchoText, classificationCode, classifyCallError, ConnectorCallError, echoedCallArgs, framingError, } from "./errors.js";
+import { downstreamValue } from "./mcp-result.js";
+import { carryFailureFacts, classifiedFailure, failureRecord, logFailure, recordedToolName, } from "./operator-record.js";
 import { splitAddress } from "./registry.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
-import { validateToolInput } from "./validate.js";
+import { validateCatalogToolInput } from "./validate.js";
+import { sentSecretsFor, sentSecretsForRequest, trackCredentialReads } from "./sent-secrets.js";
+import { classificationDigest, recordAuthFailure, recordCallEntry, replayClassificationDigest, resolveInvocationAuth, } from "./invocation-auth.js";
+import { downstreamContinuation, recordDownstreamArgumentEcho, isDownstreamInputResult, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
 function defined(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
@@ -38,8 +44,7 @@ function admitted(registry, target, args, signal) {
             args: args ?? {},
             ...defined({ signal }),
         });
-        return Effect.tryPromise({ try: () => pending, catch: (error) => error })
-            .pipe(Effect.onInterrupt(() => Effect.sync(() => {
+        return Effect.tryPromise({ try: () => pending, catch: (error) => error }).pipe(Effect.onInterrupt(() => Effect.sync(() => {
             pending.then((permit) => permit.release(), () => { });
         })));
     }), (permit) => Effect.sync(() => permit.release()), { interruptible: true });
@@ -54,23 +59,29 @@ function callerCancelledDetails() {
 function recoveryMode(registry, connector, baseUrl) {
     if (connector.startAuth)
         return "oauth";
-    if (registry.credentialUiAvailable() && connector.credential &&
+    if (registry.credentialUiAvailable() &&
+        connector.credential &&
         registry.contextFor(connector.id, baseUrl).credential) {
         return "operator_config";
     }
     return "unavailable";
 }
 function isCallerCancellation(error, signal) {
-    return (signal?.aborted === true ||
-        (isCallAdmissionError(error) && error.admissionKind === "cancelled"));
+    return signal?.aborted === true || (isCallAdmissionError(error) && error.admissionKind === "cancelled");
 }
 /**
  * A downstream MCP tool answered with `isError`. Classified exactly as the
- * plain `Error` it used to be — same message, same heuristics — and marked so
+ * plain `Error`: untyped, non-retryable, and marked so
  * a write's outcome can tell "the service said no" from "nobody answered".
  */
 class DownstreamToolError extends Error {
 }
+function isTimeoutFailure(error) {
+    const code = error.details?.code;
+    return (error.code === "timeout" ||
+        (error.code === "unavailable" &&
+            (code === "timeout" || code === "ETIMEDOUT" || code?.endsWith("_TIMEOUT") === true)));
+}
 function assertRawMcpSuccess(kind, result) {
     if (kind !== "mcp" || result == null || typeof result !== "object")
         return;
@@ -101,6 +112,7 @@ export class InvocationFailure extends Error {
     recovery;
     nextAction;
     retry;
+    data;
     constructor(details) {
         super(details.message);
         this.details = details;
@@ -113,6 +125,7 @@ export class InvocationFailure extends Error {
         this.recovery = details.recovery;
         this.nextAction = details.nextAction;
         this.retry = details.retry;
+        this.data = details;
     }
 }
 /**
@@ -145,13 +158,18 @@ export class InvocationService {
     pipeline(address, args, context) {
         return Effect.gen({ self: this }, function* () {
             const started = Date.now();
+            let argumentEcho = {};
             let catalogMs = 0;
             let admissionMs = 0;
             let connectorMs = 0;
             let resultProcessingMs = 0;
             let attempts = 0;
+            let resultBytes;
             let dispatchedToConnector = false;
+            let preInvocationAuthFailure = false;
             let answered = false;
+            const sentSecrets = sentSecretsForRequest(this.catalog.requestScope);
+            context.sentSecrets?.include(sentSecrets);
             // A write gate's refusal that is no attempt; see WriteGateDecision.
             let unrecorded = false;
             let resolved;
@@ -171,20 +189,26 @@ export class InvocationService {
                 const identity = activityTarget
                     ? {
                         connectorId: activityTarget.connector.id,
-                        toolName: activityTarget.toolName,
+                        // A resolved tool's name is the downstream's choice, recorded
+                        // only when it fits the tool-name grammar (INV-6).
+                        toolName: resolved ? recordedToolName(resolved.definition) : activityTarget.toolName,
                     }
                     : attempted;
                 if (!identity)
                     return;
+                const toolName = hasControlCharacters(identity.toolName) ? "<unlisted>" : identity.toolName;
                 this.activity?.recordTool?.(this.activity, {
                     connectorId: identity.connectorId,
-                    toolName: identity.toolName,
-                    address: `${identity.connectorId}.${identity.toolName}`,
+                    toolName,
+                    address: `${identity.connectorId}.${toolName}`,
                     source: context.source,
                     outcome,
+                    ...(activityTarget?.connector.authScope === "personal" ? { personal: true } : {}),
                     durationMs: Date.now() - started,
                     attempts,
                     ...defined({
+                        classification: resolved?.definition.classification,
+                        resultBytes,
                         errorCode: classification.errorCode,
                         friction: classification.friction,
                     }),
@@ -193,9 +217,51 @@ export class InvocationService {
             const enrich = (error, target) => {
                 if (!target)
                     return error;
+                if (isTimeoutFailure(error) && dispatchedToConnector && resolved?.definition.classification === "write") {
+                    const echoed = argumentEcho;
+                    return {
+                        ...error,
+                        code: "write_outcome_unknown",
+                        message: `${error.message} Its outcome is unknown. Check the target before repeating this call.`,
+                        retryable: false,
+                        connector: target.connector.id,
+                        operation: `${target.connector.id}.${target.toolName}`,
+                        uncertainCall: {
+                            address: `${target.connector.id}.${target.toolName}`,
+                            ...echoed,
+                            ...("args" in echoed ? {} : { argsOmitted: true }),
+                        },
+                        retry: "Do not retry automatically. Check whether the write took effect first." +
+                            (echoed.argsRedacted
+                                ? " Sensitive fields are omitted; use the original arguments if reconciliation requires another call."
+                                : "args" in echoed
+                                    ? ""
+                                    : " The arguments could not be echoed safely; use the exact arguments you sent."),
+                    };
+                }
+                if (error.code === "auth_required" && target.connector.startAuth) {
+                    error = { ...error, code: "downstream_oauth_required" };
+                }
+                const enteredWrite = resolved?.definition.classification === "write" && dispatchedToConnector;
                 switch (error.code) {
+                    case "input_required_unsupported":
+                        if (context.processInputRequired)
+                            return error;
+                        return {
+                            ...error,
+                            nextAction: {
+                                tool: resolved?.definition.classification === "read" ? "call_tool" : "call_destructive_tool",
+                                arguments: { address: `${target.connector.id}.${target.toolName}`, ...argumentEcho },
+                                purpose: "Use this direct call so the host can fulfill the downstream input request." +
+                                    (argumentEcho.argsRedacted
+                                        ? " Re-send the original arguments; sensitive fields are omitted."
+                                        : "args" in argumentEcho
+                                            ? ""
+                                            : " Re-send the original arguments; they could not be echoed safely."),
+                            },
+                        };
                     case "destructive_tool_requires_approval": {
-                        const echoed = echoedCallArgs(args);
+                        const echoed = argumentEcho;
                         return {
                             ...error,
                             nextAction: {
@@ -205,25 +271,37 @@ export class InvocationService {
                                     ...echoed,
                                 },
                                 purpose: "Ask the MCP host to approve this consequential call. " +
-                                    ("args" in echoed
-                                        ? "Re-send these arguments and add a short reason for the human reviewer."
-                                        : "Re-send the arguments you just sent — they are too large to echo back — and add a short reason for the human reviewer."),
+                                    (echoed.argsRedacted
+                                        ? "Re-send the original arguments; sensitive fields are omitted from this hint. Add a short reason for the human reviewer."
+                                        : "args" in echoed
+                                            ? "Re-send these arguments and add a short reason for the human reviewer."
+                                            : "Re-send the arguments you just sent; they could not be echoed safely. Add a short reason for the human reviewer."),
                             },
                         };
                     }
                     case "auth_required":
+                    case "downstream_oauth_required":
                         return {
                             ...error,
                             connector: target.connector.id,
                             operation: `${target.connector.id}.${target.toolName}`,
                             recovery: recoveryMode(this.registry, target.connector, this.catalog.baseUrl),
+                            ...(enteredWrite ? { reconciliationRequired: true, retryable: false } : {}),
                             nextAction: {
                                 tool: "authorize_connector",
                                 arguments: { connector: target.connector.id },
                                 operatorHandoff: "Give the URL and instructions it returns to the operator.",
                             },
-                            retry: `Retry ${target.connector.id}.${target.toolName} after ` +
-                                "the operator completes recovery.",
+                            retry: enteredWrite
+                                ? "This write may have partially run. Reconcile its target before retrying after the operator completes recovery."
+                                : `Retry ${target.connector.id}.${target.toolName} after the operator completes recovery.`,
+                        };
+                    case "provider_permission_denied":
+                        return {
+                            ...error,
+                            connector: target.connector.id,
+                            operation: `${target.connector.id}.${target.toolName}`,
+                            retry: "Ask the provider's resource owner or administrator to grant the required permission or scope, then retry. Repeating the call or reconnecting alone will not grant access.",
                         };
                     case "invalid_args":
                         if (!error.validation)
@@ -236,17 +314,33 @@ export class InvocationService {
                                 query: target.toolName,
                                 connector: target.connector.id,
                             }, "Inspect the current input shape if the validation findings are not sufficient."),
-                            retry: `Correct the listed arguments and retry ` +
-                                `${target.connector.id}.${target.toolName}.`,
+                            retry: `Correct the listed arguments and retry ` + `${target.connector.id}.${target.toolName}.`,
                         };
                     default:
                         return error;
                 }
             };
+            let stage = "catalog";
             const failed = (error) => {
                 const diagnostics = timing();
                 const target = resolved ?? activityTarget;
-                const details = enrich(error, target);
+                if (target && (error.code === "auth_required" || error.code === "downstream_oauth_required")) {
+                    recordAuthFailure(this.catalog.requestScope, target.connector.id, (resolved?.definition.classification === "read" && resolved.classificationFresh === true) ||
+                        preInvocationAuthFailure ||
+                        (!resolved && context.source === "call_tool"));
+                }
+                // Attach host deadline facts before write recovery changes the code.
+                if (isTimeoutFailure(error)) {
+                    const elapsedMs = Date.now() - started;
+                    const operation = boundedEchoText(address, 512);
+                    error = {
+                        ...error,
+                        message: `Operation "${operation}" timed out during ${stage} after ${elapsedMs}ms (effective deadline ${context.timeoutMs}ms).`,
+                        details: { ...error.details, operation, stage, elapsedMs, ...defined({ deadlineMs: context.timeoutMs }) },
+                    };
+                }
+                // Downstream diagnostics were redacted under payload rules where they entered.
+                const details = sentSecrets.redact(enrich(error, target), "envelope");
                 const outcome = () => ({
                     ok: false,
                     durationMs: Date.now() - started,
@@ -261,47 +355,50 @@ export class InvocationService {
                 // leaves no event and nothing in the operator's log.
                 if (unrecorded)
                     return outcome();
-                // Activity rows stay payload-free by construction; the operator's log is
-                // where the downstream reason goes, bounded and without arguments.
+                // Activity rows and this log line are both payload-free by
+                // construction: the line is the failure's typed record, never its
+                // message, which may be the downstream's own words (INV-6).
                 if (target && details.code !== "destructive_tool_requires_approval") {
-                    this.registry
-                        .contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope)
-                        .logger.warn("[connecta] call failed", {
+                    logFailure(this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope).logger, "call failed", failureRecord({
                         connector: target.connector.id,
-                        tool: target.toolName,
+                        // Named only when the catalog listed it (src/operator-record.ts).
+                        tool: resolved?.definition,
                         source: context.source,
-                        code: details.code,
-                        // Sanitized transport diagnostics (origin and errno only, #539).
-                        ...(details.details ? { details: details.details } : {}),
                         attempts,
                         durationMs: Date.now() - started,
-                        message: String(details.message ?? "").slice(0, 300),
-                    });
+                        // Every refusal reaching `failed` is one connecta built: a
+                        // thrown value's classification, a framing refusal, or a
+                        // cancellation. Nothing else is read as a classification.
+                    }, classifiedFailure(error)));
                 }
-                record(details.code === "timeout"
-                    ? "timeout"
-                    : details.code === "cancelled"
-                        ? "cancelled"
-                        : "error", { errorCode: details.code });
+                record(details.code === "timeout" ? "timeout" : details.code === "cancelled" ? "cancelled" : "error", defined({ errorCode: classificationCode(details.code) }));
                 return outcome();
             };
-            if (context.requestSignal?.aborted) {
+            if (context.requestSignal?.aborted || context.dispatchSignal?.aborted) {
                 // Preserve the cancelled admission-attempt count without starting discovery.
                 attempts = 1;
                 return failed(callerCancelledDetails());
             }
             let result;
+            let rawResult;
+            let inputRequiredValue;
             let observedResult;
+            let valueFormat = "json";
             // Everything up to the downstream result: resolution, the safety and
             // schema refusals, admission, and the one attempt. A refusal is its
             // success value. Its failure is an abort reason or something nobody
             // expected, and a throw anywhere in it — a defect, to Effect — is
             // classified like a failure, as the async body this replaced did.
             const dispatch = (callSignal) => Effect.gen({ self: this }, function* () {
-                const resolution = yield* this.catalog.resolve(address, defined({ signal: callSignal }));
+                const admissionSignal = context.dispatchSignal
+                    ? AbortSignal.any([context.dispatchSignal, ...(callSignal ? [callSignal] : [])])
+                    : callSignal;
+                const resolution = yield* this.catalog.resolve(address, defined({ signal: admissionSignal }));
                 catalogMs += resolution.catalogMs;
                 if (callSignal?.aborted)
                     return yield* Effect.fail(callSignal.reason);
+                if (admissionSignal?.aborted)
+                    return callerCancelledDetails();
                 if (!resolution.ok) {
                     if (resolution.connector && resolution.toolName) {
                         activityTarget = {
@@ -317,30 +414,44 @@ export class InvocationService {
                 const target = resolution.resolved;
                 resolved = target;
                 activityTarget = target;
-                const consequential = !isExplicitlyReadOnly(target.definition) && !context.allowDestructive;
-                const gate = consequential && (context.gates?.(target) ?? true)
-                    ? context.writeGate
+                argumentEcho = echoedCallArgs(args ?? {}, target.definition.inputSchema);
+                sentSecrets.arguments(args ?? {}, target.definition.inputSchema);
+                const write = target.definition.classification !== "read";
+                const canonicalAddress = `${target.connector.id}.${target.toolName}`;
+                const input = context.source !== "execute_code"
+                    ? downstreamContinuation(this.catalog.requestScope, target.connector.id, canonicalAddress)
                     : undefined;
-                if (consequential && !gate) {
+                if (input)
+                    recordDownstreamArgumentEcho(this.catalog.requestScope, argumentEcho);
+                const expectedDigest = replayClassificationDigest(this.catalog.requestScope, canonicalAddress);
+                if (expectedDigest !== undefined &&
+                    (target.classificationFresh !== true ||
+                        (yield* Effect.promise(() => classificationDigest(target.definition))) !== expectedDigest)) {
+                    return {
+                        ...framingError("auth_replay_refused", "An entered read no longer has the same fresh classification. Reconcile its target before starting a new request."),
+                        reconciliationRequired: true,
+                    };
+                }
+                if (!surfaceAllowsTool(target.definition.classification, context.source, context.trust)) {
                     const canonicalAddress = `${target.connector.id}.${target.toolName}`;
-                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is not explicitly read-only. Invoke it through call_destructive_tool so the MCP host can request explicit approval.`);
+                    return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. Invoke it through call_destructive_tool so the MCP host can request approval.`);
                 }
                 // Remote MCP tools advertise their input schema in the catalog. Validate
                 // against that same request-local definition before admission or provider
                 // dispatch, so a predictable mismatch stays structured instead of being
                 // flattened into provider-specific error prose. Unsupported schemas retain
                 // validateToolInput's fail-open behavior and reach the downstream normally.
-                if (target.connector.kind === "mcp" &&
-                    target.definition.inputSchema) {
-                    const invalid = validateToolInput(target.definition.inputSchema, args ?? {}, {
+                if (target.connector.kind === "mcp" && target.definition.inputSchema) {
+                    const invalid = validateCatalogToolInput(target.definition.inputSchema, args ?? {}, {
                         address: `${target.connector.id}.${target.toolName}`,
-                        logger: this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope).logger,
-                    });
+                        logger: this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope)
+                            .logger,
+                    }, { connector: target.connector.id, tool: target.definition });
                     if (invalid)
                         return classifyCallError(invalid);
                 }
-                if (gate) {
-                    const decision = yield* gate(target, args ?? {});
+                if (write && context.beforeWrite) {
+                    const decision = yield* context.beforeWrite(target, args ?? {});
                     if (decision.kind === "refuse") {
                         unrecorded = decision.unrecorded === true;
                         return decision.error;
@@ -349,46 +460,104 @@ export class InvocationService {
                 if (callSignal?.aborted)
                     return yield* Effect.fail(callSignal.reason);
                 attempts = 1;
-                const call = () => {
-                    const connectorContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs }));
-                    if (target.connector.credential &&
-                        !connectorContext.credential) {
-                        throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
-                            `authorize_connector({ connector: "${target.connector.id}" }).`);
+                const call = async () => {
+                    const connectorContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
+                    trackCredentialReads(connectorContext);
+                    sentSecrets.include(sentSecretsFor(connectorContext));
+                    try {
+                        if (target.connector.credential) {
+                            if (!connectorContext.credential) {
+                                throw new ConnectorCallError("auth_required", "Operator-managed credential storage is not configured. Call " +
+                                    `authorize_connector({ connector: "${target.connector.id}" }).`);
+                            }
+                            if (!(await connectorContext.credential.getAll())) {
+                                throw new ConnectorCallError("auth_required", `Connector "${target.connector.id}" has no stored credential. Call authorize_connector.`);
+                            }
+                        }
+                        await resolveInvocationAuth(target.connector, connectorContext);
+                    }
+                    catch (error) {
+                        const code = classifyCallError(error).code;
+                        preInvocationAuthFailure = code === "auth_required" || code === "downstream_oauth_required";
+                        throw error;
                     }
                     // Cancellation can arrive during admission or context construction.
-                    if (callSignal?.aborted)
-                        throw callSignal.reason;
+                    if (admissionSignal?.aborted)
+                        throw admissionSignal.reason;
                     dispatchedToConnector = true;
-                    return target.connector.callTool(target.toolName, args ?? {}, connectorContext);
+                    recordCallEntry(this.catalog.requestScope, {
+                        address: canonicalAddress,
+                        classification: write ? "write" : "read",
+                        fresh: target.classificationFresh === true,
+                    }, target.definition);
+                    return await target.connector.callTool(target.toolName, args ?? {}, connectorContext, 
+                    // The connector may retain or mutate its definition. Keep the
+                    // invocation's classification and schema private, even during
+                    // this call, and give every dispatch its own deep copy.
+                    { definition: structuredClone(target.definition), ...defined({ input }) });
                 };
                 // The permit belongs to this scope, so success, failure, and the
                 // deadline's interruption all release it. Interruption stops the
                 // wait instead of waiting for the connector, so an uncooperative one
                 // cannot hold its permit past the deadline.
                 const attempt = yield* Effect.exit(Effect.scoped(Effect.gen({ self: this }, function* () {
-                    yield* timed((elapsed) => { admissionMs += elapsed; }, admitted(this.registry, target, args, callSignal));
-                    const raw = yield* timed((elapsed) => { connectorMs += elapsed; }, Effect.tryPromise({
+                    stage = "admission";
+                    yield* timed((elapsed) => {
+                        admissionMs += elapsed;
+                    }, admitted(this.registry, target, args, admissionSignal));
+                    stage = "downstream";
+                    const reply = yield* timed((elapsed) => {
+                        connectorMs += elapsed;
+                    }, Effect.tryPromise({
                         try: () => Promise.resolve(call()),
                         catch: (error) => error,
                     }));
+                    if (target.connector.kind === "mcp" && isDownstreamInputResult(reply)) {
+                        if (!context.processInputRequired)
+                            throw new ConnectorCallError("input_required_unsupported", "The downstream returned input_required. Use the equivalent direct MCP call to provide input.");
+                        const value = yield* Effect.tryPromise({
+                            try: () => Promise.resolve(context.processInputRequired(reply, target, sentSecrets)),
+                            catch: (error) => error,
+                        });
+                        return { inputRequired: true, value };
+                    }
+                    assertDownstreamOutputSafe(this.catalog.requestScope, reply);
+                    const raw = sentSecrets.redact(reply);
                     // isError is checked here for BOTH result shapes so every adapter
                     // reports the same downstream-failure wording, and the throw lands
                     // inside the attempt where it feeds health.
                     assertRawMcpSuccess(target.connector.kind, raw);
-                    return { raw, observed: unwrapMcpResult(target.connector.kind, raw) };
+                    return { raw, observed: sentSecrets.redact(downstreamValue(target.connector.kind, raw)) };
                 })));
                 if (Exit.isFailure(attempt)) {
                     if (callSignal?.aborted)
                         return yield* Effect.fail(callSignal.reason);
+                    if (!dispatchedToConnector && admissionSignal?.aborted)
+                        return callerCancelledDetails();
                     const attemptError = Cause.squash(attempt.cause);
                     answered = answeredFailure(attemptError);
                     return isCallerCancellation(attemptError, context.requestSignal)
                         ? callerCancelledDetails()
-                        : classifyCallError(attemptError);
+                        : carryFailureFacts(attemptError, classifyCallError(sentSecrets.redact(attemptError)));
+                }
+                if ("inputRequired" in attempt.value) {
+                    inputRequiredValue = { value: attempt.value.value };
+                    return undefined;
+                }
+                observedResult = attempt.value.observed.data;
+                try {
+                    const serialized = attempt.value.observed.format === "text" && typeof observedResult === "string"
+                        ? observedResult
+                        : JSON.stringify(observedResult);
+                    if (serialized !== undefined)
+                        resultBytes = new TextEncoder().encode(serialized).byteLength;
+                }
+                catch {
+                    /* Unserializable values have no measurable byte count. */
                 }
-                observedResult = attempt.value.observed;
-                result = context.unwrapResult ? observedResult : attempt.value.raw;
+                valueFormat = attempt.value.observed.format;
+                rawResult = attempt.value.raw;
+                result = context.unwrapResult ? observedResult : rawResult;
                 return undefined;
             });
             // One deadline owns discovery, queue admission, and provider dispatch.
@@ -405,9 +574,11 @@ export class InvocationService {
                 })
                 : dispatch());
             if (Exit.isFailure(dispatched)) {
-                return failed(context.requestSignal?.aborted
+                const failure = Cause.squash(dispatched.cause);
+                const details = context.requestSignal?.aborted
                     ? callerCancelledDetails()
-                    : classifyCallError(Cause.squash(dispatched.cause)));
+                    : carryFailureFacts(failure, classifyCallError(sentSecrets.redact(failure)));
+                return failed(details);
             }
             if (dispatched.value)
                 return failed(dispatched.value);
@@ -417,13 +588,19 @@ export class InvocationService {
                 return yield* Effect.die(new Error("Invocation completed without a resolved tool"));
             }
             const processResult = context.processResult;
-            const processing = processResult
-                ? Effect.tryPromise({
-                    try: () => Promise.resolve(processResult(result, completed)),
-                    catch: (error) => error,
-                })
-                : Effect.succeed(result);
-            const processed = yield* Effect.exit(timed((elapsed) => { resultProcessingMs += elapsed; }, Effect.tap(processing, () => Effect.sync(() => {
+            const processing = inputRequiredValue
+                ? Effect.succeed(inputRequiredValue.value)
+                : processResult
+                    ? Effect.tryPromise({
+                        try: () => Promise.resolve(processResult(sentSecrets.redact(result), completed, sentSecrets, valueFormat, rawResult)),
+                        catch: (error) => error,
+                    })
+                    : Effect.succeed(result);
+            const processed = yield* Effect.exit(timed((elapsed) => {
+                resultProcessingMs += elapsed;
+            }, Effect.tap(processing, () => Effect.sync(() => {
+                if (inputRequiredValue)
+                    return;
                 try {
                     this.registry.observeOutputShape(completed.connector.id, completed.definition, observedResult);
                 }
@@ -436,13 +613,14 @@ export class InvocationService {
             if (Exit.isFailure(processed))
                 return unprocessable();
             try {
-                const value = processed.value;
+                const value = sentSecrets.redact(processed.value, "envelope");
                 const diagnostics = timing();
                 const friction = context.activityFriction?.(value);
                 record("success", friction ? { friction } : {});
                 return {
                     ok: true,
                     value,
+                    format: valueFormat,
                     resolved: completed,
                     durationMs: Date.now() - started,
                     attempts,
@@ -453,6 +631,11 @@ export class InvocationService {
             catch {
                 return unprocessable();
             }
-        });
+        }).pipe(Effect.flatMap((outcome) => outcome.ok
+            ? Effect.succeed(outcome)
+            : Effect.promise(async () => ({
+                ...outcome,
+                error: await withAuthorizationHandoff(this.catalog.requestScope, outcome.error),
+            }))));
     }
 }