@agentuity/core 1.0.33 → 1.0.34

package/dist/services/sandbox/resolve.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { type APIClient } from '../api.ts';
+/**
+ * Data schema for sandbox resolve endpoint
+ */
+export declare const SandboxResolveDataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    region: z.ZodString;
+    status: z.ZodString;
+    orgId: z.ZodString;
+    projectId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Response schema for sandbox resolve endpoint using standardized discriminated union
+ */
+export declare const SandboxResolveResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        region: z.ZodString;
+        status: z.ZodString;
+        orgId: z.ZodString;
+        projectId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "success">;
+/**
+ * Resolved sandbox info returned from the CLI API
+ */
+export type ResolvedSandboxInfo = z.infer<typeof SandboxResolveDataSchema>;
+/**
+ * Error thrown when sandbox resolution fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxResolve(client, 'sbx_123');
+ * } catch (error) {
+ *   if (error._tag === 'SandboxResolveError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export declare const SandboxResolveError: {
+    new (args?: ({
+        sandboxId?: string;
+        statusCode?: number;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("../../error.ts").RichError & {
+        readonly _tag: "SandboxResolveError";
+    } & Readonly<{
+        sandboxId?: string;
+        statusCode?: number;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * Resolve a sandbox by ID across all organizations the user has access to.
+ * Uses the CLI API endpoint which searches across all user's orgs.
+ *
+ * @param client - API client configured for CLI endpoints
+ * @param sandboxId - The sandbox ID to resolve
+ * @returns Resolved sandbox info including region and orgId
+ * @throws {SandboxResolveError} If sandbox not found or request fails
+ */
+export declare function sandboxResolve(client: APIClient, sandboxId: string): Promise<ResolvedSandboxInfo>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/services/sandbox/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/services/sandbox/resolve.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,SAAS,EAAiC,MAAM,WAAW,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;iBAYqC,CAAC;AAE3E;;GAEG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;8BAA0D,CAAC;AAEpG;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;oBACnB,MAAM;qBACL,MAAM;;;;;;;oBADP,MAAM;qBACL,MAAM;;;CAChB,CAAC;AAEL;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,CAAC,CAiC9B"}

package/dist/services/sandbox/resolve.js

