@agentuity/core 3.0.0-alpha.6 → 3.0.0-beta.0

package/src/services/sandbox/run.ts

@@ -1,16 +1,21 @@
 import type { Logger } from '../../logger.ts';
 import type { Readable, Writable } from 'node:stream';
 import { PassThrough } from 'node:stream';
+import { finished } from 'node:stream/promises';
 import { z } from 'zod';
 import { APIClient, PaymentRequiredError } from '../api.ts';
 import { sandboxCreate } from './create.ts';
 import { sandboxDestroy } from './destroy.ts';
+import { executionGet } from './execution.ts';
 import { sandboxGetStatus } from './getStatus.ts';
 import { ExecutionCancelledError, writeAndDrain } from './util.ts';
 import { SandboxRunOptionsSchema, type SandboxRunResult } from './types.ts';
 import { getServiceUrls } from '../config.ts';
 
 const timingLogsEnabled = false;
+const EXECUTION_WAIT_DURATION = '5m';
+const EXIT_CODE_FAST_WAIT_DURATION = '250ms';
+const TERMINAL_EXECUTION_STATUSES = new Set(['completed', 'failed', 'timeout', 'cancelled']);
 
 /**
  * Creates a Writable stream that captures all chunks to a buffer array
@@ -73,8 +78,19 @@ export async function sandboxRun(
 	let stdinStreamId: string | undefined;
 	let stdinStreamUrl: string | undefined;
 
-	// If stdin is provided and has data, create a stream for it
-	if (stdin && region && apiKey) {
+	// Handle stdin stream configuration:
+	// - If stdin is "ignore", pass it through to skip stdin handling on server
+	// - If stdin is an explicit stream ID, use it directly
+	// - If stdin readable is provided, create a stream for it
+	const stdinConfig = options.stream?.stdin;
+	if (stdinConfig === 'ignore') {
+		stdinStreamId = 'ignore';
+		logger?.debug('stdin explicitly ignored');
+	} else if (stdinConfig && stdinConfig !== 'ignore') {
+		// User provided an explicit stream ID
+		stdinStreamId = stdinConfig;
+		logger?.debug('using provided stdin stream ID: %s', stdinStreamId);
+	} else if (stdin && region && apiKey) {
 		const streamResult = await createStdinStream(region, apiKey, orgId, logger);
 		stdinStreamId = streamResult.id;
 		stdinStreamUrl = streamResult.url;
@@ -176,52 +192,46 @@ export async function sandboxRun(
 			}
 		}
 
-		// Wait for streams to complete — Pulse closes streams on sandbox termination (EOF).
-		// This is our primary completion signal; no polling needed.
-		logger?.debug('waiting for streams to complete...');
+		// Wait for execution completion in parallel with stream consumption. The old
+		// flow waited for stream EOF first and only then started polling for the
+		// final exit code, which adds avoidable tail latency now that create returns
+		// an execution ID immediately for oneshot sandboxes.
+		let finalExecution:
+			| {
+					exitCode?: number;
+					status: string;
+			  }
+			| undefined;
+		if (createResponse.executionId) {
+			logger?.debug(
+				'waiting for execution %s and %d stream(s) in parallel',
+				createResponse.executionId,
+				streamPromises.length
+			);
+			const completionPromise = waitForRunCompletion(
+				client,
+				sandboxId,
+				createResponse.executionId,
+				orgId,
+				signal,
+				logger,
+				started
+			);
 
-		if (streamPromises.length > 0) {
-			if (signal) {
-				// Race streams against abort signal, cleaning up the listener
-				// in all cases so an orphaned reject cannot fire after settlement.
-				let onAbort: (() => void) | undefined;
-				try {
-					await Promise.race([
-						Promise.allSettled(streamPromises),
-						new Promise<never>((_, reject) => {
-							onAbort = () => {
-								abortController.abort();
-								reject(
-									new ExecutionCancelledError({
-										message: 'Sandbox execution cancelled',
-										sandboxId,
-									})
-								);
-							};
-							if (signal.aborted) {
-								onAbort();
-							} else {
-								signal.addEventListener('abort', onAbort, { once: true });
-							}
-						}),
-					]);
-				} finally {
-					if (onAbort && signal) {
-						signal.removeEventListener('abort', onAbort);
-					}
-				}
-			} else {
-				await Promise.allSettled(streamPromises);
-			}
+			finalExecution = signal
+				? await raceWithAbort(completionPromise, signal, abortController, sandboxId)
+				: await completionPromise;
+			await waitForStreamsToDrain(streamPromises, signal, abortController, sandboxId);
 		} else {
-			// No streams available (shouldn't happen for oneshot, but handle defensively).
-			// Fall back to a single wait then check.
-			logger?.debug('no streams to wait on, checking sandbox status directly');
+			logger?.debug(
+				'missing executionId on create response, falling back to stream-first completion'
+			);
+			await waitForStreamsToDrain(streamPromises, signal, abortController, sandboxId);
 		}
 
 		if (timingLogsEnabled)
-			console.error(`[TIMING] +${Date.now() - started}ms: all streams done, fetching exit code`);
-		logger?.debug('streams completed, fetching final status');
+			console.error(`[TIMING] +${Date.now() - started}ms: completion wait finished`);
+		logger?.debug('completion wait finished, resolving final exit code');
 
 		// Stream EOF means the sandbox is done — hadron only closes streams after the
 		// container exits. Poll for the exit code with retries because the lifecycle
@@ -234,94 +244,108 @@ export async function sandboxRun(
 		// linear 1s polling interval (not exponential backoff) so we don't overshoot
 		// the window — 15 attempts × 1s = 15s total, which comfortably covers the
 		// drain + lifecycle propagation delay.
-		// Abort-aware sleep that rejects when the caller's signal fires.
-		const abortAwareSleep = (ms: number): Promise<void> =>
-			new Promise((resolve, reject) => {
-				if (signal?.aborted) {
-					reject(new DOMException('Aborted', 'AbortError'));
-					return;
-				}
-				const timer = setTimeout(resolve, ms);
-				signal?.addEventListener(
-					'abort',
-					() => {
-						clearTimeout(timer);
-						reject(new DOMException('Aborted', 'AbortError'));
-					},
-					{ once: true }
-				);
-			});
-
-		let exitCode = 0;
-		const maxStatusRetries = 15;
-		const statusPollInterval = 1000;
+		let exitCode = finalExecution?.exitCode ?? 0;
 		const statusPollStart = Date.now();
-		for (let attempt = 0; attempt < maxStatusRetries; attempt++) {
-			if (signal?.aborted) {
-				break;
+		let shouldWaitForSandboxStatus = finalExecution?.exitCode == null;
+		let sandboxStatusReconciled = false;
+		if (finalExecution?.exitCode == null) {
+			if (createResponse.executionId && finalExecution?.status === 'completed') {
+				try {
+					const execution = await executionGet(client, {
+						executionId: createResponse.executionId,
+						orgId,
+						wait: EXIT_CODE_FAST_WAIT_DURATION,
+						signal,
+					});
+					if (execution.exitCode != null) {
+						exitCode = execution.exitCode;
+						finalExecution.exitCode = execution.exitCode;
+						shouldWaitForSandboxStatus = false;
+						logger?.debug(
+							'[run] exit code %d found from fast execution retry (+%dms)',
+							exitCode,
+							Date.now() - statusPollStart
+						);
+					}
+				} catch (err) {
+					if (!(err instanceof DOMException && err.name === 'AbortError')) {
+						logger?.debug(
+							'[run] fast execution exit code retry failed (+%dms): %s',
+							Date.now() - statusPollStart,
+							err
+						);
+					}
+				}
 			}
+		}
+		if (shouldWaitForSandboxStatus) {
 			try {
-				const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
+				const sandboxStatus = await sandboxGetStatus(client, {
+					sandboxId,
+					orgId,
+					waitForStatus: ['terminated', 'failed'],
+					waitMs: 15000,
+				});
 				if (sandboxStatus.exitCode != null) {
 					exitCode = sandboxStatus.exitCode;
+					sandboxStatusReconciled = true;
 					logger?.debug(
-						'[run] exit code %d found on attempt %d/%d (+%dms)',
+						'[run] exit code %d found after server-side wait (+%dms)',
 						exitCode,
-						attempt + 1,
-						maxStatusRetries,
 						Date.now() - statusPollStart
 					);
-					break;
 				} else if (sandboxStatus.status === 'failed') {
 					exitCode = 1;
+					sandboxStatusReconciled = true;
 					logger?.debug(
-						'[run] sandbox failed on attempt %d/%d (+%dms)',
-						attempt + 1,
-						maxStatusRetries,
+						'[run] sandbox failed after server-side wait (+%dms)',
 						Date.now() - statusPollStart
 					);
-					break;
 				} else if (sandboxStatus.status === 'terminated') {
-					// Sandbox was destroyed. If exit code is missing, the
-					// terminated event may have overwritten it. Stop polling —
-					// no further updates will come.
+					sandboxStatusReconciled = true;
 					logger?.debug(
-						'[run] sandbox terminated without exit code on attempt %d/%d (+%dms)',
-						attempt + 1,
-						maxStatusRetries,
+						'[run] sandbox terminated without exit code after server-side wait (+%dms)',
+						Date.now() - statusPollStart
+					);
+				} else {
+					logger?.debug(
+						'[run] sandbox status wait expired with status=%s (+%dms)',
+						sandboxStatus.status,
 						Date.now() - statusPollStart
 					);
-					break;
-				}
-				// Exit code not yet propagated — wait before next poll.
-				if (attempt < maxStatusRetries - 1) {
-					await abortAwareSleep(statusPollInterval);
 				}
 			} catch (err) {
-				if (err instanceof DOMException && err.name === 'AbortError') {
-					break;
-				}
-				// Transient failure (sandbox briefly unavailable, network error).
-				// Retry instead of giving up — the lifecycle event may still arrive.
-				logger?.debug(
-					'[run] sandboxGetStatus attempt %d/%d failed (+%dms): %s',
-					attempt + 1,
-					maxStatusRetries,
-					Date.now() - statusPollStart,
-					err
-				);
-				if (attempt < maxStatusRetries - 1) {
-					await abortAwareSleep(statusPollInterval);
+				if (!(err instanceof DOMException && err.name === 'AbortError')) {
+					logger?.debug(
+						'[run] sandboxGetStatus server-side wait failed (+%dms): %s',
+						Date.now() - statusPollStart,
+						err
+					);
 				}
 			}
 		}
-		if (exitCode === 0) {
+		if (
+			finalExecution &&
+			finalExecution?.exitCode == null &&
+			finalExecution?.status !== 'completed' &&
+			!sandboxStatusReconciled
+		) {
+			exitCode = 1;
 			logger?.debug(
-				'[run] exit code polling finished with default 0 after %d attempts (+%dms)',
-				maxStatusRetries,
-				Date.now() - statusPollStart
+				'[run] using fallback exit code 1 for terminal status=%s after sandbox status reconciliation failed',
+				finalExecution?.status
 			);
 		}
+		if (exitCode === 0) {
+			if (finalExecution?.exitCode != null) {
+				logger?.debug('[run] using execution exit code 0 from long-poll result');
+			} else {
+				logger?.debug(
+					'[run] exit code wait finished with default 0 (+%dms)',
+					Date.now() - statusPollStart
+				);
+			}
+		}
 
 		if (timingLogsEnabled)
 			console.error(
@@ -352,6 +376,223 @@ export async function sandboxRun(
 	}
 }
 
+async function waitForRunCompletion(
+	client: APIClient,
+	sandboxId: string,
+	executionId: string,
+	orgId: string | undefined,
+	signal: AbortSignal | undefined,
+	logger: Logger | undefined,
+	started: number
+): Promise<{ exitCode?: number; status: string }> {
+	const completionAbortController = new AbortController();
+	let onAbort: (() => void) | undefined;
+	if (signal) {
+		onAbort = () => completionAbortController.abort(signal.reason);
+		if (signal.aborted) {
+			onAbort();
+		} else {
+			signal.addEventListener('abort', onAbort, { once: true });
+		}
+	}
+
+	try {
+		const completionSignal = completionAbortController.signal;
+		const executionPromise = waitForExecutionCompletion(
+			client,
+			executionId,
+			orgId,
+			completionSignal,
+			logger,
+			started
+		);
+		const statusPromise = waitForSandboxStatusCompletion(
+			client,
+			sandboxId,
+			orgId,
+			completionSignal,
+			logger,
+			started
+		).catch((err) => {
+			if (completionSignal.aborted) {
+				throw err;
+			}
+			logger?.debug('[run] sandbox status completion wait failed: %s', err);
+			return new Promise<never>(() => {});
+		});
+
+		const result = await Promise.race([executionPromise, statusPromise]);
+		return result;
+	} finally {
+		if (onAbort && signal) {
+			signal.removeEventListener('abort', onAbort);
+		}
+	}
+}
+
+async function waitForExecutionCompletion(
+	client: APIClient,
+	executionId: string,
+	orgId: string | undefined,
+	signal: AbortSignal | undefined,
+	logger: Logger | undefined,
+	started: number
+): Promise<{ exitCode?: number; status: string }> {
+	while (true) {
+		if (signal?.aborted) {
+			throw new DOMException('Aborted', 'AbortError');
+		}
+
+		const result = await executionGet(client, {
+			executionId,
+			orgId,
+			wait: EXECUTION_WAIT_DURATION,
+			signal,
+		});
+		logger?.debug(
+			'[run] execution wait: id=%s status=%s exit=%s +%dms',
+			executionId,
+			result.status,
+			result.exitCode ?? 'undefined',
+			Date.now() - started
+		);
+
+		if (TERMINAL_EXECUTION_STATUSES.has(result.status)) {
+			return {
+				exitCode: result.exitCode,
+				status: result.status,
+			};
+		}
+	}
+}
+
+async function waitForSandboxStatusCompletion(
+	client: APIClient,
+	sandboxId: string,
+	orgId: string | undefined,
+	signal: AbortSignal | undefined,
+	logger: Logger | undefined,
+	started: number
+): Promise<{ exitCode?: number; status: string }> {
+	while (true) {
+		if (signal?.aborted) {
+			throw new DOMException('Aborted', 'AbortError');
+		}
+
+		const result = await sandboxGetStatus(client, {
+			sandboxId,
+			orgId,
+			waitForStatus: ['idle', 'terminated', 'failed'],
+			waitMs: 300000,
+			signal,
+		});
+		logger?.debug(
+			'[run] sandbox status wait: sandbox=%s status=%s exit=%s +%dms',
+			sandboxId,
+			result.status,
+			result.exitCode ?? 'undefined',
+			Date.now() - started
+		);
+
+		if (result.exitCode != null) {
+			return {
+				exitCode: result.exitCode,
+				status: 'completed',
+			};
+		}
+		if (result.status === 'failed') {
+			return {
+				exitCode: 1,
+				status: 'failed',
+			};
+		}
+		if (result.status === 'terminated') {
+			return {
+				status: 'completed',
+			};
+		}
+
+		await new Promise((resolve) => setTimeout(resolve, 25));
+	}
+}
+
+async function waitForStreamsToDrain(
+	streamPromises: Promise<void>[],
+	signal: AbortSignal | undefined,
+	abortController: AbortController,
+	sandboxId: string
+): Promise<void> {
+	if (streamPromises.length === 0) {
+		return;
+	}
+
+	if (signal) {
+		let onAbort: (() => void) | undefined;
+		try {
+			await Promise.race([
+				Promise.allSettled(streamPromises).then(() => undefined),
+				new Promise<never>((_, reject) => {
+					onAbort = () => {
+						abortController.abort();
+						reject(
+							new ExecutionCancelledError({
+								message: 'Sandbox execution cancelled',
+								sandboxId,
+							})
+						);
+					};
+					if (signal.aborted) {
+						onAbort();
+					} else {
+						signal.addEventListener('abort', onAbort, { once: true });
+					}
+				}),
+			]);
+		} finally {
+			if (onAbort) {
+				signal.removeEventListener('abort', onAbort);
+			}
+		}
+		return;
+	}
+
+	await Promise.allSettled(streamPromises);
+}
+
+async function raceWithAbort<T>(
+	promise: Promise<T>,
+	signal: AbortSignal,
+	abortController: AbortController,
+	sandboxId: string
+): Promise<T> {
+	let onAbort: (() => void) | undefined;
+	try {
+		return await Promise.race([
+			promise,
+			new Promise<never>((_, reject) => {
+				onAbort = () => {
+					abortController.abort();
+					reject(
+						new ExecutionCancelledError({
+							message: 'Sandbox execution cancelled',
+							sandboxId,
+						})
+					);
+				};
+				if (signal.aborted) {
+					onAbort();
+				} else {
+					signal.addEventListener('abort', onAbort, { once: true });
+				}
+			}),
+		]);
+	} finally {
+		if (onAbort) {
+			signal.removeEventListener('abort', onAbort);
+		}
+	}
+}
+
 async function createStdinStream(
 	region: string,
 	apiKey: string,
@@ -526,6 +767,12 @@ async function streamUrlToWritable(
 		// Signal end-of-stream to the tee/pipe chain so downstream
 		// consumers (e.g. process.stdout pipe) know no more data is coming.
 		writable.end();
+		if ('once' in writable) {
+			await finished(writable as NodeJS.WritableStream).catch(() => {
+				// Ignore finish errors here; the main read/write path already
+				// reported meaningful stream errors.
+			});
+		}
 	} catch (err) {
 		if (err instanceof Error && err.name === 'AbortError') {
 			logger?.debug('[stream] aborted after %dms', Date.now() - streamStart);

package/src/services/sandbox/types.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { StructuredError } from '../../error.ts';
 import { SortDirectionSchema } from '../pagination.ts';
+import type { SandboxPauseResult } from './pause.ts';
 
 /**
  * Resource limits for a sandbox using Kubernetes-style units
@@ -274,6 +275,13 @@ export const SandboxTimeoutConfigSchema = z.object({
 		.string()
 		.optional()
 		.describe('Maximum execution time per command (e.g., "5m", "1h")'),
+	/** Maximum duration a sandbox can remain paused before termination (e.g., "24h", "0" for infinite) */
+	paused: z
+		.string()
+		.optional()
+		.describe(
+			'Maximum duration a sandbox can remain paused before termination (e.g., "24h", "0" for infinite)'
+		),
 });
 export type SandboxTimeoutConfig = z.infer<typeof SandboxTimeoutConfigSchema>;
 
