@agentuity/core 1.0.32 → 1.0.33

package/src/api/sandbox/destroy.ts

@@ -0,0 +1,41 @@
+import type { z } from 'zod';
+import { type APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { throwSandboxError } from './util.ts';
+
+export const DestroyResponseSchema = APIResponseSchemaNoData();
+
+export interface SandboxDestroyParams {
+	sandboxId: string;
+	orgId?: string;
+}
+
+/**
+ * Destroys a sandbox and releases all associated resources.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID to destroy
+ * @throws {SandboxResponseError} If the sandbox is not found or destruction fails
+ */
+export async function sandboxDestroy(
+	client: APIClient,
+	params: SandboxDestroyParams
+): Promise<void> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${sandboxId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof DestroyResponseSchema>>(
+		url,
+		DestroyResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/api/sandbox/disk-checkpoint.ts

@@ -0,0 +1,179 @@
+import type { z as zType } from 'zod';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
+import { throwSandboxError } from './util.ts';
+
+// --- Schemas ---
+
+export const DiskCheckpointInfoSchema = z.object({
+	id: z.string().describe('Globally unique checkpoint ID (ckpt_xxx)'),
+	name: z.string().describe('User-provided checkpoint name'),
+	createdAt: z.string().describe('ISO timestamp of creation'),
+	parent: z.string().describe('Parent checkpoint name (empty for base)'),
+});
+
+export type DiskCheckpointInfo = z.infer<typeof DiskCheckpointInfoSchema>;
+
+const CreateDiskCheckpointDataSchema = DiskCheckpointInfoSchema;
+export const CreateDiskCheckpointResponseSchema = APIResponseSchema(CreateDiskCheckpointDataSchema);
+
+const ListDiskCheckpointsDataSchema = z.object({
+	checkpoints: z.array(DiskCheckpointInfoSchema),
+});
+export const ListDiskCheckpointsResponseSchema = APIResponseSchema(ListDiskCheckpointsDataSchema);
+
+export const RestoreDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+export const DeleteDiskCheckpointResponseSchema = APIResponseSchemaNoData();
+
+// --- Params ---
+
+export interface DiskCheckpointCreateParams {
+	sandboxId: string;
+	name: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointListParams {
+	sandboxId: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointRestoreParams {
+	sandboxId: string;
+	checkpointId: string;
+	orgId?: string;
+}
+
+export interface DiskCheckpointDeleteParams {
+	sandboxId: string;
+	checkpointId: string;
+	orgId?: string;
+}
+
+// --- API Functions ---
+
+/**
+ * Creates a new disk checkpoint for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint name
+ * @throws {SandboxResponseError} If the sandbox is not found or checkpoint creation fails
+ */
+export async function diskCheckpointCreate(
+	client: APIClient,
+	params: DiskCheckpointCreateParams
+): Promise<DiskCheckpointInfo> {
+	const { sandboxId, name, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof CreateDiskCheckpointResponseSchema>>(
+		url,
+		{ name },
+		CreateDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Lists all disk checkpoints for a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID
+ * @throws {SandboxResponseError} If the sandbox is not found or listing fails
+ */
+export async function diskCheckpointList(
+	client: APIClient,
+	params: DiskCheckpointListParams
+): Promise<DiskCheckpointInfo[]> {
+	const { sandboxId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/checkpoints/${encodeURIComponent(sandboxId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<zType.infer<typeof ListDiskCheckpointsResponseSchema>>(
+		url,
+		ListDiskCheckpointsResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data.checkpoints;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Restores a sandbox to a specific disk checkpoint.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or restore fails
+ */
+export async function diskCheckpointRestore(
+	client: APIClient,
+	params: DiskCheckpointRestoreParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}/restore${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<zType.infer<typeof RestoreDiskCheckpointResponseSchema>>(
+		url,
+		undefined,
+		RestoreDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+/**
+ * Deletes a disk checkpoint from a sandbox.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including the sandbox ID and checkpoint ID
+ * @throws {SandboxResponseError} If the sandbox or checkpoint is not found, or deletion fails
+ */
+export async function diskCheckpointDelete(
+	client: APIClient,
+	params: DiskCheckpointDeleteParams
+): Promise<void> {
+	const { sandboxId, checkpointId, orgId } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/checkpoint/${encodeURIComponent(checkpointId)}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<zType.infer<typeof DeleteDiskCheckpointResponseSchema>>(
+		url,
+		DeleteDiskCheckpointResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/api/sandbox/execute.ts

@@ -0,0 +1,132 @@
+import type { ExecuteOptions, Execution, ExecutionStatus } from '../../services/sandbox.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { SandboxBusyError, throwSandboxError } from './util.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'),
+	})
+	.describe('Response data from command execution');
+
+export const ExecuteResponseSchema = APIResponseSchema(ExecuteDataSchema);
+
+export interface SandboxExecuteParams {
+	sandboxId: string;
+	options: ExecuteOptions;
+	orgId?: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * 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: f.content.toString('base64'),
+		}));
+	}
+	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) {
+		// 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 (
+			error &&
+			typeof error === 'object' &&
+			'_tag' in error &&
+			(error as { _tag: string })._tag === 'APIErrorResponse' &&
+			'status' in error &&
+			(error as { status: number }).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,
+		};
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}

package/src/api/sandbox/execution.ts

@@ -0,0 +1,183 @@
+import type { ExecutionStatus } from '../../services/sandbox.ts';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+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: z
+			.enum(['queued', 'running', 'completed', 'failed', 'timeout', 'cancelled'])
+			.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'),
+	})
+	.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 interface ExecutionInfo {
+	executionId: string;
+	sandboxId: string;
+	type?: string;
+	status: ExecutionStatus;
+	command?: string[];
+	exitCode?: number;
+	durationMs?: number;
+	startedAt?: string;
+	completedAt?: string;
+	error?: string;
+	stdoutStreamUrl?: string;
+	stderrStreamUrl?: string;
+}
+
+export interface ExecutionGetParams {
+	executionId: string;
+	orgId?: string;
+	/**
+	 * Optional wait duration for long-polling. If specified, the server will hold
+	 * the connection open until the execution reaches a terminal state (completed,
+	 * failed, timeout, cancelled) or the wait duration expires.
+	 *
+	 * Format: duration string like "30s", "1m", "5m"
+	 * Maximum: 5 minutes (server will cap at this value)
+	 *
+	 * If not specified, returns immediately with current status.
+	 */
+	wait?: string;
+}
+
+/**
+ * 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 } = 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
+	);
+
+	if (resp.success) {
+		return {
+			executionId: resp.data.executionId,
+			sandboxId: resp.data.sandboxId,
+			type: resp.data.type,
+			status: resp.data.status as ExecutionStatus,
+			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,
+		};
+	}
+
+	throwSandboxError(resp, { executionId });
+}
+
+export interface ExecutionListParams {
+	sandboxId: string;
+	orgId?: string;
+	limit?: number;
+}
+
+export interface ExecutionListResponse {
+	executions: ExecutionInfo[];
+}
+
+/**
+ * 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 {
+			executions: resp.data.executions.map((exec) => ({
+				executionId: exec.executionId,
+				sandboxId: exec.sandboxId,
+				type: exec.type,
+				status: exec.status as ExecutionStatus,
+				command: exec.command,
+				exitCode: exec.exitCode,
+				durationMs: exec.durationMs,
+				startedAt: exec.startedAt,
+				completedAt: exec.completedAt,
+				error: exec.error,
+				stdoutStreamUrl: exec.stdoutStreamUrl,
+				stderrStreamUrl: exec.stderrStreamUrl,
+			})),
+		};
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}