agentfootprint 11.4.0 → 12.0.0

package/dist/esm/adapters/code/agentcoreWire.js

@@ -0,0 +1,334 @@
+/**
+ * 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 { STAGED_INPUTS_ENV } from '../../provider-contract/types.js';
+import { CodeSandboxError } from '../../provider-contract/codeSandbox.js';
+import { isHighSurrogate, isLowSurrogate, payloadBytes } from './output.js';
+// ── Request size ─────────────────────────────────────────────────────────
+/**
+ * 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 const AGENTCORE_MAX_REQUEST_BYTES = 100_000_000;
+/** `{"arguments":{"content":[` … `]},"name":"writeFiles"}` around the entries. */
+const WRITE_FILES_ENVELOPE_BYTES = JSON.stringify({
+    arguments: { content: [] },
+    name: 'writeFiles',
+}).length;
+/**
+ * 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 function writeFilesRequestBytes(content) {
+    let bytes = WRITE_FILES_ENVELOPE_BYTES + Math.max(content.length - 1, 0); // the commas
+    for (const entry of content) {
+        bytes += '{"path":'.length + jsonStringBytes(entry.path) + '}'.length;
+        if (entry.text !== undefined)
+            bytes += ',"text":'.length + jsonStringBytes(entry.text);
+        else
+            bytes += ',"blob":'.length + 2 + base64Length(entry.blob.byteLength);
+    }
+    return bytes;
+}
+/** Bytes of `JSON.stringify(text)` encoded as UTF-8, quotes included, without building it. */
+export function jsonStringBytes(text) {
+    let bytes = 2;
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        if (unit === 0x22 || unit === 0x5c)
+            bytes += 2; // \" and \\
+        else if (unit < 0x20)
+            bytes += SHORT_ESCAPES.has(unit) ? 2 : 6; // \n … or \u00XX
+        else if (unit < 0x80)
+            bytes += 1;
+        else if (unit < 0x800)
+            bytes += 2;
+        else if (isHighSurrogate(unit) && isLowSurrogate(text.charCodeAt(i + 1))) {
+            bytes += 4;
+            i++;
+        }
+        else if (isHighSurrogate(unit) || isLowSurrogate(unit))
+            bytes += 6; // a lone half: \udXXX
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+/** Control characters JSON writes as a two-character escape: \b \t \n \f \r. */
+const SHORT_ESCAPES = new Set([0x08, 0x09, 0x0a, 0x0c, 0x0d]);
+function base64Length(bytes) {
+    return 4 * Math.ceil(bytes / 3);
+}
+/** One `writeFiles` entry for a payload: TEXT for a string, BYTES for bytes. */
+export function fileContent(path, data) {
+    return typeof data === 'string' ? { path, text: data } : { path, blob: data };
+}
+// ── Reading a file back ──────────────────────────────────────────────────
+/** How AgentCore names a file it returns: `file:///` + the path asked for,
+ *  percent-encoded (read from a published real `readFiles` answer:
+ *  `report.csv` → `file:///report.csv`; the shape is not in AWS's docs). */
+const FILE_URI_PREFIX = 'file:///';
+/**
+ * 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 function pairReadFile(path, answer, maxBytes) {
+    const refuse = (reason, why) => {
+        throw new CodeSandboxError(reason, `agentCoreCodeRunner: reading '${path}' — ${why}`, { path });
+    };
+    if (answer.isError === true) {
+        refuse('file-not-returned', 'the service flagged its answer as an error, so no file came back. Its words are not ' +
+            'repeated here.');
+    }
+    const resources = answer.resources ?? [];
+    if (resources.length === 0)
+        refuse('file-not-returned', 'the answer held no file.');
+    for (const resource of resources) {
+        if (typeof resource.uri !== 'string' || resource.uri.length === 0) {
+            refuse('uri-missing', 'a file came back without a URI, so it cannot be paired with the path asked for.');
+        }
+        if (hasQueryOrFragment(resource.uri)) {
+            refuse('uri-mismatch', 'a file came back under a URI with a query or fragment, which is not part of any file ' +
+                'name (a literal ? or # in a name arrives as %3F or %23).');
+        }
+        if (!uriNames(resource.uri, path)) {
+            refuse('uri-mismatch', 'a file came back under a URI that names another path.');
+        }
+    }
+    if (resources.length > 1)
+        refuse('content-ambiguous', `${resources.length} files came back for one path.`);
+    const resource = resources[0];
+    const hasText = resource.text !== undefined && resource.text !== null;
+    const hasBlob = resource.blob !== undefined && resource.blob !== null;
+    if (hasText === hasBlob) {
+        refuse('content-ambiguous', hasText
+            ? 'the file came back as both text and bytes.'
+            : 'the file came back with neither text nor bytes.');
+    }
+    if (hasText && typeof resource.text !== 'string')
+        refuse('content-ambiguous', 'its text is not a string.');
+    if (hasBlob && !isBytes(resource.blob))
+        refuse('content-ambiguous', 'its bytes are not bytes.');
+    const data = hasText ? resource.text : resource.blob;
+    const bytes = payloadBytes(data);
+    if (bytes > maxBytes) {
+        throw new CodeSandboxError('file-too-large', `agentCoreCodeRunner: '${path}' is ${bytes} bytes and this read allows ${maxBytes}. ` +
+            'Nothing was returned — a file is never handed back cut.', { path, bytes, limit: maxBytes });
+    }
+    return {
+        path,
+        data,
+        bytes,
+        ...(typeof resource.mimeType === 'string' &&
+            resource.mimeType.length > 0 && {
+            mediaType: resource.mimeType,
+        }),
+    };
+}
+/**
+ * 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 function uriNames(uri, path) {
+    if (!uri.startsWith(FILE_URI_PREFIX))
+        return false;
+    const named = uri.slice(FILE_URI_PREFIX.length);
+    if (hasQueryOrFragment(named))
+        return false;
+    const segments = [];
+    for (const encoded of named.split('/')) {
+        let segment;
+        try {
+            segment = decodeURIComponent(encoded);
+        }
+        catch {
+            return false;
+        }
+        if (segment.includes('/'))
+            return false;
+        segments.push(segment);
+    }
+    return segments.join('/') === path;
+}
+/** A raw `?` or `#` in a URI: a query or a fragment component. */
+function hasQueryOrFragment(uriTail) {
+    return uriTail.includes('?') || uriTail.includes('#');
+}
+function isBytes(value) {
+    return (value instanceof Uint8Array || Object.prototype.toString.call(value) === '[object Uint8Array]');
+}
+// ── The staged-input manifest ────────────────────────────────────────────
+/** Where staged inputs land, relative to the session's working directory. */
+export const STAGED_INPUTS_DIR = 'af-staged-inputs';
+/** The line the manifest setup prints once the variable is set. */
+export const MANIFEST_SET_MARKER = 'af-staged-inputs-set';
+/**
+ * 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 function manifestRuntime(language) {
+    if (language === undefined || language === '')
+        return 'python';
+    const lower = language.toLowerCase();
+    if (lower === 'python' || lower === 'python3' || lower === 'py')
+        return 'python';
+    if (lower === 'javascript' || lower === 'js' || lower === 'node')
+        return 'javascript';
+    if (lower === 'typescript' || lower === 'ts')
+        return 'typescript';
+    return 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 function manifestSetupCode(runtime, manifestJson) {
+    const value = JSON.stringify(manifestJson);
+    const name = JSON.stringify(STAGED_INPUTS_ENV);
+    const marker = JSON.stringify(MANIFEST_SET_MARKER);
+    if (runtime === 'python') {
+        return [
+            'import os as _af_os',
+            `_af_os.environ[${name}] = ${value}`,
+            'del _af_os',
+            `print(${marker})`,
+        ].join('\n');
+    }
+    return [
+        '{',
+        runtime === 'typescript'
+            ? '  const _afHost: any = globalThis;'
+            : '  const _afHost = globalThis;',
+        `  const _afValue = ${value};`,
+        '  if (_afHost.process && _afHost.process.env) {',
+        `    _afHost.process.env[${name}] = _afValue;`,
+        '  } else {',
+        `    _afHost.Deno.env.set(${name}, _afValue);`,
+        '  }',
+        `  console.log(${marker});`,
+        '}',
+    ].join('\n');
+}
+/**
+ * `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 function withManifestExport(command, manifestJson) {
+    return `export ${STAGED_INPUTS_ENV}=${shellQuoted(manifestJson)}\n${command}`;
+}
+function shellQuoted(text) {
+    return `'${text.split("'").join(`'\\''`)}'`;
+}
+// ── Service errors ───────────────────────────────────────────────────────
+/** The exceptions AgentCore models for `InvokeCodeInterpreter`, by class name. */
+const MODELLED_EXCEPTIONS = new Set([
+    'AccessDeniedException',
+    'ConflictException',
+    'InternalServerException',
+    'ResourceNotFoundException',
+    'ServiceQuotaExceededException',
+    'ThrottlingException',
+    'ValidationException',
+]);
+/** Words a service uses for a session that is gone — both halves required, so
+ *  a validation message that merely echoes a request containing "inactive"
+ *  is not read as a dead session. */
+const SAYS_INACTIVE = /\bnot active\b|\binactive\b/i;
+const NAMES_A_SESSION = /\bsession\b/i;
+/**
+ * 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 function sessionExpiryEvidence(err, tool) {
+    const name = errorNameOf(err);
+    const message = errorMessage(err);
+    if (MODELLED_EXCEPTIONS.has(name) &&
+        SAYS_INACTIVE.test(message) &&
+        NAMES_A_SESSION.test(message)) {
+        return 'session';
+    }
+    if (name === 'ResourceNotFoundException') {
+        return tool === 'readFiles' ? 'file-or-session' : 'session';
+    }
+    return 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 function serviceRefusal(err, tool) {
+    const name = errorNameOf(err);
+    if (!MODELLED_EXCEPTIONS.has(name))
+        return undefined;
+    const refusal = new Error(`agentCoreCodeRunner: the service refused ${tool} (${name}). Its message is not repeated ` +
+        'here, because it can quote what was sent.');
+    refusal.name = name;
+    return refusal;
+}
+/** The `name` an error carries — an SDK exception's class name — or `''`. */
+export function errorNameOf(err) {
+    const name = err?.name;
+    return typeof name === 'string' ? name : '';
+}
+function errorMessage(err) {
+    const message = err?.message;
+    return typeof message === 'string' ? message : '';
+}
+//# sourceMappingURL=agentcoreWire.js.map

package/dist/esm/adapters/code/agentcoreWire.js.map

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

package/dist/esm/adapters/code/fileName.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The one file-name encoder both code adapters stage inputs under.
+ *
+ * A staged input's name is caller data landing in a filesystem — a local temp
+ * directory for `localCodeRunner`, the sandbox's own disk for
+ * `agentCoreCodeRunner`. Both turn it into ONE inert segment through this
+ * function, so the same name lands under the same file name on either backend
+ * and two names never become one file on either.
+ */
+/**
+ * One caller-supplied name → one inert file-name segment, **without ever
+ * folding two names into one file**.
+ *
+ * Separators cannot survive as a parent hop and `a/b` cannot become two
+ * segments — the same law `artifacts/scopePath` states for scope tuples,
+ * applied to the one other place caller strings become file names in this
+ * package. But the old version got there by REPLACING every illegal character
+ * with `_`, which meant `a/b.csv` and `a_b.csv` became the same file: the
+ * second write clobbered the first's bytes, `stageInputs` answered two manifest
+ * entries pointing at one path, and the model's code opened `a/b.csv` and read
+ * whatever `a_b.csv` contained. Nothing failed. The computation was simply run
+ * against the wrong dataset — which is the worst shape a data bug can take,
+ * because the answer still looks like an answer. `.slice(0, 120)` folded the
+ * same way for any two names agreeing on their first 120 characters.
+ *
+ * So this ENCODES instead of sanitising, in two arms whose outputs cannot meet
+ * (the shape `safeSessionId` uses in `adapters/hosting/agentcore.ts`):
+ *
+ *   A. already one legal segment, not claiming to be an encoded name, and not
+ *      dots-only → returned BYTE FOR BYTE. This is what keeps the fix from
+ *      renaming anything that works today: `dataset.json`, `a_b.json`, every
+ *      name `codeRunnerTool` derives from a declared argument, all land at
+ *      exactly the path they landed at before.
+ *   B. anything else → `_enc_` + an escaped form, where `_` is the escape
+ *      character (`_` → `__`, any other illegal UTF-16 unit → `_uXXXX`). A
+ *      decoder is a left inverse of that, which is what makes it injective.
+ *
+ * Arm A never starts with `_enc_` (excluded by construction) and every arm B
+ * output does, so no name from one arm can collide with a name from the other.
+ * Both arms produce ASCII with no `/`, no `\` and no NUL, so the path-hop law
+ * the old version enforced is unchanged.
+ */
+export declare function safeFileName(raw: string): string;

package/dist/esm/adapters/code/fileName.js

@@ -0,0 +1,96 @@
+/**
+ * The one file-name encoder both code adapters stage inputs under.
+ *
+ * A staged input's name is caller data landing in a filesystem — a local temp
+ * directory for `localCodeRunner`, the sandbox's own disk for
+ * `agentCoreCodeRunner`. Both turn it into ONE inert segment through this
+ * function, so the same name lands under the same file name on either backend
+ * and two names never become one file on either.
+ */
+import { sha256Hex } from '../../lib/sha256.js';
+/** Longest file name this adapter will write. Well inside every POSIX
+ *  `NAME_MAX`, and the cap this adapter has always used. */
+const FILE_NAME_MAX = 120;
+/** Marks a name this adapter had to rewrite. Nothing arm A returns may start
+ *  with it. */
+const ENCODED_FILE_PREFIX = '_enc_';
+/** Already one inert segment: no separator, no escape-looking bytes. */
+const FILE_NAME_ALREADY_LEGAL = /^[A-Za-z0-9._-]+$/;
+/** `.`, `..`, `...` — a name that is nothing but dots. Not a hop once the
+ *  separators are gone, but not a name either, so it goes to arm B. */
+const DOTS_ONLY = /^\.+$/;
+/** Legal AND not the escape character — the set {@link encodeFileName} passes
+ *  through untouched. */
+const FILE_CHAR_PASSES_THROUGH = /[A-Za-z0-9.-]/;
+/**
+ * One caller-supplied name → one inert file-name segment, **without ever
+ * folding two names into one file**.
+ *
+ * Separators cannot survive as a parent hop and `a/b` cannot become two
+ * segments — the same law `artifacts/scopePath` states for scope tuples,
+ * applied to the one other place caller strings become file names in this
+ * package. But the old version got there by REPLACING every illegal character
+ * with `_`, which meant `a/b.csv` and `a_b.csv` became the same file: the
+ * second write clobbered the first's bytes, `stageInputs` answered two manifest
+ * entries pointing at one path, and the model's code opened `a/b.csv` and read
+ * whatever `a_b.csv` contained. Nothing failed. The computation was simply run
+ * against the wrong dataset — which is the worst shape a data bug can take,
+ * because the answer still looks like an answer. `.slice(0, 120)` folded the
+ * same way for any two names agreeing on their first 120 characters.
+ *
+ * So this ENCODES instead of sanitising, in two arms whose outputs cannot meet
+ * (the shape `safeSessionId` uses in `adapters/hosting/agentcore.ts`):
+ *
+ *   A. already one legal segment, not claiming to be an encoded name, and not
+ *      dots-only → returned BYTE FOR BYTE. This is what keeps the fix from
+ *      renaming anything that works today: `dataset.json`, `a_b.json`, every
+ *      name `codeRunnerTool` derives from a declared argument, all land at
+ *      exactly the path they landed at before.
+ *   B. anything else → `_enc_` + an escaped form, where `_` is the escape
+ *      character (`_` → `__`, any other illegal UTF-16 unit → `_uXXXX`). A
+ *      decoder is a left inverse of that, which is what makes it injective.
+ *
+ * Arm A never starts with `_enc_` (excluded by construction) and every arm B
+ * output does, so no name from one arm can collide with a name from the other.
+ * Both arms produce ASCII with no `/`, no `\` and no NUL, so the path-hop law
+ * the old version enforced is unchanged.
+ */
+export function safeFileName(raw) {
+    if (raw.length <= FILE_NAME_MAX &&
+        FILE_NAME_ALREADY_LEGAL.test(raw) &&
+        !raw.startsWith(ENCODED_FILE_PREFIX) &&
+        !DOTS_ONLY.test(raw)) {
+        return raw;
+    }
+    const encoded = ENCODED_FILE_PREFIX + encodeFileName(raw);
+    // Strictly less, so the two shapes below are told apart by LENGTH alone: a
+    // digested name is always exactly FILE_NAME_MAX and an escaped one never is.
+    if (encoded.length < FILE_NAME_MAX)
+        return encoded;
+    // Past the cap no mapping can stay injective — there are more names than
+    // there are file names — so the tail becomes a digest of the WHOLE raw name.
+    // SHA-256 rather than the package's 32-bit FNV-1a: a name reaching this
+    // adapter is caller data, and a 32-bit digest is a collision somebody can go
+    // and find, which for a file the model then reads as data is the same defect
+    // this function exists to close. `lib/sha256.ts` — the library's own,
+    // checked against `node:crypto` — so `agentCoreCodeRunner`, which may run
+    // where there is no `node:crypto`, encodes a name exactly as the local runner
+    // does.
+    const digest = sha256Hex(raw).slice(0, 32);
+    return `${encoded.slice(0, FILE_NAME_MAX - digest.length - 2)}_z${digest}`;
+}
+/** `_` → `__`, anything else illegal → `_uXXXX`. Injective by construction. */
+function encodeFileName(raw) {
+    let out = '';
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch === '_')
+            out += '__';
+        else if (FILE_CHAR_PASSES_THROUGH.test(ch))
+            out += ch;
+        else
+            out += `_u${raw.charCodeAt(i).toString(16).padStart(4, '0')}`;
+    }
+    return out;
+}
+//# sourceMappingURL=fileName.js.map

