@agentuity/server 0.0.60 → 0.0.61

package/src/api/api.ts

@@ -10,17 +10,7 @@
 
 import { z } from 'zod';
 import type { Logger } from '@agentuity/core';
-
-export interface APIErrorResponse {
-	success: boolean;
-	code?: string;
-	message?: string;
-	error?: {
-		name?: string;
-		issues?: z.ZodIssue[];
-	};
-	details?: Record<string, unknown>;
-}
+import { StructuredError } from '@agentuity/core';
 
 export interface APIClientConfig {
 	skipVersionCheck?: boolean;
@@ -29,36 +19,75 @@ export interface APIClientConfig {
 	retryDelayMs?: number;
 }
 
-export class ValidationError extends Error {
-	public url: string;
-	constructor(
-		url: string,
-		message: string,
-		public issues: z.ZodIssue[]
-	) {
-		super(message);
-		this.url = url;
-		this.name = 'ValidationError';
-	}
-}
-
-export class UpgradeRequiredError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'UpgradeRequiredError';
-	}
-}
-
-export class APIError extends Error {
-	constructor(
-		message: string,
-		public status: number,
-		public code?: string
-	) {
-		super(message);
-		this.name = 'APIError';
-	}
-}
+const ZodIssuesSchema = z.array(
+	z.object({
+		code: z.string(),
+		input: z.unknown().optional(),
+		path: z.array(z.union([z.string(), z.number()])),
+		message: z.string(),
+	})
+);
+
+export type IssuesType = z.infer<typeof ZodIssuesSchema>;
+
+const toIssues = (issues: z.core.$ZodIssue[]): IssuesType => {
+	return issues.map((issue) => ({
+		code: issue.code,
+		input: issue.input,
+		path: issue.path.map((x) => (typeof x === 'number' ? x : String(x))),
+		message: issue.message,
+	}));
+};
+
+const APIErrorSchema = z.object({
+	success: z.boolean(),
+	code: z.string().optional(),
+	message: z.string().optional(),
+	error: z.object({
+		name: z.string().optional(),
+		issues: ZodIssuesSchema.optional(),
+	}),
+	details: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const APIError = StructuredError(
+	'APIErrorResponse',
+	'The API encountered an unexpected error attempting to reach the service.'
+)<{
+	url: string;
+	error?: string;
+	status: number;
+	sessionId?: string | null;
+}>();
+
+export const ValidationInputError = StructuredError(
+	'ValidationInputError',
+	'There was an error validating the API input data.'
+)<{
+	url: string;
+	issues: IssuesType;
+}>();
+
+export const ValidationOutputError = StructuredError(
+	'ValidationOutputError',
+	'There was an unexpected error validating the API response data.'
+)<{
+	url: string;
+	issues: IssuesType;
+	sessionId?: string | null;
+}>();
+
+export const UpgradeRequiredError = StructuredError(
+	'UpgradeRequiredError',
+	'Upgrade required to continue. Please see https://agentuity.dev/CLI/installation to download the latest version of the SDK.'
+)<{
+	sessionId?: string | null;
+}>();
+
+export const MaxRetriesError = StructuredError(
+	'MaxRetriesError',
+	'Max Retries attempted and continued failures exhausted.'
+);
 
 export class APIClient {
 	#baseUrl: string;
@@ -101,11 +130,10 @@ export class APIClient {
 		if (body !== undefined && bodySchema) {
 			const validationResult = bodySchema.safeParse(body);
 			if (!validationResult.success) {
-				throw new ValidationError(
-					endpoint,
-					'Request body validation failed',
-					validationResult.error.issues
-				);
+				throw new ValidationInputError({
+					url: endpoint,
+					issues: toIssues(validationResult.error.issues),
+				});
 			}
 		}
 
@@ -133,11 +161,11 @@ export class APIClient {
 			// Validate response
 			const validationResult = responseSchema.safeParse(data);
 			if (!validationResult.success) {
-				throw new ValidationError(
-					endpoint,
-					'Response validation failed',
-					validationResult.error.issues
-				);
+				throw new ValidationOutputError({
+					url: endpoint,
+					issues: toIssues(validationResult.error.issues),
+					sessionId: response.headers.get('x-session-id'),
+				});
 			}
 
 			return validationResult.data;
@@ -167,17 +195,35 @@ export class APIClient {
 					headers['Authorization'] = `Bearer ${this.#apiKey}`;
 				}
 
-				// Log request body for debugging deployment issues
-				if (body !== undefined && endpoint.includes('/deploy/')) {
-					this.#logger.debug('Request body: %s', JSON.stringify(body, null, 2));
+				let response: Response;
+
+				try {
+					response = await fetch(url, {
+						method,
+						headers,
+						body: body !== undefined ? JSON.stringify(body) : undefined,
+					});
+				} catch (ex) {
+					const _ex = ex as { code?: string; name: string };
+					let retryable = false;
+					// Check for retryable network errors
+					if (_ex.code === 'ConnectionRefused' || _ex.code === 'ECONNREFUSED') {
+						retryable = true;
+					} else if (_ex.name === 'TypeError' || ex instanceof TypeError) {
+						// TypeError from fetch typically indicates network issues
+						retryable = true;
+					}
+					if (retryable) {
+						response = new Response(null, { status: 503 });
+					} else {
+						throw new APIError({
+							url,
+							status: 0,
+							cause: ex,
+						});
+					}
 				}
 
-				const response = await fetch(url, {
-					method,
-					headers,
-					body: body !== undefined ? JSON.stringify(body) : undefined,
-				});
-
 				// Check if we should retry on specific status codes (409, 501, 503)
 				const retryableStatuses = [409, 501, 503];
 				if (retryableStatuses.includes(response.status) && attempt < maxRetries) {
@@ -206,16 +252,18 @@ export class APIClient {
 					continue;
 				}
 
+				const sessionId = response.headers.get('x-session-id');
+
 				// Handle error responses
 				if (!response.ok) {
 					const responseBody = await response.text();
 
-					// Try to parse error response
-					let errorData: APIErrorResponse | null = null;
+					let errorData: z.infer<typeof APIErrorSchema> | undefined;
+
 					try {
-						errorData = JSON.parse(responseBody) as APIErrorResponse;
+						errorData = APIErrorSchema.parse(responseBody);
 					} catch {
-						// Not JSON, ignore
+						/** ignore */
 					}
 
 					// Sanitize headers to avoid leaking API keys
@@ -240,31 +288,32 @@ export class APIClient {
 							this.#logger.debug('Skipping version check (configured to skip)');
 							// Request is still rejected, but throw UpgradeRequiredError so callers
 							// can detect it and handle UI behavior (e.g., suppress banner) based on skip flag
-							throw new UpgradeRequiredError(
-								errorData.message ||
-									'Version check skipped, but request failed. Try upgrading the client.'
-							);
+							throw new UpgradeRequiredError({ sessionId });
 						}
 
-						throw new UpgradeRequiredError(
-							errorData.message || 'Please upgrade to the latest version'
-						);
+						throw new UpgradeRequiredError({ sessionId });
 					}
 
 					// Handle Zod validation errors from the API
 					if (errorData?.error?.name === 'ZodError' && errorData.error.issues) {
-						throw new ValidationError(url, 'API validation failed', errorData.error.issues);
+						throw new ValidationOutputError({
+							url,
+							issues: errorData.error.issues,
+							sessionId,
+						});
 					}
 
 					// Throw with message from API if available
 					if (errorData?.message) {
-						throw new APIError(errorData.message, response.status, errorData.code);
+						throw new APIError({
+							url,
+							status: response.status,
+							error: errorData.message,
+							sessionId,
+						});
 					}
 
-					throw new APIError(
-						`API error: ${response.status} ${response.statusText}`,
-						response.status
-					);
+					throw new APIError({ url: url, status: response.status, sessionId });
 				}
 
 				// Successful response; handle empty bodies (e.g., 204 No Content)
@@ -290,7 +339,7 @@ export class APIClient {
 			}
 		}
 
-		throw new Error('Max retries exceeded');
+		throw new MaxRetriesError();
 	}
 
 	#isRetryableError(error: unknown): boolean {

package/src/api/apikey/create.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { APIKeyResponseError } from './util';
 
 const APIKeyCreateResponseSchema = z.object({
 	id: z.string().describe('the API key id'),
@@ -41,5 +42,5 @@ export async function apikeyCreate(
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new APIKeyResponseError({ message: resp.message });
 }

package/src/api/apikey/delete.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { APIKeyResponseError } from './util';
 
 const APIKeyDeleteResponseSchema = APIResponseSchema(
 	z.number().describe('number of rows affected')
@@ -25,5 +26,5 @@ export async function apikeyDelete(client: APIClient, id: string): Promise<numbe
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new APIKeyResponseError({ message: resp.message });
 }

package/src/api/apikey/get.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { APIKeyResponseError } from './util';
 
 const APIKeyDetailSchema = z.object({
 	id: z.string().describe('the API key id'),
@@ -43,5 +44,5 @@ export async function apikeyGet(client: APIClient, id: string): Promise<APIKeyDe
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new APIKeyResponseError({ message: resp.message });
 }

package/src/api/apikey/list.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { APIKeyResponseError } from './util';
 
 export const APIKeySchema = z.object({
 	id: z.string().describe('the API key id'),
@@ -59,5 +60,5 @@ export async function apikeyList(
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new APIKeyResponseError({ message: resp.message });
 }

package/src/api/apikey/util.ts

@@ -0,0 +1,3 @@
+import { StructuredError } from '@agentuity/core';
+
+export const APIKeyResponseError = StructuredError('APIKeyResponseError');

package/src/api/org/list.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
+import { OrgResponseError } from './util';
 
 const ListOrganizationsResponse = z.array(
 	z.object({
@@ -27,5 +28,5 @@ export async function listOrganizations(client: APIClient): Promise<Organization
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new OrgResponseError({ message: resp.message });
 }

package/src/api/org/util.ts

@@ -0,0 +1,3 @@
+import { StructuredError } from '@agentuity/core';
+
+export const OrgResponseError = StructuredError('OrgResponseError');

package/src/api/project/agent.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { APIClient } from '../api';
 import { APIResponseSchema } from '../api';
+import { AgentNotFoundError, ProjectResponseError } from './util';
 
 const AgentSchema = z.object({
 	id: z.string().describe('Agent ID (same as identifier)'),
@@ -54,7 +55,7 @@ export async function projectAgentList(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }
 
 /**
@@ -73,9 +74,9 @@ export async function projectAgentGet(
 
 	if (resp.success) {
 		if (resp.data.length === 0) {
-			throw new Error(`Agent not found: ${agentId}`);
+			throw new AgentNotFoundError({ id: agentId, message: `Agent not found: ${agentId}` });
 		}
 		return resp.data[0];
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/create.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
 
 const CreateProjectRequestSchema = z.object({
 	name: z.string().max(255).min(1).describe('the name of the new project'),
@@ -39,5 +40,5 @@ export async function projectCreate(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/delete.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
 
 const ProjectDeleteRequestSchema = z.object({ ids: z.array(z.string()) });
 const ProjectDeleteResponseSchema = APIResponseSchema(z.array(z.string()));
@@ -20,5 +21,5 @@ export async function projectDelete(client: APIClient, ...ids: string[]): Promis
 		return resp.data;
 	}
 
-	throw new Error(resp.message ?? 'failed to delete project');
+	throw new ProjectResponseError({ message: resp.message ?? 'failed to delete project' });
 }

package/src/api/project/deploy.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { type APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
 
 export const Resources = z.object({
 	memory: z.string().default('500Mi').describe('The memory requirements'),
@@ -177,7 +178,7 @@ export async function projectDeploymentCreate(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }
 
 const DeploymentInstructionsObject = z.object({
@@ -217,7 +218,7 @@ export async function projectDeploymentUpdate(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }
 
 const DeploymentCompleteObject = z.object({
@@ -254,5 +255,5 @@ export async function projectDeploymentComplete(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/deployment.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { type APIClient, APIResponseSchema, APIResponseSchemaOptionalData } from '../api';
+import { ProjectResponseError } from './util';
 
 // Simplified metadata schema for the client
 const DeploymentMetadataSchema = z.object({
@@ -69,7 +70,7 @@ export async function projectDeploymentList(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }
 
 export async function projectDeploymentGet(
@@ -85,7 +86,7 @@ export async function projectDeploymentGet(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }
 
 export async function projectDeploymentDelete(
@@ -99,7 +100,7 @@ export async function projectDeploymentDelete(
 		DeploymentActionResponseSchema
 	);
 	if (!resp.success) {
-		throw new Error(resp.message);
+		throw new ProjectResponseError({ message: resp.message });
 	}
 }
 
@@ -114,7 +115,7 @@ export async function projectDeploymentRollback(
 		DeploymentActionResponseSchema
 	);
 	if (!resp.success) {
-		throw new Error(resp.message);
+		throw new ProjectResponseError({ message: resp.message });
 	}
 }
 
@@ -128,7 +129,7 @@ export async function projectDeploymentUndeploy(
 		DeploymentActionResponseSchema
 	);
 	if (!resp.success) {
-		throw new Error(resp.message);
+		throw new ProjectResponseError({ message: resp.message });
 	}
 }
 
@@ -159,5 +160,5 @@ export async function projectDeploymentLogs(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/env-delete.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchemaNoData } from '../api';
+import { ProjectResponseError } from './util';
 
 const _ProjectEnvDeleteRequestSchema = z.object({
 	id: z.string().describe('the project id'),
@@ -33,7 +34,7 @@ export async function projectEnvDelete(
 	);
 
 	if (!resp.success) {
-		throw new Error(resp.message ?? 'failed to delete project env');
+		throw new ProjectResponseError({ message: resp.message ?? 'failed to delete project env' });
 	}
 
 	// Delete operations don't return data, success is sufficient

package/src/api/project/env-update.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
 import type { Project } from './get';
 import { projectGet } from './get';
+import { ProjectResponseError } from './util';
 
 const _ProjectEnvUpdateRequestSchema = z.object({
 	id: z.string().describe('the project id'),
@@ -46,7 +47,7 @@ export async function projectEnvUpdate(
 	);
 
 	if (!resp.success) {
-		throw new Error(resp.message ?? 'failed to update project env');
+		throw new ProjectResponseError({ message: resp.message ?? 'failed to update project env' });
 	}
 
 	if (resp.data) {

package/src/api/project/exists.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema, APIError } from '../api';
+import { ProjectResponseError } from './util';
 
 const _ProjectExistsRequestSchema = z.object({
 	name: z.string().max(255).min(1).describe('the name of the new project'),
@@ -42,16 +43,16 @@ export async function projectExists(
 		return false;
 	} catch (ex) {
 		const _ex = ex as Error;
-		if (_ex.name === 'APIError') {
-			const apiError = _ex as APIError;
-			switch (apiError.status) {
+		if (_ex instanceof APIError) {
+			switch (_ex.status) {
 				case 409:
 					return true;
 				case 422:
 					return false;
 				default:
+					break;
 			}
 		}
-		throw ex;
+		throw new ProjectResponseError({ cause: ex });
 	}
 }

package/src/api/project/get.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
 
 const _ProjectGetRequestSchema = z.object({
 	id: z.string().describe('the project id'),
@@ -32,5 +33,5 @@ export async function projectGet(client: APIClient, request: ProjectGetRequest):
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/list.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
 
 const ProjectListResponse = z.array(
 	z.object({
@@ -38,5 +39,5 @@ export async function projectList(
 		return resp.data;
 	}
 
-	throw new Error(resp.message);
+	throw new ProjectResponseError({ message: resp.message });
 }

package/src/api/project/util.ts

@@ -0,0 +1,5 @@
+import { StructuredError } from '@agentuity/core';
+
+export const ProjectResponseError = StructuredError('ProjectResponseError');
+export const ProjectNotFoundError = StructuredError('ProjectNotFoundError')<{ id: string }>();
+export const AgentNotFoundError = StructuredError('AgentNotFoundError')<{ id: string }>();

package/src/api/region/create.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
+import { RegionResponseError } from './util';
 
 const ResourceSpec = z.object({
 	type: z.enum(['db', 's3']).describe('the resource type'),
@@ -51,5 +52,7 @@ export async function createResources(
 	if (resp.success) {
 		return resp.data.created;
 	}
-	throw new Error('message' in resp ? resp.message : 'Failed to create resources');
+	throw new RegionResponseError({
+		message: resp.message,
+	});
 }

package/src/api/region/delete.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
+import { RegionResponseError } from './util';
 
 const DeleteResourceSpec = z.object({
 	type: z.enum(['db', 's3']).describe('the resource type'),
@@ -45,5 +46,5 @@ export async function deleteResources(
 	if (resp.success) {
 		return resp.data.deleted;
 	}
-	throw new Error('message' in resp ? resp.message : 'Failed to delete resources');
+	throw new RegionResponseError({ message: resp.message });
 }

package/src/api/region/list.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
+import { RegionResponseError } from './util';
 
 const ListRegionsResponse = z.array(
 	z.object({
@@ -27,5 +28,5 @@ export async function listRegions(client: APIClient): Promise<RegionList> {
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new RegionResponseError({ message: resp.message });
 }

package/src/api/region/resources.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { APIResponseSchema, APIClient } from '../api';
+import { RegionResponseError } from './util';
 
 const ResourceListResponse = z.object({
 	s3: z.array(
@@ -47,5 +48,5 @@ export async function listResources(
 	if (resp.success) {
 		return resp.data;
 	}
-	throw new Error(resp.message);
+	throw new RegionResponseError({ message: resp.message });
 }

package/src/api/region/util.ts

@@ -0,0 +1,3 @@
+import { StructuredError } from '@agentuity/core';
+
+export const RegionResponseError = StructuredError('RegionResponseError');