@agentuity/server 0.1.22 → 0.1.24

package/src/api/sandbox/snapshot.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
-import { SandboxResponseError, API_VERSION } from './util';
+import { SandboxResponseError, throwSandboxError, API_VERSION } from './util';
 
 const SnapshotFileInfoSchema = z
 	.object({
@@ -186,7 +186,9 @@ const _SnapshotLineageParamsSchema = z
 		snapshot: z
 			.string()
 			.optional()
-			.describe('Snapshot ID or name:tag to start lineage from (e.g., "sss_xxx" or "myimage:v1")'),
+			.describe(
+				'Snapshot ID or name:tag to start lineage from (e.g., "sss_xxx" or "myimage:v1")'
+			),
 		name: z
 			.string()
 			.optional()
@@ -258,7 +260,7 @@ export async function snapshotCreate(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 /**
@@ -286,7 +288,7 @@ export async function snapshotGet(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 /**
@@ -314,7 +316,7 @@ export async function snapshotList(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 /**
@@ -338,7 +340,7 @@ export async function snapshotDelete(
 	);
 
 	if (!resp.success) {
-		throw new SandboxResponseError({ message: resp.message });
+		throwSandboxError(resp, {});
 	}
 }
 
@@ -368,7 +370,7 @@ export async function snapshotTag(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 /**
@@ -411,7 +413,7 @@ export async function snapshotLineage(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 // ===== Public Snapshot API =====
@@ -420,9 +422,7 @@ const _SnapshotPublicGetParamsSchema = z
 	.object({
 		snapshotRef: z
 			.string()
-			.describe(
-				'Snapshot reference: ID (snp_xxx), full name (@slug/name:tag), or name:tag'
-			),
+			.describe('Snapshot reference: ID (snp_xxx), full name (@slug/name:tag), or name:tag'),
 	})
 	.describe('Parameters for getting a public snapshot');
 
@@ -469,7 +469,7 @@ export async function snapshotPublicGet(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 // ===== Snapshot Build API =====
@@ -600,7 +600,7 @@ export async function snapshotBuildInit(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 /**
@@ -638,7 +638,7 @@ export async function snapshotBuildFinalize(
 		return resp.data;
 	}
 
-	throw new SandboxResponseError({ message: resp.message });
+	throwSandboxError(resp, {});
 }
 
 // ===== Snapshot Upload API (for public snapshots) =====
@@ -707,5 +707,5 @@ export async function snapshotUpload(
 		return data.data;
 	}
 
-	throw new SandboxResponseError({ message: data.message });
+	throwSandboxError(data, {});
 }

package/src/api/sandbox/util.ts

@@ -5,6 +5,18 @@ interface WritableWithDrain extends EventEmitter {
 	write(chunk: Uint8Array): boolean;
 }
 
+/**
+ * Machine-readable error codes for sandbox operations.
+ * These codes allow programmatic error handling without fragile string matching.
+ */
+export type SandboxErrorCode =
+	| 'SANDBOX_NOT_FOUND'
+	| 'SANDBOX_TERMINATED'
+	| 'EXECUTION_NOT_FOUND'
+	| 'EXECUTION_TIMEOUT'
+	| 'EXECUTION_CANCELLED'
+	| 'SNAPSHOT_NOT_FOUND';
+
 /**
  * Error thrown when a sandbox API request fails.
  *
@@ -17,8 +29,176 @@ export const SandboxResponseError = StructuredError('SandboxResponseError')<{
 	executionId?: string;
 	/** The session ID (trace ID) from the x-session-id response header for OTel correlation */
 	sessionId?: string | null;
+	/** Machine-readable error code for programmatic error handling */
+	code?: SandboxErrorCode;
+}>();
+
+/**
+ * Error thrown when a sandbox is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxGet(client, { sandboxId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxNotFoundError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxNotFoundError = StructuredError('SandboxNotFoundError')<{
+	sandboxId: string;
+}>();
+
+/**
+ * Error thrown when a sandbox has already terminated.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxExecute(client, { sandboxId: 'terminated-sandbox', command: ['ls'] });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxTerminatedError') {
+ *     console.error(`Sandbox terminated: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxTerminatedError = StructuredError('SandboxTerminatedError')<{
+	sandboxId: string;
+}>();
+
+/**
+ * Error thrown when an execution is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await executionGet(client, { executionId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionNotFoundError') {
+ *     console.error(`Execution not found: ${error.executionId}`);
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionNotFoundError = StructuredError('ExecutionNotFoundError')<{
+	executionId: string;
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when an execution times out.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxExecute(client, { sandboxId, command: ['long-running'], timeout: '30s' });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionTimeoutError') {
+ *     console.error('Execution timed out');
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionTimeoutError = StructuredError('ExecutionTimeoutError')<{
+	executionId?: string;
+	sandboxId?: string;
 }>();
 
+/**
+ * Error thrown when an execution is cancelled.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxRun(client, params, { signal: controller.signal });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionCancelledError') {
+ *     console.error('Execution was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionCancelledError = StructuredError('ExecutionCancelledError')<{
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when a snapshot is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await snapshotGet(client, { snapshotId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'SnapshotNotFoundError') {
+ *     console.error(`Snapshot not found: ${error.snapshotId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SnapshotNotFoundError = StructuredError('SnapshotNotFoundError')<{
+	snapshotId?: string;
+}>();
+
+/**
+ * Context for throwing sandbox errors.
+ */
+export interface SandboxErrorContext {
+	sandboxId?: string;
+	executionId?: string;
+	sessionId?: string | null;
+	snapshotId?: string;
+}
+
+/**
+ * Throws the appropriate sandbox error based on the response code.
+ *
+ * This helper centralizes error mapping logic, throwing specific error types
+ * when the backend returns a known error code, and falling back to
+ * SandboxResponseError for unknown codes.
+ *
+ * @param resp - The API response containing message and optional code
+ * @param context - Context about the operation (sandbox ID, execution ID, etc.)
+ * @throws {SandboxNotFoundError} When code is 'SANDBOX_NOT_FOUND'
+ * @throws {SandboxTerminatedError} When code is 'SANDBOX_TERMINATED'
+ * @throws {ExecutionNotFoundError} When code is 'EXECUTION_NOT_FOUND'
+ * @throws {ExecutionTimeoutError} When code is 'EXECUTION_TIMEOUT'
+ * @throws {ExecutionCancelledError} When code is 'EXECUTION_CANCELLED'
+ * @throws {SnapshotNotFoundError} When code is 'SNAPSHOT_NOT_FOUND'
+ * @throws {SandboxResponseError} For unknown codes or when no code is provided
+ */
+export function throwSandboxError(
+	resp: { message?: string; code?: string },
+	context: SandboxErrorContext
+): never {
+	const { sandboxId, executionId, sessionId, snapshotId } = context;
+	const code = resp.code as SandboxErrorCode | undefined;
+
+	switch (code) {
+		case 'SANDBOX_NOT_FOUND':
+			throw new SandboxNotFoundError({ message: resp.message, sandboxId: sandboxId ?? '' });
+		case 'SANDBOX_TERMINATED':
+			throw new SandboxTerminatedError({ message: resp.message, sandboxId: sandboxId ?? '' });
+		case 'EXECUTION_NOT_FOUND':
+			throw new ExecutionNotFoundError({
+				message: resp.message,
+				executionId: executionId ?? '',
+				sandboxId,
+			});
+		case 'EXECUTION_TIMEOUT':
+			throw new ExecutionTimeoutError({ message: resp.message, executionId, sandboxId });
+		case 'EXECUTION_CANCELLED':
+			throw new ExecutionCancelledError({ message: resp.message, sandboxId });
+		case 'SNAPSHOT_NOT_FOUND':
+			throw new SnapshotNotFoundError({ message: resp.message, snapshotId });
+		default:
+			throw new SandboxResponseError({ message: resp.message, sandboxId, executionId, sessionId, code });
+	}
+}
+
 /** Current sandbox API version */
 export const API_VERSION = '2025-03-17';