package/dist/esm/adapters/code/fileName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileName.js","sourceRoot":"","sources":["../../../../src/adapters/code/fileName.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;4DAC4D;AAC5D,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B;eACe;AACf,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAEpC,wEAAwE;AACxE,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAEpD;uEACuE;AACvE,MAAM,SAAS,GAAG,OAAO,CAAC;AAE1B;yBACyB;AACzB,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IACE,GAAG,CAAC,MAAM,IAAI,aAAa;QAC3B,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC;QACjC,CAAC,GAAG,CAAC,UAAU,CAAC,mBAAmB,CAAC;QACpC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EACpB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,OAAO,GAAG,mBAAmB,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IAC1D,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,OAAO,CAAC,MAAM,GAAG,aAAa;QAAE,OAAO,OAAO,CAAC;IACnD,yEAAyE;IACzE,6EAA6E;IAC7E,wEAAwE;IACxE,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,0EAA0E;IAC1E,8EAA8E;IAC9E,QAAQ;IACR,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;AAC7E,CAAC;AAED,+EAA+E;AAC/E,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAW,CAAC;QAC5B,IAAI,EAAE,KAAK,GAAG;YAAE,GAAG,IAAI,IAAI,CAAC;aACvB,IAAI,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,GAAG,IAAI,EAAE,CAAC;;YACjD,GAAG,IAAI,KAAK,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/adapters/code/local.d.ts

