@agentuity/server 0.1.8 → 0.1.10

package/src/api/api.ts

@@ -208,7 +208,8 @@ export class APIClient {
 		responseSchema?: z.ZodType<TResponse>,
 		body?: TBody,
 		bodySchema?: z.ZodType<TBody>,
-		signal?: AbortSignal
+		signal?: AbortSignal,
+		extraHeaders?: Record<string, string>
 	): Promise<TResponse> {
 		// Validate request body if schema provided
 		if (body !== undefined && bodySchema) {
@@ -221,7 +222,14 @@ export class APIClient {
 			}
 		}
 
-		const response = await this.#makeRequest(method, endpoint, body, signal);
+		const response = await this.#makeRequest(
+			method,
+			endpoint,
+			body,
+			signal,
+			undefined,
+			extraHeaders
+		);
 
 		// Handle empty responses (204 or zero-length body)
 		let data: unknown;
@@ -263,7 +271,8 @@ export class APIClient {
 		endpoint: string,
 		body?: unknown,
 		signal?: AbortSignal,
-		contentType?: string
+		contentType?: string,
+		extraHeaders?: Record<string, string>
 	): Promise<Response> {
 		this.#logger.trace('sending %s to %s%s', method, this.#baseUrl, endpoint);
 
@@ -294,6 +303,11 @@ export class APIClient {
 			);
 		}
 
