agentfootprint 11.5.0 → 12.0.1

package/CAPABILITIES.md

@@ -20,6 +20,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 
 | If you are about to build… | It is | Where | Since |
 |---|---|---|---|
+| moving files in and out of a code sandbox exactly and bounded, and running shell commands in it — staging text as text and bytes as bytes (AgentCore: one `writeFiles` call, `blob` for bytes, refused over the 100 MB per-call limit, `AF_STAGED_INPUTS` filled as the local runner fills it); reading ONE file back whole or not at all (paired to its path by the returned URI, a missing or different one refused; text or bytes by the field the backend filled, never the extension; over `maxBytes` refused, never cut); a shell command with bounded output, the cut stated, a checkpoint read before the cut, and an exit status only when the backend reported one — off unless the runner opts in; one path rule for both runners; a gone AgentCore session as one typed error; an outcome nobody reported kept unknown (`CodeResult.ok` absent, never success), and a failed program (`exitCode`) told apart from an unconfirmed run (`serviceError`) and a stopped process (`terminatedBy`) in the result and in the `tools.code_run` record | `CodeSession.readFile` + `CodeSession.runCommand` (runner option `commands: true`) + `canReadCodeFiles` / `canRunCodeCommands` + `CodeSandboxError` + `SessionExpiredError` + `sandboxPath` (`agentfootprint`); `agentCoreCodeRunner` / `localCodeRunner` (`agentfootprint/providers`) | `src/adapters/code/` | 12.0.0 |
 | tuning how an MCP call waits before asking again — the first wait, how it grows, jitter, a cap on the scheduled wait, a deadline for the whole call — and keeping a 429 retry and AgentCore Runtime's session-busy retry from multiplying requests: each call is ONE footprintjs `attempt()` series, the 429 rule JOINS a transport's own series instead of wrapping it (one attempt count, one waiting total, one deadline), a `Retry-After` is waited whole (never cut by the cap), and `onRetry` reports the refusal's `kind` but never arguments or answers | `retryOnThrottle` / `agentCoreRuntimeMcpTransport({ retry })` / `retryingFetch(fetch, options)`: `baseDelayMs`, `multiplier`, `jitter` (none, equal or full), `maxDelayMs`, `maxElapsedMs` beside `maxAttempts`, `maxWaitMs`, `onRetry` (`agentfootprint/providers`); AgentCore default 500 ms doubling, 5 attempts = 3.75–7.5 s of waiting | `src/mcp/throttleRetry.ts` | 11.2.0 |
 | deciding which MCP tool calls are sent again after a 429 or a lost connection — permission declared by the APP per (server, tool) at registration, never by the model, a tool description or server annotations (`readOnlyHint`); a generic 429 is not proof nothing ran, so `'app-authorized'` (opt-in) sends a call again only on the kinds its entry names (`throttle`, `network`) and otherwise returns the refusal (`not-permitted`); today's default stays as the NAMED `'compatibility'` policy, every retry recording its assumption (`permission: { by: 'compatibility', assumes: 'refused-before-execution' }`); the adapter you chose retries its own refusal (AgentCore session-busy) as its POLICY, recording `permission: { by: 'adapter', assumes: 'refused-before-execution' }` — never proof: a busy-shaped reply can come from a server that ran the call, so every attempt sent that did not complete is `unknown` and `none` is only a request never sent; `retryOnThrottle: false` turns off the 429 rule only — a declared `network` repeat keeps its series, budget and record; the side-effect guard — a tool declared `changes: true` is never sent again unless the server is declared to deduplicate by a key the call carries (`changes-without-key`); each attempt records failure, effect (`none`/`unknown`/`applied`, footprintjs's law) and permission apart, plus `durationMs`; the end counts the requests sent and keeps uncertainty (a later refusal or success never resolves an earlier `unknown`; `applied` = the call completed, never proof of a write); under `'app-authorized'` a received refusal or error (429, 503, JSON-RPC or tool error — or a chain of them) keeps the server's error, effect `unknown`, while a call that genuinely lacked an answer (an attempt with no response, or a request accepted over HTTP — 202, a stream — whose JSON-RPC answer never came: the ledger watches it by id) and then fails, fails as "may have run" (footprintjs `UnknownEffectError`, its final error the cause, `mayHaveRun: true`); `'compatibility'` keeps today's errors; `'app-authorized'` never silently weakens: it needs each request matched to its call (a library-private `_meta` marker, stripped before sending, so a copying SDK still matches) and each answer seen (checked when the `initialize` answer passes the observer), or the call is refused BEFORE it is sent with `McpReplayUnavailableError` (`sent: false`, `reason`: `answers-unobserved` for an SDK whose `connect` replaces `onmessage`, as 1.10's does; `request-unmatched` for one that drops `_meta`; `requests-unwatched` for stdio); an answer's watch ends by request id (answer, SDK cancellation, call settled, client closed), never with the HTTP send alone; a repeat re-sends the same arguments, server, session and identity | `mcpClient({ replay: { policy, tools: { [name]: { on, changes } }, deduplicates: { argument } } })` + `McpReplayOptions` + `McpReplayUnavailableError` (`agentfootprint/providers`); `effect` / `permission` / `durationMs` on `agentfootprint.tools.request_attempts` rows; `attempts` / `effect` / `mayHaveRun` on its `end` | `src/mcp/replay.ts` | 11.5.0 |
 | saving what an MCP call's retries did into the run that made the call — every attempt, why the series went on or stopped after it, each wait and any stated `Retry-After`, and how the request ended, a cancellation DURING A WAIT included — so a saved and re-read recording gives it back; concurrent calls and runs on one connection never mix; past 100 attempts the rest are counted (`omitted`), never dropped; a 503 received is `answered` with its status, never success and never retried; allow-listed metadata only (a thrown error is a fixed sentence and its category; the endpoint is the declared `endpointLabel`, else its origin; a filing is read as plain data). Every request sent is a row or counted; one cut in flight is `cut`, `remote: 'unknown'` (never recorded as not run), and only a request never sent has no row. Filed ONCE per request by the call's own footprintjs `attempt()` series (no second loop) through an internal per-dispatch port (`REQUEST_EVIDENCE`, not public API) and a per-connection ledger: the call's private `_meta` marker (taken out before sending) → JSON-RPC id → series. An MCP tool call honours its `ctx.signal` (the SDK request is cancelled, `notifications/cancelled` sent), its series stops with it, a wait included, filed the moment it lands, and a call that settles first cuts its series inside the call — never filed after its run, nothing re-sent | `agentfootprint.tools.request_attempts` / `SeriesEvidence` + `RequestLedger` | `src/mcp/` | 11.3.0 |

package/dist/adapters/code/agentcore.js

@@ -11,43 +11,70 @@
  * network-and-filesystem-isolated environment, and the tool code is identical
  * across the swap.
  *
- * ── The three operations, verified against the SDK ──────────────────────────
- * Pinned in `test/adapters/aws/awsCommandPin.ts`, and verified against a real
- * install of `@aws-sdk/client-bedrock-agentcore` 3.1108.0:
+ * ── The operations, verified against the SDK ────────────────────────────────
+ * Pinned in `test/adapters/aws/awsCommandPin.ts`. The three commands were
+ * verified against a real install of `@aws-sdk/client-bedrock-agentcore`
+ * 3.1108.0, and the four `InvokeCodeInterpreter` tool shapes below against
+ * 3.1159.0:
  *
  *   • `StartCodeInterpreterSessionCommand`
  *       in  `{ codeInterpreterIdentifier, name?, sessionTimeoutSeconds? }`
  *       out `{ codeInterpreterIdentifier, sessionId, createdAt }`
- *   • `InvokeCodeInterpreterCommand`
- *       in  `{ codeInterpreterIdentifier, sessionId, name: 'executeCode',
- *              arguments: { code, language } }`
- *       out `{ sessionId, stream }` — an **event stream**, not a body (below)
+ *   • `InvokeCodeInterpreterCommand` — `{ codeInterpreterIdentifier, sessionId,
+ *       name, arguments }`, one service tool per call:
+ *       `executeCode`    `{ code, language? }`        → `execute`
+ *       `writeFiles`     `{ content: [{ path, text } | { path, blob }] }` → `stageInputs`
+ *       `readFiles`      `{ paths: [path] }`           → `readFile`
+ *       `executeCommand` `{ command }`                 → `runCommand`
+ *     out `{ sessionId, stream }` — an **event stream**, not a body
  *   • `StopCodeInterpreterSessionCommand`
  *       in  `{ codeInterpreterIdentifier, sessionId }`   ← the session ID, not a URI
- *       out `{ codeInterpreterIdentifier, sessionId, lastUpdatedAt }`
  *
- * **`Invoke` answers with an `AsyncIterable`.** `InvokeCodeInterpreterResponse`
- * is `{ sessionId?, stream?: AsyncIterable<CodeInterpreterStreamOutput> }`, and
- * every member of that union is either `{ result }` or a modelled EXCEPTION —
- * `accessDeniedException`, `throttlingException`, `validationException`, and
- * four more. An adapter that read a `body` field would find `undefined` and
- * report an empty success on every call, and one that iterated only for
- * `result` would treat an AccessDenied as "the code printed nothing." So this
- * drains the stream, raises the exception members BY NAME, and folds the
- * result members into one `CodeResult`.
+ * **`Invoke` answers with an `AsyncIterable`** whose members are `{ result }`
+ * or a modelled EXCEPTION, and `./agentcoreClient.ts` drains it: exception
+ * members raise BY NAME, result members fold into one answer — and nothing
+ * the stream did not carry is filled in.
  *
- * The payload lands twice: `structuredContent` carries `{ stdout, stderr,
- * exitCode, executionTime }` and `content[]` carries typed blocks. The
- * structured half is preferred because it is typed; the text blocks are the
- * fallback for a response that only filled the other one.
+ * ── Results say only what the service reported ──────────────────────────────
+ * `CodeResult.ok` is `true` or `false` only when the service said which: an
+ * exit status, or its own `isError` verdict. When it reported neither, `ok`
+ * is ABSENT — unknown. (It used to be `true`: success from silence.) A
+ * command's `exitCode` is the reported one or absent, never read off `isError`.
+ *
+ * ── Files in and out, exactly and bounded ───────────────────────────────────
+ * `stageInputs` writes TEXT as text and BYTES as a blob — never base64 inside
+ * text with a decode step — in ONE `writeFiles` call, refused before it is
+ * sent when its body would pass AgentCore's 100 MB per-call limit. AgentCore
+ * takes no environment, so `AF_STAGED_INPUTS` reaches code by a setup
+ * execution before EVERY run (confirmed by the line it prints; the runtime is
+ * mutable by the code it runs, so an earlier setup proves nothing now) and
+ * reaches a command as an `export` line ahead of it. `readFile` reads ONE path
+ * and pairs the file to it by the URI the service returned — one `file:///`
+ * form, read one way, a raw query or fragment refused — failing closed on a
+ * missing or different one; text or bytes is whichever field the service
+ * filled, and a file over `maxBytes` is refused, never cut.
+ *
+ * ── Commands are opt-in ─────────────────────────────────────────────────────
+ * `runCommand` runs arbitrary shell, so a session has it only when the runner
+ * is built with `commands: true`. The sandbox's network is whatever the code
+ * interpreter resource was created with — the built-in `aws.codeinterpreter.v1`
+ * runs with AWS's most restrictive defaults (Sandbox mode: limited network
+ * access, Amazon S3 included); a custom interpreter may be Public (internet)
+ * or VPC. This adapter can neither see nor change that.
+ *
+ * ── A session that is gone says so, once ────────────────────────────────────
+ * A service error naming the session as "not active" becomes
+ * {@link SessionExpiredError} on every verb, and so does a
+ * `ResourceNotFoundException` on a verb that addresses nothing but the session
+ * (code, a command, a write). On a READ, "not found" may mean the file, so it
+ * is `CodeSandboxError` (`'file-not-returned'`), naming both possibilities —
+ * never offered as proof the session is gone.
  *
  * ── How this talks to the SDK (the 9.4.0 law) ───────────────────────────────
  * Through `client.send(new SomeCommand(input))`, never a method on the client.
  * A bare `@aws-sdk/client-*` **Client is command-based**: its prototype carries
