@agentuity/core 1.0.33 → 1.0.35

package/src/services/sandbox/client.ts

@@ -0,0 +1,435 @@
+import {
+	ExecuteOptionsSchema as CoreExecuteOptionsSchema,
+	type SandboxCreateOptions,
+	type SandboxInfo,
+	type Execution,
+	type FileToWrite,
+	type SandboxRunOptions,
+	type SandboxRunResult,
+} from './types.ts';
+import type { Logger } from '../../logger.ts';
+import type { Readable, Writable } from 'node:stream';
+import { z } from 'zod';
+import { APIClient } from '../api.ts';
+import { getEnv } from '../env.ts';
+import { sandboxCreate, type SandboxCreateResponse } from './create.ts';
+import { sandboxDestroy } from './destroy.ts';
+import { sandboxGet } from './get.ts';
+import { sandboxExecute } from './execute.ts';
+import { sandboxWriteFiles, sandboxReadFile } from './files.ts';
+import { sandboxRun } from './run.ts';
+import { executionGet, type ExecutionInfo } from './execution.ts';
+import { createMinimalLogger } from '../logger.ts';
+import { getServiceUrls } from '../config.ts';
+import { writeAndDrain } from './util.ts';
+
+// Server-side long-poll wait duration (max 5 minutes supported by server)
+const EXECUTION_WAIT_DURATION = '5m';
+
+/**
+ * Wait for execution completion using server-side long-polling.
+ * This is more efficient than client-side polling and provides immediate
+ * error detection if the sandbox is terminated.
+ */
+async function waitForExecution(
+	client: APIClient,
+	executionId: string,
+	orgId?: string,
+	signal?: AbortSignal
+): Promise<ExecutionInfo> {
+	if (signal?.aborted) {
+		throw new DOMException('The operation was aborted.', 'AbortError');
+	}
+
+	// Use server-side long-polling - the server will hold the connection
+	// until the execution reaches a terminal state or the wait duration expires
+	return executionGet(client, {
+		executionId,
+		orgId,
+		wait: EXECUTION_WAIT_DURATION,
+	});
+}
+
+/**
+ * Pipes a remote stream URL to a local writable stream with proper backpressure handling
+ */
+async function pipeStreamToWritable(
+	streamUrl: string,
+	writable: Writable,
+	signal?: AbortSignal
+): Promise<void> {
+	const response = await fetch(streamUrl, { signal });
+	if (!response.ok) {
+		throw new Error(`Failed to fetch stream: ${response.status} ${response.statusText}`);
+	}
+	if (!response.body) {
+		return;
+	}
+
+	const reader = response.body.getReader();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value) {
+				await writeAndDrain(writable, value);
+			}
+		}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {
+			// Ignore cancel errors - stream may already be closed
+		}
+		reader.releaseLock();
+	}
+}
+
+/**
+ * Extended execute options that support piping output to writable streams
+ */
+export const ExecuteOptionsSchema = CoreExecuteOptionsSchema.extend({
+	/** Pipe stdout/stderr to writable streams (e.g., process.stdout) */
+	pipe: z
+		.object({
+			stdout: z.custom<Writable>().optional().describe('stdout writable stream'),
+			stderr: z.custom<Writable>().optional().describe('stderr writable stream'),
+		})
+		.optional()
+		.describe('Pipe stdout/stderr to writable streams (e.g., process.stdout)'),
+});
+export type ExecuteOptions = z.infer<typeof ExecuteOptionsSchema>;
+
+export const SandboxClientOptionsSchema = z.object({
+	/** API key for authentication. Defaults to AGENTUITY_SDK_KEY/AGENTUITY_CLI_KEY */
+	apiKey: z.string().optional().describe('API key for authentication'),
+	/** Base URL for the sandbox API */
+	url: z.string().optional().describe('Base URL for the sandbox API'),
+	/** Organization ID for multi-tenant operations */
+	orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+	/** Custom logger instance */
+	logger: z.custom<Logger>().optional().describe('Custom logger instance'),
+});
+export type SandboxClientOptions = z.infer<typeof SandboxClientOptionsSchema>;
+
+/**
+ * I/O options for one-shot sandbox execution via run()
+ */
+export const SandboxClientRunIOSchema = z.object({
+	/** AbortSignal to cancel the execution */
+	signal: z.custom<AbortSignal>().optional().describe('AbortSignal to cancel the execution'),
+	/** Readable stream for stdin input */
+	stdin: z.custom<Readable>().optional().describe('Readable stream for stdin input'),
+	/** Writable stream for stdout output */
+	stdout: z.custom<Writable>().optional().describe('Writable stream for stdout output'),
+	/** Writable stream for stderr output */
+	stderr: z.custom<Writable>().optional().describe('Writable stream for stderr output'),
+	/** Optional logger override for this run */
+	logger: z.custom<Logger>().optional().describe('Optional logger override for this run'),
+});
+export type SandboxClientRunIO = z.infer<typeof SandboxClientRunIOSchema>;
+
+/**
+ * A sandbox instance returned by SandboxClient.create()
+ */
+export interface SandboxInstance {
+	/**
+	 * Unique sandbox identifier
+	 */
+	id: string;
+
+	/**
+	 * Sandbox status at creation time
+	 */
+	status: SandboxCreateResponse['status'];
+
+	/**
+	 * URL to stream stdout output
+	 */
+	stdoutStreamUrl?: string;
+
+	/**
+	 * URL to stream stderr output
+	 */
+	stderrStreamUrl?: string;
+
+	/**
+	 * URL to stream audit events (eBPF/Tetragon security events)
+	 */
+	auditStreamUrl?: string;
+
+	/**
+	 * Execute a command in the sandbox
+	 */
+	execute(options: ExecuteOptions): Promise<Execution>;
+
+	/**
+	 * Write files to the sandbox workspace
+	 */
+	writeFiles(files: FileToWrite[]): Promise<number>;
+
+	/**
+	 * Read a file from the sandbox workspace
+	 */
+	readFile(path: string): Promise<ReadableStream<Uint8Array>>;
+
+	/**
+	 * Get current sandbox information
+	 */
+	get(): Promise<SandboxInfo>;
+
+	/**
+	 * Destroy the sandbox and release all resources
+	 */
+	destroy(): Promise<void>;
+}
+
+/**
+ * Convenience client for sandbox operations.
+ *
+ * @example
+ * ```typescript
+ * // Interactive sandbox usage
+ * const client = new SandboxClient();
+ * const sandbox = await client.create();
+ * const result = await sandbox.execute({ command: ['echo', 'hello'] });
+ * await sandbox.destroy();
+ *
+ * // One-shot execution with streaming
+ * const result = await client.run(
+ *   { command: { exec: ['bun', 'run', 'script.ts'] } },
+ *   { stdout: process.stdout, stderr: process.stderr }
+ * );
+ * ```
+ */
+export class SandboxClient {
+	readonly #client: APIClient;
+	readonly #orgId?: string;
+	readonly #apiKey?: string;
+	readonly #region: string;
+	readonly #logger: Logger;
+
+	constructor(options: SandboxClientOptions = {}) {
+		const apiKey = options.apiKey || getEnv('AGENTUITY_SDK_KEY') || getEnv('AGENTUITY_CLI_KEY');
+
+		const region = getEnv('AGENTUITY_REGION') ?? 'usc';
+		const serviceUrls = getServiceUrls(region);
+
+		const url =
+			options.url ||
+			getEnv('AGENTUITY_SANDBOX_URL') ||
+			getEnv('AGENTUITY_CATALYST_URL') ||
+			getEnv('AGENTUITY_TRANSPORT_URL') ||
+			serviceUrls.sandbox;
+
+		const logger = options.logger ?? createMinimalLogger();
+
+		// Disable retries for sandbox operations - 409 Conflict means sandbox is busy,
+		// not a retryable rate limit. Retrying would waste ~360s (4 attempts × 90s timeout).
+		this.#client = new APIClient(url, logger, apiKey ?? '', { maxRetries: 0 });
+		this.#orgId = options.orgId;
+		this.#apiKey = apiKey;
+		this.#region = region;
+		this.#logger = logger;
+	}
+
+	/**
+	 * Run a one-shot command in a new sandbox (creates, executes, destroys)
+	 *
+	 * This is a high-level convenience method that handles the full lifecycle:
+	 * creating a sandbox, streaming I/O, polling for completion, and cleanup.
+	 *
+	 * @param options - Execution options including command and configuration
+	 * @param io - Optional I/O streams and abort signal
+	 * @returns The run result including exit code and duration
+	 * @throws {Error} If stdin is provided without an API key
+	 *
+	 * @example
+	 * ```typescript
+	 * const client = new SandboxClient();
+	 * const result = await client.run(
+	 *   { command: { exec: ['bun', 'run', 'script.ts'] } },
+	 *   { stdout: process.stdout, stderr: process.stderr }
+	 * );
+	 * console.log('Exit code:', result.exitCode);
+	 * ```
+	 */
+	async run(options: SandboxRunOptions, io: SandboxClientRunIO = {}): Promise<SandboxRunResult> {
+		if (io.stdin && !this.#apiKey) {
+			throw new Error('SandboxClient.run(): stdin streaming requires an API key');
+		}
+
+		return sandboxRun(this.#client, {
+			options,
+			orgId: this.#orgId,
+			region: this.#region,
+			apiKey: this.#apiKey,
+			signal: io.signal,
+			stdin: io.stdin,
+			stdout: io.stdout,
+			stderr: io.stderr,
+			logger: io.logger ?? this.#logger,
+		});
+	}
+
+	/**
+	 * Create a new sandbox instance
+	 *
+	 * @param options - Optional sandbox configuration
+	 * @returns A sandbox instance with execute and destroy methods
+	 */
+	async create(options?: SandboxCreateOptions): Promise<SandboxInstance> {
+		const response = await sandboxCreate(this.#client, {
+			options,
+			orgId: this.#orgId,
+		});
+
+		const sandboxId = response.sandboxId;
+		const client = this.#client;
+		const orgId = this.#orgId;
+
+		return {
+			id: sandboxId,
+			status: response.status,
+			stdoutStreamUrl: response.stdoutStreamUrl,
+			stderrStreamUrl: response.stderrStreamUrl,
+			auditStreamUrl: response.auditStreamUrl,
+
+			async execute(executeOptions: ExecuteOptions): Promise<Execution> {
+				const { pipe, ...coreOptions } = executeOptions;
+
+				const initialResult = await sandboxExecute(client, {
+					sandboxId,
+					options: coreOptions,
+					orgId,
+					signal: coreOptions.signal,
+				});
+
+				// If pipe options provided, stream the output to the writable streams
+				if (pipe) {
+					const streamPromises: Promise<void>[] = [];
+
+					if (pipe.stdout && initialResult.stdoutStreamUrl) {
+						streamPromises.push(
+							pipeStreamToWritable(
+								initialResult.stdoutStreamUrl,
+								pipe.stdout,
+								coreOptions.signal
+							)
+						);
+					}
+					if (pipe.stderr && initialResult.stderrStreamUrl) {
+						streamPromises.push(
+							pipeStreamToWritable(
+								initialResult.stderrStreamUrl,
+								pipe.stderr,
+								coreOptions.signal
+							)
+						);
+					}
+
+					// Wait for all streams to complete
+					if (streamPromises.length > 0) {
+						await Promise.all(streamPromises);
+					}
+				}
+
+				// Wait for execution to complete and get final result with exit code
+				const finalResult = await waitForExecution(
+					client,
+					initialResult.executionId,
+					orgId,
+					coreOptions.signal
+				);
+
+				return {
+					executionId: finalResult.executionId,
+					status: finalResult.status,
+					exitCode: finalResult.exitCode,
+					durationMs: finalResult.durationMs,
+					stdoutStreamUrl: initialResult.stdoutStreamUrl,
+					stderrStreamUrl: initialResult.stderrStreamUrl,
+				};
+			},
+
+			async writeFiles(files: FileToWrite[]): Promise<number> {
+				const result = await sandboxWriteFiles(client, { sandboxId, files, orgId });
+				return result.filesWritten;
+			},
+
+			async readFile(path: string): Promise<ReadableStream<Uint8Array>> {
+				return sandboxReadFile(client, { sandboxId, path, orgId });
+			},
+
+			async get(): Promise<SandboxInfo> {
+				return sandboxGet(client, { sandboxId, orgId });
+			},
+
+			async destroy(): Promise<void> {
+				return sandboxDestroy(client, { sandboxId, orgId });
+			},
+		};
+	}
+
+	/**
+	 * Get sandbox information by ID
+	 *
+	 * @param sandboxId - The sandbox ID
+	 * @returns Sandbox information
+	 */
+	async get(sandboxId: string): Promise<SandboxInfo> {
+		return sandboxGet(this.#client, { sandboxId, orgId: this.#orgId });
+	}
+
+	/**
+	 * Destroy a sandbox by ID
+	 *
+	 * @param sandboxId - The sandbox ID to destroy
+	 */
+	async destroy(sandboxId: string): Promise<void> {
+		return sandboxDestroy(this.#client, { sandboxId, orgId: this.#orgId });
+	}
+
+	/**
+	 * Write files to a sandbox workspace
+	 *
+	 * @param sandboxId - The sandbox ID
+	 * @param files - Array of files to write with path and content
+	 * @param signal - Optional AbortSignal to cancel the operation
+	 * @returns The number of files written
+	 */
+	async writeFiles(
+		sandboxId: string,
+		files: FileToWrite[],
+		signal?: AbortSignal
+	): Promise<number> {
+		const result = await sandboxWriteFiles(this.#client, {
+			sandboxId,
+			files,
+			orgId: this.#orgId,
+			signal,
+		});
+		return result.filesWritten;
+	}
+
+	/**
+	 * Read a file from a sandbox workspace
+	 *
+	 * @param sandboxId - The sandbox ID
+	 * @param path - Path to the file relative to the sandbox workspace
+	 * @param signal - Optional AbortSignal to cancel the operation
+	 * @returns A ReadableStream of the file contents
+	 */
+	async readFile(
+		sandboxId: string,
+		path: string,
+		signal?: AbortSignal
+	): Promise<ReadableStream<Uint8Array>> {
+		return sandboxReadFile(this.#client, {
+			sandboxId,
+			path,
+			orgId: this.#orgId,
+			signal,
+		});
+	}
+}

