agentfootprint 11.4.0 → 12.0.0

package/dist/esm/mcp/types.d.ts

@@ -23,6 +23,7 @@
 import type { Tool } from '../tools/tools.js';
 import type { CredentialProvider } from '../identity/types.js';
 import type { RetryOnThrottle } from './throttleRetry.js';
+import type { McpReplayOptions } from './replay.js';
 import type { FetchLike } from './gatewayTransport.js';
 /**
  * `stdio` transport — spawns a local subprocess and speaks MCP over
@@ -207,14 +208,17 @@ export interface McpClientOptions {
      * the transport's `retry` values as the call's overall limits and these as
      * limits on the 429 retries inside them.
      *
-     * **What this assumes.** Automatic 429 retries assume the server rejected
-     * the request before executing it. The saved response records that
-     * assumption's basis (the server's 429), not proof that nothing ran: HTTP 429
-     * says the request was rate-limited, nothing more (RFC 6585 §4). A tool with
-     * side effects is retried on 429 like any other today — this retry has no
-     * side-effect guard and sends no deduplication key — and
-     * `retryOnThrottle: false` turns that off for this server. Nothing else is
-     * retried: a 5xx or a timeout may be the record of work that ran.
+     * **Who may ask again is {@link McpClientOptions.replay}'s.** These
+     * options set the BUDGET of a call's retries; whether a tool call is sent
+     * again at all is the replay policy's. Under the default (`'compatibility'`)
+     * a 429 is repeated for every tool, ASSUMING the server refused it before
+     * running it — HTTP 429 says only that the request was rate-limited (RFC 6585
+     * §4) — and every such repeat records that assumption. A tool you declare as
+     * making changes is never repeated without a deduplication key, and
+     * `'app-authorized'` repeats only what you declare. `retryOnThrottle: false`
+     * turns 429 retries off for this server, and nothing else: a tool declared
+     * repeatable on `'network'`, and the `'app-authorized'` policy, keep their
+     * series and their record. A 5xx is an answer and is never repeated.
      *
      * **Why this is on by default.** Managed gateways rate-limit per principal by
      * design, and without this a designed, self-clearing condition reached the
@@ -223,6 +227,65 @@ export interface McpClientOptions {
      * Ignored for `stdio`, which has no HTTP status to read.
      */
     readonly retryOnThrottle?: RetryOnThrottle;
+    /**
+     * Who may send a tool call again, declared by YOU for this server's tools —
+     * never by the model, a tool's description or the server's annotations
+     * (`readOnlyHint`). Read once, here; a field it does not know is refused.
+     *
+     * ```ts
+     * const orders = await mcpClient({
+     *   name: 'orders',
+     *   transport: { transport: 'http', url },
+     *   replay: {
+     *     policy: 'app-authorized',
+     *     tools: {
+     *       search_orders: { on: ['throttle', 'network'] },
+     *       create_order: { on: ['throttle'], changes: true },
+     *     },
+     *     deduplicates: { argument: 'idempotency_key' },
+     *   },
+     * });
+     * ```
+     *
+     *   - `policy: 'compatibility'` (the default, kept in 12.0) — today's
+     *     behaviour, by name: a 429 is sent again for every tool, assuming the
+     *     server refused it before running it. Each such retry records that
+     *     assumption (`permission: { by: 'compatibility', assumes: 'refused-before-execution' }`).
+     *     It gains none of the strict guarantees below.
+     *   - `policy: 'app-authorized'` (opt-in, by name) — a 429
+     *     (`'throttle'`) or a request that failed without an answer
+     *     (`'network'`) is sent again only for a tool whose entry names it.
+     *   - `changes: true` — the tool makes changes: never sent again
+     *     automatically, under either policy, unless `deduplicates` is declared
+     *     and the call carries the key. A key protects only when the server uses it.
+     *
+     * Under both policies the adapter you chose retries its own refusal —
+     * AgentCore Runtime's session-busy reply — within the budget, as its policy:
+     * each repeat records what it assumes, never proof that nothing ran. A
+     * repeat re-sends the SAME request: the same arguments, server and session,
+     * as the same identity. Each attempt's run record says what is known of its
+     * effect — `unknown` for anything sent that did not complete, `applied` when
+     * the call completed (never proof of a write) — and what permitted the next
+     * one. Under `'app-authorized'`, a received refusal or error (a 429, a 503,
+     * a JSON-RPC or tool error) reaches the caller as the server sent it, its
+     * effect still unknown; a call that genuinely lacked an answer somewhere —
+     * a request with no response, or one accepted over HTTP whose JSON-RPC
+     * answer never came — and then fails, fails as "may have run"
+     * (footprintjs's `UnknownEffectError`, its final error as the `cause`).
+     * Under `'compatibility'` the caller sees the error it always did.
+     *
+     * `'app-authorized'` needs each request matched to its call and each answer
+     * seen. A connection that cannot give both refuses each tool call BEFORE its
+     * request is sent, with `McpReplayUnavailableError` and a typed `reason`: an
+     * MCP SDK whose `connect` replaces the transport's `onmessage` handler
+     * (`'answers-unobserved'`), one that drops the params' `_meta`
+     * (`'request-unmatched'`), or a transport whose requests the library cannot
+     * watch, such as `stdio` (`'requests-unwatched'`). Connecting and listing
+     * tools still run; only the tool invocation is refused. An explicit
+     * `'app-authorized'` never falls back to `'compatibility'`. Under
+     * `'compatibility'`, `stdio` ignores it: it has no retry series.
+     */
+    readonly replay?: McpReplayOptions;
     /**
      * Pre-resolved SDK modules. Give these and the library never touches its Node
      * `require` loader — which is what lets a browser bundle speak MCP over
@@ -295,6 +358,8 @@ export interface McpConnectionOptions {
     readonly clientInfo?: undefined;
     /** @see McpClientOptions — never set on this arm. */
     readonly retryOnThrottle?: undefined;