+		// Apply per-request extra headers (e.g., x-agentuity-orgid for CLI auth)
+		if (extraHeaders) {
+			Object.keys(extraHeaders).forEach((key) => (headers[key] = extraHeaders[key]));
+		}
+
 		const canRetry = !(body instanceof ReadableStream); // we cannot safely retry a ReadableStream as body
 
 		for (let attempt = 0; attempt <= maxRetries; attempt++) {

package/src/api/org/resources.ts

@@ -34,27 +34,32 @@ export type OrgDBResource = z.infer<typeof OrgDBResource>;
 export interface ListOrgResourcesOptions {
 	/** Filter by resource type (default: "all") */
 	type?: 'all' | 's3' | 'db';
+	/** Organization ID (required for CLI auth, extracted from context for SDK auth) */
+	orgId?: string;
 }
 
 /**
  * List all resources for the authenticated organization (across all regions)
- * Extracts orgId from authentication context (API key, SDK, or CLI token)
  *
  * @param client - Catalyst API client (must be authenticated)
- * @param options - Optional filters
+ * @param options - Optional filters including orgId for CLI auth
  * @returns List of S3 and DB resources with their cloud regions
  *
  * @example
- * // Get all resources
+ * // Get all resources (SDK auth - orgId from context)
  * const all = await listOrgResources(client);
  *
  * @example
+ * // Get all resources (CLI auth - orgId required)
+ * const all = await listOrgResources(client, { orgId: 'org_123' });
+ *
+ * @example
  * // Get only S3 buckets
- * const s3Only = await listOrgResources(client, { type: 's3' });
+ * const s3Only = await listOrgResources(client, { type: 's3', orgId: 'org_123' });
  *
  * @example
  * // Get only DBs
- * const dbsOnly = await listOrgResources(client, { type: 'db' });
+ * const dbsOnly = await listOrgResources(client, { type: 'db', orgId: 'org_123' });
  */
 export async function listOrgResources(
 	client: APIClient,
@@ -68,10 +73,20 @@ export async function listOrgResources(
 	const query = params.toString();
 	const url = `/resource/2025-11-16${query ? `?${query}` : ''}`;
 
+	// Build headers - include orgId for CLI auth
+	const headers: Record<string, string> = {};
+	if (options?.orgId) {
+		headers['x-agentuity-orgid'] = options.orgId;
+	}
+
 	const resp = await client.request<OrgResourceListResponse>(
 		'GET',
 		url,
-		OrgResourceListResponseSchema
+		OrgResourceListResponseSchema,
+		undefined,
+		undefined,
+		undefined,
+		headers
 	);
 	if (resp.success) {
 		return resp.data;

package/src/api/project/deployment.ts

@@ -90,6 +90,34 @@ export async function projectDeploymentGet(
 	throw new ProjectResponseError({ message: resp.message });
 }
 
+const DeploymentLookupSchema = z.object({
+	id: z.string(),
+	projectId: z.string(),
+	orgId: z.string(),
+	cloudRegion: z.string().nullable().optional(),
+	state: z.string().nullable().optional(),
+	active: z.boolean(),
+});
+
+const DeploymentLookupResponseSchema = APIResponseSchema(DeploymentLookupSchema);
+
+export type DeploymentLookup = z.infer<typeof DeploymentLookupSchema>;
+
+/**
+ * Get deployment info by ID only (without requiring project ID).
+ * Useful for looking up region/project info for a deployment.
+ */
+export async function deploymentGet(
+	client: APIClient,
+	deploymentId: string
+): Promise<DeploymentLookup> {
+	const resp = await client.get(`/cli/deployment/${deploymentId}`, DeploymentLookupResponseSchema);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new ProjectResponseError({ message: resp.message });
+}
+
 export async function projectDeploymentDelete(
 	client: APIClient,
 	projectId: string,

package/src/api/sandbox/create.ts

@@ -5,6 +5,10 @@ import type { SandboxCreateOptions, SandboxStatus } from '@agentuity/core';
 
 const SandboxCreateRequestSchema = z
 	.object({
+		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")'),
@@ -116,6 +120,18 @@ export async function sandboxCreate(
 	const { options = {}, orgId } = params;
 	const body: z.infer<typeof SandboxCreateRequestSchema> = {};
 
+	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;
 	}

package/src/api/sandbox/execution.ts

@@ -7,6 +7,10 @@ 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'),
@@ -34,6 +38,7 @@ const ExecutionListResponseSchema = APIResponseSchema(ExecutionListDataSchema);
 export interface ExecutionInfo {
 	executionId: string;
 	sandboxId: string;
+	type?: string;
 	status: ExecutionStatus;
 	command?: string[];
 	exitCode?: number;
@@ -79,6 +84,7 @@ export async function executionGet(
 		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,
@@ -137,6 +143,7 @@ export async function executionList(
 			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,

package/src/api/sandbox/get.ts

@@ -11,14 +11,49 @@ const SandboxResourcesSchema = z
 	})
 	.describe('Resource limits for the sandbox');
 
+const SandboxUserInfoSchema = z
+	.object({
+		id: z.string().describe('User ID'),
+		firstName: z.string().optional().describe("User's first name"),
+		lastName: z.string().optional().describe("User's last name"),
+	})
+	.describe('User who created the sandbox');
+
+const SandboxAgentInfoSchema = z
+	.object({
+		id: z.string().describe('Agent ID'),
+		name: z.string().describe('Agent name'),
+	})
+	.describe('Agent associated with the sandbox');
+
+const SandboxProjectInfoSchema = z
+	.object({
+		id: z.string().describe('Project ID'),
+		name: z.string().describe('Project name'),
+	})
+	.describe('Project associated with the sandbox');
+
+const SandboxOrgInfoSchema = z
+	.object({
+		id: z.string().describe('Organization ID'),
+		name: z.string().describe('Organization name'),
+	})
+	.describe('Organization associated with the sandbox');
+
 const SandboxInfoDataSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
+		name: z.string().optional().describe('Sandbox name'),
+		description: z.string().optional().describe('Sandbox description'),
 		status: z
-			.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+			.enum(['creating', 'idle', 'running', 'terminated', 'failed', 'deleted'])
 			.describe('Current status of the sandbox'),
+		mode: z.string().optional().describe('Sandbox mode (interactive or oneshot)'),
 		createdAt: z.string().describe('ISO timestamp when the sandbox was created'),
 		region: z.string().optional().describe('Region where the sandbox is running'),
+		runtimeId: z.string().optional().describe('Runtime ID'),
+		runtimeName: z.string().optional().describe('Runtime name (e.g., "bun:1")'),
+		runtimeIconUrl: z.string().optional().describe('URL for runtime icon'),
 		snapshotId: z.string().optional().describe('Snapshot ID this sandbox was created from'),
 		snapshotTag: z.string().optional().describe('Snapshot tag this sandbox was created from'),
 		executions: z.number().describe('Total number of executions in this sandbox'),
@@ -33,6 +68,14 @@ const SandboxInfoDataSchema = z
 			.optional()
 			.describe('User-defined metadata associated with the sandbox'),
 		resources: SandboxResourcesSchema.optional().describe('Resource limits for this sandbox'),
+		cpuTimeMs: z.number().optional().describe('Total CPU time consumed in milliseconds'),
+		memoryByteSec: z.number().optional().describe('Total memory usage in byte-seconds'),
+		networkEgressBytes: z.number().optional().describe('Total network egress in bytes'),
+		networkEnabled: z.boolean().optional().describe('Whether network access is enabled'),
+		user: SandboxUserInfoSchema.optional().describe('User who created the sandbox'),
+		agent: SandboxAgentInfoSchema.optional().describe('Agent associated with the sandbox'),
+		project: SandboxProjectInfoSchema.optional().describe('Project associated with the sandbox'),
+		org: SandboxOrgInfoSchema.describe('Organization associated with the sandbox'),
 	})
 	.describe('Detailed information about a sandbox');
 
@@ -41,6 +84,7 @@ const SandboxGetResponseSchema = APIResponseSchema(SandboxInfoDataSchema);
 export interface SandboxGetParams {
 	sandboxId: string;
 	orgId?: string;
+	includeDeleted?: boolean;
 }
 
 /**
@@ -55,11 +99,14 @@ export async function sandboxGet(
 	client: APIClient,
 	params: SandboxGetParams
 ): Promise<SandboxInfo> {
-	const { sandboxId, orgId } = params;
+	const { sandboxId, orgId, includeDeleted } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
 	}
+	if (includeDeleted) {
+		queryParams.set('includeDeleted', 'true');
+	}
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${API_VERSION}/${sandboxId}${queryString ? `?${queryString}` : ''}`;
 
@@ -71,9 +118,15 @@ export async function sandboxGet(
 	if (resp.success) {
 		return {
 			sandboxId: resp.data.sandboxId,
+			name: resp.data.name,
+			description: resp.data.description,
 			status: resp.data.status as SandboxStatus,
+			mode: resp.data.mode,
 			createdAt: resp.data.createdAt,
 			region: resp.data.region,
+			runtimeId: resp.data.runtimeId,
+			runtimeName: resp.data.runtimeName,
+			runtimeIconUrl: resp.data.runtimeIconUrl,
 			snapshotId: resp.data.snapshotId,
 			snapshotTag: resp.data.snapshotTag,
 			executions: resp.data.executions,
@@ -82,6 +135,14 @@ export async function sandboxGet(
 			dependencies: resp.data.dependencies,
 			metadata: resp.data.metadata as Record<string, unknown> | undefined,
 			resources: resp.data.resources,
+			cpuTimeMs: resp.data.cpuTimeMs,
+			memoryByteSec: resp.data.memoryByteSec,
+			networkEgressBytes: resp.data.networkEgressBytes,
+			networkEnabled: resp.data.networkEnabled,
+			user: resp.data.user,
+			agent: resp.data.agent,
+			project: resp.data.project,
+			org: resp.data.org,
 		};
 	}
 

package/src/api/sandbox/index.ts

@@ -6,6 +6,8 @@ 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 { SandboxDestroyParams } from './destroy';
 export { sandboxRun } from './run';

package/src/api/sandbox/list.ts

@@ -3,19 +3,34 @@ import { APIClient, APIResponseSchema } from '../api';
 import { SandboxResponseError, API_VERSION } from './util';
 import type { ListSandboxesParams, ListSandboxesResponse, SandboxStatus } from '@agentuity/core';
 
+const SandboxOrgInfoSchema = z
+	.object({
+		id: z.string().describe('Organization ID'),
+		name: z.string().describe('Organization name'),
+	})
+	.describe('Organization associated with the sandbox');
+
 const SandboxInfoSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the sandbox'),
+		name: z.string().optional().describe('Sandbox name'),
+		description: z.string().optional().describe('Sandbox description'),
 		status: z
-			.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+			.enum(['creating', 'idle', 'running', 'terminated', 'failed', 'deleted'])
 			.describe('Current status of the sandbox'),
+		mode: z.string().optional().describe('Sandbox mode (interactive or oneshot)'),
 		createdAt: z.string().describe('ISO timestamp when the sandbox was created'),
 		region: z.string().optional().describe('Region where the sandbox is running'),
+		runtimeId: z.string().optional().describe('Runtime ID'),
+		runtimeName: z.string().optional().describe('Runtime name (e.g., "bun:1")'),
+		runtimeIconUrl: z.string().optional().describe('URL for runtime icon'),
 		snapshotId: z.string().optional().describe('Snapshot ID this sandbox was created from'),
 		snapshotTag: z.string().optional().describe('Snapshot tag this sandbox was created from'),
 		executions: z.number().describe('Total number of executions in this sandbox'),
 		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
 		stderrStreamUrl: z.string().optional().describe('URL for streaming stderr output'),
+		networkEnabled: z.boolean().optional().describe('Whether network access is enabled'),
+		org: SandboxOrgInfoSchema.describe('Organization associated with the sandbox'),
 	})
 	.describe('Summary information about a sandbox');
 
@@ -30,6 +45,7 @@ const ListSandboxesResponseSchema = APIResponseSchema(ListSandboxesDataSchema);
 
 export interface SandboxListParams extends ListSandboxesParams {
 	orgId?: string;
+	deletedOnly?: boolean;
 }
 
 /**
@@ -64,6 +80,9 @@ export async function sandboxList(
 	if (params?.offset !== undefined) {
 		queryParams.set('offset', params.offset.toString());
 	}
+	if (params?.deletedOnly) {
+		queryParams.set('deletedOnly', 'true');
+	}
 
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${API_VERSION}${queryString ? `?${queryString}` : ''}`;
@@ -77,14 +96,22 @@ export async function sandboxList(
 		return {
 			sandboxes: resp.data.sandboxes.map((s) => ({
 				sandboxId: s.sandboxId,
+				name: s.name,
+				description: s.description,
 				status: s.status as SandboxStatus,
+				mode: s.mode,
 				createdAt: s.createdAt,
 				region: s.region,
+				runtimeId: s.runtimeId,
+				runtimeName: s.runtimeName,
+				runtimeIconUrl: s.runtimeIconUrl,
 				snapshotId: s.snapshotId,
 				snapshotTag: s.snapshotTag,
 				executions: s.executions,
 				stdoutStreamUrl: s.stdoutStreamUrl,
 				stderrStreamUrl: s.stderrStreamUrl,
+				networkEnabled: s.networkEnabled,
+				org: s.org,
 			})),
 			total: resp.data.total,
 		};

package/src/api/sandbox/runtime.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api';
+import { SandboxResponseError, API_VERSION } from './util';
+import type { ListRuntimesParams, ListRuntimesResponse, SandboxRuntime } from '@agentuity/core';
+
+const RuntimeInfoSchema = z
+	.object({
+		id: z.string().describe('Unique runtime identifier'),
+		name: z.string().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
+		description: z.string().optional().describe('Optional description'),
+		iconUrl: z.string().optional().describe('URL for runtime icon'),
+		url: z.string().optional().describe('URL for runtime documentation or homepage'),
+		tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
+	})
+	.describe('Information about a sandbox runtime');
+
+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 interface RuntimeListParams extends ListRuntimesParams {
+	orgId?: string;
+}
+
+/**
+ * Lists available sandbox runtimes with optional pagination.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Optional parameters for pagination
+ * @returns List of runtimes with total count
+ * @throws {SandboxResponseError} If the request fails
+ */
+export async function runtimeList(
+	client: APIClient,
+	params?: RuntimeListParams
+): Promise<ListRuntimesResponse> {
+	const queryParams = new URLSearchParams();
+
+	if (params?.orgId) {
+		queryParams.set('orgId', params.orgId);
+	}
+	if (params?.limit !== undefined) {
+		queryParams.set('limit', params.limit.toString());
+	}
+	if (params?.offset !== undefined) {
+		queryParams.set('offset', params.offset.toString());
+	}
+
+	const queryString = queryParams.toString();
+	const url = `/sandbox/${API_VERSION}/runtimes${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof ListRuntimesResponseSchema>>(
+		url,
+		ListRuntimesResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			runtimes: resp.data.runtimes.map(
+				(r): SandboxRuntime => ({
+					id: r.id,
+					name: r.name,
+					description: r.description,
+					iconUrl: r.iconUrl,
+					url: r.url,
+					tags: r.tags,
+				})
+			),
+			total: resp.data.total,
+		};
+	}
+
+	throw new SandboxResponseError({ message: resp.message });
+}

package/src/api/sandbox/snapshot.ts

@@ -12,7 +12,18 @@ const SnapshotFileInfoSchema = z
 const SnapshotInfoSchema = z
 	.object({
 		snapshotId: z.string().describe('Unique identifier for the snapshot'),
-		tag: z.string().nullable().optional().describe('User-defined tag for the snapshot'),
+		runtimeId: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Runtime ID associated with this snapshot'),
+		name: z
+			.string()
+			.describe(
+				'Display name for the snapshot (URL-safe: letters, numbers, underscores, dashes)'
+			),
+		description: z.string().nullable().optional().describe('Description of the snapshot'),
+		tag: z.string().nullable().optional().describe('Tag for the snapshot (defaults to "latest")'),
 		sizeBytes: z.number().describe('Total size of the snapshot in bytes'),
 		fileCount: z.number().describe('Number of files in the snapshot'),
 		parentSnapshotId: z
@@ -22,7 +33,11 @@ const SnapshotInfoSchema = z
 			.describe('ID of the parent snapshot (for incremental snapshots)'),
 		createdAt: z.string().describe('ISO timestamp when the snapshot was created'),
 		downloadUrl: z.string().optional().describe('URL to download the snapshot archive'),
-		files: z.array(SnapshotFileInfoSchema).optional().describe('List of files in the snapshot'),
+		files: z
+			.array(SnapshotFileInfoSchema)
+			.nullable()
+			.optional()
+			.describe('List of files in the snapshot'),
 	})
 	.describe('Detailed information about a snapshot');
 
@@ -44,17 +59,22 @@ export interface SnapshotFileInfo {
 
 export interface SnapshotInfo {
 	snapshotId: string;
+	runtimeId?: string | null;
+	name: string;
+	description?: string | null;
 	tag?: string | null;
 	sizeBytes: number;
 	fileCount: number;
 	parentSnapshotId?: string | null;
 	createdAt: string;
 	downloadUrl?: string;
-	files?: SnapshotFileInfo[];
+	files?: SnapshotFileInfo[] | null;
 }
 
 export interface SnapshotCreateParams {
 	sandboxId: string;
+	name?: string;
+	description?: string;
 	tag?: string;
 	orgId?: string;
 }
@@ -110,11 +130,17 @@ export async function snapshotCreate(
 	client: APIClient,
 	params: SnapshotCreateParams
 ): Promise<SnapshotInfo> {
-	const { sandboxId, tag, orgId } = params;
+	const { sandboxId, name, description, tag, orgId } = params;
 	const queryString = buildQueryString({ orgId });
 	const url = `/sandbox/${API_VERSION}/${sandboxId}/snapshot${queryString}`;
 
 	const body: Record<string, string> = {};
+	if (name) {
+		body.name = name;
+	}
+	if (description) {
+		body.description = description;
+	}
 	if (tag) {
 		body.tag = tag;
 	}

package/src/index.ts

@@ -13,6 +13,16 @@ export { createServerFetchAdapter } from './server';
 // schema.ts exports
 export { toJSONSchema } from './schema';
 
+// util/resources.ts exports
+export {
+	validateCPUSpec,
+	validateMemorySpec,
+	validateResources,
+	type ResourceValidationResult,
+	type ResourcesConfig,
+	type ValidatedResources,
+} from './util/resources';
+
 // runtime-bootstrap.ts exports
 export { bootstrapRuntimeEnv, type RuntimeBootstrapOptions } from './runtime-bootstrap';