@agentuity/server 1.0.31 → 1.0.33

package/src/api/sandbox/run.ts

@@ -1,439 +0,0 @@
-import type { Logger } from '@agentuity/core';
-import type { Readable, Writable } from 'node:stream';
-import { PassThrough } from 'node:stream';
-import { APIClient, PaymentRequiredError } from '../api.ts';
-import { sandboxCreate } from './create.ts';
-import { sandboxDestroy } from './destroy.ts';
-import { sandboxGetStatus } from './getStatus.ts';
-import { ExecutionCancelledError, writeAndDrain } from './util.ts';
-import type { SandboxRunOptions, SandboxRunResult } from '@agentuity/core';
-import { getServiceUrls } from '../../config.ts';
-
-const timingLogsEnabled = false;
-
-/**
- * Creates a Writable stream that captures all chunks to a buffer array
- * and optionally tees (forwards) them to one or more user-provided streams.
- *
- * @param chunks - Array to collect Buffer chunks into
- * @param userStreams - Optional user-provided Writable stream(s) to forward chunks to
- * @returns A Writable stream that captures and optionally forwards data
- */
-function createTeeWritable(chunks: Buffer[], ...userStreams: (Writable | undefined)[]): Writable {
-	const tee = new PassThrough();
-
-	// Always capture chunks to the buffer
-	tee.on('data', (chunk: Buffer) => {
-		chunks.push(chunk);
-	});
-
-	// Pipe to all provided user streams with proper backpressure handling
-	for (const userStream of userStreams) {
-		if (userStream) {
-			tee.pipe(userStream, { end: false });
-		}
-	}
-
-	return tee;
-}
-
-export interface SandboxRunParams {
-	options: SandboxRunOptions;
-	orgId?: string;
-	region?: string;
-	apiKey?: string;
-	signal?: AbortSignal;
-	stdin?: Readable;
-	stdout?: Writable;
-	stderr?: Writable;
-	logger?: Logger;
-}
-
-/**
- * Creates a sandbox, executes a command, and waits for completion.
- *
- * This is a high-level convenience function that handles the full lifecycle:
- * creating a sandbox, streaming I/O, polling for completion, and cleanup.
- *
- * @param client - The API client to use for the request
- * @param params - Parameters including command options, I/O streams, and timeout settings
- * @returns The run result including exit code and duration
- * @throws {SandboxResponseError} If sandbox creation fails, execution times out, or is cancelled
- */
-export async function sandboxRun(
-	client: APIClient,
-	params: SandboxRunParams
-): Promise<SandboxRunResult> {
-	const { options, orgId, region, apiKey, signal, stdin, stdout, stderr, logger } = params;
-	const started = Date.now();
-	if (timingLogsEnabled) console.error(`[TIMING] +0ms: sandbox run started`);
-
-	let stdinStreamId: string | undefined;
-	let stdinStreamUrl: string | undefined;
-
-	// If stdin is provided and has data, create a stream for it
-	if (stdin && region && apiKey) {
-		const streamResult = await createStdinStream(region, apiKey, orgId, logger);
-		stdinStreamId = streamResult.id;
-		stdinStreamUrl = streamResult.url;
-		logger?.debug('created stdin stream: %s', stdinStreamId);
-	}
-
-	const createResponse = await sandboxCreate(client, {
-		options: {
-			...options,
-			command: {
-				exec: options.command.exec,
-				files: options.command.files,
-				mode: 'oneshot',
-			},
-			stream: {
-				...options.stream,
-				stdin: stdinStreamId,
-			},
-		},
-		orgId,
-	});
-
-	const sandboxId = createResponse.sandboxId;
-	const stdoutStreamUrl = createResponse.stdoutStreamUrl;
-	const stderrStreamUrl = createResponse.stderrStreamUrl;
-
-	logger?.debug(
-		'sandbox created: %s, stdoutUrl: %s, stderrUrl: %s',
-		sandboxId,
-		stdoutStreamUrl ?? 'none',
-		stderrStreamUrl ?? 'none'
-	);
-	if (timingLogsEnabled)
-		console.error(`[TIMING] +${Date.now() - started}ms: sandbox created (${sandboxId})`);
-
-	const abortController = new AbortController();
-	const streamPromises: Promise<void>[] = [];
-
-	// Create capture buffers for stdout/stderr
-	const stdoutChunks: Buffer[] = [];
-	const stderrChunks: Buffer[] = [];
-
-	try {
-		// Start stdin streaming if we have stdin and a stream URL
-		if (stdin && stdinStreamUrl && apiKey) {
-			const stdinPromise = streamStdinToUrl(
-				stdin,
-				stdinStreamUrl,
-				apiKey,
-				abortController.signal,
-				logger
-			);
-			streamPromises.push(stdinPromise);
-		}
-
-		// Check if stdout and stderr are the same stream (combined output)
-		const isCombinedOutput =
-			stdoutStreamUrl && stderrStreamUrl && stdoutStreamUrl === stderrStreamUrl;
-
-		if (isCombinedOutput) {
-			// Stream combined output to stdout only to avoid duplicates
-			if (stdoutStreamUrl) {
-				logger?.debug('using combined output stream (stdout === stderr)');
-				const teeStream = createTeeWritable(stdoutChunks, stdout);
-				const combinedPromise = streamUrlToWritable(
-					stdoutStreamUrl,
-					teeStream,
-					abortController.signal,
-					logger,
-					started
-				);
-				streamPromises.push(combinedPromise);
-			}
-		} else {
-			// Start stdout streaming with capture
-			if (stdoutStreamUrl) {
-				const teeStream = createTeeWritable(stdoutChunks, stdout);
-				const stdoutPromise = streamUrlToWritable(
-					stdoutStreamUrl,
-					teeStream,
-					abortController.signal,
-					logger,
-					started
-				);
-				streamPromises.push(stdoutPromise);
-			}
-
-			// Start stderr streaming with capture
-			if (stderrStreamUrl) {
-				const teeStream = createTeeWritable(stderrChunks, stderr);
-				const stderrPromise = streamUrlToWritable(
-					stderrStreamUrl,
-					teeStream,
-					abortController.signal,
-					logger,
-					started
-				);
-				streamPromises.push(stderrPromise);
-			}
-		}
-
-		// 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...');
-
-		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);
-			}
-		} 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');
-		}
-
-		if (timingLogsEnabled)
-			console.error(`[TIMING] +${Date.now() - started}ms: all streams done, fetching exit code`);
-		logger?.debug('streams completed, fetching final status');
-
-		// Stream EOF means the sandbox is done — hadron only closes streams after the
-		// container exits. Fetch status once for the exit code; if lifecycle events
-		// haven't propagated to Catalyst yet, default to exit code 0.
-		let exitCode = 0;
-		try {
-			const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
-			if (sandboxStatus.exitCode != null) {
-				exitCode = sandboxStatus.exitCode;
-			} else if (sandboxStatus.status === 'failed') {
-				exitCode = 1;
-			}
-		} catch {
-			// Sandbox may already be destroyed (fire-and-forget teardown).
-			// Stream EOF already confirmed execution completed.
-			logger?.debug('sandboxGetStatus failed after stream EOF, using default exit code 0');
-		}
-
-		if (timingLogsEnabled)
-			console.error(
-				`[TIMING] +${Date.now() - started}ms: sandboxGet complete (exit: ${exitCode})`
-			);
-
-		// Build captured output strings
-		const capturedStdout = Buffer.concat(stdoutChunks).toString('utf-8');
-		const capturedStderr = isCombinedOutput
-			? capturedStdout
-			: Buffer.concat(stderrChunks).toString('utf-8');
-
-		return {
-			sandboxId,
-			exitCode,
-			durationMs: Date.now() - started,
-			stdout: capturedStdout,
-			stderr: capturedStderr,
-		};
-	} catch (error) {
-		abortController.abort();
-		try {
-			await sandboxDestroy(client, { sandboxId, orgId });
-		} catch {
-			// Ignore cleanup errors
-		}
-		throw error;
-	}
-}
-
-async function createStdinStream(
-	region: string,
-	apiKey: string,
-	orgId?: string,
-	logger?: Logger
-): Promise<{ id: string; url: string }> {
-	const urls = getServiceUrls(region);
-	const streamBaseUrl = urls.stream;
-
-	// Build URL with orgId query param for CLI token validation
-	const queryParams = new URLSearchParams();
-	if (orgId) {
-		queryParams.set('orgId', orgId);
-	}
-	const queryString = queryParams.toString();
-	const url = `${streamBaseUrl}${queryString ? `?${queryString}` : ''}`;
-	logger?.trace('creating stdin stream: %s', url);
-
-	const response = await fetch(url, {
-		method: 'POST',
-		headers: {
-			'Content-Type': 'application/json',
-			Authorization: `Bearer ${apiKey}`,
-		},
-		body: JSON.stringify({
-			name: `sandbox-stdin-${Date.now()}`,
-		}),
-	});
-
-	if (!response.ok) {
-		if (response.status === 402) {
-			throw new PaymentRequiredError({
-				url: url,
-			});
-		}
-		throw new Error(`Failed to create stdin stream: ${response.status} ${response.statusText}`);
-	}
-
-	const data = (await response.json()) as { id: string };
-	logger?.debug('created stdin stream: %s', data.id);
-
-	// Include orgId in the URL for subsequent PUT requests (needed for CLI token auth)
-	const putQueryString = orgId ? `?orgId=${encodeURIComponent(orgId)}` : '';
-	return {
-		id: data.id,
-		url: `${streamBaseUrl}/${data.id}${putQueryString}`,
-	};
-}
-
-async function streamStdinToUrl(
-	stdin: Readable,
-	url: string,
-	apiKey: string,
-	signal: AbortSignal,
-	logger?: Logger
-): Promise<void> {
-	try {
-		logger?.debug('streaming stdin to: %s', url);
-
-		// Convert Node.js Readable to a web ReadableStream for fetch body
-		let controllerClosed = false;
-		const webStream = new ReadableStream({
-			start(controller) {
-				stdin.on('data', (chunk: Buffer) => {
-					if (!signal.aborted && !controllerClosed) {
-						controller.enqueue(chunk);
-					}
-				});
-				stdin.on('end', () => {
-					if (!controllerClosed) {
-						controllerClosed = true;
-						controller.close();
-					}
-				});
-				stdin.on('error', (err) => {
-					if (!controllerClosed) {
-						controllerClosed = true;
-						controller.error(err);
-					}
-				});
-				signal.addEventListener('abort', () => {
-					if (!controllerClosed) {
-						controllerClosed = true;
-						controller.close();
-					}
-				});
-			},
-		});
-
-		const response = await fetch(url, {
-			method: 'PUT',
-			headers: {
-				Authorization: `Bearer ${apiKey}`,
-			},
-			body: webStream,
-			signal,
-			duplex: 'half',
-		} as RequestInit);
-
-		if (!response.ok) {
-			logger?.debug('stdin stream PUT failed: %d', response.status);
-		} else {
-			logger?.debug('stdin stream completed');
-		}
-	} catch (err) {
-		if (err instanceof Error && err.name === 'AbortError') {
-			logger?.debug('stdin stream aborted (expected on completion)');
-		} else {
-			logger?.debug('stdin stream error: %s', err);
-		}
-	}
-}
-
-async function streamUrlToWritable(
-	url: string,
-	writable: Writable,
-	signal: AbortSignal,
-	logger?: Logger,
-	started?: number
-): Promise<void> {
-	try {
-		logger?.debug('fetching stream: %s', url);
-		const response = await fetch(url, { signal });
-		logger?.debug('stream response status: %d', response.status);
-		if (timingLogsEnabled && started)
-			console.error(
-				`[TIMING] +${Date.now() - started}ms: stream response received (status: ${response.status})`
-			);
-
-		if (!response.ok || !response.body) {
-			logger?.debug('stream response not ok or no body');
-			return;
-		}
-
-		const reader = response.body.getReader();
-		let firstChunk = true;
-
-		// Read until EOF - Pulse will block until data is available
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) {
-				logger?.debug('stream EOF');
-				if (timingLogsEnabled && started)
-					console.error(`[TIMING] +${Date.now() - started}ms: stream EOF`);
-				break;
-			}
-
-			if (value) {
-				if (firstChunk && started) {
-					if (timingLogsEnabled)
-						console.error(
-							`[TIMING] +${Date.now() - started}ms: first chunk (${value.length} bytes)`
-						);
-					firstChunk = false;
-				}
-				logger?.debug('stream chunk: %d bytes', value.length);
-				await writeAndDrain(writable, value);
-			}
-		}
-		// 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();
-	} catch (err) {
-		if (err instanceof Error && err.name === 'AbortError') {
-			logger?.debug('stream aborted');
-			return;
-		}
-		logger?.debug('stream error: %s', err);
-	}
-}

