agentfootprint/dist/esm/adapters/mcp/agentcoreRuntime/safeAnswer.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * safeAnswer — what the MCP client may read of an answer: read ONCE, checked,
 * and handed on as the canonical form of exactly what was checked.
 *
 * ── Why an allow-list ────────────────────────────────────────────────────────
 * Whatever an answer's body says becomes the MCP client's error text, and a
 * failed tool call hands that text to the model, the run's history and
 * `tool_end`. Service text can carry anything the request did: AWS answers a
 * signature mismatch with the whole signed request (the session token among
 * it), its validation errors quote the value they refused, a proxy may echo a
 * header. So a failure is RE-WRITTEN from parts that cannot carry a secret:
 * the status; the AWS error type when it is a plain name; `Retry-After` when
 * it is seconds or a date; and for a JSON-RPC error its integer `code`, the
 * client's own `id`, and its `message` ONLY when it is one of the fixed
 * sentences the MCP SDK and the AgentCore Runtime contract use
 * ({@link KNOWN_ERROR_MESSAGES}).
 *
 * ── Why one reading ──────────────────────────────────────────────────────────
 * A check that reads a body one way and a client that reads the same bytes
 * another is a parser differential: a crafted answer passes the check and is
 * used as something else. So a 2xx answer is never handed on as its raw bytes.
 * It is classified by ONE rule (its media type, exactly `application/json` or
 * `text/event-stream`, UTF-8), decoded strictly, parsed once
 * (`strictJson.ts` — a duplicated key, trailing data or a byte-order mark is
 * refused), checked, and RE-SERIALIZED: the client reads the value that was
 * checked, never the bytes it came from. One message per body or event — a
 * batch is refused. An answer that cannot be read unambiguously is refused by
 * name, as a 502 whose text is this library's.
 *
 * Pattern: pure functions + one TransformStream. Role: outer ring, the
 * transport's one rule for what the client reads.
 */
/**
 * JSON-RPC error messages a reply may keep word for word — fixed strings that
 * carry nothing of the request: the JSON-RPC 2.0 standard errors, the MCP
 * Streamable HTTP session error, and the AgentCore Runtime MCP contract's
 * mappings of its exceptions.
 */
export declare const KNOWN_ERROR_MESSAGES: ReadonlySet<string>;
/** Is this answer an authentication or authorization failure? */
export declare function isAuthFailure(status: number, type: string | undefined): boolean;
/**
 * The answer the MCP client may read: a failure rewritten from safe parts; a
 * 2xx read once and re-serialized; an answer that cannot be read
 * unambiguously refused (502).
 */
export declare function safeAnswer(response: Response): Promise<Response>;
/** The fixed sentence a failure with no JSON-RPC reply is answered with. */
export declare function failureSentence(status: number, type: string | undefined): string;