@agentuity/core 2.0.11 → 2.0.13

package/src/services/coder/websocket.ts

@@ -70,7 +70,7 @@ import type {
 	ConnectionParams,
 	ServerMessage,
 } from './protocol.ts';
-import { CoderHubInitMessageSchema } from './protocol.ts';
+import { CoderHubInitMessageSchema, parseServerMessage } from './protocol.ts';
 import { normalizeCoderUrl } from './util.ts';
 
 /**
@@ -118,6 +118,11 @@ export const CoderHubWebSocketOptionsSchema = z.object({
 	task: z.string().optional().describe('Initial task for driver mode'),
 	/** Human-readable session label */
 	label: z.string().optional().describe('Session label'),
+	/** Observer event filters to request during the initial connection. */
+	subscribe: z
+		.array(z.string())
+		.optional()
+		.describe('Observer event filters to request during connection setup'),
 	/** Client origin (web, desktop, tui, sdk) */
 	origin: z.enum(['web', 'desktop', 'tui', 'sdk']).optional().describe('Client origin'),
 	/** Driver mode: 'rpc' for RPC bridge driver */
@@ -198,7 +203,13 @@ export const CoderHubWebSocketError = StructuredError('CoderHubWebSocketError')<
 		| 'response_timeout'
 		| 'invalid_response';
 	sessionId?: string;
+	serverCode?: string;
+	serverMessage?: string;
+	serverMessageType?: 'connection_rejected' | 'protocol_error';
+	closeCode?: number;
+	closeReason?: string;
 }>();
