@agentuity/server 1.0.1 → 1.0.3

package/src/api/sandbox/index.ts

@@ -1,103 +1,186 @@
-export { sandboxCreate } from './create';
-export type { SandboxCreateResponse, SandboxCreateParams } from './create';
-export { sandboxExecute } from './execute';
-export type { SandboxExecuteParams } from './execute';
-export { sandboxGet } from './get';
-export type { SandboxGetParams } from './get';
-export { sandboxList } from './list';
-export type { SandboxListParams } from './list';
-export { runtimeList } from './runtime';
-export type { RuntimeListParams } from './runtime';
-export { sandboxDestroy } from './destroy';
+export type { CLISandboxInfo, CLISandboxListData, CLISandboxListOptions } from './cli-list';
+export { cliSandboxList, SandboxListDataSchema, SandboxListResponseSchema } from './cli-list';
+export type {
+	ExecuteOptions,
+	SandboxClientOptions,
+	SandboxClientRunIO,
+	SandboxInstance,
+} from './client';
+export { SandboxClient } from './client';
+export type { SandboxCreateParams, SandboxCreateResponse } from './create';
+export {
+	SandboxCreateDataSchema,
+	SandboxCreateRequestSchema,
+	SandboxCreateResponseSchema,
+	sandboxCreate,
+} from './create';
 export type { SandboxDestroyParams } from './destroy';
-export { sandboxRun } from './run';
-export type { SandboxRunParams } from './run';
-export { executionGet, executionList } from './execution';
+export { DestroyResponseSchema, sandboxDestroy } from './destroy';
+export type { SandboxExecuteParams } from './execute';
+export {
+	ExecuteDataSchema,
+	ExecuteRequestSchema,
+	ExecuteResponseSchema,
+	sandboxExecute,
+} from './execute';
 export type {
-	ExecutionInfo,
 	ExecutionGetParams,
+	ExecutionInfo,
 	ExecutionListParams,
 	ExecutionListResponse,
 } from './execution';
 export {
-	SandboxResponseError,
-	SandboxNotFoundError,
-	SandboxTerminatedError,
-	ExecutionNotFoundError,
-	ExecutionTimeoutError,
-	ExecutionCancelledError,
-	SnapshotNotFoundError,
-	throwSandboxError,
-	writeAndDrain,
-} from './util';
-export type { SandboxErrorCode, SandboxErrorContext } from './util';
-export { SandboxClient } from './client';
-export type {
-	SandboxClientOptions,
-	SandboxClientRunIO,
-	SandboxInstance,
-	ExecuteOptions,
-} from './client';
-export {
-	sandboxWriteFiles,
-	sandboxReadFile,
-	sandboxMkDir,
-	sandboxRmDir,
-	sandboxRmFile,
-	sandboxListFiles,
-	sandboxDownloadArchive,
-	sandboxUploadArchive,
-	sandboxSetEnv,
-} from './files';
+	ExecutionGetResponseSchema,
+	ExecutionInfoSchema,
+	ExecutionListDataSchema,
+	ExecutionListResponseSchema,
+	executionGet,
+	executionList,
+} from './execution';
 export type {
-	WriteFilesParams,
-	WriteFilesResult,
-	ReadFileParams,
+	ArchiveFormat,
+	DownloadArchiveParams,
+	FileInfo,
+	ListFilesParams,
+	ListFilesResult,
 	MkDirParams,
+	ReadFileParams,
 	RmDirParams,
 	RmFileParams,
-	ListFilesParams,
-	ListFilesResult,
-	FileInfo,
-	ArchiveFormat,
-	DownloadArchiveParams,
-	UploadArchiveParams,
 	SetEnvParams,
 	SetEnvResult,
+	UploadArchiveParams,
+	WriteFilesParams,
+	WriteFilesResult,
 } from './files';
 export {
-	snapshotCreate,
-	snapshotGet,
-	snapshotList,
-	snapshotDelete,
-	snapshotTag,
-	snapshotLineage,
-	snapshotPublicGet,
-	snapshotPublicList,
-	snapshotBuildInit,
-	snapshotBuildFinalize,
-	snapshotUpload,
-} from './snapshot';
+	FileInfoSchema,
+	FileToWriteSchema,
+	ListFilesDataSchema,
+	ListFilesResponseSchema,
+	MkDirRequestSchema,
+	MkDirResponseSchema,
+	RmDirRequestSchema,
+	RmDirResponseSchema,
+	RmFileRequestSchema,
+	RmFileResponseSchema,
+	SetEnvDataSchema,
+	SetEnvRequestSchema,
+	SetEnvResponseSchema,
+	sandboxDownloadArchive,
+	sandboxListFiles,
+	sandboxMkDir,
+	sandboxReadFile,
+	sandboxRmDir,
+	sandboxRmFile,
+	sandboxSetEnv,
+	sandboxUploadArchive,
+	sandboxWriteFiles,
+	UploadArchiveResponseSchema,
+	WriteFilesDataSchema,
+	WriteFilesRequestSchema,
+	WriteFilesResponseSchema,
+} from './files';
+export type { SandboxGetParams } from './get';
+export {
+	SandboxAgentInfoSchema,
+	SandboxGetResponseSchema,
+	SandboxInfoDataSchema,
+	SandboxProjectInfoSchema,
+	SandboxResourcesSchema,
+	SandboxUserInfoSchema,
+	sandboxGet,
+} from './get';
+export type { SandboxListParams } from './list';
+export {
+	ListSandboxesDataSchema,
+	ListSandboxesResponseSchema,
+	SandboxInfoSchema,
+	SandboxOrgInfoSchema,
+	SandboxRuntimeInfoSchema,
+	SandboxSnapshotInfoSchema,
+	SandboxSnapshotOrgInfoSchema,
+	SandboxSnapshotUserInfoSchema,
+	sandboxList,
+} from './list';
+export type { ResolvedSandboxInfo } from './resolve';
+export {
+	SandboxResolveDataSchema,
+	SandboxResolveError,
+	SandboxResolveResponseSchema,
+	sandboxResolve,
+} from './resolve';
+export type { SandboxRunParams } from './run';
+export { sandboxRun } from './run';
+export type { RuntimeListParams } from './runtime';
+export {
+	ListRuntimesDataSchema,
+	ListRuntimesResponseSchema,
+	RuntimeInfoSchema,
+	RuntimeRequirementsSchema,
+	runtimeList,
+} from './runtime';
 export type {
-	SnapshotInfo,
-	SnapshotFileInfo,
+	SnapshotBuildFinalizeParams,
+	SnapshotBuildGitInfo,
+	SnapshotBuildInitParams,
+	SnapshotBuildInitResponse,
 	SnapshotCreateParams,
-	SnapshotGetParams,
-	SnapshotListParams,
-	SnapshotListResponse,
 	SnapshotDeleteParams,
-	SnapshotTagParams,
-	SnapshotLineageParams,
+	SnapshotFileInfo,
+	SnapshotGetParams,
+	SnapshotInfo,
 	SnapshotLineageEntry,
+	SnapshotLineageParams,
 	SnapshotLineageResponse,
+	SnapshotListParams,
+	SnapshotListResponse,
 	SnapshotPublicGetParams,
 	SnapshotPublicListParams,
-	SnapshotBuildGitInfo,
-	SnapshotBuildInitParams,
-	SnapshotBuildInitResponse,
-	SnapshotBuildFinalizeParams,
+	SnapshotTagParams,
 	SnapshotUploadParams,
 	SnapshotUploadResponse,
 } from './snapshot';