- * `send` and `destroy` and nothing else — verified again for this adapter
- * (`BedrockAgentCoreClient.prototype.startCodeInterpreterSession` is
- * `undefined`; the shortcut exists only on the aggregated `BedrockAgentCore`).
- * Three adapters have shipped that bug in this package.
+ * `send` and `destroy` and nothing else. Three adapters have shipped that bug
+ * in this package.
  *
  * ── Credentials ─────────────────────────────────────────────────────────────
  * Standard AWS credential resolution (the SDK's own chain). A tool holding a
@@ -60,17 +87,23 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentCoreCodeRunner = void 0;
+const codeSandbox_js_1 = require("../../provider-contract/codeSandbox.js");
+const sessionExpired_js_1 = require("../../provider-contract/sessionExpired.js");
 const toolSessions_js_1 = require("../../tools/toolSessions.js");
-const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+const abort_js_1 = require("../../lib/abort.js");
+const agentcoreClient_js_1 = require("./agentcoreClient.js");
+const agentcoreWire_js_1 = require("./agentcoreWire.js");
+const fileName_js_1 = require("./fileName.js");
+const output_js_1 = require("./output.js");
 const DEFAULT_MAX_OUTPUT_CHARS = 8_000;
-/** The service's own name for "run this code". Not a name we chose. */
-const EXECUTE_CODE = 'executeCode';
+/** The adapter's own name, on every refusal it raises. */
+const BACKEND = 'agentCoreCodeRunner';
 function agentCoreCodeRunner(options) {
     const id = options.id ?? 'agentcore-code-runner';
     const maxOutputChars = options.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
     let client;
     const resolve = () => {
-        client ??= options._client ?? createCodeClient(options);
+        client ??= options._client ?? (0, agentcoreClient_js_1.createCodeClient)(options);
         return client;
     };
     return {
@@ -94,66 +127,242 @@ function agentCoreCodeRunner(options) {
                     'Nothing can be invoked or stopped without one, so this is raised rather than ' +
                     'carried forward as an unusable session.');
             }
-            let stopped = false;
+            return openSession({
+                api,
+                identifier: options.identifier,
+                sessionId,
+                language: req.language ?? options.language,
+                maxOutputChars,
+                commands: options.commands === true,
+            });
+        },
+    };
+}
+exports.agentCoreCodeRunner = agentCoreCodeRunner;
+/** The session behind {@link agentCoreCodeRunner}: the verbs, in the order a caller uses them. */
+function openSession(plan) {
+    const { api, identifier, sessionId, maxOutputChars } = plan;
+    const target = { codeInterpreterIdentifier: identifier, sessionId };
+    let stopped = false;
+    /** name → path, exactly as the manifest carries it. */
+    const staged = new Map();
+    const refuseIfStopped = (toDo) => {
+        if (stopped) {
+            throw new Error(`agentCoreCodeRunner: session ${sessionId} was stopped; open a new one to ${toDo}.`);
+        }
+    };
+    const manifestJson = () => staged.size > 0 ? JSON.stringify(Object.fromEntries(staged)) : undefined;
+    /**
+     * One deadline and one cancellation for a whole verb. A verb that makes two
+     * calls — the manifest setup, then the code — spends ONE `timeoutMs`, not
+     * one each. A deadline or the caller's own signal stops the WAIT at once
+     * (`lib/abort.ts`); what the service does with a request it already
+     * received is its own business, and the timeout error says so.
+     */
+    const withinBounds = async (verb, bounds, work) => {
+        (0, abort_js_1.throwIfAborted)(bounds.signal);
+        const { controller, unlink } = (0, abort_js_1.linkedController)(bounds.signal);
+        const disarm = bounds.timeoutMs === undefined
+            ? undefined
+            : (0, abort_js_1.armDeadline)(controller, bounds.timeoutMs, () => new codeSandbox_js_1.CodeSandboxError('timed-out', `agentCoreCodeRunner: ${verb} did not answer within ${bounds.timeoutMs}ms ` +
+                'and was abandoned. The session was not stopped, so what was sent may still ' +
+                'be running in it — whether it finished is not known.'));
+        try {
+            return await work(controller.signal);
+        }
+        finally {
+            disarm?.();
+            unlink();
+        }
+    };
+    /**
+     * One invoke under `signal`. A gone session becomes `SessionExpiredError`;
+     * a modelled service error on a file or command call is rewritten without
+     * the service's words (they can quote what was sent).
+     */
+    const invoke = async (input, signal) => {
+        (0, abort_js_1.throwIfAborted)(signal);
+        try {
+            return await (0, abort_js_1.untilAborted)(api.invoke(input, { abortSignal: signal }), signal);
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw (0, abort_js_1.abortErrorOf)(signal);
+            const evidence = (0, agentcoreWire_js_1.sessionExpiryEvidence)(err, input.name);
+            if (evidence === 'session') {
+                throw new sessionExpired_js_1.SessionExpiredError(BACKEND, sessionId, (0, agentcoreWire_js_1.errorNameOf)(err));
+            }
+            if (evidence === 'file-or-session' && input.name === 'readFiles') {
+                // A read names a FILE as well as the session, so "not found" can mean
+                // either. It is not taken as proof the session is gone.
+                throw new codeSandbox_js_1.CodeSandboxError('file-not-returned', `agentCoreCodeRunner: reading '${input.arguments.paths.join(', ')}' — the service ` +
+                    'answered ResourceNotFoundException, which can mean the file is missing or the ' +
+                    'session is gone; which one is not known here.', { path: input.arguments.paths[0] ?? '' });
+            }
+            if (input.name === 'executeCode')
+                throw err;
+            throw (0, agentcoreWire_js_1.serviceRefusal)(err, input.name) ?? err;
+        }
+    };
+    /**
+     * Set {@link STAGED_INPUTS_ENV} in the runtime `language` runs in — before
+     * EVERY execution once anything is staged, and confirmed each time.
+     *
+     * Never skipped because this process set it before: the runtime is mutable
+     * by the very code it runs, so a previous execution may have changed or
+     * deleted the variable, and a record of what was once sent is not an
+     * observation of what the runtime holds. Re-applying it costs one call per
+     * execution, inside the same deadline. Nothing when nothing was staged — a
+     * session that never stages sends exactly what it always sent.
+     */
+    const exposeManifest = async (language, signal) => {
+        const json = manifestJson();
+        if (json === undefined)
+            return;
+        const runtime = (0, agentcoreWire_js_1.manifestRuntime)(language);
+        if (runtime === undefined) {
+            throw new codeSandbox_js_1.CodeSandboxError('staged-inputs-unset', `agentCoreCodeRunner: inputs were staged, and this adapter does not know how to set ` +
+                `AF_STAGED_INPUTS for language '${String(language)}', so the code is not run against ` +
+                'a manifest it could not read. AgentCore runs python, javascript and typescript.');
+        }
+        const answer = await invoke({
+            ...target,
+            name: 'executeCode',
+            arguments: { code: (0, agentcoreWire_js_1.manifestSetupCode)(runtime, json), ...(language ? { language } : {}) },
+        }, signal);
+        // The setup prints one line once the variable is set — it proves that
+        // checkpoint and nothing else, which is all that is asked of it.
+        if (!(0, output_js_1.printedLine)(answer.stdout, agentcoreWire_js_1.MANIFEST_SET_MARKER)) {
+            throw new codeSandbox_js_1.CodeSandboxError('staged-inputs-unset', `agentCoreCodeRunner: the staged inputs are in the session, but setting AF_STAGED_INPUTS ` +
+                `in its ${runtime} runtime was not confirmed, so the code is not run against a ` +
+                'manifest it may not be able to read.');
+        }
+    };
+    const session = {
+        id: sessionId,
+        async execute(exec) {
+            refuseIfStopped('run more code');
+            const language = exec.language ?? plan.language;
+            const bounds = {
+                ...(exec.timeoutMs !== undefined && { timeoutMs: exec.timeoutMs }),
+                ...(exec.signal && { signal: exec.signal }),
+            };
+            const answer = await withinBounds('executeCode', bounds, async (signal) => {
+                await exposeManifest(language, signal);
+                return invoke({
+                    ...target,
+                    name: 'executeCode',
+                    arguments: { code: exec.code, ...(language ? { language } : {}) },
+                }, signal);
+            });
+            const bounded = (0, output_js_1.boundOutput)(answer.stdout, answer.stderr, maxOutputChars);
+            const ok = reportedOutcome(answer);
+            // An error flag with no exit status is the SERVICE's verdict, not the
+            // program's: whether the code ran is unconfirmed, and the result says
+            // which kind of `false` it is.
+            const serviceError = answer.isError === true && answer.exitCode === undefined;
             return {
-                id: sessionId,
-                async execute(exec) {
-                    if (stopped) {
-                        throw new Error(`agentCoreCodeRunner: session ${sessionId} was stopped; open a new one to run more code.`);
-                    }
-                    const answer = await api.invoke({
-                        codeInterpreterIdentifier: options.identifier,
-                        sessionId,
-                        name: EXECUTE_CODE,
-                        arguments: {
-                            code: exec.code,
-                            ...(exec.language ?? req.language ?? options.language
-                                ? { language: exec.language ?? req.language ?? options.language ?? 'python' }
-                                : {}),
-                        },
-                    });
-                    const stdout = cut(answer.stdout, maxOutputChars);
-                    const stderr = cut(answer.stderr, maxOutputChars);
-                    const truncated = {
-                        ...(stdout.cut && { stdout: true }),
-                        ...(stderr.cut && { stderr: true }),
-                        ...((stdout.cut || stderr.cut) && {
-                            ofChars: Math.max(answer.stdout.length, answer.stderr.length),
-                        }),
-                    };
-                    return {
-                        // `isError` is the service's own verdict; a non-zero exit is ours.
-                        ok: answer.isError !== true && (answer.exitCode ?? 0) === 0,
-                        stdout: stdout.text,
-                        stderr: stderr.text,
-                        ...(answer.exitCode !== undefined && { exitCode: answer.exitCode }),
-                        ...(Object.keys(truncated).length > 0 && { truncated }),
-                    };
-                },
-                async stop() {
-                    if (stopped)
-                        return;
-                    stopped = true;
-                    try {
-                        await api.stopSession({
-                            codeInterpreterIdentifier: options.identifier,
-                            sessionId,
-                        });
-                    }
-                    catch (err) {
-                        // "Already gone" is the EXPECTED shape here, not an incident: the
-                        // session TTL is enforced by AWS, so a run that idled past it finds
-                        // the session collected. Anything else is re-raised, and the tier
-                        // reports it on `tools.session_close_failed`.
-                        if (!isAlreadyGone(err))
-                            throw err;
-                    }
-                },
+                ...(ok !== undefined && { ok }),
+                stdout: bounded.stdout,
+                stderr: bounded.stderr,
+                ...(answer.exitCode !== undefined && { exitCode: answer.exitCode }),
+                ...(serviceError && { serviceError: true }),
+                ...(bounded.truncated !== undefined && { truncated: bounded.truncated }),
             };
         },
+        async stageInputs(inputs) {
+            refuseIfStopped('stage inputs');
+            if (inputs.length === 0)
+                return [];
+            // The name is CALLER data landing in a filesystem, so it is ENCODED
+            // into one inert segment — the same encoder `localCodeRunner` uses, so
+            // a name lands under the same file name on either backend.
+            const landing = inputs.map((input) => ({
+                input,
+                path: `${agentcoreWire_js_1.STAGED_INPUTS_DIR}/${(0, fileName_js_1.safeFileName)(input.fileName ?? input.name)}`,
+            }));
+            const content = landing.map(({ input, path }) => (0, agentcoreWire_js_1.fileContent)(path, input.data));
+            const bytes = (0, agentcoreWire_js_1.writeFilesRequestBytes)(content);
+            if (bytes > agentcoreWire_js_1.AGENTCORE_MAX_REQUEST_BYTES) {
+                throw new codeSandbox_js_1.CodeSandboxError('request-too-large', `agentCoreCodeRunner: staging these ${inputs.length} input(s) would send a ` +
+                    `${bytes}-byte request, and AgentCore takes at most ${agentcoreWire_js_1.AGENTCORE_MAX_REQUEST_BYTES} ` +
+                    'bytes in one call. Nothing was sent. Stage fewer or smaller inputs per call, or ' +
+                    'have the code fetch large data itself (from Amazon S3, for example).', { bytes, limit: agentcoreWire_js_1.AGENTCORE_MAX_REQUEST_BYTES });
+            }
+            const answer = await withinBounds('writeFiles', {}, (signal) => invoke({ ...target, name: 'writeFiles', arguments: { content } }, signal));
+            if (answer.isError === true) {
+                throw new codeSandbox_js_1.CodeSandboxError('write-failed', 'agentCoreCodeRunner: the service flagged the write of the staged inputs as an error, ' +
+                    'so which of them landed is not known. Its words are not repeated here.');
+            }
+            for (const { input, path } of landing)
+                staged.set(input.name, path);
+            return landing.map(({ input, path }) => ({
+                name: input.name,
+                path,
+                bytes: (0, output_js_1.payloadBytes)(input.data),
+            }));
+        },
+        async readFile(path, readOptions) {
+            refuseIfStopped('read files');
+            const maxBytes = (0, codeSandbox_js_1.readBound)(readOptions);
+            const relative = (0, codeSandbox_js_1.sandboxPath)(path);
+            const answer = await withinBounds('readFiles', { ...(readOptions.signal && { signal: readOptions.signal }) }, (signal) => invoke({ ...target, name: 'readFiles', arguments: { paths: [relative] } }, signal));
+            return (0, agentcoreWire_js_1.pairReadFile)(relative, answer, maxBytes);
+        },
+        ...(plan.commands && {
+            async runCommand(command, commandOptions) {
+                refuseIfStopped('run commands');
+                const bounds = (0, output_js_1.commandBounds)(command, commandOptions, maxOutputChars);
+                const json = manifestJson();
+                const answer = await withinBounds('executeCommand', {
+                    ...(bounds.timeoutMs !== undefined && { timeoutMs: bounds.timeoutMs }),
+                    ...(bounds.signal && { signal: bounds.signal }),
+                }, (signal) => invoke({
+                    ...target,
+                    name: 'executeCommand',
+                    arguments: {
+                        command: json === undefined ? command : (0, agentcoreWire_js_1.withManifestExport)(command, json),
+                    },
+                }, signal));
+                return (0, output_js_1.commandResult)(answer, bounds);
+            },
+        }),
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            staged.clear();
+            try {
+                await api.stopSession({ codeInterpreterIdentifier: identifier, sessionId });
+            }
+            catch (err) {
+                // "Already gone" is the EXPECTED shape here, not an incident: the
+                // session TTL is enforced by AWS, so a run that idled past it finds
+                // the session collected. Anything else is re-raised, and the tier
+                // reports it on `tools.session_close_failed`.
+                if (!isAlreadyGone(err))
+                    throw err;
+            }
+        },
     };
