@agentuity/core 1.0.33 → 1.0.35

package/src/api/sandbox/client.ts

@@ -1,460 +0,0 @@
-import type {
-	SandboxCreateOptions,
-	SandboxInfo,
-	ExecuteOptions as CoreExecuteOptions,
-	Execution,
-	FileToWrite,
-	SandboxRunOptions,
-	SandboxRunResult,
-} from '../../services/sandbox.ts';
-import type { Logger } from '../../logger.ts';
-import type { Readable, Writable } from 'node:stream';
-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 interface ExecuteOptions extends CoreExecuteOptions {
-	/**
-	 * Pipe stdout/stderr to writable streams (e.g., process.stdout)
-	 */
-	pipe?: {
-		stdout?: Writable;
-		stderr?: Writable;
-	};
-}
-
-export interface SandboxClientOptions {
-	/**
-	 * API key for authentication.
-	 * Defaults to process.env.AGENTUITY_SDK_KEY || process.env.AGENTUITY_CLI_KEY
-	 */
-	apiKey?: string;
-
-	/**
-	 * Base URL for the sandbox API.
-	 * Defaults to process.env.AGENTUITY_SANDBOX_URL ||
-	 *   process.env.AGENTUITY_CATALYST_URL ||
-	 *   process.env.AGENTUITY_TRANSPORT_URL ||
-	 *   regional catalyst URL
-	 */
-	url?: string;
-
-	/**
-	 * Organization ID for multi-tenant operations
-	 */
-	orgId?: string;
-
-	/**
-	 * Custom logger instance
-	 */
-	logger?: Logger;
-}
-
-/**
- * I/O options for one-shot sandbox execution via run()
- */
-export interface SandboxClientRunIO {
-	/**
-	 * AbortSignal to cancel the execution
-	 */
-	signal?: AbortSignal;
-
-	/**
-	 * Readable stream for stdin input
-	 */
-	stdin?: Readable;
-
-	/**
-	 * Writable stream for stdout output
-	 */
-	stdout?: Writable;
-
-	/**
-	 * Writable stream for stderr output
-	 */
-	stderr?: Writable;
-
-	/**
-	 * Optional logger override for this run
-	 */
-	logger?: Logger;
-}
-
-/**
- * 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/api/sandbox/create.ts

@@ -1,256 +0,0 @@
-import type { SandboxCreateOptions, SandboxStatus } from '../../services/sandbox.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 interface SandboxCreateResponse {
-	sandboxId: string;
-	status: SandboxStatus;
-	stdoutStreamId?: string;
-	stdoutStreamUrl?: string;
-	stderrStreamId?: string;
-	stderrStreamUrl?: string;
-	auditStreamId?: string;
-	auditStreamUrl?: string;
-}
-
-export interface SandboxCreateParams {
-	options?: SandboxCreateOptions;
-	orgId?: string;
-}
-
-/**
- * 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, {});
-}