@@ -12,7 +12,13 @@
  *
  * What a child process DOES give you:
  *   • a separate process and heap — a crash or an OOM takes the child, not you;
- *   • kill on timeout, so runaway code has a ceiling;
+ *   • kill on timeout, so runaway code has a ceiling — on POSIX the child
+ *     runs in a process group of its own, and at the timeout, on an abort or
+ *     at the output ceiling the runner stops that OWNED group (SIGKILL). That
+ *     is cleanup, not containment: a descendant that starts its own session
+ *     or group escapes it, and a host killed before its exit handlers run
+ *     stops nothing. On Windows only the child itself can be stopped, and the
+ *     timeout error says so;
  *   • no inherited stdin, so nothing can block waiting for a terminal;
  *   • an environment ALLOWLIST — `process.env` is not inherited (only `PATH`,
  *     so the interpreter can be found), so an `AWS_SECRET_ACCESS_KEY` in your
@@ -34,11 +40,21 @@
  * is not a set this adapter can identify without guessing which of a developer's
  * files were meant, and a dev-loop runner that quietly uploaded whatever
  * appeared beside your source would be the worse failure. Producing outputs
- * needs three things this adapter does not have yet: a declared output
- * directory the model is told about, a bounded read-back of what landed in it,
- * and a size policy for what is too big to carry in-band. A runner that has
- * them (a managed sandbox that returns file contents) fills the field, and
- * `codeRunnerTool` mints every data-carrying entry with no further wiring.
+ * needs a declared output directory the model is told about and a size policy
+ * for what is too big to carry in-band; `readFile` below is the bounded
+ * read-back, for a caller that names the file. A runner that has all three
+ * fills the field, and `codeRunnerTool` mints every data-carrying entry with
+ * no further wiring.
+ *
+ * ── Files and commands ─────────────────────────────────────────────────────
+ * `readFile(path, { maxBytes })` reads ONE file back from the working
+ * directory — the path checked by the port's one rule (`sandboxPath`), then
+ * by its REAL location, so a symbolic link cannot lead it outside; a file over
+ * `maxBytes` is refused, never cut; a file on disk is bytes, so bytes come
+ * back and no encoding is guessed. `runCommand(command)` runs ONE `sh -c`
+ * command with the same environment allowlist as the code, and exists only on
+ * a runner built with `commands: true`. Neither is a network or filesystem
+ * jail: a command reaches whatever this machine reaches.
  *
  * So: a development loop, a trusted-input pipeline, a machine you would be
  * relaxed about a shell script running on. NOT arbitrary model-written code