-export { SnapshotBuildFileSchema } from './snapshot-build';
+export {
+	SnapshotBuildGitInfoSchema,
+	SnapshotBuildInitAPIResponseSchema,
+	SnapshotBuildInitResponseSchema,
+	SnapshotCreateResponseSchema,
+	SnapshotDeleteResponseSchema,
+	SnapshotFileInfoSchema,
+	SnapshotGetResponseSchema,
+	SnapshotInfoSchema,
+	SnapshotLineageDataSchema,
+	SnapshotLineageEntrySchema,
+	SnapshotLineageResponseSchema,
+	SnapshotListDataSchema,
+	SnapshotListResponseSchema,
+	SnapshotOrgInfoSchema,
+	SnapshotUploadResponseSchema,
+	SnapshotUserInfoSchema,
+	snapshotBuildFinalize,
+	snapshotBuildInit,
+	snapshotCreate,
+	snapshotDelete,
+	snapshotGet,
+	snapshotLineage,
+	snapshotList,
+	snapshotPublicGet,
+	snapshotPublicList,
+	snapshotTag,
+	snapshotUpload,
+} from './snapshot';
 export type { SnapshotBuildFile } from './snapshot-build';
+export { SnapshotBuildFileSchema } from './snapshot-build';
+export type { SandboxErrorCode, SandboxErrorContext } from './util';
+export {
+	ExecutionCancelledError,
+	ExecutionNotFoundError,
+	ExecutionTimeoutError,
+	SandboxNotFoundError,
+	SandboxResponseError,
+	SandboxTerminatedError,
+	SnapshotNotFoundError,
+	throwSandboxError,
+	writeAndDrain,
+} from './util';

