@agentuity/server 1.0.16 → 1.0.18

package/src/api/queue/sources.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { type APIClient, APIError, APIResponseSchema, APIResponseSchemaNoData } from '../api';
+import { type APIClient, APIResponseSchema, APIResponseSchemaNoData } from '../api.ts';
 import {
 	type CreateSourceRequest,
 	CreateSourceRequestSchema,
@@ -8,16 +8,14 @@ import {
 	SourceSchema,
 	type UpdateSourceRequest,
 	UpdateSourceRequestSchema,
-} from './types';
+} from './types.ts';
 import {
 	buildQueueHeaders,
 	QueueError,
-	QueueNotFoundError,
 	queueApiPath,
-	SourceAlreadyExistsError,
-	SourceNotFoundError,
-} from './util';
-import { validateQueueName, validateSourceId, validateSourceName } from './validation';
+	withQueueErrorHandling,
+} from './util.ts';
+import { validateQueueName, validateSourceId, validateSourceName } from './validation.ts';
 
 export const SourceResponseSchema = APIResponseSchema(z.object({ source: SourceSchema }));
 export const SourcesListResponseSchema = APIResponseSchema(
@@ -64,63 +62,27 @@ export async function createSource(
 	validateSourceName(params.name);
 
 	const url = queueApiPath('sources/create', queueName);
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.post(
+				url,
+				params,
+				SourceResponseSchema,
+				CreateSourceRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceName: params.name }
+	);
 
-	try {
-		const resp = await client.post(
-			url,
-			params,
-			SourceResponseSchema,
-			CreateSourceRequestSchema,
-			undefined,
-			buildQueueHeaders(options?.orgId)
-		);
-
-		if (resp.success) {
-			return resp.data.source;
-		}
-
-		if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
-			throw new QueueNotFoundError({
-				queueName,
-				message: resp.message,
-			});
-		}
-
-		if (resp.message?.includes('already exists')) {
-			throw new SourceAlreadyExistsError({
-				queueName,
-				name: params.name,
-				message: `A source with name "${params.name}" already exists for queue "${queueName}"`,
-			});
-		}
-
-		throw new QueueError({
-			queueName,
-			message: resp.message || 'Failed to create source',
-		});
-	} catch (error) {
-		if (error instanceof APIError) {
-			const message = error.message || '';
-			if (message.includes('already exists')) {
-				throw new SourceAlreadyExistsError({
-					queueName,
-					name: params.name,
-					message: `A source with name "${params.name}" already exists for queue "${queueName}"`,
-				});
-			}
-			if (message.includes('queue') && message.includes('not found')) {
-				throw new QueueNotFoundError({
-					queueName,
-					message,
-				});
-			}
-			throw new QueueError({
-				queueName,
-				message: message || 'Failed to create source',
-			});
-		}
-		throw error;
+	if (resp.success) {
+		return resp.data.source;
 	}
+
+	throw new QueueError({
+		queueName,
+		message: resp.message || 'Failed to create source',
+	});
 }
 
 /**
@@ -153,24 +115,16 @@ export async function listSources(
 ): Promise<Source[]> {
 	validateQueueName(queueName);
 	const url = queueApiPath('sources/list', queueName);
-	const resp = await client.get(
-		url,
-		SourcesListResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.get(url, SourcesListResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName }
 	);
 
 	if (resp.success) {
 		return resp.data.sources;
 	}
 
-	if (resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName,
 		message: resp.message || 'Failed to list sources',
@@ -210,32 +164,15 @@ export async function getSource(
 	validateSourceId(sourceId);
 
 	const url = queueApiPath('sources/get', queueName, sourceId);
-	const resp = await client.get(
-		url,
-		SourceResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() => client.get(url, SourceResponseSchema, undefined, buildQueueHeaders(options?.orgId)),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return resp.data.source;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			message: resp.message,
-		});
-	}
-
-	if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName,
 		message: resp.message || 'Failed to get source',
@@ -286,34 +223,23 @@ export async function updateSource(
 	}
 
 	const url = queueApiPath('sources/update', queueName, sourceId);
-	const resp = await client.patch(
-		url,
-		params,
-		SourceResponseSchema,
-		UpdateSourceRequestSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.patch(
+				url,
+				params,
+				SourceResponseSchema,
+				UpdateSourceRequestSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return resp.data.source;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			message: resp.message,
-		});
-	}
-
-	if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName,
 		message: resp.message || 'Failed to update source',
@@ -351,32 +277,21 @@ export async function deleteSource(
 	validateSourceId(sourceId);
 
 	const url = queueApiPath('sources/delete', queueName, sourceId);
-	const resp = await client.delete(
-		url,
-		DeleteSourceResponseSchema,
-		undefined,
-		buildQueueHeaders(options?.orgId)
+	const resp = await withQueueErrorHandling(
+		() =>
+			client.delete(
+				url,
+				DeleteSourceResponseSchema,
+				undefined,
+				buildQueueHeaders(options?.orgId)
+			),
+		{ queueName, sourceId }
 	);
 
 	if (resp.success) {
 		return;
 	}
 
-	if (resp.message?.includes('source') && resp.message?.includes('not found')) {
-		throw new SourceNotFoundError({
-			queueName,
-			sourceId,
-			message: resp.message,
-		});
-	}
-
-	if (resp.message?.includes('queue') && resp.message?.includes('not found')) {
-		throw new QueueNotFoundError({
-			queueName,
-			message: resp.message,
-		});
-	}
-
 	throw new QueueError({
 		queueName,
 		message: resp.message || 'Failed to delete source',

package/src/api/queue/util.ts

@@ -1,4 +1,5 @@
 import { StructuredError } from '@agentuity/core';
+import { APIError } from '../api.ts';
 
 /**
  * General queue operation error.
@@ -202,3 +203,76 @@ export function buildQueueHeaders(orgId?: string): Record<string, string> | unde
 	}
 	return undefined;
 }
+
+/**
+ * Wraps an API call and translates APIError with HTTP status codes to domain-specific queue errors.
+ *
+ * - 404 → QueueNotFoundError / MessageNotFoundError / DestinationNotFoundError / SourceNotFoundError
+ * - 409 with "already exists" → DestinationAlreadyExistsError / SourceAlreadyExistsError
+ *
+ * @internal
+ */
+export async function withQueueErrorHandling<T>(
+	apiCall: () => Promise<T>,
+	context: {
+		queueName?: string;
+		messageId?: string;
+		destinationId?: string;
+		sourceId?: string;
+		sourceName?: string;
+		destinationUrl?: string;
+	}
+): Promise<T> {
+	try {
+		return await apiCall();
+	} catch (error) {
+		if (error instanceof APIError) {
+			if (error.status === 404) {
+				if (context.messageId && context.queueName) {
+					throw new MessageNotFoundError({
+						queueName: context.queueName,
+						messageId: context.messageId,
+						message: error.message,
+					});
+				}
+				if (context.destinationId && context.queueName) {
+					throw new DestinationNotFoundError({
+						queueName: context.queueName,
+						destinationId: context.destinationId,
+						message: error.message,
+					});
+				}
+				if (context.sourceId && context.queueName) {
+					throw new SourceNotFoundError({
+						queueName: context.queueName,
+						sourceId: context.sourceId,
+						message: error.message,
+					});
+				}
+				if (context.queueName) {
+					throw new QueueNotFoundError({
+						queueName: context.queueName,
+						message: error.message,
+					});
+				}
+			}
+			if (error.status === 409) {
+				if (context.destinationUrl && context.queueName) {
+					throw new DestinationAlreadyExistsError({
+						queueName: context.queueName,
+						url: context.destinationUrl,
+						message: error.message,
+					});
+				}
+				if (context.sourceName && context.queueName) {
+					throw new SourceAlreadyExistsError({
+						queueName: context.queueName,
+						name: context.sourceName,
+						message: error.message,
+					});
+				}
+			}
+		}
+		throw error;
+	}
+}

