@agentuity/core 0.0.60 → 0.0.62

package/src/services/keyvalue.ts

@@ -1,5 +1,6 @@
 import { FetchAdapter } from './adapter';
 import { buildUrl, toServiceException, toPayload } from './_util';
+import { StructuredError } from '../error';
 
 /**
  * the result of a data operation when the data is found
@@ -159,6 +160,8 @@ export interface KeyValueStorage {
 	createNamespace(name: string): Promise<void>;
 }
 
+const KeyValueInvalidTTLError = StructuredError('KeyValueInvalidTTLError');
+
 export class KeyValueStorageService implements KeyValueStorage {
 	#adapter: FetchAdapter;
 	#baseUrl: string;
@@ -207,7 +210,9 @@ export class KeyValueStorageService implements KeyValueStorage {
 		let ttlstr = '';
 		if (params?.ttl) {
 			if (params.ttl < 60) {
-				throw new Error(`ttl for keyvalue set must be at least 60 seconds, got ${params.ttl}`);
+				throw new KeyValueInvalidTTLError({
+					message: `ttl for keyvalue set must be at least 60 seconds, got ${params.ttl}`,
+				});
 			}
 			ttlstr = `/${params.ttl}`;
 		}

package/src/services/objectstore.ts

@@ -1,5 +1,6 @@
 import type { FetchAdapter, FetchRequest, Body } from './adapter';
 import { buildUrl, toServiceException } from './_util';
+import { StructuredError } from '../error';
 
 /**
  * Parameters for putting an object into the object store
@@ -280,6 +281,26 @@ export interface ObjectStorage {
 	deleteBucket(bucket: string): Promise<boolean>;
 }
 
+const ObjectStoreBucketMissingError = StructuredError(
+	'ObjectStoreBucketMissingError',
+	'bucket is required and cannot be empty'
+);
+
+const ObjectStoreKeyMissingError = StructuredError(
+	'ObjectStoreKeyMissingError',
+	'key is required and cannot be empty'
+);
+
+const ObjectStoreDataMissingError = StructuredError(
+	'ObjectStoreDataMissingError',
+	'data is required'
+);
+
+const ObjectStoreResponseError = StructuredError('ObjectStoreResponseError')<{ status: number }>();
+const ObjectStoreResponseInvalidError = StructuredError('ObjectStoreResponseInvalidError');
+
+const ObjectStoreNotFoundError = StructuredError('ObjectStoreNotFoundError', 'object not found');
+
 /**
  * Implementation of the ObjectStorage interface
  */