package/src/api/sandbox/runtime.ts

@@ -1,100 +0,0 @@
-import type { ListRuntimesParams, ListRuntimesResponse, SandboxRuntime } from '@agentuity/core';
-import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api.ts';
-import { API_VERSION, throwSandboxError } from './util.ts';
-
-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")'),
-		disk: z.string().optional().describe('Disk requirement (e.g., "500Mi")'),
-		networkEnabled: z.boolean().describe('Whether network access is enabled'),
-	})
-	.describe('Runtime resource requirements');
-
-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")'),
-		description: z.string().optional().describe('Optional description'),
-		iconUrl: z.string().optional().describe('URL for runtime icon'),
-		brandColor: z.string().optional().describe('Brand color for the runtime (hex color code)'),
-		url: z.string().optional().describe('URL for runtime documentation or homepage'),
-		tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
-		requirements: RuntimeRequirementsSchema.optional().describe('Runtime resource requirements'),
-		readme: z.string().optional().describe('Readme content in markdown format'),
-	})
-	.describe('Information about a sandbox runtime');
-
-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');
-
-export 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());
-	}
-	if (params?.sort) {
-		queryParams.set('sort', params.sort);
-	}
-	if (params?.direction) {
-		queryParams.set('direction', params.direction);
-	}
-
-	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,
-					brandColor: r.brandColor,
-					url: r.url,
-					tags: r.tags,
-					requirements: r.requirements,
-					readme: r.readme,
-				})
-			),
-			total: resp.data.total,
-		};
-	}
-
-	throwSandboxError(resp, {});
-}