+    /** @see McpClientOptions — never set on this arm. */
+    readonly replay?: undefined;
     /** @internal @see McpClientOptions — never set on this arm. */
     readonly _client?: undefined;
 }

package/dist/esm/provider-contract/codeSandbox.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The code-session port's refusals and its one path rule.
+ *
+ * Every adapter behind the `CodeSession` port refuses the same things with the
+ * same error, and reads a session path by the same rule, so a caller that
+ * swaps `localCodeRunner` for `agentCoreCodeRunner` catches the same names.
+ * The rule lives here, beside the port, rather than in either adapter: two
+ * copies of a path rule are two rules.
+ */
+/** Why a code-session operation was refused. */
+export type CodeSandboxRefusal = 
+/** The path is absolute, climbs above the working directory, or is not a path. */
+'path-refused'
+/** A read found a file larger than its `maxBytes`. Nothing was returned. */
+ | 'file-too-large'
+/** The backend answered a read with no file for the path. */
+ | 'file-not-returned'
+/** The backend returned a file without saying which path it is. */
+ | 'uri-missing'
+/** The backend returned a file for a path other than the one asked for. */
+ | 'uri-mismatch'
+/** The backend returned several files for one path, or a file with both text and bytes, or neither. */
+ | 'content-ambiguous'
+/** One request would be larger than the backend accepts in a single call. Nothing was sent. */
+ | 'request-too-large'
+/** The backend did not confirm a write. */
+ | 'write-failed'
+/** The caller's `timeoutMs` passed before the backend answered. */
+ | 'timed-out'
+/** A process started, then the runtime reported an error for it. It was
+ *  stopped; whether it finished, and what it changed, is unknown. */
+ | 'error-after-start'
+/** The staged-input manifest could not be set where the next run reads it. */
+ | 'staged-inputs-unset';
+/**
+ * A code-session operation refused — before anything was sent, or because
+ * what came back could not be trusted as the answer.
+ *
+ * Carries the path, sizes and limits as data. Never a file's contents and
+ * never a command's text: those are the two things a code session holds that
+ * an error message must not repeat, because error messages reach logs, traces
+ * and the model.
+ */
+export declare class CodeSandboxError extends Error {
+    readonly code: "ERR_CODE_SANDBOX";
+    /** What was refused. */
+    readonly reason: CodeSandboxRefusal;
+    /** The session path involved, when there was one. */
+    readonly path?: string;
+    /** The size that was measured, in bytes, when the refusal is about size. */
+    readonly bytes?: number;
+    /** The limit that size was held to, in bytes. */
+    readonly limit?: number;
+    constructor(reason: CodeSandboxRefusal, message: string, details?: {
+        readonly path?: string;
+        readonly bytes?: number;
+        readonly limit?: number;
+    });
+}
+/**
+ * One session path, checked and put in canonical form — THE path rule every
+ * adapter applies before it reads a file.
+ *
+ * Refused, by name, before anything is sent:
+ *   - an empty path, and one that names the working directory itself (`.`);
+ *   - an absolute path (`/etc/passwd`) and a drive (`C:…`);
+ *   - a leading `~`, which a shell would read as a home directory;
+ *   - any backslash — a separator on one platform and an ordinary character
+ *     on another, so `a\..\..\x` cannot be judged the same way everywhere;
+ *   - a NUL, which ends a path early in the operating system's own calls;
+ *   - a `..` that climbs above the working directory (`../x`, `a/../../x`).
+ *
+ * A `..` that stays inside is resolved here (`a/../b` → `b`), `.` and empty
+ * segments are dropped (`./out//a.csv` → `out/a.csv`), and the result never
+ * contains `..` at all — so no backend is ever handed a parent hop to
+ * interpret. Lexical, not physical: on the caller's own machine a symbolic
+ * link can still point elsewhere, which `localCodeRunner` checks separately.
+ *
+ * @throws CodeSandboxError with reason `'path-refused'`.
+ */
+export declare function sandboxPath(path: string): string;
+/**
+ * The one check of a `maxBytes` bound: a positive whole number, or a
+ * `TypeError` naming the option. A read with no bound, or with a bound of
+ * zero, is a programming error rather than a file that happened to be large.
+ */
+export declare function readBound(options: {
+    readonly maxBytes?: unknown;
+} | undefined): number;

