@agentuity/server 1.0.17 → 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'),

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({

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({

package/src/api/sandbox/index.ts

@@ -1,34 +1,38 @@
-export type { CLISandboxInfo, CLISandboxListData, CLISandboxListOptions } from './cli-list';
-export { cliSandboxList, SandboxListDataSchema, SandboxListResponseSchema } from './cli-list';
+export type { CLISandboxInfo, CLISandboxListData, CLISandboxListOptions } from './cli-list.ts';
+export { cliSandboxList, SandboxListDataSchema, SandboxListResponseSchema } from './cli-list.ts';
 export type {
 	ExecuteOptions,
 	SandboxClientOptions,
 	SandboxClientRunIO,
 	SandboxInstance,
-} from './client';
-export { SandboxClient } from './client';
-export type { SandboxCreateParams, SandboxCreateResponse } from './create';
+} from './client.ts';
+export { SandboxClient } from './client.ts';
+export type { SandboxCreateParams, SandboxCreateResponse } from './create.ts';
 export {
 	SandboxCreateDataSchema,
 	SandboxCreateRequestSchema,
 	SandboxCreateResponseSchema,
 	sandboxCreate,
-} from './create';
-export type { SandboxDestroyParams } from './destroy';
-export { DestroyResponseSchema, sandboxDestroy } from './destroy';
-export type { SandboxExecuteParams } from './execute';
+} from './create.ts';
+export type { SandboxDestroyParams } from './destroy.ts';
+export { DestroyResponseSchema, sandboxDestroy } from './destroy.ts';
+export type { SandboxPauseParams } from './pause.ts';
+export { PauseResponseSchema, sandboxPause } from './pause.ts';
+export type { SandboxResumeParams } from './resume.ts';
+export { ResumeResponseSchema, sandboxResume } from './resume.ts';
+export type { SandboxExecuteParams } from './execute.ts';
 export {
 	ExecuteDataSchema,
 	ExecuteRequestSchema,
 	ExecuteResponseSchema,
 	sandboxExecute,
-} from './execute';
+} from './execute.ts';
 export type {
 	ExecutionGetParams,
 	ExecutionInfo,
 	ExecutionListParams,
 	ExecutionListResponse,
-} from './execution';
+} from './execution.ts';
 export {
 	ExecutionGetResponseSchema,
 	ExecutionInfoSchema,
@@ -36,7 +40,7 @@ export {
 	ExecutionListResponseSchema,
 	executionGet,
 	executionList,
-} from './execution';
+} from './execution.ts';
 export type {
 	ArchiveFormat,
 	DownloadArchiveParams,
@@ -52,7 +56,7 @@ export type {
 	UploadArchiveParams,
 	WriteFilesParams,
 	WriteFilesResult,
-} from './files';
+} from './files.ts';
 export {
 	FileInfoSchema,
 	FileToWriteSchema,
@@ -80,8 +84,8 @@ export {
 	WriteFilesDataSchema,
 	WriteFilesRequestSchema,
 	WriteFilesResponseSchema,
-} from './files';
-export type { SandboxGetParams } from './get';
+} from './files.ts';
+export type { SandboxGetParams } from './get.ts';
 export {
 	SandboxAgentInfoSchema,
 	SandboxGetResponseSchema,
@@ -90,8 +94,8 @@ export {
 	SandboxResourcesSchema,
 	SandboxUserInfoSchema,
 	sandboxGet,
-} from './get';
-export type { SandboxListParams } from './list';
+} from './get.ts';
+export type { SandboxListParams } from './list.ts';
 export {
 	ListSandboxesDataSchema,
 	ListSandboxesResponseSchema,
@@ -102,24 +106,24 @@ export {
 	SandboxSnapshotOrgInfoSchema,
 	SandboxSnapshotUserInfoSchema,
 	sandboxList,
-} from './list';
-export type { ResolvedSandboxInfo } from './resolve';
+} from './list.ts';
+export type { ResolvedSandboxInfo } from './resolve.ts';
 export {
 	SandboxResolveDataSchema,
 	SandboxResolveError,
 	SandboxResolveResponseSchema,
 	sandboxResolve,
-} from './resolve';
-export type { SandboxRunParams } from './run';
-export { sandboxRun } from './run';
-export type { RuntimeListParams } from './runtime';
+} from './resolve.ts';
+export type { SandboxRunParams } from './run.ts';
+export { sandboxRun } from './run.ts';
+export type { RuntimeListParams } from './runtime.ts';
 export {
 	ListRuntimesDataSchema,
 	ListRuntimesResponseSchema,
 	RuntimeInfoSchema,
 	RuntimeRequirementsSchema,
 	runtimeList,
-} from './runtime';
+} from './runtime.ts';
 export type {
 	SnapshotBuildFinalizeParams,
 	SnapshotBuildGitInfo,
@@ -140,7 +144,7 @@ export type {
 	SnapshotTagParams,
 	SnapshotUploadParams,
 	SnapshotUploadResponse,
-} from './snapshot';
+} from './snapshot.ts';
 export {
 	SnapshotBuildGitInfoSchema,
 	SnapshotBuildInitAPIResponseSchema,
@@ -169,10 +173,10 @@ export {
 	snapshotPublicList,
 	snapshotTag,
 	snapshotUpload,
-} from './snapshot';
-export type { SnapshotBuildFile } from './snapshot-build';
-export { SnapshotBuildFileSchema, NPM_PACKAGE_NAME_PATTERN } from './snapshot-build';
-export type { SandboxErrorCode, SandboxErrorContext } from './util';
+} from './snapshot.ts';
+export type { SnapshotBuildFile } from './snapshot-build.ts';
+export { SnapshotBuildFileSchema, NPM_PACKAGE_NAME_PATTERN } from './snapshot-build.ts';
+export type { SandboxErrorCode, SandboxErrorContext } from './util.ts';
 export {
 	ExecutionCancelledError,
 	ExecutionNotFoundError,
@@ -184,4 +188,4 @@ export {
 	SnapshotNotFoundError,
 	throwSandboxError,
 	writeAndDrain,
-} from './util';
+} from './util.ts';

package/src/api/sandbox/list.ts

@@ -6,8 +6,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 SandboxOrgInfoSchema = z
 	.object({