@@ -0,0 +1,76 @@
+import { StructuredError } from "../../error.js";
+import { z } from 'zod';
+import { APIResponseSchemaOptionalData } from "../api.js";
+/**
+ * Data schema for sandbox resolve endpoint
+ */
+export const SandboxResolveDataSchema = z
+    .object({
+    id: z.string().describe('Unique identifier for the sandbox.'),
+    name: z.string().nullable().describe('Sandbox name, or null if unnamed.'),
+    region: z.string().describe('Cloud region where the sandbox is running.'),
+    status: z.string().describe('Current status of the sandbox.'),
+    orgId: z.string().describe('Organization ID that owns the sandbox.'),
+    projectId: z
+        .string()
+        .nullable()
+        .describe('Project ID the sandbox belongs to, or null if unassigned.'),
+})
+    .describe('Resolved sandbox information from cross-organization lookup.');
+/**
+ * Response schema for sandbox resolve endpoint using standardized discriminated union
+ */
+export const SandboxResolveResponseSchema = APIResponseSchemaOptionalData(SandboxResolveDataSchema);
+/**
+ * Error thrown when sandbox resolution fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxResolve(client, 'sbx_123');
+ * } catch (error) {
+ *   if (error._tag === 'SandboxResolveError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxResolveError = StructuredError('SandboxResolveError')();
+/**
+ * Resolve a sandbox by ID across all organizations the user has access to.
+ * Uses the CLI API endpoint which searches across all user's orgs.
+ *
+ * @param client - API client configured for CLI endpoints
+ * @param sandboxId - The sandbox ID to resolve
+ * @returns Resolved sandbox info including region and orgId
+ * @throws {SandboxResolveError} If sandbox not found or request fails
+ */
+export async function sandboxResolve(client, sandboxId) {
+    const response = await client.get(`/cli/sandbox/${sandboxId}`, SandboxResolveResponseSchema);
+    if (!response.success) {
+        // Extract status code from error code if present (e.g., "NOT_FOUND" -> 404)
+        // Fall back to 404 if no code is provided
+        const statusCode = response.code === 'NOT_FOUND' ? 404 : response.code ? 400 : 404;
+        throw new SandboxResolveError({
+            message: response.message || 'Sandbox not found',
+            sandboxId,
+            statusCode,
+        });
+    }
+    if (!response.data) {
+        throw new SandboxResolveError({
+            message: 'Sandbox not found',
+            sandboxId,
+            statusCode: 404,
+        });
+    }
+    return {
+        id: response.data.id,
+        name: response.data.name,
+        region: response.data.region,
+        status: response.data.status,
+        orgId: response.data.orgId,
+        projectId: response.data.projectId,
+    };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/services/sandbox/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/services/sandbox/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAE1E;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC;KACvC,MAAM,CAAC;IACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC7D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACzE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACzE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAC7D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IACpE,SAAS,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;CACvE,CAAC;KACD,QAAQ,CAAC,8DAA8D,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,6BAA6B,CAAC,wBAAwB,CAAC,CAAC;AAOpG;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC,qBAAqB,CAAC,EAGrE,CAAC;AAEL;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,MAAiB,EACjB,SAAiB;IAEjB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAChC,gBAAgB,SAAS,EAAE,EAC3B,4BAA4B,CAC5B,CAAC;IAEF,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvB,4EAA4E;QAC5E,0CAA0C;QAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QACnF,MAAM,IAAI,mBAAmB,CAAC;YAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,mBAAmB;YAChD,SAAS;YACT,UAAU;SACV,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,mBAAmB,CAAC;YAC7B,OAAO,EAAE,mBAAmB;YAC5B,SAAS;YACT,UAAU,EAAE,GAAG;SACf,CAAC,CAAC;IACJ,CAAC;IAED,OAAO;QACN,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE;QACpB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI;QACxB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QAC5B,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK;QAC1B,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS;KAClC,CAAC;AACH,CAAC"}

package/dist/services/sandbox/resume.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { type APIClient } from '../api.ts';
+export declare const ResumeResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+}, z.core.$strip>], "success">;
+export declare const SandboxResumeParamsSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+    orgId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SandboxResumeParams = z.infer<typeof SandboxResumeParamsSchema>;
+/**
+ * Resumes a paused sandbox from its checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to resume
+ * @throws {SandboxResponseError} If the sandbox is not found or resume fails
+ */
+export declare function sandboxResume(client: APIClient, params: SandboxResumeParams): Promise<void>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/services/sandbox/resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../../src/services/sandbox/resume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,SAAS,EAA2B,MAAM,WAAW,CAAC;AAGpE,eAAO,MAAM,oBAAoB;;;;;;8BAA4B,CAAC;AAE9D,eAAO,MAAM,yBAAyB;;;iBAGpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjG"}