package/dist/esm/provider-contract/codeSandbox.js

@@ -0,0 +1,119 @@
+/**
+ * The code-session port's refusals and its one path rule.
+ *
+ * Every adapter behind the `CodeSession` port refuses the same things with the
+ * same error, and reads a session path by the same rule, so a caller that
+ * swaps `localCodeRunner` for `agentCoreCodeRunner` catches the same names.
+ * The rule lives here, beside the port, rather than in either adapter: two
+ * copies of a path rule are two rules.
+ */
+/**
+ * A code-session operation refused — before anything was sent, or because
+ * what came back could not be trusted as the answer.
+ *
+ * Carries the path, sizes and limits as data. Never a file's contents and
+ * never a command's text: those are the two things a code session holds that
+ * an error message must not repeat, because error messages reach logs, traces
+ * and the model.
+ */
+export class CodeSandboxError extends Error {
+    code = 'ERR_CODE_SANDBOX';
+    /** What was refused. */
+    reason;
+    /** The session path involved, when there was one. */
+    path;
+    /** The size that was measured, in bytes, when the refusal is about size. */
+    bytes;
+    /** The limit that size was held to, in bytes. */
+    limit;
+    constructor(reason, message, details = {}) {
+        super(message);
+        this.name = 'CodeSandboxError';
+        this.reason = reason;
+        if (details.path !== undefined)
+            this.path = details.path;
+        if (details.bytes !== undefined)
+            this.bytes = details.bytes;
+        if (details.limit !== undefined)
+            this.limit = details.limit;
+    }
+}
+/** The longest stretch of a refused path a message quotes. */
+const QUOTED_PATH_MAX = 200;
+function quoted(path) {
+    const shown = path.length > QUOTED_PATH_MAX ? `${path.slice(0, QUOTED_PATH_MAX)}…` : path;
+    return JSON.stringify(shown);
+}
+function refused(path, why) {
+    return new CodeSandboxError('path-refused', `code session: the path ${quoted(path)} ${why}. A session path is relative to the ` +
+        "session's working directory and stays inside it — name the file as the session's code " +
+        'would, for example `out/result.csv`.', { path });
+}
+/**
+ * One session path, checked and put in canonical form — THE path rule every
+ * adapter applies before it reads a file.
+ *
+ * Refused, by name, before anything is sent:
+ *   - an empty path, and one that names the working directory itself (`.`);
+ *   - an absolute path (`/etc/passwd`) and a drive (`C:…`);
+ *   - a leading `~`, which a shell would read as a home directory;
+ *   - any backslash — a separator on one platform and an ordinary character
+ *     on another, so `a\..\..\x` cannot be judged the same way everywhere;
+ *   - a NUL, which ends a path early in the operating system's own calls;
+ *   - a `..` that climbs above the working directory (`../x`, `a/../../x`).
+ *
+ * A `..` that stays inside is resolved here (`a/../b` → `b`), `.` and empty
+ * segments are dropped (`./out//a.csv` → `out/a.csv`), and the result never
+ * contains `..` at all — so no backend is ever handed a parent hop to
+ * interpret. Lexical, not physical: on the caller's own machine a symbolic
+ * link can still point elsewhere, which `localCodeRunner` checks separately.
+ *
+ * @throws CodeSandboxError with reason `'path-refused'`.
+ */
+export function sandboxPath(path) {
+    if (typeof path !== 'string') {
+        throw refused(String(path), 'is not a string');
+    }
+    if (path.length === 0)
+        throw refused(path, 'is empty');
+    if (path.includes('\0'))
+        throw refused(path, 'contains a NUL character');
+    if (path.includes('\\')) {
+        throw refused(path, 'contains a backslash, which is a separator on one platform and an ordinary character on another');
+    }
+    if (path.startsWith('/'))
+        throw refused(path, 'is absolute');
+    if (/^[A-Za-z]:/.test(path))
+        throw refused(path, 'names a drive');
+    if (path.startsWith('~'))
+        throw refused(path, "starts with '~', which a shell reads as a home directory");
+    const kept = [];
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (kept.length === 0)
+                throw refused(path, 'climbs above the working directory');
+            kept.pop();
+            continue;
+        }
+        kept.push(segment);
+    }
+    if (kept.length === 0)
+        throw refused(path, 'names the working directory itself, not a file');
+    return kept.join('/');
+}
+/**
+ * The one check of a `maxBytes` bound: a positive whole number, or a
+ * `TypeError` naming the option. A read with no bound, or with a bound of
+ * zero, is a programming error rather than a file that happened to be large.
+ */
+export function readBound(options) {
+    const maxBytes = options?.maxBytes;
+    if (typeof maxBytes !== 'number' || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new TypeError('code session: readFile needs `maxBytes`, a positive whole number of bytes — a read names ' +
+            'its bound, and a file over it is refused rather than cut.');
+    }
+    return maxBytes;
+}
+//# sourceMappingURL=codeSandbox.js.map