package/src/api/sandbox/list.ts

@@ -1,22 +1,22 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type {
 	ListSandboxesParams,
 	ListSandboxesResponse,
-	SandboxStatus,
 	SandboxRuntimeInfo,
 	SandboxSnapshotInfo,
+	SandboxStatus,
 } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const SandboxOrgInfoSchema = z
+export const SandboxOrgInfoSchema = z
 	.object({
 		id: z.string().describe('Organization ID'),
 		name: z.string().describe('Organization name'),
 	})
 	.describe('Organization associated with the sandbox');
 
-const SandboxRuntimeInfoSchema = z
+export const SandboxRuntimeInfoSchema = z
 	.object({
 		id: z.string().describe('Runtime ID'),
 		name: z.string().describe('Runtime name (e.g., "bun:1")'),
@@ -26,7 +26,7 @@ const SandboxRuntimeInfoSchema = z
 	})
 	.describe('Runtime information');
 
-const SandboxSnapshotUserInfoSchema = z
+export const SandboxSnapshotUserInfoSchema = z
 	.object({
 		id: z.string().describe('User ID'),
 		firstName: z.string().optional().describe("User's first name"),
@@ -34,7 +34,7 @@ const SandboxSnapshotUserInfoSchema = z
 	})
 	.describe('Snapshot user information');
 
-const SandboxSnapshotOrgInfoSchema = z
+export const SandboxSnapshotOrgInfoSchema = z
 	.object({
 		id: z.string().describe('Organization ID'),
 		name: z.string().describe('Organization name'),
@@ -42,7 +42,7 @@ const SandboxSnapshotOrgInfoSchema = z
 	})
 	.describe('Snapshot organization information');
 
-const SandboxSnapshotInfoSchema = z
+export const SandboxSnapshotInfoSchema = z
 	.union([
 		z
 			.object({
@@ -69,7 +69,7 @@ const SandboxSnapshotInfoSchema = z
 	])
 	.describe('Snapshot information (discriminated union)');
 
-const SandboxInfoSchema = z
+export const SandboxInfoSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
 		identifier: z.string().optional().describe('Short identifier for DNS hostname'),
@@ -96,14 +96,14 @@ const SandboxInfoSchema = z
 	})
 	.describe('Summary information about a sandbox');
 
-const ListSandboxesDataSchema = z
+export const ListSandboxesDataSchema = z
 	.object({
 		sandboxes: z.array(SandboxInfoSchema).describe('List of sandbox entries'),
 		total: z.number().describe('Total number of sandboxes matching the query'),
 	})
 	.describe('Paginated list of sandboxes');
 
-const ListSandboxesResponseSchema = APIResponseSchema(ListSandboxesDataSchema);
+export const ListSandboxesResponseSchema = APIResponseSchema(ListSandboxesDataSchema);
 
 export interface SandboxListParams extends ListSandboxesParams {
 	orgId?: string;

package/src/api/sandbox/resolve.ts

@@ -0,0 +1,98 @@
+import { StructuredError } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchemaOptionalData } from '../api';
+
+/**
+ * Data schema for sandbox resolve endpoint
+ */
+export const SandboxResolveDataSchema = z.object({
+	id: z.string(),
+	name: z.string().nullable(),
+	region: z.string(),
+	status: z.string(),
+	orgId: z.string(),
+	projectId: z.string().nullable(),
+});
+
+/**
+ * Response schema for sandbox resolve endpoint using standardized discriminated union
+ */
+export const SandboxResolveResponseSchema = APIResponseSchemaOptionalData(SandboxResolveDataSchema);
+
+/**
+ * Resolved sandbox info returned from the CLI API
+ */
+export interface ResolvedSandboxInfo {
+	id: string;
+	name: string | null;
+	region: string;
+	status: string;
+	orgId: string;
+	projectId: string | null;
+}
+
+/**
+ * Error thrown when sandbox resolution fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxResolve(client, 'sbx_123');
+ * } catch (error) {
+ *   if (error._tag === 'SandboxResolveError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxResolveError = StructuredError('SandboxResolveError')<{
+	sandboxId?: string;
+	statusCode?: number;
+}>();
+
+/**
+ * Resolve a sandbox by ID across all organizations the user has access to.
+ * Uses the CLI API endpoint which searches across all user's orgs.
+ *
+ * @param client - API client configured for CLI endpoints
+ * @param sandboxId - The sandbox ID to resolve
+ * @returns Resolved sandbox info including region and orgId
+ * @throws {SandboxResolveError} If sandbox not found or request fails
+ */
+export async function sandboxResolve(
+	client: APIClient,
+	sandboxId: string
+): Promise<ResolvedSandboxInfo> {
+	const response = await client.get<z.infer<typeof SandboxResolveResponseSchema>>(
+		`/cli/sandbox/${sandboxId}`,
+		SandboxResolveResponseSchema
+	);
+
+	if (!response.success) {
+		// Extract status code from error code if present (e.g., "NOT_FOUND" -> 404)
+		// Fall back to 404 if no code is provided
+		const statusCode = response.code === 'NOT_FOUND' ? 404 : response.code ? 400 : 404;
+		throw new SandboxResolveError({
+			message: response.message || 'Sandbox not found',
+			sandboxId,
+			statusCode,
+		});
+	}
+
+	if (!response.data) {
+		throw new SandboxResolveError({
+			message: 'Sandbox not found',
+			sandboxId,
+			statusCode: 404,
+		});
+	}
+
+	return {
+		id: response.data.id,
+		name: response.data.name,
+		region: response.data.region,
+		status: response.data.status,
+		orgId: response.data.orgId,
+		projectId: response.data.projectId,
+	};
+}

