@agentuity/core 1.0.33 → 1.0.34

package/src/api/sandbox/util.ts

@@ -1,275 +0,0 @@
-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

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

package/src/api/services/stats.ts

@@ -1,213 +0,0 @@
-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

@@ -1,106 +0,0 @@
-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

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