package/dist/esm/provider-contract/codeSandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeSandbox.js","sourceRoot":"","sources":["../../../src/provider-contract/codeSandbox.ts"],"names":[],"mappings":"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"}

package/dist/esm/provider-contract/sessionExpired.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `SessionExpiredError` — a remote session that is gone, said ONE way.
+ *
+ * A managed backend reaps its sessions on its own schedule (a timeout, a stop,
+ * a restart), and each service words that differently: AgentCore's Code
+ * Interpreter answers with a `ValidationException` saying the session is "not
+ * active", a stream error naming an inactive session, or a
+ * `ResourceNotFoundException` on a call that addresses nothing but the session.
+ * A caller that has to recognise all of those by message text will miss the
+ * next one. An adapter recognises them once and raises this instead, so "start
+ * a new session" is one `instanceof` away.
+ *
+ * Raised only on evidence that names the session. A "not found" that could be
+ * about something else in the session (a file a read asked for) is not taken
+ * as proof the session is gone.
+ *
+ * It names the session and the signal that said so — never the request that
+ * hit it. Nothing reconnects: the session's files and state are gone, and a
+ * session name is not an address (names are not unique), so the only honest
+ * next step is a new session.
+ */
+export declare class SessionExpiredError extends Error {
+    readonly code: "ERR_SESSION_EXPIRED";
+    /** The adapter that raised it, e.g. `'agentCoreCodeRunner'`. */
+    readonly backend: string;
+    /** The backend's id for the session that is gone. */
+    readonly sessionId: string;
+    /** The service's own name for the signal that said so, e.g. `'ResourceNotFoundException'`. */
+    readonly evidence: string;
+    constructor(backend: string, sessionId: string, evidence: string);
+}

package/dist/esm/provider-contract/sessionExpired.js

