agentfootprint/dist/esm/adapters/code/agentcoreWire.d.ts

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

/**
 * What `agentCoreCodeRunner` has to know about AgentCore's wire, as pure
 * functions: how big a request is, how a returned file is paired with the
 * path asked for, how the staged-input manifest reaches a runtime that has no
 * environment parameter, and which service errors mean the session is gone.
 *
 * Kept apart from the session so each rule is one small function with its
 * own test, and so the session reads as the sequence it is.
 */
import type { CodeFile } from '../../provider-contract/types.js';
import type { AgentCoreFileContent, AgentCoreInvokeAnswer, AgentCoreInvokeInput } from './agentcoreClient.js';
/**
 * AgentCore's per-call limit for `InvokeCodeInterpreter`: "Max payload size —
 * 100 MB — Maximum size for request/response payloads", not adjustable
 * (AgentCore Code Interpreter service quotas).
 *
 * The service does not say whether that MB is 10^6 or 2^20 bytes, so the
 * adapter holds a request to the SMALLER reading: a request it sends is never
 * one the limit could refuse on size, and one between the two readings is
 * refused here by name rather than by the service in words nobody can act on.
 */
export declare const AGENTCORE_MAX_REQUEST_BYTES = 100000000;
/**
 * The size, in bytes, of the JSON body one `writeFiles` request sends —
 * computed, not built: text as its JSON-escaped UTF-8, bytes as base64 (how
 * the JSON protocol carries a blob), plus the envelope. Building the body to
 * measure it would hold a second copy of up to a hundred megabytes.
 */
export declare function writeFilesRequestBytes(content: readonly AgentCoreFileContent[]): number;
/** Bytes of `JSON.stringify(text)` encoded as UTF-8, quotes included, without building it. */
export declare function jsonStringBytes(text: string): number;
/** One `writeFiles` entry for a payload: TEXT for a string, BYTES for bytes. */
export declare function fileContent(path: string, data: string | Uint8Array): AgentCoreFileContent;
/**
 * The one file a `readFiles` answer returned for `path` — or a refusal.
 *
 * Paired by the URI the SERVICE put on the file, never by position: a file
 * with no URI, or a URI naming another path, fails closed, and so does an
 * answer carrying several files for one path. Text or bytes is read off which
 * field the service filled — never off the file's name — and an entry with
 * both, or neither, is refused. A file over `maxBytes` is refused whole.
 */
export declare function pairReadFile(path: string, answer: AgentCoreInvokeAnswer, maxBytes: number): CodeFile;
/**
 * Does `uri` name `path`? ONE declared form, read ONE way (RFC 8089's file
 * URI, RFC 3986's path syntax): `file:///` followed by a path whose segments
 * are percent-encoded.
 *
 * - A raw `?` or `#` starts a query or a fragment, which is never part of a
 *   file name, so a URI carrying one is refused outright. A name that really
 *   contains `?` or `#` arrives as `%3F` / `%23`.
 * - Each segment is decoded on its own. An invalid escape refuses the URI, and
 *   a decoded `/` (an encoded `%2F`) is a character inside one name, so it can
 *   never stand in for the separator.
 * - Only the decoded path is compared. There is no second, raw reading to fall
 *   back on when the first does not match.
 */
export declare function uriNames(uri: string, path: string): boolean;
/** Where staged inputs land, relative to the session's working directory. */
export declare const STAGED_INPUTS_DIR = "af-staged-inputs";
/** The line the manifest setup prints once the variable is set. */
export declare const MANIFEST_SET_MARKER = "af-staged-inputs-set";
/** The runtimes whose environment the adapter knows how to set. */
export type ManifestRuntime = 'python' | 'javascript' | 'typescript';
/**
 * Which runtime a language names, for the manifest setup. `undefined` (no
 * language sent) is the service's default runtime, Python; a language this
 * adapter does not know is `undefined` — and refused, never guessed.
 */
export declare function manifestRuntime(language: string | undefined): ManifestRuntime | undefined;
/**
 * The code that sets {@link STAGED_INPUTS_ENV} inside one runtime of the
 * session, then prints {@link MANIFEST_SET_MARKER}.
 *
 * WHY A SEPARATE CALL. `executeCode` takes no environment, and prepending a
 * line to the caller's code would shift every line number its traceback
 * reports and break a Python `from __future__` import. The session's runtime
 * keeps its state between executions, so the variable is set once per
 * runtime and manifest, by this code, before the caller's code runs.
 *
 * The value is the manifest JSON as a JSON string literal, which is a valid
 * string literal in Python and in JavaScript alike.
 */
export declare function manifestSetupCode(runtime: ManifestRuntime, manifestJson: string): string;
/**
 * `command`, with {@link STAGED_INPUTS_ENV} exported ahead of it.
 *
 * A command is its own shell process, so a variable set in a code runtime
 * never reaches it; this line does, every time, and needs no state. The value
 * is single-quoted, the one shell quoting with no expansions inside it.
 */
export declare function withManifestExport(command: string, manifestJson: string): string;
/**
 * What a service error says about the session: `'session'` when it means the
 * session itself is gone, `'file-or-session'` when it could mean that or a
 * missing file, `undefined` otherwise.
 *
 * - A modelled exception — a `ValidationException` above all — whose words
 *   name a session and say it is "not active" or "inactive": `'session'`.
 * - A `ResourceNotFoundException`, thrown by the SDK or carried on the stream:
 *   on a call that addresses nothing but the session (code, a command, a
 *   write) the missing resource is the session, so `'session'`. A READ also
 *   names a file, and AgentCore does not say which resource was missing, so
 *   `'file-or-session'` — never taken as proof the session is gone.
 */
export declare function sessionExpiryEvidence(err: unknown, tool: AgentCoreInvokeInput['name']): 'session' | 'file-or-session' | undefined;
/**
 * A modelled service exception from a file or command call, rewritten in
 * fixed words that name the exception and the call — or `undefined` for any
 * other error, which passes through as it is.
 *
 * The service's own message is NOT repeated: a validation message can quote
 * what was sent, and what was sent here is a path, a command or a file's
 * bytes. The exception's name is kept as the error's `name`, so a caller
 * branches on it exactly as on the SDK's own error.
 */
export declare function serviceRefusal(err: unknown, tool: AgentCoreInvokeInput['name']): Error | undefined;
/** The `name` an error carries — an SDK exception's class name — or `''`. */
export declare function errorNameOf(err: unknown): string;