@@ -399,7 +407,7 @@ export const SandboxSchema = z.object({
 		.describe('Set environment variables on the sandbox. Pass null to delete a variable.'),
 	/** Pause the sandbox, creating a checkpoint of its current state. */
 	pause: z
-		.custom<() => Promise<void>>()
+		.custom<() => Promise<SandboxPauseResult>>()
 		.describe('Pause the sandbox, creating a checkpoint of its current state.'),
 	/** Resume the sandbox from a paused or evacuated state. */
 	resume: z
@@ -592,6 +600,11 @@ export const SandboxInfoSchema = z.object({
 			idle: z.string().optional().describe('Idle timeout duration (e.g., "10m0s")'),
 			/** Execution timeout duration (e.g., "5m0s") */
 			execution: z.string().optional().describe('Execution timeout duration (e.g., "5m0s")'),
+			/** Paused timeout duration (e.g., "24h0s", "0s" for infinite) */
+			paused: z
+				.string()
+				.optional()
+				.describe('Paused timeout duration (e.g., "24h0s", "0s" for infinite)'),
 		})
 		.optional()
 		.describe('Timeout configuration for this sandbox'),
@@ -830,6 +843,8 @@ export const SnapshotCreateOptionsSchema = z.object({
 	tag: z.string().optional().describe('Tag for the snapshot (defaults to "latest")'),
 	/** Make the snapshot publicly accessible */
 	public: z.boolean().optional().describe('Make the snapshot publicly accessible'),
+	/** Organization ID to use for CLI-authenticated requests */
+	orgId: z.string().optional().describe('Organization ID for CLI-authenticated requests'),
 });
 export type SnapshotCreateOptions = z.infer<typeof SnapshotCreateOptionsSchema>;
 
@@ -905,7 +920,7 @@ export interface SandboxService {
 	list(params?: ListSandboxesParams): Promise<ListSandboxesResponse>;
 	destroy(sandboxId: string): Promise<void>;
 	/** Pause a running sandbox, creating a checkpoint of its current state. */
-	pause(sandboxId: string): Promise<void>;
+	pause(sandboxId: string): Promise<SandboxPauseResult>;
 	/** Resume a paused or evacuated sandbox from its checkpoint. */
 	resume(sandboxId: string): Promise<void>;
 	snapshot: SnapshotService;

package/src/services/stream/namespaces.ts

@@ -40,11 +40,11 @@ export const StreamNamespaceEntrySchema = z.object({
 	chunks: z.number().describe('number of chunks'),
 	completed: z.boolean().describe('whether the stream upload is completed'),
 	size_bytes: z.number().describe('size in bytes'),
-	started_at: z.string().nullable().describe('ISO 8601 stream start timestamp'),
+	started_at: z.string().nullable().optional().describe('ISO 8601 stream start timestamp'),
 	ended_at: z.string().nullable().describe('ISO 8601 stream end timestamp'),
 	headers: z.record(z.string(), z.string()).nullable().optional().describe('stream headers'),
 	metadata: z.record(z.string(), z.string()).nullable().optional().describe('stream metadata'),
-	expires_at: z.string().nullable().describe('ISO 8601 expiration timestamp or null'),
+	expires_at: z.string().nullable().optional().describe('ISO 8601 expiration timestamp or null'),
 	url: z.string().describe('public URL to access the stream'),
 });