@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/agentcore/runtime.d.ts

@@ -0,0 +1,177 @@
+import { Buffer } from "node:buffer";
+import type { RunScriptResult, SandboxCountOptions, SandboxLookupOptions, SandboxRuntime } from "../port.js";
+import type { ExecOptions, ExecResult, LaunchOptions, RuntimeHandle, WorkflowRuntime } from "../types.js";
+import type { AgentCoreRuntimeOptions } from "./config.js";
+import { type AgentCoreApiFactory } from "./internal/sdk.js";
+export declare class AgentCoreOperationTimeoutError extends Error {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class AgentCoreDestroyVerificationError extends Error {
+    readonly sessionId: string;
+    readonly timeoutMs: number;
+    constructor(sessionId: string, timeoutMs: number);
+}
+export declare class AgentCoreUnregisteredHandleError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class AgentCoreNetworkConfigError extends Error {
+    constructor(message: string);
+}
+export declare class AgentCoreInterpreterNotReadyError extends Error {
+    readonly codeInterpreterId: string;
+    readonly lastStatus: string;
+    readonly timeoutMs: number;
+    constructor(codeInterpreterId: string, lastStatus: string, timeoutMs: number);
+}
+export declare class AgentCoreCommandFailedError extends Error {
+    readonly stderr: string;
+    constructor(stderr: string);
+}
+export interface AgentCoreRunScriptOptions extends ExecOptions {
+    command: string;
+}
+/** Test-only injection seam. Not exported from the package barrel. */
+export interface AgentCoreRuntimeDependencies {
+    apiFactory?: AgentCoreApiFactory;
+}
+/**
+ * AWS Bedrock AgentCore Code Interpreter provider adapter.
+ *
+ * Identity note: `RuntimeHandle.id` carries the AgentCore **session id**, not
+ * the code interpreter id. A session is the ephemeral, billable unit
+ * (bounded lifetime, terminal stop) that maps onto this package's notion of
+ * a "sandbox"; the code interpreter resource underneath it is closer to a
+ * Vercel `image` or a Modal `App` — a template every session in this runtime
+ * shares, created once and reused, not torn down per handle.
+ *
+ * Ownership is tracked only in this process's `registrations` map, not by a
+ * name prefix: AgentCore session ids are opaque tokens with no addressable
+ * namespace to scope a prefix against (see `capabilities.ts` on `warmLease`).
+ */
+export declare class AgentCoreSandboxRuntime implements SandboxRuntime, WorkflowRuntime {
+    readonly id = "agentcore";
+    readonly capabilities: {
+        readonly pty: false;
+        readonly snapshots: false;
+        readonly isolation: "strong";
+        readonly persistentHandle: true;
+        readonly streamingLogs: false;
+    };
+    readonly declaredCapabilities: {
+        readonly warmLease: false;
+        readonly lifecycle: false;
+    };
+    readonly declaredCapabilityModes: {
+        readonly outputStreams: "buffered";
+        readonly filesystem: "ephemeral";
+        readonly lifetime: "deadline";
+        readonly interactive: "unsupported";
+        readonly snapshots: "unsupported";
+    };
+    readonly observedCapabilities: import("./capabilities.js").AgentCoreObservedCapabilities;
+    private readonly region;
+    private readonly credentials;
+    private readonly interpreter;
+    private readonly defaultHomeDir;
+    private readonly sessionTimeoutSeconds;
+    private readonly env;
+    private readonly requestTimeoutMs;
+    private readonly createInterpreterTimeoutMs;
+    private readonly launchTimeoutMs;
+    private readonly lookupTimeoutMs;
+    private readonly execTimeoutMs;
+    private readonly fileTimeoutMs;
+    private readonly destroyTimeoutMs;
+    private readonly injectedApiFactory?;
+    private readonly registrations;
+    private apiPromise?;
+    /** Resolved once, lazily, and cached for the life of this instance. */
+    private resolvedInterpreterId?;
+    private resolvingInterpreter?;
+    constructor(options: AgentCoreRuntimeOptions, dependencies?: AgentCoreRuntimeDependencies);
+    launch(options?: LaunchOptions): Promise<RuntimeHandle>;
+    readonly launchDetached?: undefined;
+    findByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle | null>;
+    /**
+     * In-process only. See `capabilities.ts`: AgentCore sessions carry no
+     * server-side tag/label field, so there is no way to discover a labeled
+     * session started by another process. This still returns real matches
+     * among sessions this runtime instance itself registered.
+     */
+    findAllByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle[]>;
+    countByLabels(labels: Record<string, string>, options?: SandboxCountOptions): Promise<number>;
+    /**
+     * Re-resolve a session by id via `GetCodeInterpreterSession`. Works across
+     * a process restart as long as the caller's runtime config resolves to the
+     * same code interpreter (fixed by `AgentCoreInterpreterSource`) and the
+     * session has not reached its `sessionTimeoutSeconds` deadline.
+     */
+    getById(id: string, options?: {
+        states?: readonly string[] | null;
+        owned?: boolean;
+    }): Promise<RuntimeHandle | null>;
+    runScript(handle: RuntimeHandle, options: AgentCoreRunScriptOptions): Promise<RunScriptResult>;
+    exec(handle: RuntimeHandle, command: string, options?: ExecOptions): Promise<ExecResult>;
+    uploadFile(handle: RuntimeHandle, source: string | Buffer, destination: string): Promise<void>;
+    uploadBundle(handle: RuntimeHandle, options: {
+        files: Array<{
+            source: string | Buffer;
+            destination: string;
+        }>;
+    }): Promise<void>;
+    downloadFile(handle: RuntimeHandle, source: string, destination?: string): Promise<Buffer | void>;
+    getHomeDir(handle: RuntimeHandle): Promise<string>;
+    /**
+     * Stop a session and verify it reached `TERMINATED`.
+     *
+     * The registration is retained when verification fails, so a caller can
+     * retry cleanup — dropping it would make a leaked session unreachable
+     * through this runtime and therefore invisible to any subsequent audit.
+     */
+    destroy(handle: RuntimeHandle): Promise<void>;
+    /**
+     * Delete the owned code interpreter resource itself.
+     *
+     * Not part of `SandboxRuntime`/`WorkflowRuntime`: the code interpreter is
+     * a shared template across every session this runtime starts (see the
+     * class doc), analogous to a Vercel `image` or a Modal `App`, and neither
+     * of those is destroyed by a per-handle `destroy()` either. Callers that
+     * own the whole runtime's lifecycle (tests, a process shutdown hook) call
+     * this explicitly once they are done with every session.
+     */
+    deleteOwnedCodeInterpreter(): Promise<void>;
+    private api;
+    /**
+     * Resolve the code interpreter this runtime's sessions run against,
+     * creating it on first use and caching the id for the life of the
+     * instance. Idempotent under concurrent callers via `resolvingInterpreter`.
+     */
+    private ensureInterpreter;
+    private createOrAdoptInterpreter;
+    /**
+     * Search for an already-created interpreter with this exact name.
+     *
+     * Bounded at `MAX_ADOPT_LIST_PAGES` pages so a large or pathologically
+     * paginated account cannot turn adoption into an unbounded crawl. Falling
+     * through to `createCodeInterpreter` when the search is inconclusive is
+     * safe rather than silent: a genuine duplicate name beyond the search
+     * window surfaces as a loud `ConflictException` from the create call
+     * (names are unique per account), not a silently-adopted wrong resource.
+     */
+    private findExistingInterpreterByName;
+    private waitUntilInterpreterReady;
+    private waitUntilTerminated;
+    private requireRegistered;
+    /**
+     * AgentCore's `executeCommand` action takes a bare `command` string with
+     * no `cwd`/`env` fields of its own, so both are folded into the command
+     * text: `cd` for the working directory, `export` for each variable, each
+     * value single-quoted so nothing a caller passes is ever interpreted as
+     * shell syntax.
+     */
+    private shellCommand;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/agentcore/runtime.d.ts.map

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