@agentuity/core 1.0.31 → 1.0.33

package/src/api/sandbox/util.ts

@@ -0,0 +1,275 @@
+import { StructuredError } from '../../error.ts';
+import type { EventEmitter } from 'node:events';
+
+interface WritableWithDrain extends EventEmitter {
+	write(chunk: Uint8Array): boolean;
+}
+
+/**
+ * Machine-readable error codes for sandbox operations.
+ * These codes allow programmatic error handling without fragile string matching.
+ */
+export type SandboxErrorCode =
+	| 'SANDBOX_NOT_FOUND'
+	| 'SANDBOX_TERMINATED'
+	| 'SANDBOX_BUSY'
+	| 'EXECUTION_NOT_FOUND'
+	| 'EXECUTION_TIMEOUT'
+	| 'EXECUTION_CANCELLED'
+	| 'SNAPSHOT_NOT_FOUND';
+
+/**
+ * Error thrown when a sandbox API request fails.
+ *
+ * Includes optional context about which sandbox or execution caused the error.
+ */
+export const SandboxResponseError = StructuredError('SandboxResponseError')<{
+	/** The sandbox ID associated with the error, if applicable */
+	sandboxId?: string;
+	/** The execution ID associated with the error, if applicable */
+	executionId?: string;
+	/** The session ID (trace ID) from the x-session-id response header for OTel correlation */
+	sessionId?: string | null;
+	/** Machine-readable error code for programmatic error handling */
+	code?: SandboxErrorCode;
+}>();
+
+/**
+ * Error thrown when a sandbox is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxGet(client, { sandboxId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxNotFoundError') {
+ *     console.error(`Sandbox not found: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxNotFoundError = StructuredError('SandboxNotFoundError')<{
+	sandboxId: string;
+}>();
+
+/**
+ * Error thrown when a sandbox has already terminated.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxExecute(client, { sandboxId: 'terminated-sandbox', command: ['ls'] });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxTerminatedError') {
+ *     console.error(`Sandbox terminated: ${error.sandboxId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SandboxTerminatedError = StructuredError('SandboxTerminatedError')<{
+	sandboxId: string;
+}>();
+
+/**
+ * Error thrown when a sandbox is currently busy executing another command.
+ *
+ * This typically occurs when a second execute request is sent before the
+ * previous execution has completed. Sandbox executions are serialized -
+ * wait for the current execution to complete before sending a new one.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandbox.execute({ command: ['ls'] });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxBusyError') {
+ *     console.error('Sandbox is busy, waiting for current execution to finish');
+ *     // Wait and retry, or use executionGet with long-polling to wait for completion
+ *   }
+ * }
+ * ```
+ */
+export const SandboxBusyError = StructuredError('SandboxBusyError')<{
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when an execution is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await executionGet(client, { executionId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionNotFoundError') {
+ *     console.error(`Execution not found: ${error.executionId}`);
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionNotFoundError = StructuredError('ExecutionNotFoundError')<{
+	executionId: string;
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when an execution times out.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxExecute(client, { sandboxId, command: ['long-running'], timeout: '30s' });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionTimeoutError') {
+ *     console.error('Execution timed out');
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionTimeoutError = StructuredError('ExecutionTimeoutError')<{
+	executionId?: string;
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when an execution is cancelled.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandboxRun(client, params, { signal: controller.signal });
+ * } catch (error) {
+ *   if (error._tag === 'ExecutionCancelledError') {
+ *     console.error('Execution was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export const ExecutionCancelledError = StructuredError('ExecutionCancelledError')<{
+	sandboxId?: string;
+}>();
+
+/**
+ * Error thrown when a snapshot is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await snapshotGet(client, { snapshotId: 'non-existent' });
+ * } catch (error) {
+ *   if (error._tag === 'SnapshotNotFoundError') {
+ *     console.error(`Snapshot not found: ${error.snapshotId}`);
+ *   }
+ * }
+ * ```
+ */
+export const SnapshotNotFoundError = StructuredError('SnapshotNotFoundError')<{
+	snapshotId?: string;
+}>();
+
+/**
+ * Context for throwing sandbox errors.
+ */
+export interface SandboxErrorContext {
+	sandboxId?: string;
+	executionId?: string;
+	sessionId?: string | null;
+	snapshotId?: string;
+}
+
+/**
+ * Throws the appropriate sandbox error based on the response code.
+ *
+ * This helper centralizes error mapping logic, throwing specific error types
+ * when the backend returns a known error code, and falling back to
+ * SandboxResponseError for unknown codes.
+ *
+ * Note: Pause and resume operations use standard error codes. The backend
+ * returns SANDBOX_NOT_FOUND when the sandbox doesn't exist, and HTTP 409
+ * Conflict (handled by APIClient retries) for invalid state transitions
+ * (e.g. pausing a non-running sandbox, resuming a non-suspended sandbox).
+ * No additional error codes are needed for pause/resume.
+ *
+ * @param resp - The API response containing message and optional code
+ * @param context - Context about the operation (sandbox ID, execution ID, etc.)
+ * @throws {SandboxNotFoundError} When code is 'SANDBOX_NOT_FOUND'
+ * @throws {SandboxTerminatedError} When code is 'SANDBOX_TERMINATED'
+ * @throws {SandboxBusyError} When code is 'SANDBOX_BUSY'
+ * @throws {ExecutionNotFoundError} When code is 'EXECUTION_NOT_FOUND'
+ * @throws {ExecutionTimeoutError} When code is 'EXECUTION_TIMEOUT'
+ * @throws {ExecutionCancelledError} When code is 'EXECUTION_CANCELLED'
+ * @throws {SnapshotNotFoundError} When code is 'SNAPSHOT_NOT_FOUND'
+ * @throws {SandboxResponseError} For unknown codes or when no code is provided
+ */
+export function throwSandboxError(
+	resp: { message?: string; code?: string },
+	context: SandboxErrorContext
+): never {
+	const { sandboxId, executionId, sessionId, snapshotId } = context;
+	const code = resp.code as SandboxErrorCode | undefined;
+
+	switch (code) {
+		case 'SANDBOX_NOT_FOUND':
+			throw new SandboxNotFoundError({ message: resp.message, sandboxId: sandboxId ?? '' });
+		case 'SANDBOX_TERMINATED':
+			throw new SandboxTerminatedError({ message: resp.message, sandboxId: sandboxId ?? '' });
+		case 'SANDBOX_BUSY':
+			throw new SandboxBusyError({ message: resp.message, sandboxId });
+		case 'EXECUTION_NOT_FOUND':
+			throw new ExecutionNotFoundError({
+				message: resp.message,
+				executionId: executionId ?? '',
+				sandboxId,
+			});
+		case 'EXECUTION_TIMEOUT':
+			throw new ExecutionTimeoutError({ message: resp.message, executionId, sandboxId });
+		case 'EXECUTION_CANCELLED':
+			throw new ExecutionCancelledError({ message: resp.message, sandboxId });
+		case 'SNAPSHOT_NOT_FOUND':
+			throw new SnapshotNotFoundError({ message: resp.message, snapshotId });
+		default:
+			throw new SandboxResponseError({
+				message: resp.message,
+				sandboxId,
+				executionId,
+				sessionId,
+				code,
+			});
+	}
+}
+
+/** Current sandbox API version */
+
+/**
+ * Write a chunk to a writable stream and wait for it to drain if necessary.
+ * Properly cleans up event listeners to avoid memory leaks.
+ */
+export function writeAndDrain(writable: WritableWithDrain, chunk: Uint8Array): Promise<void> {
+	return new Promise((resolve, reject) => {
+		let needsDrain: boolean;
+		try {
+			needsDrain = !writable.write(chunk);
+		} catch (err) {
+			reject(err);
+			return;
+		}
+		if (needsDrain) {
+			const cleanup = () => {
+				writable.removeListener('drain', onDrain);
+				writable.removeListener('error', onError);
+			};
+			const onDrain = () => {
+				cleanup();
+				resolve();
+			};
+			const onError = (err: Error) => {
+				cleanup();
+				reject(err);
+			};
+			writable.once('drain', onDrain);
+			writable.once('error', onError);
+		} else {
+			resolve();
+		}
+	});
+}

package/src/api/services/index.ts

@@ -0,0 +1 @@
+export * from './stats.ts';

package/src/api/services/stats.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { StructuredError } from '../../error.ts';
+
+// --- Error ---
+
+export const ServiceStatsError = StructuredError('ServiceStatsError')<{
+	message: string;
+}>();
+
+// --- Per-Service Stat Schemas ---
+
+export const KeyValueStatSchema = z.object({
+	namespaceCount: z.number(),
+	keyCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const VectorStatSchema = z.object({
+	namespaceCount: z.number(),
+	documentCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const QueueStatSchema = z.object({
+	queueCount: z.number(),
+	totalMessages: z.number(),
+	totalDlq: z.number(),
+});
+
+export const StreamStatSchema = z.object({
+	streamCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+export const SandboxStatSchema = z.object({
+	totalActive: z.number(),
+	running: z.number(),
+	idle: z.number(),
+	creating: z.number(),
+	totalExecutions: z.number(),
+	totalCpuTimeMs: z.number(),
+	totalMemoryByteSec: z.number(),
+	totalNetworkEgressBytes: z.number(),
+});
+
+export const EmailStatSchema = z.object({
+	addressCount: z.number(),
+	inboundCount: z.number(),
+	outboundCount: z.number(),
+	outboundSuccess: z.number(),
+	outboundFailed: z.number(),
+});
+
+export const TaskStatSchema = z.object({
+	total: z.number().default(0),
+	open: z.number().default(0),
+	inProgress: z.number().default(0),
+	done: z.number().default(0),
+	closed: z.number().default(0),
+	cancelled: z.number().default(0),
+});
+
+export const ScheduleStatSchema = z.object({
+	scheduleCount: z.number(),
+	totalDeliveries: z.number(),
+	successDeliveries: z.number(),
+	failedDeliveries: z.number(),
+});
+
+export const DatabaseStatSchema = z.object({
+	databaseCount: z.number(),
+	totalTableCount: z.number(),
+	totalRecordCount: z.number(),
+	totalSizeBytes: z.number(),
+});
+
+// --- Aggregate Schema ---
+
+export const ServiceStatsDataSchema = z.object({
+	services: z.object({
+		database: DatabaseStatSchema.optional(),
+		keyvalue: KeyValueStatSchema.optional(),
+		vector: VectorStatSchema.optional(),
+		queue: QueueStatSchema.optional(),
+		stream: StreamStatSchema.optional(),
+		sandbox: SandboxStatSchema.optional(),
+		email: EmailStatSchema.optional(),
+		task: TaskStatSchema.optional(),
+		schedule: ScheduleStatSchema.optional(),
+	}),
+});
+
+export const ServiceStatsResponseSchema = APIResponseSchema(ServiceStatsDataSchema);
+
+// --- Types ---
+
+export type KeyValueStat = z.infer<typeof KeyValueStatSchema>;
+export type VectorStat = z.infer<typeof VectorStatSchema>;
+export type QueueStat = z.infer<typeof QueueStatSchema>;
+export type StreamStat = z.infer<typeof StreamStatSchema>;
+export type SandboxStat = z.infer<typeof SandboxStatSchema>;
+export type EmailStat = z.infer<typeof EmailStatSchema>;
+export type TaskStat = z.infer<typeof TaskStatSchema>;
+export type ScheduleStat = z.infer<typeof ScheduleStatSchema>;
+export type DatabaseStat = z.infer<typeof DatabaseStatSchema>;
+export type ServiceStatsData = z.infer<typeof ServiceStatsDataSchema>;
+export type ServiceStatsResponse = z.infer<typeof ServiceStatsResponseSchema>;
+
+// --- Valid Services ---
+
+/**
+ * Valid service names that can be used to filter stats.
+ */
+export const VALID_SERVICES = [
+	'database',
+	'keyvalue',
+	'email',
+	'vector',
+	'schedule',
+	'task',
+	'stream',
+	'sandbox',
+	'queue',
+] as const;
+
+export type ServiceName = (typeof VALID_SERVICES)[number];
+
+// --- Options ---
+
+export interface ServiceStatsOptions {
+	/**
+	 * Filter to a specific service. If omitted, returns stats for all services.
+	 */
+	service?: ServiceName;
+	/**
+	 * Start time filter (ISO 8601 timestamp).
+	 */
+	start?: string;
+	/**
+	 * End time filter (ISO 8601 timestamp).
+	 */
+	end?: string;
+	/**
+	 * For CLI auth: sets x-agentuity-orgid header.
+	 * Required when using CLI token auth (bearer tokens without embedded org).
+	 */
+	orgIdHeader?: string;
+}
+
+// --- API Function ---
+
+/**
+ * Get aggregated stats for services used by an organization.
+ *
+ * Returns per-service stats with service-specific fields (counts, sizes, etc.).
+ * Services that error on the backend are omitted from the response.
+ * Services with no provisioned tenant DB return zero values.
+ *
+ * @param client - The API client instance
+ * @param orgId - The organization ID
+ * @param options - Optional filtering (service, time range)
+ * @returns Service stats data with per-service breakdown
+ * @throws {ServiceStatsError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Get stats for all services
+ * const stats = await getServiceStats(client, 'org_123');
+ * console.log(`KV keys: ${stats.services.keyvalue?.keyCount}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get stats for a specific service
+ * const stats = await getServiceStats(client, 'org_123', {
+ *   service: 'keyvalue',
+ * });
+ * ```
+ */
+export async function getServiceStats(
+	client: APIClient,
+	orgId: string,
+	options?: ServiceStatsOptions
+): Promise<ServiceStatsData> {
+	const params = new URLSearchParams();
+	if (options?.service) params.set('service', options.service);
+	if (options?.start) params.set('start', options.start);
+	if (options?.end) params.set('end', options.end);
+
+	const queryString = params.toString();
+	const url = `/services/stats/${encodeURIComponent(orgId)}${queryString ? `?${queryString}` : ''}`;
+
+	const headers: Record<string, string> = {};
+	if (options?.orgIdHeader) {
+		headers['x-agentuity-orgid'] = options.orgIdHeader;
+	}
+
+	const resp = await client.get(
+		url,
+		ServiceStatsResponseSchema,
+		undefined,
+		Object.keys(headers).length > 0 ? headers : undefined
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ServiceStatsError({
+		message: resp.message || 'Failed to get service stats',
+	});
+}

package/src/api/session/get.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { SessionSchema, type Session } from './list.ts';
+import { SessionResponseError } from './util.ts';
+
+export const _SessionGetRequestSchema = z.object({
+	id: z.string().describe('the session id'),
+});
+
+export const SessionEvalRunSchema = z.object({
+	id: z.string().describe('eval run id'),
+	created_at: z.string().describe('creation timestamp'),
+	eval_id: z.string().describe('evaluation id'),
+	pending: z.boolean().describe('pending status'),
+	success: z.boolean().describe('success status'),
+	error: z.string().nullable().describe('error message'),
+	result: z.record(z.string(), z.unknown()).nullable().describe('result object'),
+});
+
+export interface SpanNode {
+	id: string;
+	duration: number;
+	operation: string;
+	attributes: Record<string, unknown>;
+	children?: SpanNode[];
+	error?: string;
+}
+
+export const SpanNodeSchema: z.ZodType<SpanNode> = z.lazy(() =>
+	z.object({
+		id: z.string().describe('span ID'),
+		duration: z.number().describe('duration in milliseconds'),
+		operation: z.string().describe('operation name'),
+		attributes: z.record(z.string(), z.unknown()).describe('span attributes'),
+		children: z.array(SpanNodeSchema).optional().describe('child spans'),
+		error: z.string().optional().describe('error message'),
+	})
+);
+
+export const RouteInfoSchema = z
+	.object({
+		id: z.string().describe('route id'),
+		method: z.string().describe('HTTP method'),
+		path: z.string().describe('route path'),
+	})
+	.nullable();
+
+export const AgentInfoSchema = z.object({
+	name: z.string().describe('agent name'),
+	identifier: z.string().describe('agent identifier'),
+});
+
+export const EnrichedSessionDataSchema = z.object({
+	session: SessionSchema,
+	agents: z.array(AgentInfoSchema).describe('resolved agents'),
+	eval_runs: z.array(SessionEvalRunSchema).describe('eval runs for this session'),
+	route: RouteInfoSchema.describe('route information'),
+});
+
+export const SessionGetResponseSchema = APIResponseSchema(EnrichedSessionDataSchema);
+
+type SessionGetRequest = z.infer<typeof _SessionGetRequestSchema>;
+type SessionGetResponse = z.infer<typeof SessionGetResponseSchema>;
+
+/**
+ * Get a single session by id
+ *
+ * @param client
+ * @param request
+ * @returns
+ */
+export type SessionEvalRun = z.infer<typeof SessionEvalRunSchema>;
+/** @deprecated Use SessionEvalRun instead */
+export type EvalRun = SessionEvalRun;
+export type RouteInfo = z.infer<typeof RouteInfoSchema>;
+export type AgentInfo = z.infer<typeof AgentInfoSchema>;
+export type EnrichedSession = {
+	session: Session;
+	agents: AgentInfo[];
+	evalRuns: SessionEvalRun[];
+	timeline: SpanNode | null;
+	route: RouteInfo;
+};
+
+export async function sessionGet(
+	client: APIClient,
+	request: SessionGetRequest
+): Promise<EnrichedSession> {
+	const resp = await client.request<SessionGetResponse>(
+		'GET',
+		`/session/${request.id}`,
+		SessionGetResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			session: resp.data.session,
+			agents: resp.data.agents,
+			evalRuns: resp.data.eval_runs,
+			timeline: (resp.data.session.timeline as SpanNode) ?? null,
+			route: resp.data.route,
+		};
+	}
+
+	throw new SessionResponseError({ message: resp.message });
+}

package/src/api/session/index.ts

@@ -0,0 +1,3 @@
+export * from './get.ts';
+export * from './list.ts';
+export * from './logs.ts';