@agentuity/core 0.0.47 → 0.0.49

package/src/services/objectstore.ts

@@ -97,6 +97,26 @@ type ObjectStoreCreatePublicURLResponse =
 	| ObjectStoreCreatePublicURLSuccessResponse
 	| ObjectStoreCreatePublicURLErrorResponse;
 
+/**
+ * Information about an object in the object store
+ */
+export interface ObjectInfo {
+	key: string;
+	size: number;
+	etag: string;
+	created_at: string;
+	updated_at: string;
+}
+
+/**
+ * Information about a bucket in the object store
+ */
+export interface BucketInfo {
+	name: string;
+	object_count: number;
+	total_bytes: number;
+}
+
 /**
  * Object store service for storing and retrieving binary data
  */
@@ -179,6 +199,85 @@ export interface ObjectStorage {
 	 * ```
 	 */
 	createPublicURL(bucket: string, key: string, params?: CreatePublicURLParams): Promise<string>;
+
+	/**
+	 * List all buckets in the object store
+	 *
+	 * @returns array of bucket information
+	 *
+	 * @example
+	 * ```typescript
+	 * const buckets = await objectStore.listBuckets();
+	 * for (const bucket of buckets) {
+	 *   console.log(`${bucket.name}: ${bucket.object_count} objects, ${bucket.total_bytes} bytes`);
+	 * }
+	 * ```
+	 */
+	listBuckets(): Promise<BucketInfo[]>;
+
+	/**
+	 * List all keys in a bucket
+	 *
+	 * @param bucket - the bucket to list keys from
+	 * @returns array of object information
+	 *
+	 * @example
+	 * ```typescript
+	 * const objects = await objectStore.listKeys('my-bucket');
+	 * for (const obj of objects) {
+	 *   console.log(`${obj.key}: ${obj.size} bytes`);
+	 * }
+	 * ```
+	 */
+	listKeys(bucket: string): Promise<ObjectInfo[]>;
+
+	/**
+	 * List objects in a bucket with optional filtering
+	 *
+	 * @param bucket - the bucket to list objects from
+	 * @param options - optional filtering (prefix, limit)
+	 * @returns array of object information
+	 *
+	 * @example
+	 * ```typescript
+	 * const objects = await objectStore.listObjects('my-bucket', { prefix: 'docs/', limit: 100 });
+	 * for (const obj of objects) {
+	 *   console.log(`${obj.key}: ${obj.size} bytes`);
+	 * }
+	 * ```
+	 */
+	listObjects(
+		bucket: string,
+		options?: { prefix?: string; limit?: number }
+	): Promise<ObjectInfo[]>;
+
+	/**
+	 * Get object metadata without retrieving the data
+	 *
+	 * @param bucket - the bucket containing the object
+	 * @param key - the key of the object
+	 * @returns object metadata (size, contentType, etc.)
+	 *
+	 * @example
+	 * ```typescript
+	 * const metadata = await objectStore.headObject('my-bucket', 'my-key');
+	 * console.log(`Size: ${metadata.size}, Type: ${metadata.contentType}`);
+	 * ```
+	 */
+	headObject(bucket: string, key: string): Promise<ObjectInfo>;
+
+	/**
+	 * Delete a bucket and all its contents
+	 *
+	 * @param bucket - the bucket to delete
+	 * @returns true if the bucket was deleted
+	 *
+	 * @example
+	 * ```typescript
+	 * await objectStore.deleteBucket('my-bucket');
+	 * ```
+	 */
+	deleteBucket(bucket: string): Promise<boolean>;
 }
 
 /**
@@ -247,7 +346,7 @@ export class ObjectStorageService implements ObjectStorage {
 			} as ObjectResultFound;
 		} catch (err) {
 			if (err instanceof Response) {
-				throw await toServiceException(url, err);
+				throw await toServiceException(url, 'GET', err);
 			}
 			throw err;
 		}
@@ -342,7 +441,7 @@ export class ObjectStorageService implements ObjectStorage {
 			}
 		} catch (err) {
 			if (err instanceof Response) {
-				throw await toServiceException(url, err);
+				throw await toServiceException(url, 'PUT', err);
 			}
 			throw err;
 		}
@@ -390,7 +489,7 @@ export class ObjectStorageService implements ObjectStorage {
 			);
 		} catch (err) {
 			if (err instanceof Response) {
-				throw await toServiceException(url, err);
+				throw await toServiceException(url, 'DELETE', err);
 			}
 			throw err;
 		}
@@ -458,7 +557,223 @@ export class ObjectStorageService implements ObjectStorage {
 				throw err;
 			}
 			if (err instanceof Response) {
-				throw await toServiceException(url, err);
+				throw await toServiceException(url, 'POST', err);
+			}
+			throw err;
+		}
+	}
+
+	async listBuckets(): Promise<BucketInfo[]> {
+		const url = buildUrl(this.#baseUrl, '/object/2025-03-17/buckets');
+
+		const signal = AbortSignal.timeout(10_000);
+		const options: FetchRequest = {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.objectstore.listBuckets',
+				attributes: {},
+			},
+		};
+
+		try {
+			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})`
+				);
+			}
+
+			return result.data.buckets;
+		} catch (err) {
+			if (err instanceof Response) {
+				throw await toServiceException(url, 'GET', err);
+			}
+			throw err;
+		}
+	}
+
+	async listKeys(bucket: string): Promise<ObjectInfo[]> {
+		if (!bucket?.trim()) {
+			throw new Error('bucket is required and cannot be empty');
+		}
+
+		const url = buildUrl(this.#baseUrl, `/object/2025-03-17/keys/${encodeURIComponent(bucket)}`);
+
+		const signal = AbortSignal.timeout(10_000);
+		const options: FetchRequest = {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.objectstore.listKeys',
+				attributes: {
+					'objectstore.bucket': bucket,
+				},
+			},
+		};
+
+		try {
+			const result = await this.#adapter.invoke<{ bucket: string; objects: ObjectInfo[] }>(
+				url,
+				options
+			);
+
+			if (!result.ok) {
+				throw new Error(
+					`Failed to list keys: ${result.response.statusText} (${result.response.status})`
+				);
+			}
+
+			return result.data.objects;
+		} catch (err) {
+			if (err instanceof Response) {
+				throw await toServiceException(url, 'GET', err);
+			}
+			throw err;
+		}
+	}
+
+	async listObjects(
+		bucket: string,
+		options?: { prefix?: string; limit?: number }
+	): Promise<ObjectInfo[]> {
+		if (!bucket?.trim()) {
+			throw new Error('bucket is required and cannot be empty');
+		}
+
+		const params = new URLSearchParams();
+		if (options?.prefix) {
+			params.set('prefix', options.prefix);
+		}
+		if (options?.limit) {
+			params.set('limit', options.limit.toString());
+		}
+
+		const queryString = params.toString();
+		const url = buildUrl(
+			this.#baseUrl,
+			`/object/2025-03-17/objects/${encodeURIComponent(bucket)}${queryString ? `?${queryString}` : ''}`
+		);
+
+		const signal = AbortSignal.timeout(10_000);
+		const fetchOptions: FetchRequest = {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.objectstore.listObjects',
+				attributes: {
+					'objectstore.bucket': bucket,
+					'objectstore.prefix': options?.prefix || '',
+					'objectstore.limit': (options?.limit || 1000).toString(),
+				},
+			},
+		};
+
+		try {
+			const result = await this.#adapter.invoke<{ bucket: string; objects: ObjectInfo[] }>(
+				url,
+				fetchOptions
+			);
+
+			if (!result.ok) {
+				throw new Error(
+					`Failed to list objects: ${result.response.statusText} (${result.response.status})`
+				);
+			}
+
+			return result.data.objects;
+		} catch (err) {
+			if (err instanceof Response) {
+				throw await toServiceException(url, 'GET', err);
+			}
+			throw err;
+		}
+	}
+
+	async headObject(bucket: string, key: string): Promise<ObjectInfo> {
+		if (!bucket?.trim()) {
+			throw new Error('bucket is required and cannot be empty');
+		}
+		if (!key?.trim()) {
+			throw new Error('key is required and cannot be empty');
+		}
+
+		const url = buildUrl(
+			this.#baseUrl,
+			`/object/2025-03-17/head/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`
+		);
+
+		const signal = AbortSignal.timeout(10_000);
+		const fetchOptions: FetchRequest = {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.objectstore.headObject',
+				attributes: {
+					'objectstore.bucket': bucket,
+					'objectstore.key': key,
+				},
+			},
+		};
+
+		try {
+			const result = await this.#adapter.invoke<ObjectInfo>(url, fetchOptions);
+
+			if (!result.ok) {
+				if (result.response.status === 404) {
+					throw new Error('Object not found');
+				}
+				throw new Error(
+					`Failed to get object metadata: ${result.response.statusText} (${result.response.status})`
+				);
+			}
+
+			return result.data;
+		} catch (err) {
+			if (err instanceof Response) {
+				throw await toServiceException(url, 'GET', err);
+			}
+			throw err;
+		}
+	}
+
+	async deleteBucket(bucket: string): Promise<boolean> {
+		if (!bucket?.trim()) {
+			throw new Error('bucket is required and cannot be empty');
+		}
+
+		const url = buildUrl(this.#baseUrl, `/object/2025-03-17/${encodeURIComponent(bucket)}`);
+
+		const signal = AbortSignal.timeout(30_000);
+		const options: FetchRequest = {
+			method: 'DELETE',
+			signal,
+			telemetry: {
+				name: 'agentuity.objectstore.deleteBucket',
+				attributes: {
+					'objectstore.bucket': bucket,
+				},
+			},
+		};
+
+		try {
+			const result = await this.#adapter.invoke(url, options);
+
+			if (result.response.status === 404) {
+				return false;
+			}
+
+			if (result.response.status === 200) {
+				return true;
+			}
+
+			throw new Error(
+				`Failed to delete bucket: ${result.response.statusText} (${result.response.status})`
+			);
+		} catch (err) {
+			if (err instanceof Response) {
+				throw await toServiceException(url, 'DELETE', err);
 			}
 			throw err;
 		}

package/src/services/session.ts

@@ -45,20 +45,58 @@ export const SessionCompleteEventDelayedSchema = z.intersection(
 );
 
 /**
- * SessionEventProvider is a provider for logging session events
+ * SessionEventProvider is a provider for logging and tracking agent session lifecycle events.
+ * Sessions represent individual agent executions triggered by API calls, cron jobs, or other sources.
  */
 export interface SessionEventProvider {
 	/**
-	 * called when the session starts
+	 * Called when an agent session starts. Records the initial context and metadata
+	 * for the session including trigger source, environment, and routing information.
 	 *
-	 * @param event SessionStartEvent
+	 * @param event - SessionStartEvent containing session initialization data
+	 *
+	 * @example
+	 * ```typescript
+	 * await sessionProvider.start({
+	 *   id: 'session-123',
+	 *   threadId: 'thread-abc',
+	 *   orgId: 'org-456',
+	 *   projectId: 'proj-789',
+	 *   deploymentId: 'deploy-xyz',
+	 *   routeId: 'route-001',
+	 *   environment: 'production',
+	 *   devmode: false,
+	 *   url: '/api/agent/chat',
+	 *   method: 'POST',
+	 *   trigger: 'api'
+	 * });
+	 * ```
 	 */
 	start(event: SessionStartEvent): Promise<void>;
 
 	/**
-	 * called when the session completes
+	 * Called when an agent session completes (successfully or with error).
+	 * Records final status, any errors, and which agents participated.
+	 *
+	 * @param event - SessionCompleteEvent containing completion status and results
+	 *
+	 * @example
+	 * ```typescript
+	 * // Successful completion
+	 * await sessionProvider.complete({
+	 *   id: 'session-123',
+	 *   statusCode: 200,
+	 *   agentIds: ['agent-1', 'agent-2']
+	 * });
 	 *
-	 * @param event SessionCompleteEvent
+	 * // Completion with error
+	 * await sessionProvider.complete({
+	 *   id: 'session-123',
+	 *   statusCode: 500,
+	 *   error: 'Database connection timeout',
+	 *   agentIds: ['agent-1']
+	 * });
+	 * ```
 	 */
 	complete(event: SessionCompleteEvent): Promise<void>;
 }

package/src/services/stream.ts

@@ -151,31 +151,83 @@ export interface Stream extends WritableStream {
 }
 
 /**
- * Stream API for creating and managing streams
+ * Stream API for creating and managing durable, resumable data streams.
+ * Streams are backed by durable storage and provide public URLs for access.
  */
 export interface StreamStorage {
 	/**
-	 * create a new stream
+	 * Create a new stream for writing data that can be read multiple times
 	 *
-	 * @param name - the name of the stream (1-254 characters). you can group streams by name to organize them.
-	 * @param props - optional properties for creating the stream
+	 * @param name - the name of the stream (1-254 characters). Use names to group and organize streams.
+	 * @param props - optional properties including metadata, content type, and compression
 	 * @returns a Promise that resolves to the created Stream
+	 *
+	 * @example
+	 * ```typescript
+	 * // Create a simple text stream
+	 * const stream = await streams.create('agent-logs');
+	 * await stream.write('Starting agent execution\n');
+	 * await stream.write('Processing data...\n');
+	 * await stream.close();
+	 * console.log('Stream URL:', stream.url);
+	 *
+	 * // Create a compressed JSON stream with metadata
+	 * const dataStream = await streams.create('data-export', {
+	 *   contentType: 'application/json',
+	 *   compress: true,
+	 *   metadata: { exportDate: '2024-01-15', version: '1.0' }
+	 * });
+	 * await dataStream.write({ records: [...] });
+	 * await dataStream.close();
+	 *
+	 * // Read back from the stream
+	 * const reader = dataStream.getReader();
+	 * for await (const chunk of reader) {
+	 *   console.log('Chunk:', chunk);
+	 * }
+	 * ```
 	 */
 	create(name: string, props?: CreateStreamProps): Promise<Stream>;
 
 	/**
-	 * list streams with optional filtering and pagination
+	 * List streams with optional filtering and pagination
 	 *
 	 * @param params - optional parameters for filtering and pagination
-	 * @returns a Promise that resolves to the list of streams
+	 * @returns a Promise that resolves to the list of streams with metadata
+	 *
+	 * @example
+	 * ```typescript
+	 * // List all streams
+	 * const all = await streams.list();
+	 * console.log(`Found ${all.total} streams`);
+	 *
+	 * // Filter by name
+	 * const logs = await streams.list({ name: 'agent-logs' });
+	 *
+	 * // Filter by metadata and paginate
+	 * const filtered = await streams.list({
+	 *   metadata: { type: 'export' },
+	 *   limit: 50,
+	 *   offset: 100
+	 * });
+	 *
+	 * for (const stream of filtered.streams) {
+	 *   console.log(`${stream.name}: ${stream.sizeBytes} bytes at ${stream.url}`);
+	 * }
+	 * ```
 	 */
 	list(params?: ListStreamsParams): Promise<ListStreamsResponse>;
 
 	/**
-	 * delete a stream by id
+	 * Delete a stream by its ID
 	 *
-	 * @param id - the stream id to delete
+	 * @param id - the stream ID to delete
 	 * @returns a Promise that resolves when the stream is deleted
+	 *
+	 * @example
+	 * ```typescript
+	 * await streams.delete('stream-id-123');
+	 * ```
 	 */
 	delete(id: string): Promise<void>;
 }
@@ -537,7 +589,7 @@ export class StreamStorageService implements StreamStorage {
 
 			return stream;
 		}
-		throw await toServiceException(url, res.response);
+		throw await toServiceException(url, 'POST', res.response);
 	}
 
 	async list(params?: ListStreamsParams): Promise<ListStreamsResponse> {
@@ -587,7 +639,7 @@ export class StreamStorageService implements StreamStorage {
 		if (res.ok) {
 			return res.data;
 		}
-		throw await toServiceException(url, res.response);
+		throw await toServiceException(url, 'POST', res.response);
 	}
 
 	async delete(id: string): Promise<void> {
@@ -609,6 +661,6 @@ export class StreamStorageService implements StreamStorage {
 		if (res.ok) {
 			return;
 		}
-		throw await toServiceException(url, res.response);
+		throw await toServiceException(url, 'DELETE', res.response);
 	}
 }