+    return session;
+}
+/**
+ * Did the code complete — as far as the service SAID?
+ *
+ * Its own error verdict first, then an exit status, then its explicit
+ * "not an error". When it said none of those, the answer is `undefined`:
+ * unknown, never success from silence.
+ */
+function reportedOutcome(answer) {
+    if (answer.isError === true)
+        return false;
+    if (answer.exitCode !== undefined)
+        return answer.exitCode === 0;
+    if (answer.isError === false)
+        return true;
+    return undefined;
 }
-exports.agentCoreCodeRunner = agentCoreCodeRunner;
 /**
  * A label for the remote session — derived FROM the isolation key, carrying
  * none of it.
@@ -181,7 +390,8 @@ exports.agentCoreCodeRunner = agentCoreCodeRunner;
  * nothing — here or in the SDK — ever looks a session up by it. The address is
  * the service-assigned `sessionId`, which `start()` reads back and passes to
  * every `Invoke` and `Stop` verbatim. So no stored state is keyed on this
- * string and relabelling migrates nothing.
+ * string and relabelling migrates nothing — and no session is ever reattached
+ * by it.
  */
 function sessionName(key) {
     return `af-${(0, toolSessions_js_1.hashSessionKey)(key)}`;
@@ -190,133 +400,4 @@ function isAlreadyGone(err) {
     const name = err instanceof Error ? err.name : '';
     return name === 'ResourceNotFoundException' || name === 'ValidationException';
 }
-/**
- * Map {@link AgentCoreCodeClientLike} onto the real SDK commands.
- *
- * Two things this function owns and nothing else does: the COMMAND FORM (see
- * the module header), and the DRAIN of `InvokeCodeInterpreterResponse.stream`.
- */
-function createCodeClient(options) {
-    let mod;
-    if (options._sdk) {
-        mod = options._sdk;
-    }
-    else {
-        try {
-            // Lazy peer-dep: only loaded when no _client/_sdk is injected and start() runs.
-            mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-bedrock-agentcore');
-        }
-        catch {
-            throw new Error('agentCoreCodeRunner requires the `@aws-sdk/client-bedrock-agentcore` peer dependency.\n' +
-                '  Install:  npm install @aws-sdk/client-bedrock-agentcore\n' +
-                '  Or pass `_client` for a pre-built or mock client.\n' +
-                '  For a local dev loop with no AWS at all, use `localCodeRunner()`.');
-        }
-    }
-    if (!mod.BedrockAgentCoreClient) {
-        throw new Error('agentCoreCodeRunner: `@aws-sdk/client-bedrock-agentcore` is installed but ' +
-            '`BedrockAgentCoreClient` was not found. Update the SDK.');
-    }
-    const sdk = new mod.BedrockAgentCoreClient({ ...(options.region && { region: options.region }) });
-    const send = async (Ctor, name, input) => {
-        if (!Ctor) {
-            throw new Error(`agentCoreCodeRunner: \`@aws-sdk/client-bedrock-agentcore\` is missing ${name}. ` +
-                'Upgrade the SDK, or pass `_client` with your own mapping.');
-        }
-        return sdk.send(new Ctor(input));
-    };
-    return {
-        async startSession(input) {
-            const r = (await send(mod.StartCodeInterpreterSessionCommand, 'StartCodeInterpreterSessionCommand', input));
-            return { ...(r?.sessionId !== undefined && { sessionId: r.sessionId }) };
-        },
-        async invoke(input) {
-            const r = (await send(mod.InvokeCodeInterpreterCommand, 'InvokeCodeInterpreterCommand', input));
-            return drainStream(r?.stream);
-        },
-        async stopSession(input) {
-            await send(mod.StopCodeInterpreterSessionCommand, 'StopCodeInterpreterSessionCommand', input);
-        },
-    };
-}
-/** Every modelled error member of the stream union, in SDK spelling. */
-const STREAM_ERROR_MEMBERS = [
-    'accessDeniedException',
-    'conflictException',
-    'internalServerException',
-    'resourceNotFoundException',
-    'serviceQuotaExceededException',
-    'throttlingException',
-    'validationException',
-];
-/**
- * Drain the event stream into one answer.
- *
- * An ERROR MEMBER RAISES. This is the honesty line for this adapter: the SDK
- * models seven failure shapes as ordinary members of the stream union, so an
- * `AccessDeniedException` arrives as a value, not a rejection. Folding it in
- * as empty output would report a clean run in which the code "printed
- * nothing" — a silent success, at the exact moment an operator most needs the
- * word "AccessDenied".
- */
-async function drainStream(stream) {
-    if (!stream) {
-        throw new Error('agentCoreCodeRunner: InvokeCodeInterpreter returned no stream. The response carries ' +
-            'its payload as an event stream (`response.stream`), so an absent one is a broken ' +
-            'call, not an empty result.');
-    }
-    let stdout = '';
-    let stderr = '';
-    let exitCode;
-    let isError = false;
-    for await (const event of stream) {
-        for (const member of STREAM_ERROR_MEMBERS) {
-            const raised = event[member];
-            if (raised) {
-                const error = new Error(`agentCoreCodeRunner: ${member} from InvokeCodeInterpreter — ` +
-                    `${raised.message ?? 'no message supplied'}`);
-                error.name = member.charAt(0).toUpperCase() + member.slice(1);
-                throw error;
-            }
-        }
-        const result = event.result;
-        if (!result)
-            continue;
-        if (result.isError === true)
-            isError = true;
-        const structured = result.structuredContent;
-        if (structured) {
-            if (structured.stdout !== undefined)
-                stdout += structured.stdout;
-            if (structured.stderr !== undefined)
-                stderr += structured.stderr;
-            if (structured.exitCode !== undefined)
-                exitCode = structured.exitCode;
-        }
-        else {
-            // Fallback: a response that filled only the typed content blocks. Text
-            // blocks are the readable half; a binary/resource block is described by
-            // name rather than inlined, because inlining it is the bug this port exists
-            // to prevent.
-            for (const block of result.content ?? []) {
-                if (block.text !== undefined)
-                    stdout += block.text;
-                else if (block.name !== undefined)
-                    stdout += `[${block.type ?? 'resource'}: ${block.name}]`;
-            }
-        }
-    }
-    return {
-        stdout,
-        stderr,
-        ...(exitCode !== undefined && { exitCode }),
-        ...(isError && { isError }),
-    };
-}
-/** Cut to `max` characters, saying whether it cut. */
-function cut(text, max) {
-    if (text.length <= max)
-        return { text, cut: false };
-    return { text: text.slice(0, max), cut: true };
-}
 //# sourceMappingURL=agentcore.js.map