@@ -294,10 +315,10 @@ export class ObjectStorageService implements ObjectStorage {
 
 	async get(bucket: string, key: string): Promise<ObjectResult> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 		if (!key?.trim()) {
-			throw new Error('key is required and cannot be empty');
+			throw new ObjectStoreKeyMissingError();
 		}
 
 		const url = buildUrl(
@@ -326,14 +347,17 @@ export class ObjectStorageService implements ObjectStorage {
 			}
 
 			if (!result.ok) {
-				throw new Error(
-					`Failed to get object: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to get object: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			const data = result.data;
 			if (!(data instanceof ArrayBuffer)) {
-				throw new Error('Expected ArrayBuffer response from object store');
+				throw new ObjectStoreResponseInvalidError({
+					message: 'Expected ArrayBuffer response from object store',
+				});
 			}
 
 			const contentType =
@@ -359,13 +383,13 @@ export class ObjectStorageService implements ObjectStorage {
 		params?: ObjectStorePutParams
 	): Promise<void> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 		if (!key?.trim()) {
-			throw new Error('key is required and cannot be empty');
+			throw new ObjectStoreKeyMissingError();
 		}
 		if (!data) {
-			throw new Error('data is required');
+			throw new ObjectStoreDataMissingError();
 		}
 
 		const url = buildUrl(
@@ -435,9 +459,10 @@ export class ObjectStorageService implements ObjectStorage {
 			const result = await this.#adapter.invoke(url, options);
 
 			if (!result.ok || (result.response.status !== 200 && result.response.status !== 201)) {
-				throw new Error(
-					`Failed to put object: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to put object: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 		} catch (err) {
 			if (err instanceof Response) {
@@ -449,10 +474,10 @@ export class ObjectStorageService implements ObjectStorage {
 
 	async delete(bucket: string, key: string): Promise<boolean> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 		if (!key?.trim()) {
-			throw new Error('key is required and cannot be empty');
+			throw new ObjectStoreKeyMissingError();
 		}
 
 		const url = buildUrl(
@@ -484,9 +509,10 @@ export class ObjectStorageService implements ObjectStorage {
 				return true;
 			}
 
-			throw new Error(
-				`Failed to delete object: ${result.response.statusText} (${result.response.status})`
-			);
+			throw new ObjectStoreResponseError({
+				status: result.response.status,
+				message: `Failed to delete object: ${result.response.statusText} (${result.response.status})`,
+			});
 		} catch (err) {
 			if (err instanceof Response) {
 				throw await toServiceException('DELETE', url, err);
@@ -501,10 +527,10 @@ export class ObjectStorageService implements ObjectStorage {
 		params?: CreatePublicURLParams
 	): Promise<string> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 		if (!key?.trim()) {
-			throw new Error('key is required and cannot be empty');
+			throw new ObjectStoreKeyMissingError();
 		}
 
 		const url = buildUrl(
@@ -540,15 +566,19 @@ export class ObjectStorageService implements ObjectStorage {
 			);
 
 			if (!result.ok) {
-				throw new Error(
-					`Failed to create public URL: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to create public URL: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			const data = result.data;
 
 			if (!data.success) {
-				throw new Error(data.message || 'Failed to create public URL');
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: data.message || 'Failed to create public URL',
+				});
 			}
 
 			return data.url;
@@ -580,9 +610,10 @@ export class ObjectStorageService implements ObjectStorage {
 			const result = await this.#adapter.invoke<{ buckets: BucketInfo[] }>(url, options);
 
 			if (!result.ok) {
-				throw new Error(
-					`Failed to list buckets: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to list buckets: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			return result.data.buckets;
@@ -596,7 +627,7 @@ export class ObjectStorageService implements ObjectStorage {
 
 	async listKeys(bucket: string): Promise<ObjectInfo[]> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 
 		const url = buildUrl(this.#baseUrl, `/object/2025-03-17/keys/${encodeURIComponent(bucket)}`);
@@ -620,9 +651,10 @@ export class ObjectStorageService implements ObjectStorage {
 			);
 
 			if (!result.ok) {
-				throw new Error(
-					`Failed to list keys: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to list keys: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			return result.data.objects;
@@ -639,7 +671,7 @@ export class ObjectStorageService implements ObjectStorage {
 		options?: { prefix?: string; limit?: number }
 	): Promise<ObjectInfo[]> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 
 		const params = new URLSearchParams();
@@ -677,9 +709,10 @@ export class ObjectStorageService implements ObjectStorage {
 			);
 
 			if (!result.ok) {
-				throw new Error(
-					`Failed to list objects: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to list objects: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			return result.data.objects;
@@ -693,10 +726,10 @@ export class ObjectStorageService implements ObjectStorage {
 
 	async headObject(bucket: string, key: string): Promise<ObjectInfo> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 		if (!key?.trim()) {
-			throw new Error('key is required and cannot be empty');
+			throw new ObjectStoreKeyMissingError();
 		}
 
 		const url = buildUrl(
@@ -722,11 +755,12 @@ export class ObjectStorageService implements ObjectStorage {
 
 			if (!result.ok) {
 				if (result.response.status === 404) {
-					throw new Error('Object not found');
+					throw new ObjectStoreNotFoundError();
 				}
-				throw new Error(
-					`Failed to get object metadata: ${result.response.statusText} (${result.response.status})`
-				);
+				throw new ObjectStoreResponseError({
+					status: result.response.status,
+					message: `Failed to get object metadata: ${result.response.statusText} (${result.response.status})`,
+				});
 			}
 
 			return result.data;
@@ -740,7 +774,7 @@ export class ObjectStorageService implements ObjectStorage {
 
 	async deleteBucket(bucket: string): Promise<boolean> {
 		if (!bucket?.trim()) {
-			throw new Error('bucket is required and cannot be empty');
+			throw new ObjectStoreBucketMissingError();
 		}
 
 		const url = buildUrl(this.#baseUrl, `/object/2025-03-17/${encodeURIComponent(bucket)}`);
@@ -768,9 +802,10 @@ export class ObjectStorageService implements ObjectStorage {
 				return true;
 			}
 
-			throw new Error(
-				`Failed to delete bucket: ${result.response.statusText} (${result.response.status})`
-			);
+			throw new ObjectStoreResponseError({
+				status: result.response.status,
+				message: `Failed to delete bucket: ${result.response.statusText} (${result.response.status})`,
+			});
 		} catch (err) {
 			if (err instanceof Response) {
 				throw await toServiceException('DELETE', url, err);

package/src/services/session.ts

@@ -29,6 +29,7 @@ export const SessionCompleteEventSchema = z
 			.optional()
 			.describe('optional array of ids for the agents that executed for the session'),
 		statusCode: z.number().describe('the HTTP status code'),
+		userData: z.string().optional().describe('optional JSON string of session state data'),
 	})
 	.describe('The event to record a session completed successfully');
 

package/src/services/stream.ts

@@ -1,6 +1,7 @@
 import { safeStringify } from '../json';
 import { FetchAdapter, FetchResponse } from './adapter';
 import { buildUrl, toServiceException } from './_util';
+import { StructuredError } from '../error';
 
 /**
  * Properties for creating a stream
@@ -262,6 +263,8 @@ export interface StreamStorage {
 
 const encoder = new TextEncoder();
 
+const ReadStreamFailedError = StructuredError('ReadStreamFailedError')<{ status: number }>();
+
 /**
  * A writable stream implementation that extends WritableStream
  */
@@ -384,13 +387,21 @@ class StreamImpl extends WritableStream implements Stream {
 
 					if (!res.ok) {
 						controller.error(
-							new Error(`Failed to read stream: ${response.status} ${response.statusText}`)
+							new ReadStreamFailedError({
+								status: response.status,
+								message: `Failed to read stream: ${response.status} ${response.statusText}`,
+							})
 						);
 						return;
 					}
 
 					if (!response.body) {
-						controller.error(new Error('Response body is null'));
+						controller.error(
+							new ReadStreamFailedError({
+								status: response.status,
+								message: 'Response body was null',
+							})
+						);
 						return;
 					}
 
@@ -420,6 +431,13 @@ class StreamImpl extends WritableStream implements Stream {
 	}
 }
 
+const StreamWriterInitializationError = StructuredError(
+	'StreamWriterInitializationError',
+	'Stream writer is not initialized'
+);
+
+const StreamAPIError = StructuredError('StreamAPIError')<{ status: number }>();
+
 // Create a WritableStream that writes to the backend stream
 // Create the underlying sink that will handle the actual streaming
 class UnderlyingSink {
@@ -498,7 +516,7 @@ class UnderlyingSink {
 
 	async write(chunk: string | Uint8Array | ArrayBuffer | Buffer | object) {
 		if (!this.writer) {
-			throw new Error('Stream writer not initialized');
+			throw new StreamWriterInitializationError();
 		}
 		// Convert input to Uint8Array if needed
 		let binaryChunk: Uint8Array;
@@ -533,9 +551,10 @@ class UnderlyingSink {
 			try {
 				const res = await this.putRequestPromise;
 				if (!res.ok) {
-					throw new Error(
-						`PUT request failed: ${res.response.status} ${res.response.statusText}`
-					);
+					throw new StreamAPIError({
+						status: res.response.status,
+						message: `PUT request failed: ${res.response.status} ${res.response.statusText}`,
+					});
 				}
 			} catch (error) {
 				if (error instanceof Error && error.name !== 'AbortError') {
@@ -560,6 +579,21 @@ class UnderlyingSink {
 	}
 }
 
+const StreamNameInvalidError = StructuredError(
+	'StreamNameInvalidError',
+	'Stream name must be between 1 and 254 characters'
+);
+
+const StreamLimitInvalidError = StructuredError(
+	'StreamLimitInvalidError',
+	'Stream limit must be greater than 0 and less than or equal to 1000'
+);
+
+const StreamIDRequiredError = StructuredError(
+	'StreamIDRequiredError',
+	'Stream id is required and must be a non-empty string'
+);
+
 export class StreamStorageService implements StreamStorage {
 	#adapter: FetchAdapter;
 	#baseUrl: string;
@@ -571,7 +605,7 @@ export class StreamStorageService implements StreamStorage {
 
 	async create(name: string, props?: CreateStreamProps): Promise<Stream> {
 		if (!name || name.length < 1 || name.length > 254) {
-			throw new Error('Stream name must be between 1 and 254 characters');
+			throw new StreamNameInvalidError();
 		}
 		const url = this.#baseUrl;
 		const signal = AbortSignal.timeout(10_000);
@@ -624,7 +658,7 @@ export class StreamStorageService implements StreamStorage {
 		const attributes: Record<string, string> = {};
 		if (params?.limit !== undefined) {
 			if (params.limit <= 0 || params.limit > 1000) {
-				throw new Error('limit must be greater than 0 and less than or equal to 1000');
+				throw new StreamLimitInvalidError();
 			}
 			attributes['limit'] = String(params.limit);
 		}
@@ -695,7 +729,7 @@ export class StreamStorageService implements StreamStorage {
 
 	async get(id: string): Promise<StreamInfo> {
 		if (!id || typeof id !== 'string' || id.trim().length === 0) {
-			throw new Error('Stream id is required and must be a non-empty string');
+			throw new StreamIDRequiredError();
 		}
 		const signal = AbortSignal.timeout(30_000);
 		const url = buildUrl(this.#baseUrl, id, 'info');
@@ -731,7 +765,7 @@ export class StreamStorageService implements StreamStorage {
 
 	async download(id: string): Promise<ReadableStream<Uint8Array>> {
 		if (!id || typeof id !== 'string' || id.trim().length === 0) {
-			throw new Error('Stream id is required and must be a non-empty string');
+			throw new StreamIDRequiredError();
 		}
 		const signal = AbortSignal.timeout(300_000); // 5 minutes for download
 		const url = buildUrl(this.#baseUrl, id);
@@ -754,7 +788,7 @@ export class StreamStorageService implements StreamStorage {
 
 	async delete(id: string): Promise<void> {
 		if (!id || typeof id !== 'string' || id.trim().length === 0) {
-			throw new Error('Stream id is required and must be a non-empty string');
+			throw new StreamIDRequiredError();
 		}
 		const signal = AbortSignal.timeout(30_000);
 		const url = buildUrl(this.#baseUrl, id);