agentfootprint 11.4.0 → 12.0.0

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

@@ -10,43 +10,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
@@ -58,11 +85,14 @@
  * `start()` first runs (or never, if you inject `_client` / `_sdk`).
  */
 import type { CodeRunner } from '../../provider-contract/types.js';
+import { type AgentCoreCodeClientLike, type BedrockAgentCoreCodeSdkModule } from './agentcoreClient.js';
+export type { AgentCoreCodeClientLike, AgentCoreFileContent, AgentCoreInvokeAnswer, AgentCoreInvokeInput, AgentCoreInvokeTarget, AgentCoreResource, BedrockAgentCoreCodeSdkModule, } from './agentcoreClient.js';
 export interface AgentCoreCodeRunnerOptions {
     readonly region?: string;
     /**
      * The code-interpreter resource to run in — AWS's built-in
      * (`'aws.codeinterpreter.v1'`) or your own custom interpreter's identifier.
+     * Its network mode (Sandbox, Public or VPC) is set on the resource, not here.
      */
     readonly identifier: string;
     /**
@@ -71,7 +101,8 @@ export interface AgentCoreCodeRunnerOptions {
      *
      * **This is why "already gone" is a normal outcome, not an incident**: the
      * far side reaps on its own schedule, so a `Stop` may arrive after AWS has
-     * already collected the session. `stop()` treats that as done.
+     * already collected the session. `stop()` treats that as done, and every
+     * other verb raises `SessionExpiredError`.
      */
     readonly sessionTimeoutSeconds?: number;
     /** Default language when a call does not name one. `'python'` (the service
@@ -80,54 +111,20 @@ export interface AgentCoreCodeRunnerOptions {
     /** Per-stream output ceiling, in characters. Default 8000; anything cut is
      *  REPORTED on `CodeResult.truncated`, never dropped quietly. */
     readonly maxOutputChars?: number;
+    /**
+     * Give each session `runCommand` — one shell command through AgentCore's
+     * `executeCommand`. 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.
+     */
+    readonly commands?: boolean;
     /** Stable id (default `'agentcore-code-runner'`). Rides the session events. */
     readonly id?: string;
     /** Test seam — inject a client implementing {@link AgentCoreCodeClientLike}.
-     *  Bypasses the SDK entirely; the field mapping below is then yours. */
+     *  Bypasses the SDK entirely; the field mapping is then yours. */
     readonly _client?: AgentCoreCodeClientLike;
     /** @internal Test injection — the AWS SDK module, to exercise the real shim
      *  (`send(new Command(...))`) with a fake SDK. */
     readonly _sdk?: BedrockAgentCoreCodeSdkModule;
 }
-/** The operation-semantic surface this adapter calls. */
-export interface AgentCoreCodeClientLike {
-    startSession(input: {
-        readonly codeInterpreterIdentifier: string;
-        readonly name?: string;
-        readonly sessionTimeoutSeconds?: number;
-    }): Promise<{
-        readonly sessionId?: string;
-    }>;
-    invoke(input: {
-        readonly codeInterpreterIdentifier: string;
-        readonly sessionId: string;
-        readonly name: string;
-        readonly arguments: {
-            readonly code: string;
-            readonly language?: string;
-        };
-    }): Promise<AgentCoreInvokeAnswer>;
-    stopSession(input: {
-        readonly codeInterpreterIdentifier: string;
-        readonly sessionId: string;
-    }): Promise<void>;
-}
-/** What `invoke` reports back, already drained of its event stream. */
-export interface AgentCoreInvokeAnswer {
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly exitCode?: number;
-    readonly isError?: boolean;
-}
-/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
-export interface BedrockAgentCoreCodeSdkModule {
-    readonly BedrockAgentCoreClient?: new (config: {
-        region?: string;
-    }) => {
-        send(cmd: unknown): Promise<unknown>;
-    };
-    readonly StartCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
-    readonly InvokeCodeInterpreterCommand?: new (input: unknown) => unknown;
-    readonly StopCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
-}
 export declare function agentCoreCodeRunner(options: AgentCoreCodeRunnerOptions): CodeRunner;