@@ -93,19 +109,30 @@ export interface LocalCodeRunnerOptions {
      * reason over is a fragment.
      */
     readonly maxOutputChars?: number;
+    /**
+     * Give each session `runCommand` — one `sh -c` command in the working
+     * directory, with the same environment allowlist as the code. Default
+     * `false`, and then the member is ABSENT (`canRunCodeCommands` says no):
+     * it runs arbitrary shell, so a runner offers it only when built to. Build
+     * one runner per agent that should have it.
+     *
+     * Not a jail: the command reaches this machine's filesystem and network, as
+     * the code already does.
+     */
+    readonly commands?: boolean;
     /** Stable id (default `'local-code-runner'`). Rides the session events. */
     readonly id?: string;
     /** @internal Test seam — the `node:child_process` module. */
     readonly _childProcess?: ChildProcessModuleLike;
-    /** @internal Test seam — the `node:fs` slice staging uses. */
+    /** @internal Test seam — the `node:fs` slice staging and reading use. */
     readonly _fs?: FsModuleLike;
     /** @internal Test seam — where staging directories are created. Defaults to
      *  the OS temp directory. */
     readonly _stagingRoot?: string;
 }
-/** The slice of `node:fs` staging touches. Loaded lazily, and ONLY when a
- *  caller actually stages something — a session that never stages never asks
- *  this runtime for a filesystem. */
+/** The slice of `node:fs` staging and reading touch. Loaded lazily, and ONLY
+ *  when a caller actually stages or reads something — a session that does
+ *  neither never asks this runtime for a filesystem. */
 export interface FsModuleLike {
     readonly mkdtempSync?: (prefix: string) => string;
     readonly writeFileSync?: (path: string, data: string | Uint8Array) => void;
@@ -113,18 +140,70 @@ export interface FsModuleLike {
         recursive?: boolean;
         force?: boolean;
     }) => void;