package/src/api/queue/websocket.ts

@@ -41,10 +41,10 @@
  * ```
  */
 
-import type { Message } from './types';
-import { WebSocketAuthResponseSchema, WebSocketMessageSchema } from './types';
-import { QueueError } from './util';
-import { validateQueueName } from './validation';
+import type { Message } from './types.ts';
+import { WebSocketAuthResponseSchema, WebSocketMessageSchema } from './types.ts';
+import { QueueError } from './util.ts';
+import { validateQueueName } from './validation.ts';
 
 // ============================================================================
 // Types

package/src/api/region/create.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 /**
  * Database name validation regex - must match catalyst server validation:

package/src/api/region/delete.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const DeleteResourceSpec = z.object({
 	type: z.enum(['db', 's3']).describe('the resource type'),

package/src/api/region/index.ts

@@ -1,4 +1,4 @@
-export * from './list';
-export * from './resources';
-export * from './create';
-export * from './delete';
+export * from './list.ts';
+export * from './resources.ts';
+export * from './create.ts';
+export * from './delete.ts';

package/src/api/region/list.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const ListRegionsResponse = z.array(
 	z.object({

package/src/api/region/resources.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIResponseSchema, APIClient } from '../api';
-import { RegionResponseError } from './util';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { RegionResponseError } from './util.ts';
 
 export const ResourceListResponse = z.object({
 	s3: z.array(

package/src/api/sandbox/cli-list.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { SandboxResponseError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { SandboxResponseError } from './util.ts';
 
 export const SandboxInfoSchema = z.object({
 	id: z.string().describe('the sandbox id'),
@@ -45,7 +45,7 @@ export interface CLISandboxListOptions {
 	/**
 	 * Filter by sandbox status
 	 */
-	status?: 'creating' | 'idle' | 'running' | 'terminated' | 'failed';
+	status?: 'creating' | 'idle' | 'running' | 'paused' | 'stopping' | 'suspended' | 'terminated' | 'failed';
 	/**
 	 * Maximum number of sandboxes to return (default: 50, max: 100)
 	 */

package/src/api/sandbox/client.ts

@@ -9,17 +9,17 @@ import type {
 	SandboxRunResult,
 } from '@agentuity/core';
 import type { Readable, Writable } from 'node:stream';
-import { APIClient } from '../api';
-import { sandboxCreate, type SandboxCreateResponse } from './create';
-import { sandboxDestroy } from './destroy';
-import { sandboxGet } from './get';
-import { sandboxExecute } from './execute';
-import { sandboxWriteFiles, sandboxReadFile } from './files';
-import { sandboxRun } from './run';
-import { executionGet, type ExecutionInfo } from './execution';
-import { ConsoleLogger } from '../../logger';
-import { getServiceUrls } from '../../config';
-import { writeAndDrain } from './util';
+import { APIClient } from '../api.ts';
+import { sandboxCreate, type SandboxCreateResponse } from './create.ts';
+import { sandboxDestroy } from './destroy.ts';
+import { sandboxGet } from './get.ts';
+import { sandboxExecute } from './execute.ts';
+import { sandboxWriteFiles, sandboxReadFile } from './files.ts';
+import { sandboxRun } from './run.ts';
+import { executionGet, type ExecutionInfo } from './execution.ts';
+import { ConsoleLogger } from '../../logger.ts';
+import { getServiceUrls } from '../../config.ts';
+import { writeAndDrain } from './util.ts';
 
 // Server-side long-poll wait duration (max 5 minutes supported by server)
 const EXECUTION_WAIT_DURATION = '5m';

package/src/api/sandbox/create.ts

@@ -1,8 +1,8 @@
 import type { SandboxCreateOptions, SandboxStatus } from '@agentuity/core';
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { NPM_PACKAGE_NAME_PATTERN } from './snapshot-build';
-import { API_VERSION, throwSandboxError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { NPM_PACKAGE_NAME_PATTERN } from './snapshot-build.ts';
+import { API_VERSION, throwSandboxError } from './util.ts';
 
 export const SandboxCreateRequestSchema = z
 	.object({
@@ -122,7 +122,7 @@ export const SandboxCreateDataSchema = z
 	.object({
 		sandboxId: z.string().describe('Unique identifier for the created sandbox'),
 		status: z
-			.enum(['creating', 'idle', 'running', 'terminated', 'failed'])
+			.enum(['creating', 'idle', 'running', 'paused', 'stopping', 'suspended', 'terminated', 'failed'])
 			.describe('Current status of the sandbox'),
 		stdoutStreamId: z.string().optional().describe('Stream ID for reading stdout'),
 		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),

package/src/api/sandbox/destroy.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
-import { type APIClient, APIResponseSchemaNoData } from '../api';
-import { API_VERSION, throwSandboxError } from './util';
+import { type APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { API_VERSION, throwSandboxError } from './util.ts';
 
 export const DestroyResponseSchema = APIResponseSchemaNoData();
 

package/src/api/sandbox/execute.ts

@@ -1,7 +1,7 @@
 import type { ExecuteOptions, Execution, ExecutionStatus } from '@agentuity/core';
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { API_VERSION, SandboxBusyError, throwSandboxError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { API_VERSION, SandboxBusyError, throwSandboxError } from './util.ts';
 
 export const ExecuteRequestSchema = z
 	.object({

package/src/api/sandbox/execution.ts

@@ -1,7 +1,7 @@
 import type { ExecutionStatus } from '@agentuity/core';
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { API_VERSION, throwSandboxError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { API_VERSION, throwSandboxError } from './util.ts';
 
 export const ExecutionInfoSchema = z
 	.object({

package/src/api/sandbox/files.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { APIClient } from '../api';
-import { SandboxResponseError, throwSandboxError, API_VERSION } from './util';
+import { APIClient } from '../api.ts';
+import { SandboxResponseError, throwSandboxError, API_VERSION } from './util.ts';
 import type { FileToWrite } from '@agentuity/core';
 
 export const FileToWriteSchema = z.object({

package/src/api/sandbox/get.ts

@@ -5,8 +5,8 @@ import type {
 	SandboxStatus,
 } from '@agentuity/core';
 import { z } from 'zod';
-import { type APIClient, APIResponseSchema } from '../api';
-import { API_VERSION, throwSandboxError } from './util';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { API_VERSION, throwSandboxError } from './util.ts';
 
 export const SandboxResourcesSchema = z
 	.object({
@@ -105,7 +105,7 @@ export const SandboxInfoDataSchema = z
 		name: z.string().optional().describe('Sandbox name'),
 		description: z.string().optional().describe('Sandbox description'),
 		status: z
-			.enum(['creating', 'idle', 'running', 'terminated', 'failed', 'deleted'])
+			.enum(['creating', 'idle', 'running', 'paused', 'stopping', 'suspended', 'terminated', 'failed', 'deleted'])
 			.describe('Current status of the sandbox'),
 		mode: z.string().optional().describe('Sandbox mode (interactive or oneshot)'),
 		createdAt: z.string().describe('ISO timestamp when the sandbox was created'),