@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/agentcore/runtime.js

@@ -0,0 +1,706 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { agentCoreObservedCapabilities, agentCoreCapabilityModes, agentCoreSandboxCapabilities, agentCoreWorkflowCapabilities, } from "./capabilities.js";
+import { createOfficialAgentCoreApi, isAgentCoreNotFoundError, } from "./internal/sdk.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_CREATE_INTERPRETER_TIMEOUT_MS = 60_000;
+const DEFAULT_LAUNCH_TIMEOUT_MS = 60_000;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 15_000;
+const DEFAULT_EXEC_TIMEOUT_MS = 120_000;
+const DEFAULT_FILE_TIMEOUT_MS = 120_000;
+const DEFAULT_DESTROY_TIMEOUT_MS = 30_000;
+/** AgentCore session default per `StartCodeInterpreterSession` docs. */
+const DEFAULT_SESSION_TIMEOUT_SECONDS = 900;
+/** AgentCore session hard ceiling. */
+const MAX_SESSION_TIMEOUT_SECONDS = 28_800;
+const SYSTEM_INTERPRETER_ID = "aws.codeinterpreter.v1";
+/** Bound on pages walked while searching for an owned interpreter to adopt by name. */
+const MAX_ADOPT_LIST_PAGES = 10;
+export class AgentCoreOperationTimeoutError extends Error {
+    operation;
+    timeoutMs;
+    constructor(operation, timeoutMs) {
+        super(`AgentCore ${operation} did not complete within ${timeoutMs}ms`);
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+        this.name = "AgentCoreOperationTimeoutError";
+    }
+}
+export class AgentCoreDestroyVerificationError extends Error {
+    sessionId;
+    timeoutMs;
+    constructor(sessionId, timeoutMs) {
+        super(`AgentCore session "${sessionId}" stop was accepted but termination was not `
+            + `verified within ${timeoutMs}ms`);
+        this.sessionId = sessionId;
+        this.timeoutMs = timeoutMs;
+        this.name = "AgentCoreDestroyVerificationError";
+    }
+}
+export class AgentCoreUnregisteredHandleError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`AgentCore session "${sessionId}" is not registered on this runtime instance; `
+            + "call getById() to attach it first");
+        this.sessionId = sessionId;
+        this.name = "AgentCoreUnregisteredHandleError";
+    }
+}
+export class AgentCoreNetworkConfigError extends Error {
+    constructor(message) {
+        super(`AgentCore network configuration: ${message}`);
+        this.name = "AgentCoreNetworkConfigError";
+    }
+}
+export class AgentCoreInterpreterNotReadyError extends Error {
+    codeInterpreterId;
+    lastStatus;
+    timeoutMs;
+    constructor(codeInterpreterId, lastStatus, timeoutMs) {
+        super(`AgentCore code interpreter "${codeInterpreterId}" did not reach READY within `
+            + `${timeoutMs}ms (last status: "${lastStatus}")`);
+        this.codeInterpreterId = codeInterpreterId;
+        this.lastStatus = lastStatus;
+        this.timeoutMs = timeoutMs;
+        this.name = "AgentCoreInterpreterNotReadyError";
+    }
+}
+export class AgentCoreCommandFailedError extends Error {
+    stderr;
+    constructor(stderr) {
+        super(`AgentCore command reported an error: ${stderr || "(no stderr)"}`);
+        this.stderr = stderr;
+        this.name = "AgentCoreCommandFailedError";
+    }
+}
+/** One budget for one logical operation, shared across every round trip it makes. */
+class Deadline {
+    totalMs;
+    operation;
+    expiresAt;
+    constructor(totalMs, operation) {
+        this.totalMs = totalMs;
+        this.operation = operation;
+        this.expiresAt = Date.now() + totalMs;
+    }
+    remaining() {
+        return Math.max(0, this.expiresAt - Date.now());
+    }
+    require() {
+        const left = this.remaining();
+        if (left <= 0) {
+            throw new AgentCoreOperationTimeoutError(this.operation, this.totalMs);
+        }
+        return left;
+    }
+    signal() {
+        return AbortSignal.timeout(this.require());
+    }
+}
+/**
+ * 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 class AgentCoreSandboxRuntime {
+    id = "agentcore";
+    capabilities = agentCoreWorkflowCapabilities;
+    declaredCapabilities = agentCoreSandboxCapabilities;
+    declaredCapabilityModes = agentCoreCapabilityModes;
+    observedCapabilities = agentCoreObservedCapabilities;
+    region;
+    credentials;
+    interpreter;
+    defaultHomeDir;
+    sessionTimeoutSeconds;
+    env;
+    requestTimeoutMs;
+    createInterpreterTimeoutMs;
+    launchTimeoutMs;
+    lookupTimeoutMs;
+    execTimeoutMs;
+    fileTimeoutMs;
+    destroyTimeoutMs;
+    injectedApiFactory;
+    registrations = new Map();
+    apiPromise;
+    /** Resolved once, lazily, and cached for the life of this instance. */
+    resolvedInterpreterId;
+    resolvingInterpreter;
+    constructor(options, dependencies = {}) {
+        this.region = required(options.region, "AgentCore region");
+        this.credentials = options.credentials;
+        this.interpreter = validateInterpreterSource(options.interpreter);
+        this.defaultHomeDir = required(options.defaultHomeDir, "AgentCore default home directory");
+        this.sessionTimeoutSeconds = validateSessionTimeoutSeconds(options.sessionTimeoutSeconds);
+        this.env = { ...(options.env ?? {}) };
+        this.requestTimeoutMs = positiveDuration(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+        this.createInterpreterTimeoutMs = positiveDuration(options.createInterpreterTimeoutMs, DEFAULT_CREATE_INTERPRETER_TIMEOUT_MS);
+        this.launchTimeoutMs = positiveDuration(options.launchTimeoutMs, DEFAULT_LAUNCH_TIMEOUT_MS);
+        this.lookupTimeoutMs = positiveDuration(options.lookupTimeoutMs, DEFAULT_LOOKUP_TIMEOUT_MS);
+        this.execTimeoutMs = positiveDuration(options.execTimeoutMs, DEFAULT_EXEC_TIMEOUT_MS);
+        this.fileTimeoutMs = positiveDuration(options.fileTimeoutMs, DEFAULT_FILE_TIMEOUT_MS);
+        this.destroyTimeoutMs = positiveDuration(options.destroyTimeoutMs, DEFAULT_DESTROY_TIMEOUT_MS);
+        this.injectedApiFactory = dependencies.apiFactory;
+    }
+    // --- launch -----------------------------------------------------------
+    async launch(options = {}) {
+        const deadline = new Deadline(options.createTimeoutSeconds && options.createTimeoutSeconds > 0
+            ? Math.ceil(options.createTimeoutSeconds * 1_000)
+            : this.launchTimeoutMs, "launch");
+        const codeInterpreterId = await this.ensureInterpreter(deadline);
+        const api = await this.api();
+        const started = await api.data.startSession({
+            codeInterpreterIdentifier: codeInterpreterId,
+            ...(options.name?.trim() ? { name: options.name.trim() } : {}),
+            sessionTimeoutSeconds: this.sessionTimeoutSeconds,
+            clientToken: randomUUID(),
+            abortSignal: deadline.signal(),
+        });
+        this.registrations.set(started.sessionId, {
+            owned: true,
+            labels: { ...(options.labels ?? {}) },
+            codeInterpreterIdentifier: codeInterpreterId,
+            state: "READY",
+        });
+        return {
+            id: started.sessionId,
+            state: "READY",
+            homeDir: this.defaultHomeDir,
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+            ...(started.createdAt ? { createdAt: started.createdAt.toISOString() } : {}),
+        };
+    }
+    // --- lookup -------------------------------------------------------------
+    async findByLabels(labels, options = {}) {
+        const matches = await this.findAllByLabels(labels, { ...options, limit: 1 });
+        return matches[0] ?? 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.
+     */
+    async findAllByLabels(labels, options = {}) {
+        const wanted = { ...labels };
+        const excluded = new Set(options.excludeIds ?? []);
+        const handles = [];
+        for (const [sessionId, entry] of this.registrations) {
+            if (!entry.owned || excluded.has(sessionId)) {
+                continue;
+            }
+            if (!matchesAllLabels(entry.labels, wanted)) {
+                continue;
+            }
+            handles.push({ id: sessionId, state: entry.state, homeDir: this.defaultHomeDir });
+            if (options.limit && handles.length >= options.limit) {
+                break;
+            }
+        }
+        return handles;
+    }
+    async countByLabels(labels, options = {}) {
+        const matches = await this.findAllByLabels(labels, {
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.maxCount !== undefined ? { limit: options.maxCount } : {}),
+        });
+        return matches.length;
+    }
+    /**
+     * 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.
+     */
+    async getById(id, options = {}) {
+        const deadline = new Deadline(this.lookupTimeoutMs, "get session");
+        const codeInterpreterId = await this.ensureInterpreter(deadline);
+        const api = await this.api();
+        let session;
+        try {
+            session = await api.data.getSession({
+                codeInterpreterIdentifier: codeInterpreterId,
+                sessionId: id,
+                abortSignal: deadline.signal(),
+            });
+        }
+        catch (error) {
+            if (isAgentCoreNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+        const states = options.states === undefined ? null : options.states;
+        if (states && !states.includes(session.status)) {
+            return null;
+        }
+        const existing = this.registrations.get(id);
+        this.registrations.set(id, {
+            owned: options.owned ?? existing?.owned ?? false,
+            labels: existing?.labels ?? {},
+            codeInterpreterIdentifier: codeInterpreterId,
+            state: session.status,
+        });
+        return { id, state: session.status, homeDir: this.defaultHomeDir };
+    }
+    // --- exec -----------------------------------------------------------------
+    async runScript(handle, options) {
+        const entry = this.requireRegistered(handle);
+        const timeoutMs = options.timeoutMs && options.timeoutMs > 0
+            ? Math.ceil(options.timeoutMs)
+            : this.execTimeoutMs;
+        const deadline = new Deadline(timeoutMs, "invoke executeCommand");
+        const api = await this.api();
+        const result = await api.data.invoke({
+            codeInterpreterIdentifier: entry.codeInterpreterIdentifier,
+            sessionId: handle.id,
+            name: "executeCommand",
+            arguments: { command: this.shellCommand(options) },
+            abortSignal: deadline.signal(),
+        });
+        const stdout = result.structuredContent?.stdout
+            ?? textContent(result.content);
+        const stderr = result.structuredContent?.stderr ?? "";
+        const exitCode = result.structuredContent?.exitCode
+            ?? (result.isError ? 1 : 0);
+        return {
+            output: combineOutput(stdout, stderr),
+            ...(stdout ? { stdout } : {}),
+            ...(stderr ? { stderr } : {}),
+            exitCode,
+        };
+    }
+    async exec(handle, command, options = {}) {
+        const result = await this.runScript(handle, { command, ...options });
+        return { output: result.output, exitCode: result.exitCode ?? 1 };
+    }
+    // AgentCore's `InvokeCodeInterpreter` is a single synchronous call per
+    // action — there is no submit-then-poll pair to build `startScript`/
+    // `getScriptStatus`/`getScriptLogs` on, so async exec is omitted rather
+    // than faked with a buffered result masquerading as a pending one.
+    // --- files ------------------------------------------------------------
+    async uploadFile(handle, source, destination) {
+        await this.uploadBundle(handle, { files: [{ source, destination }] });
+    }
+    async uploadBundle(handle, options) {
+        const entry = this.requireRegistered(handle);
+        const deadline = new Deadline(this.fileTimeoutMs, "upload bundle");
+        const api = await this.api();
+        const textFiles = [];
+        // `writeFiles` only documents a `text` field for content, not a binary
+        // one; buffers are shipped as a base64 sidecar file and decoded in-
+        // sandbox with Python (a guaranteed-present runtime), rather than
+        // assuming an unconfirmed binary content type on the vendor API.
+        const decodeCommands = [];
+        for (const file of options.files) {
+            const isBuffer = typeof file.source !== "string";
+            const content = isBuffer
+                ? file.source
+                : await readFile(file.source);
+            const binary = isBuffer || content.subarray(0, 8_192).includes(0);
+            if (binary) {
+                const b64Path = `${file.destination}.__b64__`;
+                textFiles.push({ path: b64Path, text: content.toString("base64") });
+                decodeCommands.push(`python3 -c "import base64; open(${shellSingleQuote(file.destination)}, 'wb').write(base64.b64decode(open(${shellSingleQuote(b64Path)}).read()))" && rm -f ${shellSingleQuote(b64Path)}`);
+            }
+            else {
+                textFiles.push({ path: file.destination, text: content.toString("utf8") });
+            }
+        }
+        if (textFiles.length === 0) {
+            return;
+        }
+        await api.data.invoke({
+            codeInterpreterIdentifier: entry.codeInterpreterIdentifier,
+            sessionId: handle.id,
+            name: "writeFiles",
+            arguments: { content: textFiles },
+            abortSignal: deadline.signal(),
+        });
+        if (decodeCommands.length > 0) {
+            const verified = await this.runScript(handle, {
+                command: decodeCommands.join(" && "),
+                timeoutMs: deadline.require(),
+            });
+            if (verified.exitCode !== 0) {
+                throw new Error("Failed to decode uploaded AgentCore bundle files");
+            }
+        }
+    }
+    async downloadFile(handle, source, destination) {
+        this.requireRegistered(handle);
+        // Downloaded through `executeCommand` + base64, not the `readFiles`
+        // action: the AWS docs do not confirm whether `readFiles` returns binary
+        // content safely, and shelling through base64 is correct for both text
+        // and binary files regardless of that answer.
+        const result = await this.runScript(handle, {
+            command: `base64 ${shellSingleQuote(source)}`,
+            timeoutMs: this.fileTimeoutMs,
+        });
+        if (result.exitCode !== 0) {
+            throw new Error(`AgentCore session "${handle.id}" has no file at "${source}"`);
+        }
+        const buffer = Buffer.from(result.output.trim(), "base64");
+        if (destination) {
+            await writeFile(destination, buffer);
+            return;
+        }
+        return buffer;
+    }
+    async getHomeDir(handle) {
+        this.requireRegistered(handle);
+        handle.homeDir = handle.homeDir ?? this.defaultHomeDir;
+        return handle.homeDir;
+    }
+    // --- lifecycle ----------------------------------------------------------
+    // No `start`/`stop`: `StopCodeInterpreterSession` is a terminal transition
+    // with no resume path (`GetCodeInterpreterSession.status` is only
+    // `READY | TERMINATED`), the same shape the Modal adapter's `lifecycle:
+    // false` documents for `Sandbox.terminate()`. Shipping a `stop` that
+    // cannot be undone under a name implying it can would be worse than
+    // omitting it.
+    /**
+     * 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.
+     */
+    async destroy(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry) {
+            return;
+        }
+        if (!entry.owned) {
+            this.registrations.delete(handle.id);
+            return;
+        }
+        const deadline = new Deadline(this.destroyTimeoutMs, "stop session");
+        const api = await this.api();
+        try {
+            await api.data.stopSession({
+                codeInterpreterIdentifier: entry.codeInterpreterIdentifier,
+                sessionId: handle.id,
+                abortSignal: deadline.signal(),
+            });
+        }
+        catch (error) {
+            if (!isAgentCoreNotFoundError(error)) {
+                throw error;
+            }
+            // Already gone. Fall through to verification, which will agree.
+        }
+        const verified = await this.waitUntilTerminated(entry.codeInterpreterIdentifier, handle.id, deadline);
+        if (!verified) {
+            throw new AgentCoreDestroyVerificationError(handle.id, deadline.totalMs);
+        }
+        this.registrations.delete(handle.id);
+    }
+    /**
+     * 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.
+     */
+    async deleteOwnedCodeInterpreter() {
+        if (this.interpreter.type !== "owned" || !this.resolvedInterpreterId) {
+            return;
+        }
+        const deadline = new Deadline(this.destroyTimeoutMs, "delete code interpreter");
+        const api = await this.api();
+        await api.control.deleteCodeInterpreter({
+            codeInterpreterId: this.resolvedInterpreterId,
+            clientToken: randomUUID(),
+            abortSignal: deadline.signal(),
+        });
+        this.resolvedInterpreterId = undefined;
+    }
+    // --- internals ------------------------------------------------------------
+    async api() {
+        if (this.injectedApiFactory) {
+            return this.injectedApiFactory();
+        }
+        this.apiPromise ??= createOfficialAgentCoreApi(this.credentials, this.region);
+        return this.apiPromise;
+    }
+    /**
+     * 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`.
+     */
+    async ensureInterpreter(callerDeadline) {
+        if (this.interpreter.type === "system") {
+            return SYSTEM_INTERPRETER_ID;
+        }
+        if (this.resolvedInterpreterId) {
+            return this.resolvedInterpreterId;
+        }
+        if (!this.resolvingInterpreter) {
+            this.resolvingInterpreter = this.createOrAdoptInterpreter().finally(() => {
+                this.resolvingInterpreter = undefined;
+            });
+        }
+        // The caller's own deadline still governs how long *it* is willing to
+        // wait, independent of how long interpreter resolution takes.
+        callerDeadline.require();
+        return this.resolvingInterpreter;
+    }
+    async createOrAdoptInterpreter() {
+        if (this.interpreter.type !== "owned") {
+            throw new Error("createOrAdoptInterpreter called without an owned interpreter source");
+        }
+        const source = this.interpreter;
+        const deadline = new Deadline(this.createInterpreterTimeoutMs, "create code interpreter");
+        const api = await this.api();
+        // Adopt first: the name is fixed and deterministic precisely so a fresh
+        // process instance (or a second runtime pointed at the same
+        // configuration) rediscovers and reuses the interpreter a prior one
+        // created, instead of every instance independently creating its own —
+        // which would leave each instance's sessions unreachable from every
+        // other instance's `getById`, since a session can only be looked up
+        // through the `codeInterpreterIdentifier` that created it.
+        const existing = await this.findExistingInterpreterByName(api, source.name, deadline);
+        if (existing) {
+            const ready = await this.waitUntilInterpreterReady(existing.codeInterpreterId, existing.status ?? "CREATING", deadline);
+            this.resolvedInterpreterId = ready;
+            return ready;
+        }
+        const network = toNetworkConfigParams(source.network);
+        const created = await api.control.createCodeInterpreter({
+            name: source.name,
+            ...(source.description ? { description: source.description } : {}),
+            ...(source.executionRoleArn ? { executionRoleArn: source.executionRoleArn } : {}),
+            networkConfiguration: network,
+            ...(source.tags ? { tags: { ...source.tags } } : {}),
+            clientToken: randomUUID(),
+            abortSignal: deadline.signal(),
+        });
+        const ready = await this.waitUntilInterpreterReady(created.codeInterpreterId, created.status, deadline);
+        this.resolvedInterpreterId = ready;
+        return ready;
+    }
+    /**
+     * 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.
+     */
+    async findExistingInterpreterByName(api, name, deadline) {
+        let nextToken;
+        for (let page = 0; page < MAX_ADOPT_LIST_PAGES; page += 1) {
+            const result = await api.control.listCodeInterpreters({
+                maxResults: 100,
+                ...(nextToken ? { nextToken } : {}),
+                abortSignal: deadline.signal(),
+            });
+            const match = result.items.find((item) => item.name === name);
+            if (match) {
+                return { codeInterpreterId: match.codeInterpreterId, ...(match.status ? { status: match.status } : {}) };
+            }
+            if (!result.nextToken) {
+                return null;
+            }
+            nextToken = result.nextToken;
+        }
+        return null;
+    }
+    async waitUntilInterpreterReady(codeInterpreterId, initialStatus, deadline) {
+        let status = initialStatus;
+        const api = await this.api();
+        while (status !== "READY") {
+            if (status === "CREATE_FAILED") {
+                throw new AgentCoreInterpreterNotReadyError(codeInterpreterId, status, deadline.totalMs);
+            }
+            deadline.require();
+            await sleep(Math.min(1_000, deadline.remaining()));
+            const current = await api.control.getCodeInterpreter({
+                codeInterpreterId,
+                abortSignal: deadline.signal(),
+            });
+            status = current.status;
+        }
+        return codeInterpreterId;
+    }
+    async waitUntilTerminated(codeInterpreterId, sessionId, deadline) {
+        const api = await this.api();
+        while (deadline.remaining() > 0) {
+            try {
+                const current = await api.data.getSession({
+                    codeInterpreterIdentifier: codeInterpreterId,
+                    sessionId,
+                    abortSignal: deadline.signal(),
+                });
+                if (current.status === "TERMINATED") {
+                    return true;
+                }
+            }
+            catch (error) {
+                if (isAgentCoreNotFoundError(error)) {
+                    return true;
+                }
+                throw error;
+            }
+            if (deadline.remaining() <= 0) {
+                return false;
+            }
+            await sleep(Math.min(750, deadline.remaining()));
+        }
+        return false;
+    }
+    requireRegistered(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry) {
+            throw new AgentCoreUnregisteredHandleError(handle.id);
+        }
+        return entry;
+    }
+    /**
+     * 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.
+     */
+    shellCommand(options) {
+        const env = { ...this.env, ...(options.env ?? {}) };
+        const prefix = [];
+        if (options.cwd) {
+            prefix.push(`cd ${shellSingleQuote(options.cwd)}`);
+        }
+        for (const [key, value] of Object.entries(env)) {
+            prefix.push(`export ${key}=${shellSingleQuote(value)}`);
+        }
+        return prefix.length > 0
+            ? `${prefix.join(" && ")} && ${options.command}`
+            : options.command;
+    }
+}
+// --- validation helpers -----------------------------------------------------
+function required(value, label) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        throw new Error(`${label} is required`);
+    }
+    return trimmed;
+}
+function positiveDuration(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Expected a positive duration, got ${value}`);
+    }
+    return value;
+}
+function validateSessionTimeoutSeconds(value) {
+    if (value === undefined) {
+        return DEFAULT_SESSION_TIMEOUT_SECONDS;
+    }
+    if (!Number.isFinite(value) || value < 1 || value > MAX_SESSION_TIMEOUT_SECONDS) {
+        throw new Error(`AgentCore sessionTimeoutSeconds must be between 1 and ${MAX_SESSION_TIMEOUT_SECONDS}, `
+            + `got ${value}`);
+    }
+    return Math.floor(value);
+}
+function validateInterpreterSource(source) {
+    if (source.type === "system") {
+        return source;
+    }
+    if (source.type !== "owned") {
+        throw new Error(`Unknown AgentCore interpreter source type: ${source.type}`);
+    }
+    required(source.name, "AgentCore owned interpreter name");
+    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/.test(source.name)) {
+        throw new Error(`AgentCore code interpreter name "${source.name}" must match [a-zA-Z][a-zA-Z0-9_]{0,47}`);
+    }
+    toNetworkConfigParams(source.network);
+    return source;
+}
+/**
+ * Translate the SDK-free `AgentCoreNetworkConfig` into the vendor API's
+ * `networkConfiguration` shape, enforcing the VPC-default / explicit-opt-in
+ * rule documented on `AgentCoreNetworkConfig` itself.
+ */
+function toNetworkConfigParams(network) {
+    const mode = network.mode ?? "VPC";
+    if (mode === "SANDBOX") {
+        // eslint-disable-next-line no-console
+        console.warn("[agentcore] network mode SANDBOX was explicitly requested. Public research "
+            + "disclosed in March 2026 (BeyondTrust Phantom Labs, corroborated by Unit 42 "
+            + "and the Cloud Security Alliance) showed SANDBOX mode still permits outbound "
+            + "DNS A/AAAA queries, which is sufficient to build a covert command-and-"
+            + "control and data-exfiltration channel out of the sandbox. AWS's mitigation "
+            + "is VPC mode plus a Route 53 Resolver DNS Firewall, not a SANDBOX-mode fix. "
+            + "Prefer network: { vpc: {...} } unless this session has no secrets to leak.");
+        return { networkMode: "SANDBOX" };
+    }
+    if (mode === "PUBLIC") {
+        return { networkMode: "PUBLIC" };
+    }
+    if (!("vpc" in network) || !network.vpc) {
+        throw new AgentCoreNetworkConfigError("mode is VPC (the default) but no `vpc` config was supplied; provide "
+            + "{ vpc: { subnetIds, securityGroupIds } } or explicitly opt into "
+            + '{ mode: "SANDBOX" } / { mode: "PUBLIC" }');
+    }
+    const { subnetIds, securityGroupIds, requireServiceS3Endpoint } = network.vpc;
+    if (subnetIds.length === 0) {
+        throw new AgentCoreNetworkConfigError("vpc.subnetIds must contain at least one subnet");
+    }
+    if (securityGroupIds.length === 0) {
+        throw new AgentCoreNetworkConfigError("vpc.securityGroupIds must contain at least one security group");
+    }
+    return {
+        networkMode: "VPC",
+        vpcConfig: {
+            subnets: [...subnetIds],
+            securityGroups: [...securityGroupIds],
+            ...(requireServiceS3Endpoint !== undefined ? { requireServiceS3Endpoint } : {}),
+        },
+    };
+}
+function matchesAllLabels(actual, wanted) {
+    for (const [key, value] of Object.entries(wanted)) {
+        if (actual[key] !== value) {
+            return false;
+        }
+    }
+    return true;
+}
+function textContent(content) {
+    return content
+        .filter((item) => typeof item.text === "string")
+        .map((item) => item.text)
+        .join("");
+}
+function combineOutput(stdout, stderr) {
+    if (stdout && stderr) {
+        return `${stdout}\n${stderr}`;
+    }
+    return stdout || stderr;
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+//# sourceMappingURL=runtime.js.map