@@ -0,0 +1,40 @@
+/**
+ * `SessionExpiredError` — a remote session that is gone, said ONE way.
+ *
+ * A managed backend reaps its sessions on its own schedule (a timeout, a stop,
+ * a restart), and each service words that differently: AgentCore's Code
+ * Interpreter answers with a `ValidationException` saying the session is "not
+ * active", a stream error naming an inactive session, or a
+ * `ResourceNotFoundException` on a call that addresses nothing but the session.
+ * A caller that has to recognise all of those by message text will miss the
+ * next one. An adapter recognises them once and raises this instead, so "start
+ * a new session" is one `instanceof` away.
+ *
+ * Raised only on evidence that names the session. A "not found" that could be
+ * about something else in the session (a file a read asked for) is not taken
+ * as proof the session is gone.
+ *
+ * It names the session and the signal that said so — never the request that
+ * hit it. Nothing reconnects: the session's files and state are gone, and a
+ * session name is not an address (names are not unique), so the only honest
+ * next step is a new session.
+ */
+export class SessionExpiredError extends Error {
+    code = 'ERR_SESSION_EXPIRED';
+    /** The adapter that raised it, e.g. `'agentCoreCodeRunner'`. */
+    backend;
+    /** The backend's id for the session that is gone. */
+    sessionId;
+    /** The service's own name for the signal that said so, e.g. `'ResourceNotFoundException'`. */
+    evidence;
+    constructor(backend, sessionId, evidence) {
+        super(`${backend}: session ${sessionId} is no longer active (${evidence}). The service ends a ` +
+            'session at its timeout or when it is stopped, and its files and state end with it. ' +
+            'Start a new session; nothing reconnects to this one.');
+        this.name = 'SessionExpiredError';
+        this.backend = backend;
+        this.sessionId = sessionId;
+        this.evidence = evidence;
+    }
+}
+//# sourceMappingURL=sessionExpired.js.map

package/dist/esm/provider-contract/sessionExpired.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionExpired.js","sourceRoot":"","sources":["../../../src/provider-contract/sessionExpired.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,qBAA8B,CAAC;IAC/C,gEAAgE;IACvD,OAAO,CAAS;IACzB,qDAAqD;IAC5C,SAAS,CAAS;IAC3B,8FAA8F;IACrF,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,SAAiB,EAAE,QAAgB;QAC9D,KAAK,CACH,GAAG,OAAO,aAAa,SAAS,yBAAyB,QAAQ,wBAAwB;YACvF,qFAAqF;YACrF,sDAAsD,CACzD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/esm/provider-contract/types.d.ts

