agentfootprint 11.4.0 → 12.0.0

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

@@ -0,0 +1,193 @@
+/**
+ * The AgentCore Code Interpreter client seam: the operation-semantic surface
+ * `agentCoreCodeRunner` calls, and its ONE mapping onto the real SDK.
+ *
+ * Two things this file owns and nothing else does:
+ *
+ *   • the COMMAND FORM — a bare `@aws-sdk/client-*` client is command-based:
+ *     `client.send(new SomeCommand(input))`, never a method on the client
+ *     (the 9.4.0 law; `BedrockAgentCoreClient.prototype.startCodeInterpreterSession`
+ *     is `undefined`, the shortcut exists only on the aggregated client);
+ *   • the DRAIN of `InvokeCodeInterpreterResponse.stream`, an event stream
+ *     whose members are `{ result }` or a modelled EXCEPTION.
+ *
+ * The request and response shapes below were read off a real install of
+ * `@aws-sdk/client-bedrock-agentcore` 3.1159.0 (`InvokeCodeInterpreterRequest`,
+ * `ToolArguments`, `InputContentBlock`, `CodeInterpreterResult`,
+ * `ResourceContent`, `ToolResultStructuredContent`) and are pinned against
+ * transcribed copies of those types in
+ * `test/type-regressions/AgentCoreCodeInterpreter.sdk.test.ts`.
+ *
+ * Pattern: Adapter (GoF) + lazy peer-dep load — the SDK is required only when
+ * a session first starts (or never, if you inject `_client` / `_sdk`).
+ */
+/** The operation-semantic surface `agentCoreCodeRunner` calls. Inject your own as `_client`. */
+export interface AgentCoreCodeClientLike {
+    startSession(input: {
+        readonly codeInterpreterIdentifier: string;
+        readonly name?: string;
+        readonly sessionTimeoutSeconds?: number;
+    }): Promise<{
+        readonly sessionId?: string;
+    }>;
+    /**
+     * One `InvokeCodeInterpreter` call, its event stream already drained.
+     *
+     * `options.abortSignal` cancels the request where the client can; the
+     * adapter also stops WAITING when it fires, so a client that ignores it
+     * cannot hold a caller open.
+     */
+    invoke(input: AgentCoreInvokeInput, options?: {
+        readonly abortSignal?: AbortSignal;
+    }): Promise<AgentCoreInvokeAnswer>;
+    stopSession(input: {
+        readonly codeInterpreterIdentifier: string;
+        readonly sessionId: string;
+    }): Promise<void>;
+}
+/** Which interpreter, and which of its sessions, one invoke goes to. */
+export interface AgentCoreInvokeTarget {
+    readonly codeInterpreterIdentifier: string;
+    readonly sessionId: string;
+}
+/**
+ * One file for `writeFiles` — AgentCore's `InputContentBlock`: TEXT for a
+ * string, BYTES for a `Uint8Array`, never both, and never bytes smuggled
+ * through text as base64.
+ */
+export type AgentCoreFileContent = {
+    readonly path: string;
+    readonly text: string;
+    readonly blob?: never;
+} | {
+    readonly path: string;
+    readonly blob: Uint8Array;
+    readonly text?: never;
+};
+/**
+ * One `InvokeCodeInterpreter` request: the four of the service's tool names
+ * this adapter sends, each with exactly the arguments AgentCore takes for it.
+ */
+export type AgentCoreInvokeInput = AgentCoreInvokeTarget & ({
+    readonly name: 'executeCode';
+    readonly arguments: {
+        readonly code: string;
+        readonly language?: string;
+    };
+} | {
+    readonly name: 'executeCommand';
+    readonly arguments: {
+        readonly command: string;
+    };
+} | {
+    readonly name: 'writeFiles';
+    readonly arguments: {
+        readonly content: readonly AgentCoreFileContent[];
+    };
+} | {
+    readonly name: 'readFiles';
+    readonly arguments: {
+        readonly paths: readonly string[];
+    };
+});
+/** What `invoke` reports back, already drained of its event stream — only what the service sent. */
+export interface AgentCoreInvokeAnswer {
+    readonly stdout: string;
+    readonly stderr: string;
+    /** The exit status the service reported; absent when no result carried one. */
+    readonly exitCode?: number;
+    /**
+     * The service's own error flag: `true` when any result was flagged, `false`
+     * when results said `false` and none said `true`, ABSENT when no result
+     * carried the flag at all. Absent is not `false`.
+     */
+    readonly isError?: boolean;
+    /** Every embedded resource the answer carried, in order — what `readFiles`
+     *  answers with. Absent when there were none. */
+    readonly resources?: readonly AgentCoreResource[];
+}
+/** One embedded resource (AgentCore's `ResourceContent`), as the service sent it. */
+export interface AgentCoreResource {
+    readonly uri?: string;
+    readonly mimeType?: string;
+    readonly text?: string;
+    readonly blob?: Uint8Array;
+}
+/** The slice of `@aws-sdk/client-bedrock-agentcore` this shim touches. */
+export interface BedrockAgentCoreCodeSdkModule {
+    readonly BedrockAgentCoreClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown, options?: {
+            abortSignal?: AbortSignal;
+        }): Promise<unknown>;
+    };
+    readonly StartCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
+    readonly InvokeCodeInterpreterCommand?: new (input: unknown) => unknown;
+    readonly StopCodeInterpreterSessionCommand?: new (input: unknown) => unknown;
+}
+/**
+ * Map {@link AgentCoreCodeClientLike} onto the real SDK commands.
+ */
+export declare function createCodeClient(options: {
+    readonly region?: string;
+    readonly _sdk?: BedrockAgentCoreCodeSdkModule;
+}): AgentCoreCodeClientLike;
+/** One event off `InvokeCodeInterpreterResponse.stream` — the fields this adapter reads. */
+export interface CodeInterpreterStreamOutputLike {
+    readonly result?: {
+        readonly content?: readonly {
+            readonly type?: string;
+            readonly text?: string;
+            readonly name?: string;
+            readonly resource?: AgentCoreResource;
+        }[];
+        readonly structuredContent?: {
+            readonly stdout?: string;
+            readonly stderr?: string;
+            readonly exitCode?: number;
+        };
+        readonly isError?: boolean;
+    };
+    readonly accessDeniedException?: {
+        readonly message?: string;
+    };
+    readonly conflictException?: {
+        readonly message?: string;
+    };
+    readonly internalServerException?: {
+        readonly message?: string;
+    };
+    readonly resourceNotFoundException?: {
+        readonly message?: string;
+    };
+    readonly serviceQuotaExceededException?: {
+        readonly message?: string;
+    };
+    readonly throttlingException?: {
+        readonly message?: string;
+    };
+    readonly validationException?: {
+        readonly message?: string;
+    };
+}
+/** Every modelled error member of the stream union, in SDK spelling. */
+export declare const STREAM_ERROR_MEMBERS: readonly ["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".
+ *
+ * Nothing is filled in that the stream did not carry: no exit status, no
+ * error flag. And a file operation whose stream ended with no result at all
+ * (`requireResult`) is a broken call, not an empty answer.
+ */
+export declare function drainStream(stream: AsyncIterable<CodeInterpreterStreamOutputLike> | undefined, options: {
+    readonly requireResult: boolean;
+    readonly signal?: AbortSignal;
+}): Promise<AgentCoreInvokeAnswer>;

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

@@ -0,0 +1,173 @@
+/**
+ * The AgentCore Code Interpreter client seam: the operation-semantic surface
+ * `agentCoreCodeRunner` calls, and its ONE mapping onto the real SDK.
+ *
+ * Two things this file owns and nothing else does:
+ *
+ *   • the COMMAND FORM — a bare `@aws-sdk/client-*` client is command-based:
+ *     `client.send(new SomeCommand(input))`, never a method on the client
+ *     (the 9.4.0 law; `BedrockAgentCoreClient.prototype.startCodeInterpreterSession`
+ *     is `undefined`, the shortcut exists only on the aggregated client);
+ *   • the DRAIN of `InvokeCodeInterpreterResponse.stream`, an event stream
+ *     whose members are `{ result }` or a modelled EXCEPTION.
+ *
+ * The request and response shapes below were read off a real install of
+ * `@aws-sdk/client-bedrock-agentcore` 3.1159.0 (`InvokeCodeInterpreterRequest`,
+ * `ToolArguments`, `InputContentBlock`, `CodeInterpreterResult`,
+ * `ResourceContent`, `ToolResultStructuredContent`) and are pinned against
+ * transcribed copies of those types in
+ * `test/type-regressions/AgentCoreCodeInterpreter.sdk.test.ts`.
+ *
+ * Pattern: Adapter (GoF) + lazy peer-dep load — the SDK is required only when
+ * a session first starts (or never, if you inject `_client` / `_sdk`).
+ */
+import { abortableIterable } from '../../lib/abort.js';
+import { lazyRequire } from '../../lib/lazyRequire.js';
+/** The tool names whose answer is only an answer if it carried a result. */
+const RESULT_REQUIRED = new Set([
+    'writeFiles',
+    'readFiles',
+]);
+/**
+ * Map {@link AgentCoreCodeClientLike} onto the real SDK commands.
+ */
+export 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 = 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, abortSignal) => {
+        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 abortSignal ? sdk.send(new Ctor(input), { abortSignal }) : 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, invokeOptions) {
+            const abortSignal = invokeOptions?.abortSignal;
+            const r = (await send(mod.InvokeCodeInterpreterCommand, 'InvokeCodeInterpreterCommand', input, abortSignal));
+            return drainStream(r?.stream, {
+                requireResult: RESULT_REQUIRED.has(input.name),
+                ...(abortSignal && { signal: abortSignal }),
+            });
+        },
+        async stopSession(input) {
+            await send(mod.StopCodeInterpreterSessionCommand, 'StopCodeInterpreterSessionCommand', input);
+        },
+    };
+}
+/** Every modelled error member of the stream union, in SDK spelling. */
+export 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".
+ *
+ * Nothing is filled in that the stream did not carry: no exit status, no
+ * error flag. And a file operation whose stream ended with no result at all
+ * (`requireResult`) is a broken call, not an empty answer.
+ */
+export async function drainStream(stream, options) {
+    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;
+    let results = 0;
+    const resources = [];
+    for await (const event of abortableIterable(stream, options.signal)) {
+        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;
+        results += 1;
+        if (result.isError === true)
+            isError = true;
+        else if (result.isError === false && isError === undefined)
+            isError = false;
+        for (const block of result.content ?? []) {
+            if (block.resource !== undefined && block.resource !== null)
+                resources.push(block.resource);
+        }
+        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}]`;
+            }
+        }
+    }
+    if (options.requireResult && results === 0) {
+        throw new Error('agentCoreCodeRunner: InvokeCodeInterpreter answered a file operation with no result. ' +
+            'Nothing confirmed it, so it is not reported as done.');
+    }
+    return {
+        stdout,
+        stderr,
+        ...(exitCode !== undefined && { exitCode }),
+        ...(isError !== undefined && { isError }),
+        ...(resources.length > 0 && { resources }),
+    };
+}
+//# sourceMappingURL=agentcoreClient.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agentcoreClient.js","sourceRoot":"","sources":["../../../../src/adapters/code/agentcoreClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA8FvD,4EAA4E;AAC5E,MAAM,eAAe,GAA8C,IAAI,GAAG,CAAC;IACzE,YAAY;IACZ,WAAW;CACZ,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAGhC;IACC,IAAI,GAAkC,CAAC;IACvC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IACrB,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,gFAAgF;YAChF,GAAG,GAAG,WAAW,CAAgC,mCAAmC,CAAC,CAAC;QACxF,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACvF,6DAA6D;gBAC7D,uDAAuD;gBACvD,qEAAqE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAElG,MAAM,IAAI,GAAG,KAAK,EAChB,IAA+C,EAC/C,IAAY,EACZ,KAAc,EACd,WAAyB,EACP,EAAE;QACpB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,yEAAyE,IAAI,IAAI;gBAC/E,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9F,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,KAAK;YACtB,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CACnB,GAAG,CAAC,kCAAkC,EACtC,oCAAoC,EACpC,KAAK,CACN,CAAkC,CAAC;YACpC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;QAC3E,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa;YAC/B,MAAM,WAAW,GAAG,aAAa,EAAE,WAAW,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CACnB,GAAG,CAAC,4BAA4B,EAChC,8BAA8B,EAC9B,KAAK,EACL,WAAW,CACZ,CAAuE,CAAC;YACzE,OAAO,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE;gBAC5B,aAAa,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC9C,GAAG,CAAC,WAAW,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;aAC5C,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,KAAK;YACrB,MAAM,IAAI,CAAC,GAAG,CAAC,iCAAiC,EAAE,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAChG,CAAC;KACF,CAAC;AACJ,CAAC;AA2BD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,uBAAuB;IACvB,mBAAmB;IACnB,yBAAyB;IACzB,2BAA2B;IAC3B,+BAA+B;IAC/B,qBAAqB;IACrB,qBAAqB;CACb,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAkE,EAClE,OAA2E;IAE3E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,sFAAsF;YACpF,mFAAmF;YACnF,4BAA4B,CAC/B,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,QAA4B,CAAC;IACjC,IAAI,OAA4B,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,SAAS,GAAwB,EAAE,CAAC;IAC1C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpE,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;YAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7B,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,KAAK,GAAG,IAAI,KAAK,CACrB,wBAAwB,MAAM,gCAAgC;oBAC5D,GAAG,MAAM,CAAC,OAAO,IAAI,qBAAqB,EAAE,CAC/C,CAAC;gBACF,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC9D,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,OAAO,IAAI,CAAC,CAAC;QACb,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;YAAE,OAAO,GAAG,IAAI,CAAC;aACvC,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,GAAG,KAAK,CAAC;QAC5E,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC;QAC5C,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC;YACjE,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC;YACjE,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS;gBAAE,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,wEAAwE;YACxE,4EAA4E;YAC5E,cAAc;YACd,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACzC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC;qBAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,UAAU,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,uFAAuF;YACrF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM;QACN,MAAM;QACN,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC3C,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;QACzC,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC"}

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

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