package/src/services/sandbox/create.ts

@@ -0,0 +1,249 @@
+import type { SandboxCreateOptions } from './types.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { NPM_PACKAGE_NAME_PATTERN } from './snapshot-build.ts';
+import { throwSandboxError } from './util.ts';
+
+export const SandboxCreateRequestSchema = z
+	.object({
+		projectId: z.string().optional().describe('Project ID to associate the sandbox with'),
+		runtime: z.string().optional().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
+		runtimeId: z.string().optional().describe('Runtime ID (e.g., "srt_xxx")'),
+		name: z.string().optional().describe('Optional sandbox name'),
+		description: z.string().optional().describe('Optional sandbox description'),
+		resources: z
+			.object({
+				memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
+				cpu: z.string().optional().describe('CPU limit (e.g., "0.5", "1")'),
+				disk: z.string().optional().describe('Disk size limit (e.g., "1Gi", "10Gi")'),
+			})
+			.optional()
+			.describe('Resource constraints for the sandbox'),
+		env: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe('Environment variables to set in the sandbox'),
+		network: z
+			.object({
+				enabled: z.boolean().optional().describe('Whether network access is enabled'),
+				port: z
+					.number()
+					.int()
+					.min(1024)
+					.max(65535)
+					.optional()
+					.describe('Port to expose from the sandbox (1024-65535)'),
+			})
+			.optional()
+			.describe('Network configuration for the sandbox'),
+		stream: z
+			.object({
+				stdout: z.string().optional().describe('Stream ID for stdout output'),
+				stderr: z.string().optional().describe('Stream ID for stderr output'),
+				stdin: z.string().optional().describe('Stream ID for stdin input'),
+				timestamps: z.boolean().optional().describe('Whether to include timestamps in output'),
+			})
+			.optional()
+			.describe('Stream configuration for I/O redirection'),
+		timeout: z
+			.object({
+				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h")'),
+				execution: z.string().optional().describe('Maximum execution time (e.g., "30m", "2h")'),
+			})
+			.optional()
+			.describe('Timeout settings for the sandbox'),
+		command: z
+			.object({
+				exec: z.array(z.string()).describe('Command and arguments to execute'),
+				files: z
+					.array(
+						z.object({
+							path: z
+								.string()
+								.describe('Path to the file relative to the sandbox workspace'),
+							content: z.string().describe('Base64-encoded file content'),
+						})
+					)
+					.optional()
+					.describe('Files to write before execution (deprecated: use top-level files)'),
+				mode: z
+					.enum(['oneshot', 'interactive'])
+					.optional()
+					.describe('Execution mode: oneshot runs once, interactive keeps running'),
+			})
+			.optional()
+			.describe('Initial command to run in the sandbox'),
+		files: z
+			.array(
+				z.object({
+					path: z.string().describe('Path to the file relative to the sandbox workspace'),
+					content: z.string().describe('Base64-encoded file content'),
+				})
+			)
+			.optional()
+			.describe('Files to write to sandbox on creation'),
+		snapshot: z.string().optional().describe('Snapshot ID to restore the sandbox from'),
+		dependencies: z
+			.array(z.string())
+			.optional()
+			.describe('Apt packages to install when creating the sandbox'),
+		packages: z
+			.array(
+				z
+					.string()
+					.regex(
+						NPM_PACKAGE_NAME_PATTERN,
+						'Invalid npm/bun package specifier: must not contain whitespace, semicolons, backticks, pipes, or dollar signs'
+					)
+			)
+			.optional()
+			.describe('npm/bun packages to install globally when creating the sandbox'),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe('Optional user-defined metadata to associate with the sandbox'),
+	})
+	.refine(
+		(data) => {
+			// If snapshot is provided, runtime and runtimeId must not be provided
+			if (data.snapshot) {
+				return !data.runtime && !data.runtimeId;
+			}
+			return true;
+		},
+		{
+			message: 'cannot specify both snapshot and runtime; snapshot includes its own runtime',
+			path: ['snapshot'],
+		}
+	)
+	.describe('Request body for creating a new sandbox');
+
+export const SandboxCreateDataSchema = z
+	.object({
+		sandboxId: z.string().describe('Unique identifier for the created sandbox'),
+		status: z
+			.enum([
+				'creating',
+				'idle',
+				'running',
+				'paused',
+				'stopping',
+				'suspended',
+				'terminated',
+				'failed',
+			])
+			.describe('Current status of the sandbox'),
+		stdoutStreamId: z.string().optional().describe('Stream ID for reading stdout'),
+		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
+		stderrStreamId: z.string().optional().describe('Stream ID for reading stderr'),
+		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+		auditStreamId: z.string().optional().describe('Stream ID for reading audit events'),
+		auditStreamUrl: z.string().optional().describe('URL for streaming audit events'),
+	})
+	.describe('Response data from sandbox creation');
+
+export const SandboxCreateResponseSchema = APIResponseSchema(SandboxCreateDataSchema);
+
+export type SandboxCreateResponse = z.infer<typeof SandboxCreateDataSchema>;
+
+export const SandboxCreateParamsSchema = z.object({
+	options: z.custom<SandboxCreateOptions>().optional().describe('Optional sandbox create options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+});
+
+export type SandboxCreateParams = z.infer<typeof SandboxCreateParamsSchema>;
+
+/**
+ * Creates a new sandbox instance.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters for creating the sandbox
+ * @returns The created sandbox response including sandbox ID and stream URLs
+ * @throws {SandboxResponseError} If the sandbox creation fails
+ */
+export async function sandboxCreate(
+	client: APIClient,
+	params: SandboxCreateParams = {}
+): Promise<SandboxCreateResponse> {
+	const { options = {}, orgId } = params;
+	const body: z.infer<typeof SandboxCreateRequestSchema> = {};
+
+	if (options.projectId) {
+		body.projectId = options.projectId;
+	}
+	if (options.runtime) {
+		body.runtime = options.runtime;
+	}
+	if (options.runtimeId) {
+		body.runtimeId = options.runtimeId;
+	}
+	if (options.name) {
+		body.name = options.name;
+	}
+	if (options.description) {
+		body.description = options.description;
+	}
+	if (options.resources) {
+		body.resources = options.resources;
+	}
+	if (options.env) {
+		body.env = options.env;
+	}
+	if (options.network) {
+		body.network = options.network;
+	}
+	if (options.stream) {
+		body.stream = options.stream;
+	}
+	if (options.timeout) {
+		body.timeout = options.timeout;
+	}
+	if (options.command) {
+		body.command = {
+			exec: options.command.exec,
+			mode: options.command.mode,
+			files: options.command.files?.map((f) => ({
+				path: f.path,
+				content: f.content.toString('base64'),
+			})),
+		};
+	}
+	if (options.files && options.files.length > 0) {
+		body.files = options.files.map((f) => ({
+			path: f.path,
+			content: f.content.toString('base64'),
+		}));
+	}
+	if (options.snapshot) {
+		body.snapshot = options.snapshot;
+	}
+	if (options.dependencies && options.dependencies.length > 0) {
+		body.dependencies = options.dependencies;
+	}
+	if (options.packages && options.packages.length > 0) {
+		body.packages = options.packages;
+	}
+	if (options.metadata) {
+		body.metadata = options.metadata;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof SandboxCreateResponseSchema>>(
+		url,
+		body,
+		SandboxCreateResponseSchema,
+		SandboxCreateRequestSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, {});
+}