@agentuity/core 2.0.0-beta.0 → 2.0.0

package/src/services/sandbox/job.ts

@@ -0,0 +1,161 @@
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { CreateJobOptionsSchema, JobSchema, type Job } from './types.ts';
+import { throwSandboxError } from './util.ts';
+import { z } from 'zod';
+
+export const CreateJobRequestSchema = CreateJobOptionsSchema;
+
+export const CreateJobDataSchema = JobSchema;
+
+export const CreateJobResponseSchema = APIResponseSchema(CreateJobDataSchema);
+
+export const JobCreateParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID where the job should run'),
+	options: CreateJobOptionsSchema.describe('Job creation options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	signal: z.custom<AbortSignal>().optional().describe('Optional abort signal for cancellation'),
+});
+export type JobCreateParams = z.infer<typeof JobCreateParamsSchema>;
+
+export async function jobCreate(client: APIClient, params: JobCreateParams): Promise<Job> {
+	const { sandboxId, options, orgId, signal } = params;
+	const body: z.infer<typeof CreateJobRequestSchema> = {
+		command: options.command,
+	};
+	if (options.streams) {
+		body.streams = options.streams;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof CreateJobResponseSchema>>(
+		url,
+		body,
+		CreateJobResponseSchema,
+		CreateJobRequestSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobGetDataSchema = JobSchema;
+
+export const JobGetResponseSchema = APIResponseSchema(JobGetDataSchema);
+
+export const JobGetParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobGetParams = z.infer<typeof JobGetParamsSchema>;
+
+export async function jobGet(client: APIClient, params: JobGetParams): Promise<Job> {
+	const { sandboxId, jobId, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobGetResponseSchema>>(
+		url,
+		JobGetResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}
+
+export const JobListDataSchema = z.object({
+	jobs: z.array(JobSchema).describe('List of jobs'),
+});
+export type JobListResponse = z.infer<typeof JobListDataSchema>;
+
+export const JobListResponseSchema = APIResponseSchema(JobListDataSchema);
+
+export const JobListParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	limit: z.number().optional().describe('Maximum number of results'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobListParams = z.infer<typeof JobListParamsSchema>;
+
+export async function jobList(client: APIClient, params: JobListParams): Promise<JobListResponse> {
+	const { sandboxId, orgId, limit, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (limit !== undefined) {
+		queryParams.set('limit', String(limit));
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobListResponseSchema>>(
+		url,
+		JobListResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobStopDataSchema = JobSchema;
+
+export const JobStopResponseSchema = APIResponseSchema(JobStopDataSchema);
+
+export const JobStopParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	force: z.boolean().optional().describe('Force termination (SIGKILL)'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobStopParams = z.infer<typeof JobStopParamsSchema>;
+
+export async function jobStop(client: APIClient, params: JobStopParams): Promise<Job> {
+	const { sandboxId, jobId, force, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (force) {
+		queryParams.set('force', 'true');
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof JobStopResponseSchema>>(
+		url,
+		JobStopResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}

package/src/services/sandbox/run.ts

@@ -224,20 +224,103 @@ export async function sandboxRun(
 		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.
+		// container exits. Poll for the exit code with retries because the lifecycle
+		// event (carrying the exit code) may still be in flight to Catalyst when the
+		// stream completes.
+		//
+		// Hadron drains container logs for up to 5s after exit, then closes the
+		// stream, then sends the lifecycle event in a goroutine. So the exit code
+		// typically arrives at Catalyst 5–7s after the container exits. We use a
+		// 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;
-		try {
-			const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
-			if (sandboxStatus.exitCode != null) {
-				exitCode = sandboxStatus.exitCode;
-			} else if (sandboxStatus.status === 'failed') {
-				exitCode = 1;
+		const maxStatusRetries = 15;
+		const statusPollInterval = 1000;
+		const statusPollStart = Date.now();
+		for (let attempt = 0; attempt < maxStatusRetries; attempt++) {
+			if (signal?.aborted) {
+				break;
+			}
+			try {
+				const sandboxStatus = await sandboxGetStatus(client, { sandboxId, orgId });
+				if (sandboxStatus.exitCode != null) {
+					exitCode = sandboxStatus.exitCode;
+					logger?.debug(
+						'[run] exit code %d found on attempt %d/%d (+%dms)',
+						exitCode,
+						attempt + 1,
+						maxStatusRetries,
+						Date.now() - statusPollStart
+					);
+					break;
+				} else if (sandboxStatus.status === 'failed') {
+					exitCode = 1;
+					logger?.debug(
+						'[run] sandbox failed on attempt %d/%d (+%dms)',
+						attempt + 1,
+						maxStatusRetries,
+						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.
+					logger?.debug(
+						'[run] sandbox terminated without exit code on attempt %d/%d (+%dms)',
+						attempt + 1,
+						maxStatusRetries,
+						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);
+				}
 			}
-		} 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 (exitCode === 0) {
+			logger?.debug(
+				'[run] exit code polling finished with default 0 after %d attempts (+%dms)',
+				maxStatusRetries,
+				Date.now() - statusPollStart
+			);
 		}
 
 		if (timingLogsEnabled)
@@ -387,44 +470,56 @@ async function streamUrlToWritable(
 	writable: Writable,
 	signal: AbortSignal,
 	logger?: Logger,
-	started?: number
+	_started?: number
 ): Promise<void> {
+	const streamStart = Date.now();
 	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})`
-			);
+		// Signal to Pulse that this is a v2 stream so it waits for v2 metadata
+		// instead of falling back to the legacy download path on a short timeout.
+		const v2Url = new URL(url);
+		v2Url.searchParams.set('v', '2');
+		logger?.debug('[stream] fetching: %s', v2Url.href);
+		const response = await fetch(v2Url.href, { signal });
+		logger?.debug(
+			'[stream] response status=%d in %dms',
+			response.status,
+			Date.now() - streamStart
+		);
 
 		if (!response.ok || !response.body) {
-			logger?.debug('stream response not ok or no body');
+			logger?.debug('[stream] not ok or no body (status=%d) — returning empty', response.status);
 			return;
 		}
 
 		const reader = response.body.getReader();
-		let firstChunk = true;
+		let chunks = 0;
+		let totalBytes = 0;
 
 		// 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`);
+				logger?.debug(
+					'[stream] EOF after %dms (%d chunks, %d bytes)',
+					Date.now() - streamStart,
+					chunks,
+					totalBytes
+				);
 				break;
 			}
 
 			if (value) {
-				if (firstChunk && started) {
-					if (timingLogsEnabled)
-						console.error(
-							`[TIMING] +${Date.now() - started}ms: first chunk (${value.length} bytes)`
-						);
-					firstChunk = false;
+				chunks++;
+				totalBytes += value.length;
+				if (chunks <= 3 || chunks % 100 === 0) {
+					logger?.debug(
+						'[stream] chunk #%d: %d bytes (total: %d bytes, +%dms)',
+						chunks,
+						value.length,
+						totalBytes,
+						Date.now() - streamStart
+					);
 				}
-				logger?.debug('stream chunk: %d bytes', value.length);
 				await writeAndDrain(writable, value);
 			}
 		}
@@ -433,9 +528,9 @@ async function streamUrlToWritable(
 		writable.end();
 	} catch (err) {
 		if (err instanceof Error && err.name === 'AbortError') {
-			logger?.debug('stream aborted');
+			logger?.debug('[stream] aborted after %dms', Date.now() - streamStart);
 			return;
 		}
-		logger?.debug('stream error: %s', err);
+		logger?.debug('[stream] error after %dms: %s', Date.now() - streamStart, err);
 	}
 }

package/src/services/sandbox/types.ts

@@ -167,6 +167,35 @@ export const ExecutionStatusSchema = z.enum([
 ]);
 export type ExecutionStatus = z.infer<typeof ExecutionStatusSchema>;
 
+export const JobStatusSchema = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']);
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+
+export const JobSchema = z.object({
+	jobId: z.string().describe('Unique identifier for the job'),
+	sandboxId: z.string().describe('ID of the sandbox where the job is running'),
+	command: z.array(z.string()).describe('Command and arguments being executed'),
+	status: JobStatusSchema.describe('Current status of the job'),
+	exitCode: z.number().nullish().describe('Exit code of the job (set when completed)'),
+	startedAt: z.string().nullish().describe('ISO timestamp when the job started'),
+	completedAt: z.string().nullish().describe('ISO timestamp when the job completed'),
+	error: z.string().nullish().describe('Error message if the job failed'),
+	stdoutStreamUrl: z.string().nullish().describe('URL to stream stdout output'),
+	stderrStreamUrl: z.string().nullish().describe('URL to stream stderr output'),
+});
+export type Job = z.infer<typeof JobSchema>;
+
+export const CreateJobOptionsSchema = z.object({
+	command: z.array(z.string()).describe('Command and arguments to execute'),
+	streams: z
+		.object({
+			stdout: z.string().optional().describe('Stream ID for stdout output'),
+			stderr: z.string().optional().describe('Stream ID for stderr output'),
+		})
+		.optional()
+		.describe('Stream configuration for output redirection'),
+});
+export type CreateJobOptions = z.infer<typeof CreateJobOptionsSchema>;
+
 /** Read-only stream interface for consuming streams without write access */
 export const StreamReaderSchema = z.object({
 	/** Unique stream identifier */
@@ -299,6 +328,13 @@ export const SandboxCreateOptionsSchema = z.object({
 		.record(z.string(), z.unknown())
 		.optional()
 		.describe('Optional user-defined metadata to associate with the sandbox.'),
+	/** Permission scopes for automatic service access (e.g., "services:read", "services:write"). */
+	scopes: z
+		.array(z.string())
+		.optional()
+		.describe(
+			'Permission scopes for automatic service access (e.g., "services:read", "services:write").'
+		),
 });
 export type SandboxCreateOptions = z.infer<typeof SandboxCreateOptionsSchema>;
 
@@ -369,6 +405,20 @@ export const SandboxSchema = z.object({
 		.describe('Resume the sandbox from a paused or evacuated state.'),
 	/** Destroy the sandbox */
 	destroy: z.custom<() => Promise<void>>().describe('Destroy the sandbox'),
+	/** Create a new job in the sandbox */
+	createJob: z
+		.custom<(options: CreateJobOptions) => Promise<Job>>()
+		.describe('Create a new job in the sandbox'),
+	/** Get a job by ID */
+	getJob: z.custom<(jobId: string) => Promise<Job>>().describe('Get a job by ID'),
+	/** List jobs in the sandbox */
+	listJobs: z
+		.custom<(limit?: number) => Promise<{ jobs: Job[] }>>()
+		.describe('List jobs in the sandbox'),
+	/** Stop a running job */
+	stopJob: z
+		.custom<(jobId: string, force?: boolean) => Promise<Job>>()
+		.describe('Stop a running job'),
 });
 export type Sandbox = z.infer<typeof SandboxSchema>;
 

package/src/services/sandbox/util.ts

@@ -176,6 +176,7 @@ export const SnapshotNotFoundError = StructuredError('SnapshotNotFoundError')<{
 export const SandboxErrorContextSchema = z.object({
 	sandboxId: z.string().optional().describe('sandbox id'),
 	executionId: z.string().optional().describe('execution id'),
+	jobId: z.string().optional().describe('job id'),
 	sessionId: z.string().nullish().describe('session id'),
 	snapshotId: z.string().optional().describe('snapshot id'),
 });

package/src/services/schedule/service.ts

@@ -58,6 +58,18 @@ export const ScheduleSchema = z.object({
 	 * the schedule fires or the expression is changed.
 	 */
 	due_date: z.string().describe('ISO 8601 timestamp of the next scheduled execution.'),
+
+	/**
+	 * Whether this is a system-managed schedule.
+	 *
+	 * @remarks Internal schedules are created by the system and cannot be modified
+	 * or deleted by users.
+	 */
+	internal: z
+		.boolean()
+		.describe(
+			'Whether this is a system-managed schedule. Internal schedules cannot be modified or deleted users.'
+		),
 });
 
 export type Schedule = z.infer<typeof ScheduleSchema>;
@@ -204,6 +216,14 @@ export const CreateScheduleParamsSchema = z.object({
 	 */
 	expression: z.string().describe('Cron expression defining when the schedule fires'),
 
+	/**
+	 * Whether this is a system-managed schedule.
+	 *
+	 * @remarks Internal schedules are created by the system for workflows and cannot
+	 * be modified or deleted directly by users.
+	 */
+	internal: z.boolean().optional().describe('Whether this is a system-managed schedule.'),
+
 	/**
 	 * Optional array of destinations to create alongside the schedule.
 	 *