package/src/api/sandbox/run.ts

@@ -1,7 +1,7 @@
 import type { Logger } from '@agentuity/core';
 import type { Readable, Writable } from 'node:stream';
 import { PassThrough } from 'node:stream';
-import { APIClient } from '../api';
+import { APIClient, PaymentRequiredError } from '../api';
 import { sandboxCreate } from './create';
 import { sandboxDestroy } from './destroy';
 import { sandboxGet } from './get';
@@ -286,6 +286,11 @@ async function createStdinStream(
 	});
 
 	if (!response.ok) {
+		if (response.status === 402) {
+			throw new PaymentRequiredError({
+				url: url,
+			});
+		}
 		throw new Error(`Failed to create stdin stream: ${response.status} ${response.statusText}`);
 	}
 

package/src/api/sandbox/runtime.ts

@@ -1,9 +1,9 @@
-import { z } from 'zod';
-import { APIClient, APIResponseSchema } from '../api';
-import { throwSandboxError, API_VERSION } from './util';
 import type { ListRuntimesParams, ListRuntimesResponse, SandboxRuntime } from '@agentuity/core';
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { API_VERSION, throwSandboxError } from './util';
 
-const RuntimeRequirementsSchema = z
+export const RuntimeRequirementsSchema = z
 	.object({
 		memory: z.string().optional().describe('Memory requirement (e.g., "1Gi")'),
 		cpu: z.string().optional().describe('CPU requirement (e.g., "1")'),
@@ -12,7 +12,7 @@ const RuntimeRequirementsSchema = z
 	})
 	.describe('Runtime resource requirements');
 
-const RuntimeInfoSchema = z
+export const RuntimeInfoSchema = z
 	.object({
 		id: z.string().describe('Unique runtime identifier'),
 		name: z.string().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
@@ -26,14 +26,14 @@ const RuntimeInfoSchema = z
 	})
 	.describe('Information about a sandbox runtime');
 
-const ListRuntimesDataSchema = z
+export const ListRuntimesDataSchema = z
 	.object({
 		runtimes: z.array(RuntimeInfoSchema).describe('List of runtime entries'),
 		total: z.number().describe('Total number of runtimes'),
 	})
 	.describe('List of sandbox runtimes');
 