@@ -1165,6 +1165,42 @@ export interface CodeSession {
      * the accepted-and-silently-wrong failure.
      */
     stageInputs?(inputs: readonly CodeInput[]): Promise<readonly StagedCodeInput[]>;
+    /**
+     * OPTIONAL — read ONE file back out of the session, whole or not at all.
+     *
+     * `path` is relative to the session's working directory and may not leave
+     * it. An absolute path, a `..` that climbs above the working directory, a
+     * backslash, a leading `~` or a NUL is refused by name before anything is
+     * sent (`CodeSandboxError`, reason `'path-refused'`) — one rule,
+     * `sandboxPath`, shared by every adapter.
+     *
+     * The answer is the file the BACKEND returned for that path, paired to it
+     * by what the backend said it returned. A file the adapter cannot pair with
+     * the path it asked for is refused, never guessed at — a backend that
+     * answers with another file, or with two, has not answered this read.
+     *
+     * `maxBytes` is required: a read names its bound. A file over it is refused
+     * (reason `'file-too-large'`), never cut — a truncated file handed back as
+     * the file is the silent success this port refuses everywhere else.
+     *
+     * Feature-detect with `canReadCodeFiles(session)`.
+     */
+    readFile?(path: string, options: CodeReadOptions): Promise<CodeFile>;
+    /**
+     * OPTIONAL — run ONE shell command in the session.
+     *
+     * It runs arbitrary shell, so an adapter offers it only when the runner was
+     * built with `commands: true`; otherwise the member is ABSENT. Feature-detect
+     * with `canRunCodeCommands(session)`. The command runs in the session's
+     * working directory with the environment `execute` gets, staged-input
+     * manifest included.
+     *
+     * The result says only what the backend reported. The exit status comes
+     * from the backend or not at all: when it reported none, `exitCode` is
+     * absent — unknown, never inferred from an error flag and never defaulted.
+     * stdout and stderr are bounded, and a cut is stated on `truncated`.
+     */
+    runCommand?(command: string, options?: CodeCommandOptions): Promise<CodeCommandResult>;
     /**
      * Release the session.
      *
@@ -1177,13 +1213,138 @@ export interface CodeSession {
 /** Can this session accept staged inputs? The feature-detection law: read the
  *  member, never assume it from the adapter's name. */
 export declare function canStageCodeInputs(session: CodeSession): session is CodeSession & Required<Pick<CodeSession, 'stageInputs'>>;
+/** Can this session read files back out? Read the member, never the adapter's name. */
+export declare function canReadCodeFiles(session: CodeSession): session is CodeSession & Required<Pick<CodeSession, 'readFile'>>;
+/** Can this session run shell commands? Absent unless the runner was built
+ *  with `commands: true`. Read the member, never the adapter's name. */
+export declare function canRunCodeCommands(session: CodeSession): session is CodeSession & Required<Pick<CodeSession, 'runCommand'>>;
+/** How one {@link CodeSession.readFile} is bounded. */
+export interface CodeReadOptions {
+    /**
+     * The most bytes this read may return. Required, and a positive whole
+     * number: a file larger than this is refused, never cut.
+     */
+    readonly maxBytes: number;
+    /** Stop waiting for the read. */
+    readonly signal?: AbortSignal;
+}
+/** One file read back out of a code session — exactly as the backend returned it. */
+export interface CodeFile {
+    /** The path that was read, in the canonical form the backend was asked for
+     *  (`./out//a.csv` → `out/a.csv`). */
+    readonly path: string;
+    /**
+     * The contents. A string when the backend returned TEXT, bytes when it
+     * returned BYTES — decided by which of the two the backend filled, never by
+     * the file's name or extension. A backend that draws no such line
+     * (`localCodeRunner`: a file on disk is bytes) returns bytes, and never
+     * guesses an encoding.
+     */
+    readonly data: string | Uint8Array;
+    /** The size of `data` in bytes (a string's UTF-8 length). */
+    readonly bytes: number;
+    /** The backend's own statement of the media type, when it made one. Never guessed. */
+    readonly mediaType?: string;
+}
+/** How one {@link CodeSession.runCommand} is bounded. */
+export interface CodeCommandOptions {
+    /**
+     * Stop waiting after this many milliseconds. What happens to the command
+     * depends on the backend, and the error says which: a local child process is
+     * killed; a managed sandbox may keep running it.
+     */
+    readonly timeoutMs?: number;
+    /** Stop waiting when this fires. */
+    readonly signal?: AbortSignal;
+    /** Per-stream ceiling for this command's output, in characters. The
+     *  runner's own `maxOutputChars` when absent. A cut is stated on `truncated`. */
+    readonly maxOutputChars?: number;
+    /**
+     * A line the command prints when it reaches a point you care about — for
+     * example `make && echo STEP_DONE` with `checkpoint: 'STEP_DONE'`. The
+     * result then says, on `checkpointSeen`, whether stdout held that exact line,
+     * read BEFORE any cut, so a marker printed past `maxOutputChars` is still
+     * found.
+     *
+     * It proves the command reached that line and nothing more: not that it
+     * exited cleanly, and not that anything after it ran. Its absence proves
+     * nothing about why. One line, no line breaks.
+     */
+    readonly checkpoint?: string;
+}
+/** What one shell command produced — only what the backend reported. */
+export interface CodeCommandResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    /**
+     * The exit status the backend reported. ABSENT when it reported none: the
+     * outcome is unknown. Never inferred from {@link CodeCommandResult.isError},
+     * never defaulted, never derived from the output.
+     */
+    readonly exitCode?: number;
+    /**
+     * The backend's own error flag, as it reported it (AgentCore's `isError`);
+     * absent when it reported none. It is NOT an exit status — a command can
+     * fail without it, and it can be set with no exit status at all.
+     */
+    readonly isError?: boolean;
+    /** The signal that ended the command before it exited, when the runner knows
+     *  it (`'SIGKILL'`). There is no `exitCode` then, and none is made up. */
+    readonly terminatedBy?: string;
+    /** Present IFF output was cut — see {@link CodeTruncation}. */
+    readonly truncated?: CodeTruncation;
+    /** Present IFF a `checkpoint` was asked for: whether stdout held that line. */
+    readonly checkpointSeen?: boolean;
+}
+/**
+ * Present IFF output was cut, and then it says by how much.
+ *
+ * Load-bearing, not politeness. A runner exists so big data is computed
+ * outside the context window instead of pasted into it; a runner that
+ * quietly slices its own output to fit is the same bug wearing a different
+ * hat, and the model would go on to reason over a truncated table it was
+ * never told was truncated. An unstated slice is a silent success.
+ */
+export interface CodeTruncation {
+    readonly stdout?: boolean;
+    readonly stderr?: boolean;
+    /** The pre-truncation length, in characters, of whichever stream was cut. */
+    readonly ofChars?: number;
+}
 /** What one execution produced. */
 export interface CodeResult {
-    /** Did the code run to completion without an error exit? */
-    readonly ok: boolean;
+    /**
+     * Did the code run to completion without an error exit? WHAT THE RUNNER
+     * REPORTED, nothing more.
+     *
+     * `true` or `false` only when the backend said so: an exit status, or its
+     * own error verdict. ABSENT when it reported neither — the outcome is
+     * unknown, and an absent `ok` is never success. (Before this was optional,
+     * `agentCoreCodeRunner` filled `true` from silence.) A `false` is told
+     * apart by the fields below: a program that exited non-zero (`exitCode`), a
+     * backend error with no exit status (`serviceError`, where the run is
+     * unconfirmed), and a process ended before it exited (`terminatedBy`).
+     */
+    readonly ok?: boolean;
     readonly stdout: string;
     readonly stderr: string;
+    /** The exit status — exactly when the runner reported one. Never inferred
+     *  from an error flag, never defaulted. */
     readonly exitCode?: number;
+    /**
+     * `true` when the backend flagged its answer as an error and reported NO
+     * exit status: whether the code ran at all is not confirmed. That is not a
+     * program that failed — a program that ran and failed has an `exitCode`.
+     * `ok` is `false` alongside it.
+     */
+    readonly serviceError?: true;
+    /**
+     * The signal that ended the process before it exited, when the runner knows
+     * it (`'SIGKILL'`): there is no exit status then, and none is made up. A
+     * local child the operating system ended, or one the runner ended because
+     * its output passed the buffer ceiling. `ok` is `false` alongside it.
+     */
+    readonly terminatedBy?: string;
     /** Files the run produced, described rather than inlined — the whole point is
      *  that big data does not enter the window. All fields beyond the original
      *  `{ name, bytes, uri? }` are ADDITIVE (9.22.0) and honest about absence:
@@ -1221,19 +1382,7 @@ export interface CodeResult {
         readonly data?: string | Uint8Array;
         readonly ref?: string;
     }[];
-    /**
-     * Present IFF output was cut, and then it says by how much.
-     *
-     * Load-bearing, not politeness. A runner exists so big data is computed
-     * outside the context window instead of pasted into it; a runner that
-     * quietly slices its own output to fit is the same bug wearing a different
-     * hat, and the model would go on to reason over a truncated table it was
-     * never told was truncated. An unstated slice is a silent success.
-     */
-    readonly truncated?: {
-        readonly stdout?: boolean;
-        readonly stderr?: boolean;
-        /** The pre-truncation length, in characters, of whichever stream was cut. */
-        readonly ofChars?: number;
-    };
+    /** Present IFF output was cut — see {@link CodeTruncation}. An unstated
+     *  slice is a silent success. */
+    readonly truncated?: CodeTruncation;
 }

package/dist/esm/provider-contract/types.js

@@ -50,4 +50,13 @@ export const STAGED_INPUTS_ENV = 'AF_STAGED_INPUTS';
 export function canStageCodeInputs(session) {
     return typeof session.stageInputs === 'function';
 }
+/** Can this session read files back out? Read the member, never the adapter's name. */
+export function canReadCodeFiles(session) {
+    return typeof session.readFile === 'function';
+}
+/** Can this session run shell commands? Absent unless the runner was built
+ *  with `commands: true`. Read the member, never the adapter's name. */
+export function canRunCodeCommands(session) {
+    return typeof session.runCommand === 'function';
+}
 //# sourceMappingURL=types.js.map

package/dist/esm/provider-contract/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/provider-contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8OH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AA0sBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAqID;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/provider-contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8OH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AA0sBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAqID;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAoIpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAC9B,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU,CAAC;AAChD,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,CAAC;AAClD,CAAC"}