@agentuity/sandbox 3.0.12 → 3.1.1

package/src/execute.ts

@@ -0,0 +1,167 @@
+import type { ExecuteOptions, Execution, ExecutionStatus } from './types.ts';
+import { z } from 'zod';
+import type { APIClient } from '@agentuity/api';
+import { SandboxBusyError, SandboxNotFoundError, throwSandboxError } from './util.ts';
+import { base64Encode } from './base64.ts';
+
+export const ExecuteRequestSchema = z
+	.object({
+		command: z.array(z.string()).describe('Command and arguments to execute'),
+		files: z
+			.array(
+				z.object({
+					path: z.string().describe('File path relative to workspace'),
+					content: z.string().describe('Base64-encoded file content'),
+				})
+			)
+			.optional()
+			.describe('Files to write before execution'),
+		timeout: z.string().optional().describe('Execution timeout (e.g., "30s", "5m")'),
+		stream: z
+			.object({
+				stdout: z.string().optional().describe('Stream ID for stdout output'),
+				stderr: z.string().optional().describe('Stream ID for stderr output'),
+				timestamps: z.boolean().optional().describe('Whether to include timestamps in output'),
+			})
+			.optional()
+			.describe('Stream configuration for output redirection'),
+	})
+	.describe('Request body for executing a command in a sandbox');
+
+export const ExecuteDataSchema = z
+	.object({
+		executionId: z.string().describe('Unique identifier for the execution'),
+		status: z
+			.enum(['queued', 'running', 'completed', 'failed', 'timeout', 'cancelled'])
+			.describe('Current status of the execution'),
+		exitCode: z.number().optional().describe('Exit code of the executed command'),
+		durationMs: z.number().optional().describe('Execution duration in milliseconds'),
+		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
+		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+		outputTruncated: z
+			.boolean()
+			.optional()
+			.describe('Whether the captured output was truncated due to size limits'),
+	})
+	.describe('Response data from command execution');
+
+export const ExecuteResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal(false),
+		message: z.string(),
+		code: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal(true),
+		data: ExecuteDataSchema,
+		/** True if the sandbox was automatically resumed from a suspended state */
+		autoResumed: z.boolean().optional(),
+	}),
+]);
+
+export const SandboxExecuteParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID where command should execute'),
+	options: z.custom<ExecuteOptions>().describe('Command execution options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	signal: z.custom<AbortSignal>().optional().describe('Optional abort signal for cancellation'),
+});
+
+export type SandboxExecuteParams = z.infer<typeof SandboxExecuteParamsSchema>;
+
+/**
+ * Executes a command in an existing sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including sandbox ID and execution options
+ * @returns The execution result including status and stream URLs
+ * @throws {SandboxResponseError} If the execution request fails
+ */
+export async function sandboxExecute(
+	client: APIClient,
+	params: SandboxExecuteParams
+): Promise<Execution> {
+	const { sandboxId, options, orgId, signal } = params;
+	const body: z.infer<typeof ExecuteRequestSchema> = {
+		command: options.command,
+	};
+
+	if (options.files && options.files.length > 0) {
+		body.files = options.files.map((f) => ({
+			path: f.path,
+			content: base64Encode(f.content),
+		}));
+	}
+	if (options.timeout) {
+		body.timeout = options.timeout;
+	}
+	if (options.stream) {
+		body.stream = options.stream;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${sandboxId}/execute${queryString ? `?${queryString}` : ''}`;
+
+	let resp: z.infer<typeof ExecuteResponseSchema>;
+	try {
+		resp = await client.post<z.infer<typeof ExecuteResponseSchema>>(
+			url,
+			body,
+			ExecuteResponseSchema,
+			ExecuteRequestSchema,
+			signal ?? options.signal
+		);
+	} catch (error: unknown) {
+		if (
+			error &&
+			typeof error === 'object' &&
+			'_tag' in error &&
+			(error as { _tag: string })._tag === 'APIErrorResponse' &&
+			'status' in error
+		) {
+			const status = (error as { status: number }).status;
+
+			// Detect 404 Not Found — sandbox may not exist or may still be initializing.
+			// The server normally handles the creating→idle wait transparently, but this
+			// provides a clear typed error if a 404 reaches the SDK for any reason.
+			if (status === 404) {
+				throw new SandboxNotFoundError({
+					message:
+						'Sandbox not found. If you just created this sandbox, it may still be initializing. The server should handle this automatically — if this persists, the sandbox may have been destroyed.',
+					sandboxId,
+				});
+			}
+
+			// Detect 409 Conflict (sandbox busy) and throw a specific error.
+			// The sandbox API client is configured with maxRetries: 0 to fail fast
+			// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
+			// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
+			if (status === 409) {
+				throw new SandboxBusyError({
+					message:
+						'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
+					sandboxId,
+				});
+			}
+		}
+		throw error;
+	}
+
+	if (resp.success) {
+		return {
+			executionId: resp.data.executionId,
+			status: resp.data.status as ExecutionStatus,
+			exitCode: resp.data.exitCode,
+			durationMs: resp.data.durationMs,
+			stdoutStreamUrl: resp.data.stdoutStreamUrl,
+			stderrStreamUrl: resp.data.stderrStreamUrl,
+			outputTruncated: resp.data.outputTruncated,
+			autoResumed: resp.autoResumed,
+		};
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/execution.ts

@@ -0,0 +1,152 @@
+import { ExecutionStatusSchema } from './types.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '@agentuity/api';
+import { throwSandboxError } from './util.ts';
+
+export const ExecutionInfoSchema = z
+	.object({
+		executionId: z.string().describe('Unique identifier for the execution'),
+		sandboxId: z.string().describe('ID of the sandbox where the execution ran'),
+		type: z
+			.string()
+			.optional()
+			.describe('Type of execution (e.g., exec, write_files, read_file)'),
+		status: ExecutionStatusSchema.describe('Current status of the execution'),
+		command: z.array(z.string()).optional().describe('Command that was executed'),
+		exitCode: z.number().optional().describe('Exit code of the executed command'),
+		durationMs: z.number().optional().describe('Execution duration in milliseconds'),
+		startedAt: z.string().optional().describe('ISO timestamp when execution started'),
+		completedAt: z.string().optional().describe('ISO timestamp when execution completed'),
+		error: z.string().optional().describe('Error message if execution failed'),
+		stdoutStreamUrl: z.string().optional().describe('URL to stream stdout output'),
+		stderrStreamUrl: z.string().optional().describe('URL to stream stderr output'),
+		outputTruncated: z
+			.boolean()
+			.optional()
+			.describe('Whether the captured output was truncated due to size limits'),
+	})
+	.describe('Detailed information about a command execution');
+
+export const ExecutionGetResponseSchema = APIResponseSchema(ExecutionInfoSchema);
+
+export const ExecutionListDataSchema = z
+	.object({
+		executions: z.array(ExecutionInfoSchema).describe('List of executions'),
+	})
+	.describe('List of executions for a sandbox');
+
+export const ExecutionListResponseSchema = APIResponseSchema(ExecutionListDataSchema);
+
+export type ExecutionInfo = z.infer<typeof ExecutionInfoSchema>;
+
+export const ExecutionGetParamsSchema = z.object({
+	executionId: z.string().describe('execution id'),
+	orgId: z.string().optional().describe('organization id'),
+	/** Optional wait duration for long-polling. */
+	wait: z.string().optional().describe('wait duration for long-polling'),
+	/** Optional AbortSignal to cancel the in-flight request. */
+	signal: z.custom<AbortSignal>().optional().describe('abort signal for cancellation'),
+});
+export type ExecutionGetParams = z.infer<typeof ExecutionGetParamsSchema>;
+
+/**
+ * Retrieves detailed information about a specific execution.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the execution ID and optional wait duration
+ * @returns Detailed execution information including status, timing, and errors
+ * @throws {SandboxResponseError} If the execution is not found or request fails
+ *
+ * @example
+ * // Immediate return (current behavior)
+ * const info = await executionGet(client, { executionId: 'exec_123' });
+ *
+ * @example
+ * // Long-poll: wait up to 60 seconds for completion
+ * const info = await executionGet(client, { executionId: 'exec_123', wait: '60s' });
+ */
+export async function executionGet(
+	client: APIClient,
+	params: ExecutionGetParams
+): Promise<ExecutionInfo> {
+	const { executionId, orgId, wait, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (wait) {
+		queryParams.set('wait', wait);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/execution/${executionId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ExecutionGetResponseSchema>>(
+		url,
+		ExecutionGetResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return {
+			executionId: resp.data.executionId,
+			sandboxId: resp.data.sandboxId,
+			type: resp.data.type,
+			status: resp.data.status,
+			command: resp.data.command,
+			exitCode: resp.data.exitCode,
+			durationMs: resp.data.durationMs,
+			startedAt: resp.data.startedAt,
+			completedAt: resp.data.completedAt,
+			error: resp.data.error,
+			stdoutStreamUrl: resp.data.stdoutStreamUrl,
+			stderrStreamUrl: resp.data.stderrStreamUrl,
+			outputTruncated: resp.data.outputTruncated,
+		};
+	}
+
+	throwSandboxError(resp, { executionId });
+}
+
+export const ExecutionListParamsSchema = z.object({
+	sandboxId: z.string().describe('sandbox id'),
+	orgId: z.string().optional().describe('organization id'),
+	limit: z.number().optional().describe('limit'),
+});
+export type ExecutionListParams = z.infer<typeof ExecutionListParamsSchema>;
+
+export type ExecutionListResponse = z.infer<typeof ExecutionListDataSchema>;
+
+/**
+ * Lists all executions for a specific sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and optional limit
+ * @returns List of execution information for the sandbox
+ * @throws {SandboxResponseError} If the sandbox is not found or request fails
+ */
+export async function executionList(
+	client: APIClient,
+	params: ExecutionListParams
+): Promise<ExecutionListResponse> {
+	const { sandboxId, orgId, limit } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (limit !== undefined) {
+		queryParams.set('limit', String(limit));
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/executions${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ExecutionListResponseSchema>>(
+		url,
+		ExecutionListResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}