package/src/api/sandbox/snapshot-build.ts

@@ -1,98 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Regex pattern for validating npm/bun package specifiers.
- * Uses a blocklist approach: rejects shell injection characters while allowing
- * all legitimate specifier formats (names, scoped packages, URLs, git refs, etc.).
- *
- * Valid examples: "typescript", "@types/node", "opencode-ai@1.2.3",
- *   "https://github.com/user/repo", "git+https://github.com/user/repo.git",
- *   "github:user/repo", "file:../local-pkg"
- * Invalid examples: "foo bar", "pkg;rm -rf", "pkg|cat /etc/passwd", "$(evil)"
- */
-export const NPM_PACKAGE_NAME_PATTERN = /^[^\s;`|$]+$/;
-
-/**
- * Base schema for snapshot build configuration file (agentuity-snapshot.yaml)
- * This is the canonical schema - used for JSON Schema generation.
- */
-export const SnapshotBuildFileBaseSchema = z
-	.object({
-		version: z.literal(1).describe('Schema version, must be 1'),
-		runtime: z
-			.string()
-			.describe('Runtime identifier (name:tag format, e.g., bun:1, node:20, python:3.12)'),
-		name: z
-			.string()
-			.regex(/^[a-zA-Z0-9_-]+$/)
-			.optional()
-			.describe('Snapshot name (alphanumeric, underscores, dashes only)'),
-		description: z.string().optional().describe('Human-readable description of the snapshot'),
-		dir: z
-			.string()
-			.optional()
-			.describe(
-				'Subdirectory to use as the build context for file resolution (relative to the CLI directory argument)'
-			),
-		dependencies: z
-			.array(z.string())
-			.optional()
-			.describe(
-				'List of apt packages to install. Supports version pinning: package=version or package=version* for prefix matching'
-			),
-		packages: z
-			.array(
-				z
-					.string()
-					.regex(
-						NPM_PACKAGE_NAME_PATTERN,
-						'Invalid npm/bun package specifier: must not contain whitespace, semicolons, backticks, pipes, or dollar signs'
-					)
-			)
-			.optional()
-			.describe(
-				'List of npm/bun packages to install globally via bun install -g. Example: opencode-ai, typescript'
-			),
-		files: z
-			.array(z.string())
-			.optional()
-			.describe(
-				'Glob patterns for files to include from the build context. Supports negative patterns with ! prefix for exclusions'
-			),
-		env: z
-			.record(z.string(), z.string())
-			.optional()
-			.describe(
-				'Environment variables to set. Use ${VAR} syntax for build-time substitution via --env flag'
-			),
-		metadata: z
-			.record(z.string(), z.string())
-			.optional()
-			.describe(
-				'User-defined metadata key-value pairs. Use ${VAR} syntax for build-time substitution via --metadata flag'
-			),
-		public: z
-			.boolean()
-			.optional()
-			.describe('Whether to make the snapshot publicly accessible (default: false)'),
-	})
-	.describe('Agentuity Snapshot Build File - defines a reproducible sandbox environment');
-
-/**
- * Schema with validation refinement - use this for parsing/validation.
- * Ensures at least one of dependencies, files, env, or packages is specified.
- */
-export const SnapshotBuildFileSchema = SnapshotBuildFileBaseSchema.refine(
-	(data) => {
-		const hasDependencies = data.dependencies && data.dependencies.length > 0;
-		const hasFiles = data.files && data.files.length > 0;
-		const hasEnv = data.env && Object.keys(data.env).length > 0;
-		const hasPackages = data.packages && data.packages.length > 0;
-		return hasDependencies || hasFiles || hasEnv || hasPackages;
-	},
-	{
-		message: 'At least one of dependencies, files, env, or packages must be specified',
-	}
-);
-
-export type SnapshotBuildFile = z.infer<typeof SnapshotBuildFileSchema>;