package/dist/services/sandbox/resume.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { APIResponseSchemaNoData } from "../api.js";
+import { throwSandboxError } from "./util.js";
+export const ResumeResponseSchema = APIResponseSchemaNoData();
+export const SandboxResumeParamsSchema = z.object({
+    sandboxId: z.string().describe('Sandbox ID to resume'),
+    orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+/**
+ * Resumes a paused sandbox from its checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to resume
+ * @throws {SandboxResponseError} If the sandbox is not found or resume fails
+ */
+export async function sandboxResume(client, params) {
+    const { sandboxId, orgId } = params;
+    const queryParams = new URLSearchParams();
+    if (orgId) {
+        queryParams.set('orgId', orgId);
+    }
+    const queryString = queryParams.toString();
+    const url = `/sandbox/${encodeURIComponent(sandboxId)}/resume${queryString ? `?${queryString}` : ''}`;
+    const resp = await client.post(url, undefined, ResumeResponseSchema);
+    if (resp.success) {
+        return;
+    }
+    throwSandboxError(resp, { sandboxId });
+}
+//# sourceMappingURL=resume.js.map

package/dist/services/sandbox/resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.js","sourceRoot":"","sources":["../../../src/services/sandbox/resume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,uBAAuB,EAAE,CAAC;AAE9D,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACtD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;CAC7E,CAAC,CAAC;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB,EAAE,MAA2B;IACjF,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;IAC1C,IAAI,KAAK,EAAE,CAAC;QACX,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,YAAY,kBAAkB,CAAC,SAAS,CAAC,UAAU,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAEtG,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAC7B,GAAG,EACH,SAAS,EACT,oBAAoB,CACpB,CAAC;IAEF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO;IACR,CAAC;IAED,iBAAiB,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/services/sandbox/run.d.ts

@@ -0,0 +1,71 @@
+import type { Logger } from '../../logger.ts';
+import type { Readable, Writable } from 'node:stream';
+import { z } from 'zod';
+import { APIClient } from '../api.ts';
+import { type SandboxRunResult } from './types.ts';
+export declare const SandboxRunParamsSchema: z.ZodObject<{
+    options: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        projectId: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        stream: z.ZodOptional<z.ZodObject<{
+            stdout: z.ZodOptional<z.ZodString>;
+            stderr: z.ZodOptional<z.ZodString>;
+            stdin: z.ZodOptional<z.ZodString>;
+            timestamps: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            memory: z.ZodOptional<z.ZodString>;
+            cpu: z.ZodOptional<z.ZodString>;
+            disk: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeout: z.ZodOptional<z.ZodObject<{
+            idle: z.ZodOptional<z.ZodString>;
+            execution: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            content: z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
+        }, z.core.$strip>>>;
+        runtime: z.ZodOptional<z.ZodString>;
+        runtimeId: z.ZodOptional<z.ZodString>;
+        network: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            port: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        snapshot: z.ZodOptional<z.ZodString>;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodObject<{
+            exec: z.ZodArray<z.ZodString>;
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                content: z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    orgId: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    stdin: z.ZodOptional<z.ZodCustom<Readable, Readable>>;
+    stdout: z.ZodOptional<z.ZodCustom<Writable, Writable>>;
+    stderr: z.ZodOptional<z.ZodCustom<Writable, Writable>>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+}, z.core.$strip>;
+export type SandboxRunParams = z.infer<typeof SandboxRunParamsSchema>;
+/**
+ * Creates a sandbox, executes a command, and waits for completion.
+ *
+ * This is a high-level convenience function that handles the full lifecycle:
+ * creating a sandbox, streaming I/O, polling for completion, and cleanup.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including command options, I/O streams, and timeout settings
+ * @returns The run result including exit code and duration
+ * @throws {SandboxResponseError} If sandbox creation fails, execution times out, or is cancelled
+ */
+export declare function sandboxRun(client: APIClient, params: SandboxRunParams): Promise<SandboxRunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/services/sandbox/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/services/sandbox/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAwB,MAAM,WAAW,CAAC;AAK5D,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA+B5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA0M3B"}

package/dist/services/sandbox/run.js

@@ -0,0 +1,355 @@
+import { PassThrough } from 'node:stream';
+import { z } from 'zod';
+import { PaymentRequiredError } from "../api.js";
+import { sandboxCreate } from "./create.js";
+import { sandboxDestroy } from "./destroy.js";
+import { sandboxGetStatus } from "./getStatus.js";
+import { ExecutionCancelledError, writeAndDrain } from "./util.js";
+import { SandboxRunOptionsSchema } from "./types.js";
+import { getServiceUrls } from "../config.js";
+const timingLogsEnabled = false;
+/**
+ * Creates a Writable stream that captures all chunks to a buffer array
+ * and optionally tees (forwards) them to one or more user-provided streams.
+ *
+ * @param chunks - Array to collect Buffer chunks into
+ * @param userStreams - Optional user-provided Writable stream(s) to forward chunks to
+ * @returns A Writable stream that captures and optionally forwards data
+ */
+function createTeeWritable(chunks, ...userStreams) {
+    const tee = new PassThrough();
+    // Always capture chunks to the buffer
+    tee.on('data', (chunk) => {
+        chunks.push(chunk);
+    });
+    // Pipe to all provided user streams with proper backpressure handling
+    for (const userStream of userStreams) {
+        if (userStream) {
+            tee.pipe(userStream, { end: false });
+        }
+    }
+    return tee;
+}
+export const SandboxRunParamsSchema = z.object({
+    options: SandboxRunOptionsSchema.describe('sandbox run options'),
+    orgId: z.string().optional().describe('organization id'),
+    region: z.string().optional().describe('region id'),
+    apiKey: z.string().optional().describe('api key'),
+    signal: z.custom().optional().describe('abort signal'),
+    stdin: z.custom().optional().describe('stdin readable stream'),
+    stdout: z.custom().optional().describe('stdout writable stream'),
+    stderr: z.custom().optional().describe('stderr writable stream'),
+    logger: z.custom().optional().describe('logger instance'),
+});
+/**
+ * Creates a sandbox, executes a command, and waits for completion.
+ *
+ * This is a high-level convenience function that handles the full lifecycle:
+ * creating a sandbox, streaming I/O, polling for completion, and cleanup.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including command options, I/O streams, and timeout settings
+ * @returns The run result including exit code and duration
+ * @throws {SandboxResponseError} If sandbox creation fails, execution times out, or is cancelled
+ */
+export async function sandboxRun(client, params) {
+    const { options, orgId, region, apiKey, signal, stdin, stdout, stderr, logger } = params;
+    const started = Date.now();
+    if (timingLogsEnabled)
+        console.error(`[TIMING] +0ms: sandbox run started`);
+    let stdinStreamId;
+    let stdinStreamUrl;
+    // If stdin is provided and has data, create a stream for it
+    if (stdin && region && apiKey) {
+        const streamResult = await createStdinStream(region, apiKey, orgId, logger);
+        stdinStreamId = streamResult.id;
+        stdinStreamUrl = streamResult.url;
+        logger?.debug('created stdin stream: %s', stdinStreamId);
+    }
+    const createResponse = await sandboxCreate(client, {
+        options: {
+            ...options,
+            command: {
+                exec: options.command.exec,
+                files: options.command.files,
+                mode: 'oneshot',
+            },
+            stream: {
+                ...options.stream,
+                stdin: stdinStreamId,
+            },
+        },
+        orgId,
+    });
+    const sandboxId = createResponse.sandboxId;
+    const stdoutStreamUrl = createResponse.stdoutStreamUrl;
+    const stderrStreamUrl = createResponse.stderrStreamUrl;
+    logger?.debug('sandbox created: %s, stdoutUrl: %s, stderrUrl: %s', sandboxId, stdoutStreamUrl ?? 'none', stderrStreamUrl ?? 'none');
+    if (timingLogsEnabled)
+        console.error(`[TIMING] +${Date.now() - started}ms: sandbox created (${sandboxId})`);
+    const abortController = new AbortController();
+    const streamPromises = [];
+    // Create capture buffers for stdout/stderr
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    try {
+        // Start stdin streaming if we have stdin and a stream URL
+        if (stdin && stdinStreamUrl && apiKey) {
+            const stdinPromise = streamStdinToUrl(stdin, stdinStreamUrl, apiKey, abortController.signal, logger);
+            streamPromises.push(stdinPromise);
+        }
+        // Check if stdout and stderr are the same stream (combined output)
+        const isCombinedOutput = stdoutStreamUrl && stderrStreamUrl && stdoutStreamUrl === stderrStreamUrl;
+        if (isCombinedOutput) {
+            // Stream combined output to stdout only to avoid duplicates
+            if (stdoutStreamUrl) {
+                logger?.debug('using combined output stream (stdout === stderr)');
+                const teeStream = createTeeWritable(stdoutChunks, stdout);
+                const combinedPromise = streamUrlToWritable(stdoutStreamUrl, teeStream, abortController.signal, logger, started);
+                streamPromises.push(combinedPromise);
+            }
+        }
+        else {
+            // Start stdout streaming with capture
+            if (stdoutStreamUrl) {
+                const teeStream = createTeeWritable(stdoutChunks, stdout);
+                const stdoutPromise = streamUrlToWritable(stdoutStreamUrl, teeStream, abortController.signal, logger, started);
+                streamPromises.push(stdoutPromise);
+            }
+            // Start stderr streaming with capture
+            if (stderrStreamUrl) {
+                const teeStream = createTeeWritable(stderrChunks, stderr);
+                const stderrPromise = streamUrlToWritable(stderrStreamUrl, teeStream, abortController.signal, logger, started);
+                streamPromises.push(stderrPromise);
+            }
+        }
+        // Wait for streams to complete — Pulse closes streams on sandbox termination (EOF).
+        // This is our primary completion signal; no polling needed.
+        logger?.debug('waiting for streams to complete...');
+        if (streamPromises.length > 0) {
+            if (signal) {
+                // Race streams against abort signal, cleaning up the listener
+                // in all cases so an orphaned reject cannot fire after settlement.
+                let onAbort;
+                try {
+                    await Promise.race([
+                        Promise.allSettled(streamPromises),
+                        new Promise((_, reject) => {
+                            onAbort = () => {
+                                abortController.abort();
+                                reject(new ExecutionCancelledError({
+                                    message: 'Sandbox execution cancelled',
+                                    sandboxId,
+                                }));
+                            };
+                            if (signal.aborted) {
+                                onAbort();
+                            }
+                            else {
+                                signal.addEventListener('abort', onAbort, { once: true });
+                            }
+                        }),
+                    ]);
+                }
+                finally {
+                    if (onAbort && signal) {
+                        signal.removeEventListener('abort', onAbort);
+                    }
+                }
+            }
+            else {
+                await Promise.allSettled(streamPromises);
+            }
+        }
+        else {
+            // No streams available (shouldn't happen for oneshot, but handle defensively).
+            // Fall back to a single wait then check.
+            logger?.debug('no streams to wait on, checking sandbox status directly');
+        }
+        if (timingLogsEnabled)
+            console.error(`[TIMING] +${Date.now() - started}ms: all streams done, fetching exit code`);
+        logger?.debug('streams completed, fetching final status');
+        // Stream EOF means the sandbox is done — hadron only closes streams after the
+        // container exits. Fetch status once for the exit code; if lifecycle events
+        // haven't propagated to Catalyst yet, default to exit code 0.
+        let exitCode = 0;
+        try {
+            const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
+            if (sandboxStatus.exitCode != null) {
+                exitCode = sandboxStatus.exitCode;
+            }
+            else if (sandboxStatus.status === 'failed') {
+                exitCode = 1;
+            }
+        }
+        catch {
+            // Sandbox may already be destroyed (fire-and-forget teardown).
+            // Stream EOF already confirmed execution completed.
+            logger?.debug('sandboxGetStatus failed after stream EOF, using default exit code 0');
+        }
+        if (timingLogsEnabled)
+            console.error(`[TIMING] +${Date.now() - started}ms: sandboxGet complete (exit: ${exitCode})`);
+        // Build captured output strings
+        const capturedStdout = Buffer.concat(stdoutChunks).toString('utf-8');
+        const capturedStderr = isCombinedOutput
+            ? capturedStdout
+            : Buffer.concat(stderrChunks).toString('utf-8');
+        return {
+            sandboxId,
+            exitCode,
+            durationMs: Date.now() - started,
+            stdout: capturedStdout,
+            stderr: capturedStderr,
+        };
+    }
+    catch (error) {
+        abortController.abort();
+        try {
+            await sandboxDestroy(client, { sandboxId, orgId });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+async function createStdinStream(region, apiKey, orgId, logger) {
+    const urls = getServiceUrls(region);
+    const streamBaseUrl = urls.stream;
+    // Build URL with orgId query param for CLI token validation
+    const queryParams = new URLSearchParams();
+    if (orgId) {
+        queryParams.set('orgId', orgId);
+    }
+    const queryString = queryParams.toString();
+    const url = `${streamBaseUrl}${queryString ? `?${queryString}` : ''}`;
+    logger?.trace('creating stdin stream: %s', url);
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            name: `sandbox-stdin-${Date.now()}`,
+        }),
+    });
+    if (!response.ok) {
+        if (response.status === 402) {
+            throw new PaymentRequiredError({
+                url: url,
+            });
+        }
+        throw new Error(`Failed to create stdin stream: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    logger?.debug('created stdin stream: %s', data.id);
+    // Include orgId in the URL for subsequent PUT requests (needed for CLI token auth)
+    const putQueryString = orgId ? `?orgId=${encodeURIComponent(orgId)}` : '';
+    return {
+        id: data.id,
+        url: `${streamBaseUrl}/${data.id}${putQueryString}`,
+    };
+}
+async function streamStdinToUrl(stdin, url, apiKey, signal, logger) {
+    try {
+        logger?.debug('streaming stdin to: %s', url);
+        // Convert Node.js Readable to a web ReadableStream for fetch body
+        let controllerClosed = false;
+        const webStream = new ReadableStream({
+            start(controller) {
+                stdin.on('data', (chunk) => {
+                    if (!signal.aborted && !controllerClosed) {
+                        controller.enqueue(chunk);
+                    }
+                });
+                stdin.on('end', () => {
+                    if (!controllerClosed) {
+                        controllerClosed = true;
+                        controller.close();
+                    }
+                });
+                stdin.on('error', (err) => {
+                    if (!controllerClosed) {
+                        controllerClosed = true;
+                        controller.error(err);
+                    }
+                });
+                signal.addEventListener('abort', () => {
+                    if (!controllerClosed) {
+                        controllerClosed = true;
+                        controller.close();
+                    }
+                });
+            },
+        });
+        const response = await fetch(url, {
+            method: 'PUT',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: webStream,
+            signal,
+            duplex: 'half',
+        });
+        if (!response.ok) {
+            logger?.debug('stdin stream PUT failed: %d', response.status);
+        }
+        else {
+            logger?.debug('stdin stream completed');
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            logger?.debug('stdin stream aborted (expected on completion)');
+        }
+        else {
+            logger?.debug('stdin stream error: %s', err);
+        }
+    }
+}
+async function streamUrlToWritable(url, writable, signal, logger, started) {
+    try {
+        logger?.debug('fetching stream: %s', url);
+        const response = await fetch(url, { signal });
+        logger?.debug('stream response status: %d', response.status);
+        if (timingLogsEnabled && started)
+            console.error(`[TIMING] +${Date.now() - started}ms: stream response received (status: ${response.status})`);
+        if (!response.ok || !response.body) {
+            logger?.debug('stream response not ok or no body');
+            return;
+        }
+        const reader = response.body.getReader();
+        let firstChunk = true;
+        // Read until EOF - Pulse will block until data is available
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                logger?.debug('stream EOF');
+                if (timingLogsEnabled && started)
+                    console.error(`[TIMING] +${Date.now() - started}ms: stream EOF`);
+                break;
+            }
+            if (value) {
+                if (firstChunk && started) {
+                    if (timingLogsEnabled)
+                        console.error(`[TIMING] +${Date.now() - started}ms: first chunk (${value.length} bytes)`);
+                    firstChunk = false;
+                }
+                logger?.debug('stream chunk: %d bytes', value.length);
+                await writeAndDrain(writable, value);
+            }
+        }
+        // Signal end-of-stream to the tee/pipe chain so downstream
+        // consumers (e.g. process.stdout pipe) know no more data is coming.
+        writable.end();
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            logger?.debug('stream aborted');
+            return;
+        }
+        logger?.debug('stream error: %s', err);
+    }
+}
+//# sourceMappingURL=run.js.map