+    readonly realpathSync?: (path: string) => string;
+    readonly openSync?: (path: string, flags: string | number) => number;
+    /** The open flags a read uses where the platform has them. */
+    readonly constants?: {
+        readonly O_RDONLY?: number;
+        readonly O_NONBLOCK?: number;
+        readonly O_NOFOLLOW?: number;
+    };
+    readonly fstatSync?: (fd: number) => {
+        isFile(): boolean;
+        readonly size: number;
+    };
+    readonly readSync?: (fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null) => number;
+    readonly closeSync?: (fd: number) => void;
 }
 /** The slice of `node:child_process` this adapter touches. */
 export interface ChildProcessModuleLike {
+    /** Used when present (the real module always has it): only `spawn` can give
+     *  a child a process group of its own. */
+    readonly spawn?: SpawnLike;
     readonly execFile?: (file: string, args: readonly string[], options: {
         cwd?: string;
         env?: Record<string, string>;
-        timeout?: number;
         maxBuffer?: number;
-        signal?: AbortSignal;
+        killSignal?: string;
+        detached?: boolean;
     }, callback: (error: (Error & {
         code?: number | string;
         killed?: boolean;
+        signal?: string | null;
     }) | null, stdout: string, stderr: string) => void) => unknown;
 }
+/** The part of the child `execFile` / `spawn` hands back that ending it needs. */
+interface ChildLike {
+    readonly pid?: number;
+    kill?(signal?: string): boolean;
+    readonly stdout?: {
+        destroy?(): void;
+    } | null;
+    readonly stderr?: {
+        destroy?(): void;
+    } | null;
+}
+/** A readable end of a spawned child's pipe, as far as collecting it goes. */
+interface PipeLike {
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+    destroy?(): void;
+}
+/** The child `spawn` hands back, as far as this adapter uses it. */
+interface SpawnedLike extends ChildLike {
+    readonly stdout?: PipeLike | null;
+    readonly stderr?: PipeLike | null;
+    on(event: 'error', listener: (error: Error & {
+        code?: string;
+    }) => void): unknown;
+    on(event: 'close', listener: (code: number | null, signal: string | null) => void): unknown;
+}
+/** The slice of `node:child_process` · `spawn` the runner uses — preferred
+ *  over `execFile`, which does not pass `detached` on to the child. */
+type SpawnLike = (file: string, args: readonly string[], options: {
+    cwd?: string;
+    env?: Record<string, string>;
+    detached?: boolean;
+    stdio?: readonly ['ignore', 'pipe', 'pipe'];
+}) => SpawnedLike;
 export declare function localCodeRunner(options?: LocalCodeRunnerOptions): CodeRunner;
+export {};