-const ListRuntimesResponseSchema = APIResponseSchema(ListRuntimesDataSchema);
+export const ListRuntimesResponseSchema = APIResponseSchema(ListRuntimesDataSchema);
 
 export interface RuntimeListParams extends ListRuntimesParams {
 	orgId?: string;

package/src/api/sandbox/snapshot.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
-import { SandboxResponseError, throwSandboxError, API_VERSION } from './util';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api';
+import { API_VERSION, SandboxResponseError, throwSandboxError } from './util';
 
-const SnapshotFileInfoSchema = z
+export const SnapshotFileInfoSchema = z
 	.object({
 		path: z.string().describe('File path within the snapshot'),
 		size: z.number().describe('File size in bytes'),
@@ -12,7 +12,7 @@ const SnapshotFileInfoSchema = z
 	})
 	.describe('Information about a file in a snapshot');
 
-const SnapshotOrgInfoSchema = z
+export const SnapshotOrgInfoSchema = z
 	.object({
 		id: z.string().describe('Organization ID'),
 		name: z.string().describe('Organization name'),
@@ -20,7 +20,7 @@ const SnapshotOrgInfoSchema = z
 	})
 	.describe('Organization information for public snapshots');
 
-const SnapshotUserInfoSchema = z
+export const SnapshotUserInfoSchema = z
 	.object({
 		id: z.string().describe('User ID'),
 		firstName: z.string().nullable().optional().describe('User first name'),
@@ -28,7 +28,7 @@ const SnapshotUserInfoSchema = z
 	})
 	.describe('User information for private snapshots');
 
-const SnapshotInfoSchema = z
+export const SnapshotInfoSchema = z
 	.object({
 		snapshotId: z.string().describe('Unique identifier for the snapshot'),
 		runtimeId: z
@@ -79,18 +79,18 @@ const SnapshotInfoSchema = z
 	})
 	.describe('Detailed information about a snapshot');
 
-const SnapshotCreateResponseSchema = APIResponseSchema(SnapshotInfoSchema);
-const SnapshotGetResponseSchema = APIResponseSchema(SnapshotInfoSchema);
-const SnapshotListDataSchema = z
+export const SnapshotCreateResponseSchema = APIResponseSchema(SnapshotInfoSchema);
+export const SnapshotGetResponseSchema = APIResponseSchema(SnapshotInfoSchema);
+export const SnapshotListDataSchema = z
 	.object({
 		snapshots: z.array(SnapshotInfoSchema).describe('List of snapshot entries'),
 		total: z.number().describe('Total number of snapshots matching the query'),
 	})
 	.describe('Paginated list of snapshots');
-const SnapshotListResponseSchema = APIResponseSchema(SnapshotListDataSchema);
-const SnapshotDeleteResponseSchema = APIResponseSchemaNoData();
+export const SnapshotListResponseSchema = APIResponseSchema(SnapshotListDataSchema);
+export const SnapshotDeleteResponseSchema = APIResponseSchemaNoData();
 
-const SnapshotLineageEntrySchema = z
+export const SnapshotLineageEntrySchema = z
 	.object({
 		snapshotId: z.string().describe('Unique identifier for the snapshot'),
 		name: z
@@ -121,14 +121,14 @@ const SnapshotLineageEntrySchema = z
 	})
 	.describe('A single entry in the snapshot lineage chain');
 
-const SnapshotLineageDataSchema = z
+export const SnapshotLineageDataSchema = z
 	.object({
 		lineage: z.array(SnapshotLineageEntrySchema).describe('Ordered list of snapshots in lineage'),
 		total: z.number().describe('Total number of snapshots in the lineage'),
 	})
 	.describe('Snapshot lineage response');
 
-const SnapshotLineageResponseSchema = APIResponseSchema(SnapshotLineageDataSchema);
+export const SnapshotLineageResponseSchema = APIResponseSchema(SnapshotLineageDataSchema);
 
 export type SnapshotFileInfo = z.infer<typeof SnapshotFileInfoSchema>;
 export type SnapshotInfo = z.infer<typeof SnapshotInfoSchema>;
@@ -529,7 +529,7 @@ export async function snapshotPublicList(
 /**
  * Git information for snapshot builds
  */
-const SnapshotBuildGitInfoSchema = z
+export const SnapshotBuildGitInfoSchema = z
 	.object({
 		branch: z.string().optional().describe('Git branch name'),
 		commit: z.string().optional().describe('Git commit SHA'),
@@ -563,7 +563,7 @@ const _SnapshotBuildInitParamsSchema = z
 
 export type SnapshotBuildGitInfo = z.infer<typeof SnapshotBuildGitInfoSchema>;
 
-const SnapshotBuildInitResponseSchema = z
+export const SnapshotBuildInitResponseSchema = z
 	.object({
 		snapshotId: z.string().optional().describe('Unique identifier for the snapshot being built'),
 		uploadUrl: z
@@ -581,7 +581,9 @@ const SnapshotBuildInitResponseSchema = z
 	})
 	.describe('Response from snapshot build init API');
 
-const SnapshotBuildInitAPIResponseSchema = APIResponseSchema(SnapshotBuildInitResponseSchema);
+export const SnapshotBuildInitAPIResponseSchema = APIResponseSchema(
+	SnapshotBuildInitResponseSchema
+);
 
 const _SnapshotBuildFinalizeParamsSchema = z
 	.object({
@@ -695,7 +697,7 @@ export async function snapshotBuildFinalize(
 
 // ===== Snapshot Upload API (for public snapshots) =====
 
-const SnapshotUploadResponseSchema = z
+export const SnapshotUploadResponseSchema = z
 	.object({
 		success: z.boolean().describe('Whether the upload was successful'),
 		scanned: z.boolean().describe('Whether the upload was virus scanned'),