+export type CoderHubWebSocketErrorInstance = InstanceType<typeof CoderHubWebSocketError>;
 
 interface PendingRequest {
 	resolve: (response: CoderHubResponse) => void;
@@ -270,6 +281,7 @@ export class CoderHubWebSocketClient {
 		parentSessionId: string;
 		task: string;
 		label: string;
+		subscribe: string[];
 		origin: 'web' | 'desktop' | 'tui' | 'sdk';
 		driverMode: 'rpc' | undefined;
 		driverInstanceId: string;
@@ -317,6 +329,7 @@ export class CoderHubWebSocketClient {
 			parentSessionId: options.parentSessionId ?? '',
 			task: options.task ?? '',
 			label: options.label ?? '',
+			subscribe: options.subscribe ?? [],
 			origin: options.origin ?? 'sdk',
 			driverMode: options.driverMode,
 			driverInstanceId: options.driverInstanceId ?? '',
@@ -522,6 +535,57 @@ export class CoderHubWebSocketClient {
 		return `${Date.now()}-${++this.#messageId}`;
 	}
 
+	#buildHandshakeError(input: {
+		code: 'auth_failed' | 'connection_error';
+		message: string;
+		serverCode?: string;
+		serverMessage?: string;
+		serverMessageType?: 'connection_rejected' | 'protocol_error';
+		closeCode?: number;
+		closeReason?: string;
+	}): CoderHubWebSocketErrorInstance {
+		return new CoderHubWebSocketError({
+			code: input.code,
+			message: input.message,
+			sessionId: this.sessionId,
+			serverCode: input.serverCode,
+			serverMessage: input.serverMessage,
+			serverMessageType: input.serverMessageType,
+			closeCode: input.closeCode,
+			closeReason: input.closeReason,
+		});
+	}
+
+	#markReady(input?: {
+		initMessage?: CoderHubInitMessage;
+		firstMessage?: ServerMessage;
+		sendBootstrapReady?: boolean;
+	}): void {
+		this.#authenticated = true;
+		this.#initMessage = input?.initMessage ?? null;
+		this.#sessionId =
+			input?.initMessage?.sessionId ??
+			(input?.firstMessage && 'sessionId' in input.firstMessage
+				? input.firstMessage.sessionId
+				: undefined) ??
+			this.#options.sessionId ??
+			null;
+		this.#reconnectAttempts = 0;
+		this.#setState('connected');
+		this.#startHeartbeat();
+		if (input?.initMessage) {
+			this.#options.onInit(input.initMessage);
+		}
+		if (input?.sendBootstrapReady && this.#ws?.readyState === WebSocket.OPEN) {
+			this.#ws.send(JSON.stringify({ type: 'bootstrap_ready' }));
+		}
+		this.#flushMessageQueue();
+		this.#options.onOpen();
+		if (input?.firstMessage) {
+			this.#options.onMessage(input.firstMessage);
+		}
+	}
+
 	#setState(state: CoderHubWebSocketState): void {
 		if (this.#state !== state) {
 			this.#state = state;
@@ -589,6 +653,8 @@ export class CoderHubWebSocketClient {
 			parent: this.#options.parentSessionId || undefined,
 			task: this.#options.task || undefined,
 			label: this.#options.label || undefined,
+			subscribe:
+				this.#options.subscribe.length > 0 ? this.#options.subscribe.join(',') : undefined,
 			orgId: this.#options.orgId || undefined,
 			origin: this.#options.origin || undefined,
 			driverMode: this.#options.driverMode || undefined,
@@ -601,6 +667,9 @@ export class CoderHubWebSocketClient {
 				params.set(key, String(value));
 			}
 		}
+		if (this.#options.apiKey) {
+			params.set('api_key', this.#options.apiKey);
+		}
 
 		const queryString = params.toString();
 		return queryString ? `${wsUrl}?${queryString}` : wsUrl;
@@ -642,12 +711,16 @@ export class CoderHubWebSocketClient {
 		ws.onopen = () => {
 			if (ws !== this.#ws) return;
 			this.#setState('authenticating');
-			ws.send(
-				JSON.stringify({
-					authorization: this.#options.apiKey,
-					org_id: this.#options.orgId,
-				})
-			);
+			if (this.#options.apiKey || this.#options.orgId) {
+				const bootstrapPayload: { authorization?: string; org_id?: string } = {};
+				if (this.#options.apiKey) {
+					bootstrapPayload.authorization = this.#options.apiKey;
+				}
+				if (this.#options.orgId) {
+					bootstrapPayload.org_id = this.#options.orgId;
+				}
+				ws.send(JSON.stringify(bootstrapPayload));
+			}
 		};
 
 		ws.onmessage = (event: MessageEvent) => {
@@ -685,10 +758,12 @@ export class CoderHubWebSocketClient {
 					if (msg.type === 'connection_rejected' || msg.type === 'protocol_error') {
 						this.#setState('closed');
 						this.#options.onError(
-							new CoderHubWebSocketError({
-								message: `Connection rejected: ${msg.message ?? msg.code ?? 'Unknown error'}`,
+							this.#buildHandshakeError({
 								code: 'auth_failed',
-								sessionId: this.sessionId,
+								message: `Connection rejected: ${msg.message ?? msg.code ?? 'Unknown error'}`,
+								serverCode: msg.code,
+								serverMessage: msg.message,
+								serverMessageType: msg.type,
 							})
 						);
 						this.#intentionallyClosed = true;
@@ -700,15 +775,18 @@ export class CoderHubWebSocketClient {
 				const initResult = CoderHubInitMessageSchema.safeParse(parsed);
 				if (initResult.success) {
 					const initMsg = initResult.data;
-					this.#authenticated = true;
-					this.#initMessage = initMsg;
-					this.#sessionId = initMsg.sessionId ?? this.#options.sessionId ?? null;
-					this.#reconnectAttempts = 0;
-					this.#setState('connected');
-					this.#startHeartbeat();
-					this.#flushMessageQueue();
-					this.#options.onInit(initMsg);
-					this.#options.onOpen();
+					this.#markReady({
+						initMessage: initMsg,
+						sendBootstrapReady: this.#options.role === 'controller',
+					});
+					return;
+				}
+
+				if (this.#options.role === 'observer') {
+					const firstObserverMessage = parseServerMessage(parsed);
+					if (firstObserverMessage) {
+						this.#markReady({ firstMessage: firstObserverMessage });
+					}
 				}
 				return;
 			}
@@ -759,14 +837,31 @@ export class CoderHubWebSocketClient {
 			this.#clearTimers();
 			this.#setState('closed');
 
+			const wasAuthenticated = this.#authenticated;
+			const hadTerminalError = this.#intentionallyClosed;
+			const terminalClose = isTerminalCloseCode(event.code);
+
 			// Clear auth state for clean reconnect
 			this.#authenticated = false;
 			this.#initMessage = null;
 
-			if (isTerminalCloseCode(event.code)) {
+			if (terminalClose) {
 				this.#intentionallyClosed = true;
 			}
 
+			if (!wasAuthenticated && terminalClose && !hadTerminalError) {
+				this.#options.onError(
+					this.#buildHandshakeError({
+						code: 'connection_error',
+						message: `WebSocket closed before connection was ready (code ${event.code})${
+							event.reason ? `: ${event.reason}` : ''
+						}`,
+						closeCode: event.code,
+						closeReason: event.reason || undefined,
+					})
+				);
+			}
+
 			this.#options.onClose(event.code, event.reason);
 
 			if (!this.#intentionallyClosed) {
@@ -896,7 +991,11 @@ export async function* subscribeToCoderHub(
 		onError: (error) => {
 			if (
 				error instanceof CoderHubWebSocketError &&
-				(error.code === 'max_reconnects_exceeded' || error.code === 'auth_failed')
+				(error.code === 'max_reconnects_exceeded' ||
+					error.code === 'auth_failed' ||
+					(error.code === 'connection_error' &&
+						typeof error.closeCode === 'number' &&
+						isTerminalCloseCode(error.closeCode)))
 			) {
 				terminalError = error;
 				done = true;

package/src/services/coder/workspaces.ts

@@ -2,9 +2,13 @@ import { z } from 'zod/v4';
 import { type APIClient } from '../api.ts';
 import {
 	CoderCreateWorkspaceRequestSchema,
+	CoderUpdateWorkspaceRequestSchema,
+	CoderWorkspaceDependencyValidationResponseSchema,
 	CoderWorkspaceDetailSchema,
 	CoderWorkspaceListResponseSchema,
 	type CoderCreateWorkspaceRequest,
+	type CoderUpdateWorkspaceRequest,
+	type CoderWorkspaceDependencyValidationResponse,
 	type CoderWorkspaceDetail,
 	type CoderWorkspaceListResponse,
 } from './types.ts';
@@ -25,6 +29,34 @@ const WorkspaceCreateResponseSchema = z
 	.passthrough()
 	.describe('Wrapped workspace create response from coder hub');
 
+const WorkspaceUpdateResponseSchema = z
+	.object({
+		workspace: CoderWorkspaceDetailSchema.describe(
+			'Updated workspace payload returned by coder hub'
+		),
+	})
+	.passthrough()
+	.describe('Wrapped workspace update response from coder hub');
+
+const WorkspaceSnapshotRefreshResponseSchema = z
+	.object({
+		workspace: CoderWorkspaceDetailSchema.describe(
+			'Workspace payload returned after refreshing its snapshot'
+		),
+	})
+	.passthrough()
+	.describe('Wrapped workspace snapshot refresh response from coder hub');
+
+const WorkspaceDependencyValidationWrappedResponseSchema = z
+	.object({
+		success: z.boolean().describe('Validation request success indicator'),
+		data: CoderWorkspaceDependencyValidationResponseSchema.describe(
+			'Dependency validation result'
+		),
+	})
+	.passthrough()
+	.describe('Wrapped workspace dependency validation response from coder hub');
+
 const OkResponseSchema = z
 	.object({
 		ok: z.boolean().describe('Operation success indicator'),
@@ -68,6 +100,48 @@ export async function coderCreateWorkspace(
 	return resp.workspace;
 }
 
+export async function coderUpdateWorkspace(
+	client: APIClient,
+	params: { workspaceId: string; body: CoderUpdateWorkspaceRequest }
+): Promise<CoderWorkspaceDetail> {
+	const path = `/hub/workspaces/${encodeURIComponent(params.workspaceId)}`;
+	const resp = await client.patch<
+		z.infer<typeof WorkspaceUpdateResponseSchema>,
+		CoderUpdateWorkspaceRequest
+	>(path, params.body, WorkspaceUpdateResponseSchema, CoderUpdateWorkspaceRequestSchema);
+
+	return resp.workspace;
+}
+
+export async function coderRefreshWorkspaceSnapshot(
+	client: APIClient,
+	params: { workspaceId: string }
+): Promise<CoderWorkspaceDetail> {
+	const path = `/hub/workspaces/${encodeURIComponent(params.workspaceId)}/snapshot/refresh`;
+	const resp = await client.post<z.infer<typeof WorkspaceSnapshotRefreshResponseSchema>>(
+		path,
+		undefined,
+		WorkspaceSnapshotRefreshResponseSchema
+	);
+
+	return resp.workspace;
+}
+
+export async function coderValidateWorkspaceDependencies(
+	client: APIClient,
+	params: { dependencies: string[] }
+): Promise<CoderWorkspaceDependencyValidationResponse> {
+	const resp = await client.post<
+		z.infer<typeof WorkspaceDependencyValidationWrappedResponseSchema>
+	>(
+		'/hub/workspaces/dependencies/validate',
+		{ dependencies: params.dependencies },
+		WorkspaceDependencyValidationWrappedResponseSchema
+	);
+
+	return resp.data;
+}
+
 export async function coderDeleteWorkspace(
 	client: APIClient,
 	params: { workspaceId: string }

package/src/services/sandbox/api-reference.ts

@@ -613,7 +613,7 @@ const service: Service = {
 			],
 			requestBody: {
 				description: 'Snapshot creation payload.',
-				fields: { schema: SnapshotCreateOptionsSchema },
+				fields: { schema: SnapshotCreateOptionsSchema.omit({ orgId: true }) },
 			},
 			responseDescription: 'Returns the created snapshot.',
 			statuses: [
@@ -887,15 +887,15 @@ const service: Service = {
 			exampleHeaders: { 'Content-Type': 'application/gzip' },
 			exampleBody: '<binary gzip data>',
 		},
-		// ── Disk Checkpoints ──────────────────────────────────────────────
+		// ── Sandbox Checkpoints ───────────────────────────────────────────
 		{
 			id: 'create-checkpoint',
 			title: 'Create Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'POST',
 			path: '/sandbox/{sandboxId}/checkpoint',
 			description:
-				'Create a named checkpoint of the sandbox filesystem. Checkpoint names must be unique — creating a checkpoint with a name that already exists returns 409 Conflict. Disk checkpoints are persisted across pause/resume cycles.',
+				'Create a named checkpoint of the sandbox filesystem. Checkpoint names must be unique — creating a checkpoint with a name that already exists returns 409 Conflict. Checkpoints are persisted across pause/resume cycles.',
 			pathParams: [
 				{ name: 'sandboxId', type: 'string', description: 'Sandbox ID', required: true },
 			],
@@ -923,11 +923,11 @@ const service: Service = {
 		{
 			id: 'list-checkpoints',
 			title: 'List Checkpoints',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'GET',
 			path: '/sandbox/checkpoints/{sandboxId}',
 			description:
-				'List checkpoints for a specific sandbox. Disk checkpoints are persisted across pause/resume cycles.',
+				'List checkpoints for a specific sandbox. Checkpoints are persisted across pause/resume cycles.',
 			pathParams: [
 				{ name: 'sandboxId', type: 'string', description: 'Sandbox ID', required: true },
 			],
@@ -947,7 +947,7 @@ const service: Service = {
 		{
 			id: 'restore-checkpoint',
 			title: 'Restore Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'POST',
 			path: '/sandbox/{sandboxId}/checkpoint/{checkpointId}/restore',
 			description: 'Restore the sandbox filesystem to a checkpoint state.',
@@ -971,7 +971,7 @@ const service: Service = {
 		{
 			id: 'delete-checkpoint',
 			title: 'Delete Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'DELETE',
 			path: '/sandbox/{sandboxId}/checkpoint/{checkpointId}',
 			description: 'Delete a checkpoint.',

package/src/services/sandbox/client.ts

@@ -34,7 +34,7 @@ import {
 	sandboxRmDir,
 	sandboxSetEnv,
 } from './files.ts';
-import { sandboxPause } from './pause.ts';
+import { sandboxPause, type SandboxPauseResult } from './pause.ts';
 import { sandboxResume } from './resume.ts';
 import { sandboxRun } from './run.ts';
 import {
@@ -281,7 +281,7 @@ export interface SandboxInstance {
 	/**
 	 * Pause the sandbox, creating a checkpoint of its current state
 	 */
-	pause(): Promise<void>;
+	pause(): Promise<SandboxPauseResult>;
 
 	/**
 	 * Resume the sandbox from a paused or evacuated state
@@ -399,7 +399,7 @@ function createSandboxInstanceMethods(
 			return sandboxGet(client, { sandboxId, orgId });
 		},
 
-		async pause(): Promise<void> {
+		async pause(): Promise<SandboxPauseResult> {
 			return sandboxPause(client, { sandboxId, orgId });
 		},
 
@@ -725,7 +725,7 @@ export class SandboxClient {
 	 *
 	 * @param sandboxId - The sandbox ID to pause
 	 */
-	async pause(sandboxId: string): Promise<void> {
+	async pause(sandboxId: string): Promise<SandboxPauseResult> {
 		return sandboxPause(this.#client, { sandboxId, orgId: this.#orgId });
 	}
 

package/src/services/sandbox/create.ts

@@ -49,6 +49,12 @@ export const SandboxCreateRequestSchema = z
 			.object({
 				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h")'),
 				execution: z.string().optional().describe('Maximum execution time (e.g., "30m", "2h")'),
+				paused: z
+					.string()
+					.optional()
+					.describe(
+						'Maximum time sandbox can remain paused before termination (e.g., "24h", "0s" for infinite)'
+					),
 			})
 			.optional()
 			.describe('Timeout settings for the sandbox'),
@@ -139,6 +145,10 @@ export const SandboxCreateDataSchema = z
 				'failed',
 			])
 			.describe('Current status of the sandbox'),
+		executionId: z
+			.string()
+			.optional()
+			.describe('Initial execution identifier for oneshot sandbox creation'),
 		url: z
 			.string()
 			.optional()

package/src/services/sandbox/get.ts

@@ -156,7 +156,7 @@ export const SandboxInfoDataSchema = z
 		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'),
+		org: SandboxOrgInfoSchema.nullish().describe('Organization associated with the sandbox'),
 		timeout: z
 			.object({
 				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h").'),
@@ -164,6 +164,10 @@ export const SandboxInfoDataSchema = z
 					.string()
 					.optional()
 					.describe('Execution timeout duration (e.g., "30m", "2h").'),
+				paused: z
+					.string()
+					.optional()
+					.describe('Paused timeout duration (e.g., "24h", "0s" for infinite).'),
 			})
 			.optional()
 			.describe('Timeout configuration for the sandbox.'),
@@ -189,6 +193,16 @@ export const SandboxGetParamsSchema = z.object({
 		.boolean()
 		.optional()
 		.describe('Whether deleted sandboxes should be included in lookup'),
+	waitForStatus: z
+		.union([z.string(), z.array(z.string())])
+		.optional()
+		.describe('Optional desired status or statuses to wait for before responding'),
+	waitMs: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Maximum time in milliseconds to wait for the desired status'),
 });
 
 export type SandboxGetParams = z.infer<typeof SandboxGetParamsSchema>;
@@ -205,7 +219,7 @@ export async function sandboxGet(
 	client: APIClient,
 	params: SandboxGetParams
 ): Promise<SandboxInfo> {
-	const { sandboxId, orgId, includeDeleted } = params;
+	const { sandboxId, orgId, includeDeleted, waitForStatus, waitMs } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
@@ -213,6 +227,15 @@ export async function sandboxGet(
 	if (includeDeleted) {
 		queryParams.set('includeDeleted', 'true');
 	}
+	if (waitForStatus) {
+		queryParams.set(
+			'waitForStatus',
+			Array.isArray(waitForStatus) ? waitForStatus.join(',') : waitForStatus
+		);
+	}
+	if (waitMs != null) {
+		queryParams.set('waitMs', String(waitMs));
+	}
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${encodeURIComponent(sandboxId)}${queryString ? `?${queryString}` : ''}`;
 
@@ -222,6 +245,12 @@ export async function sandboxGet(
 	);
 
 	if (resp.success) {
+		// Newly created sandboxes can be served from the server's pending cache before
+		// the backing row and related org hydration are fully available. That response
+		// serializes `org: null`, so normalize it to a placeholder object instead of
+		// failing response validation for an otherwise valid sandbox status poll.
+		const org = resp.data.org ?? { id: orgId ?? '', name: '' };
+
 		return {
 			sandboxId: resp.data.sandboxId,
 			identifier: resp.data.identifier,
@@ -252,7 +281,7 @@ export async function sandboxGet(
 			user: resp.data.user,
 			agent: resp.data.agent,
 			project: resp.data.project,
-			org: resp.data.org,
+			org,
 			timeout: resp.data.timeout,
 			command: resp.data.command,
 		};

package/src/services/sandbox/getStatus.ts

@@ -13,6 +13,16 @@ const SandboxStatusResponseSchema = APIResponseSchema(SandboxStatusDataSchema);
 export const SandboxGetStatusParamsSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID to retrieve status for'),
 	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	waitForStatus: z
+		.union([z.string(), z.array(z.string())])
+		.optional()
+		.describe('Optional desired status or statuses to wait for before responding'),
+	waitMs: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Maximum time in milliseconds to wait for the desired status'),
 });
 
 export type SandboxGetStatusParams = z.infer<typeof SandboxGetStatusParamsSchema>;
@@ -26,11 +36,20 @@ export async function sandboxGetStatus(
 	client: APIClient,
 	params: SandboxGetStatusParams
 ): Promise<SandboxStatusResult> {
-	const { sandboxId, orgId } = params;
+	const { sandboxId, orgId, waitForStatus, waitMs } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
 	}
+	if (waitForStatus) {
+		queryParams.set(
+			'waitForStatus',
+			Array.isArray(waitForStatus) ? waitForStatus.join(',') : waitForStatus
+		);
+	}
+	if (waitMs != null) {
+		queryParams.set('waitMs', String(waitMs));
+	}
 	const queryString = queryParams.toString();
 	const url = `/sandbox/status/${sandboxId}${queryString ? `?${queryString}` : ''}`;
 

package/src/services/sandbox/index.ts

@@ -52,7 +52,7 @@ export {
 	diskCheckpointRestore,
 	diskCheckpointDelete,
 } from './disk-checkpoint.ts';
-export type { SandboxPauseParams } from './pause.ts';
+export type { SandboxPauseParams, SandboxPauseResult } from './pause.ts';
 export { PauseResponseSchema, SandboxPauseParamsSchema, sandboxPause } from './pause.ts';
 export type { SandboxResumeParams } from './resume.ts';
 export { ResumeResponseSchema, SandboxResumeParamsSchema, sandboxResume } from './resume.ts';

package/src/services/sandbox/list.ts

@@ -112,6 +112,10 @@ export const SandboxInfoSchema = z
 					.string()
 					.optional()
 					.describe('Execution timeout duration (e.g., "30m", "2h").'),
+				paused: z
+					.string()
+					.optional()
+					.describe('Paused timeout duration (e.g., "24h", "0s" for infinite).'),
 			})
 			.optional()
 			.describe('Timeout configuration for the sandbox.'),
@@ -225,6 +229,7 @@ export async function sandboxList(
 				networkPort: s.networkPort,
 				url: s.url,
 				org: s.org,
+				timeout: s.timeout,
 			})),
 			total: resp.data.total,
 		};

package/src/services/sandbox/pause.ts

@@ -1,8 +1,21 @@
 import { z } from 'zod';
-import { type APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { type APIClient } from '../api.ts';
 import { throwSandboxError } from './util.ts';
 
-export const PauseResponseSchema = APIResponseSchemaNoData();
+export const PauseResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string(),
+		code: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		sandboxId: z.string(),
+		status: z.string(),
+		checkpointId: z.string().optional(),
+		terminatesAt: z.string().optional(),
+	}),
+]);
 
 export const SandboxPauseParamsSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID to pause'),
@@ -11,14 +24,30 @@ export const SandboxPauseParamsSchema = z.object({
 
 export type SandboxPauseParams = z.infer<typeof SandboxPauseParamsSchema>;
 
+/** Result returned from pausing a sandbox */
+export interface SandboxPauseResult {
+	/** The sandbox ID that was paused */
+	sandboxId: string;
+	/** New status (typically "suspended") */
+	status: string;
+	/** Checkpoint ID created during pause */
+	checkpointId?: string;
+	/** ISO 8601 timestamp when sandbox will auto-terminate if not resumed (omitted if no paused timeout) */
+	terminatesAt?: string;
+}
+
 /**
  * Pauses a running sandbox, creating a checkpoint of its current state.
  *
  * @param client - The API client to use for the request
  * @param params - Parameters including the sandbox ID to pause
+ * @returns Pause result including terminatesAt if a paused timeout is configured
  * @throws {SandboxResponseError} If the sandbox is not found or pause fails
  */
-export async function sandboxPause(client: APIClient, params: SandboxPauseParams): Promise<void> {
+export async function sandboxPause(
+	client: APIClient,
+	params: SandboxPauseParams
+): Promise<SandboxPauseResult> {
 	const { sandboxId, orgId } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
@@ -34,7 +63,12 @@ export async function sandboxPause(client: APIClient, params: SandboxPauseParams
 	);
 
 	if (resp.success) {
-		return;
+		return {
+			sandboxId: resp.sandboxId,
+			status: resp.status,
+			checkpointId: resp.checkpointId,
+			terminatesAt: resp.terminatesAt,
+		};
 	}
 
 	throwSandboxError(resp, { sandboxId });