@agentuity/core 1.0.30 → 1.0.32

package/src/services/queue.ts

@@ -108,6 +108,59 @@ export interface QueuePublishResult {
 	publishedAt: string;
 }
 
+/**
+ * Parameters for creating a queue.
+ *
+ * @example
+ * ```typescript
+ * const result = await ctx.queue.createQueue('my-queue', {
+ *   queueType: 'pubsub',
+ *   settings: { defaultTtlSeconds: 86400 },
+ * });
+ * ```
+ */
+export interface QueueCreateParams {
+	/**
+	 * Type of queue to create.
+	 * - `worker`: Messages are consumed by exactly one consumer with acknowledgment.
+	 * - `pubsub`: Messages are broadcast to all subscribers.
+	 * @default 'worker'
+	 */
+	queueType?: 'worker' | 'pubsub';
+
+	/**
+	 * Optional description of the queue's purpose.
+	 */
+	description?: string;
+
+	/**
+	 * Optional settings to customize queue behavior.
+	 * Only provided fields are applied; others use server defaults.
+	 */
+	settings?: {
+		/** Default time-to-live for messages in seconds. Null means no expiration. */
+		defaultTtlSeconds?: number | null;
+		/** Time in seconds a message is invisible after being received. */
+		defaultVisibilityTimeoutSeconds?: number;
+		/** Maximum number of delivery attempts before moving to DLQ. */
+		defaultMaxRetries?: number;
+		/** Maximum number of messages a single client can process concurrently. */
+		maxInFlightPerClient?: number;
+		/** Retention period for acknowledged messages in seconds. */
+		retentionSeconds?: number;
+	};
+}
+
+/**
+ * Result of creating a queue.
+ */
+export interface QueueCreateResult {
+	/** The queue name. */
+	name: string;
+	/** The queue type ('worker' or 'pubsub'). */
+	queueType: string;
+}
+
 /**
  * Queue service interface for publishing messages.
  *
@@ -167,6 +220,49 @@ export interface QueueService {
 		payload: string | object,
 		params?: QueuePublishParams
 	): Promise<QueuePublishResult>;
+
+	/**
+	 * Create a queue with idempotent semantics.
+	 *
+	 * If the queue already exists, this returns successfully without error.
+	 * Safe to call multiple times — uses an internal cache to avoid redundant API calls.
+	 *
+	 * @param queueName - The name of the queue to create
+	 * @param params - Optional creation parameters (queue type, settings, etc.)
+	 * @returns The create result with queue name and type
+	 * @throws {QueueValidationError} If the queue name is invalid
+	 *
+	 * @example Creating a worker queue
+	 * ```typescript
+	 * const result = await ctx.queue.createQueue('task-queue');
+	 * ```
+	 *
+	 * @example Creating a pubsub queue with settings
+	 * ```typescript
+	 * const result = await ctx.queue.createQueue('events', {
+	 *   queueType: 'pubsub',
+	 *   settings: { defaultTtlSeconds: 86400 },
+	 * });
+	 * ```
+	 */
+	createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult>;
+
+	/**
+	 * Delete a queue.
+	 *
+	 * Permanently deletes a queue and all its messages. This action cannot be undone.
+	 * If the queue has already been deleted or does not exist, a {@link QueueNotFoundError} is thrown.
+	 *
+	 * @param queueName - The name of the queue to delete
+	 * @throws {QueueNotFoundError} If the queue does not exist
+	 * @throws {QueueValidationError} If the queue name is invalid
+	 *
+	 * @example Deleting a queue
+	 * ```typescript
+	 * await ctx.queue.deleteQueue('old-queue');
+	 * ```
+	 */
+	deleteQueue(queueName: string): Promise<void>;
 }
 
 // ============================================================================
@@ -277,6 +373,7 @@ function validatePayloadInternal(payload: string): void {
 export class QueueStorageService implements QueueService {
 	#adapter: FetchAdapter;
 	#baseUrl: string;
+	#knownQueues = new Set<string>();
 
 	/**
 	 * Creates a new QueueStorageService.
@@ -388,4 +485,122 @@ export class QueueStorageService implements QueueService {
 
 		throw await toServiceException('POST', url, res.response);
 	}
+
+	/**
+	 * @inheritdoc
+	 */
+	async createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult> {
+		validateQueueNameInternal(queueName);
+
+		if (this.#knownQueues.has(queueName)) {
+			return {
+				name: queueName,
+				queueType: params?.queueType ?? 'worker',
+			};
+		}
+
+		const url = buildUrl(this.#baseUrl, '/queue/create/2026-01-15');
+
+		const requestBody: Record<string, unknown> = {
+			name: queueName,
+			queue_type: params?.queueType ?? 'worker',
+		};
+
+		if (params?.description !== undefined) {
+			requestBody.description = params.description;
+		}
+
+		if (params?.settings) {
+			const settings: Record<string, unknown> = {};
+			if (params.settings.defaultTtlSeconds !== undefined) {
+				settings.default_ttl_seconds = params.settings.defaultTtlSeconds;
+			}
+			if (params.settings.defaultVisibilityTimeoutSeconds !== undefined) {
+				settings.default_visibility_timeout_seconds =
+					params.settings.defaultVisibilityTimeoutSeconds;
+			}
+			if (params.settings.defaultMaxRetries !== undefined) {
+				settings.default_max_retries = params.settings.defaultMaxRetries;
+			}
+			if (params.settings.maxInFlightPerClient !== undefined) {
+				settings.max_in_flight_per_client = params.settings.maxInFlightPerClient;
+			}
+			if (params.settings.retentionSeconds !== undefined) {
+				settings.retention_seconds = params.settings.retentionSeconds;
+			}
+			if (Object.keys(settings).length > 0) {
+				requestBody.settings = settings;
+			}
+		}
+
+		const signal = AbortSignal.timeout(30_000);
+		const res = await this.#adapter.invoke<QueueCreateResult>(url, {
+			method: 'POST',
+			signal,
+			body: JSON.stringify(requestBody),
+			contentType: 'application/json',
+			telemetry: {
+				name: 'agentuity.queue.create',
+				attributes: {
+					queueName,
+				},
+			},
+		});
+
+		if (res.ok) {
+			const data = res.data as unknown as Record<string, unknown>;
+			this.#knownQueues.add(queueName);
+			return {
+				name: (data.name as string) ?? queueName,
+				queueType: (data.queue_type as string) ?? params?.queueType ?? 'worker',
+			};
+		}
+
+		if (res.response.status === 409) {
+			this.#knownQueues.add(queueName);
+			return {
+				name: queueName,
+				queueType: params?.queueType ?? 'worker',
+			};
+		}
+
+		throw await toServiceException('POST', url, res.response);
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	async deleteQueue(queueName: string): Promise<void> {
+		validateQueueNameInternal(queueName);
+
+		const url = buildUrl(
+			this.#baseUrl,
+			`/queue/delete/2026-01-15/${encodeURIComponent(queueName)}`
+		);
+
+		const signal = AbortSignal.timeout(30_000);
+		const res = await this.#adapter.invoke<void>(url, {
+			method: 'DELETE',
+			signal,
+			telemetry: {
+				name: 'agentuity.queue.delete',
+				attributes: {
+					queueName,
+				},
+			},
+		});
+
+		if (res.ok) {
+			this.#knownQueues.delete(queueName);
+			return;
+		}
+
+		if (res.response.status === 404) {
+			throw new QueueNotFoundError({
+				message: `Queue not found: ${queueName}`,
+			});
+		}
+
+		throw await toServiceException('DELETE', url, res.response);
+	}
 }

package/src/services/stream.ts

@@ -1,7 +1,7 @@
+import { StructuredError } from '../error.ts';
 import { safeStringify } from '../json.ts';
-import { FetchAdapter } from './adapter.ts';
 import { buildUrl, toServiceException } from './_util.ts';
-import { StructuredError } from '../error.ts';
+import type { FetchAdapter } from './adapter.ts';
 import type { ListParams } from './pagination.ts';
 
 /**
@@ -19,17 +19,11 @@ export const STREAM_MAX_TTL_SECONDS = 7776000;
  */
 export const STREAM_DEFAULT_TTL_SECONDS = 2592000;
 
-// Use Web API streams - in Node.js/Bun, import from 'stream/web' which provides proper Web API
-// In browsers, use globalThis directly
-// Check for Node.js/Bun by looking for process.versions.node
-const isNode =
-	typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const streamWeb = isNode ? require('stream/web') : globalThis;
-const NativeWritableStream = streamWeb.WritableStream as typeof WritableStream;
-const NativeReadableStream = streamWeb.ReadableStream as typeof ReadableStream;
-const NativeCompressionStream = (streamWeb.CompressionStream ??
-	globalThis.CompressionStream) as typeof CompressionStream;
+// Web Streams API (ReadableStream, WritableStream, CompressionStream) are globally
+// available in all modern runtimes: Node.js 18+, Bun, Deno, and browsers.
+const NativeWritableStream = globalThis.WritableStream;
+const NativeReadableStream = globalThis.ReadableStream;
+const NativeCompressionStream = globalThis.CompressionStream;
 
 /**
  * Properties for creating a stream

package/src/services/task.ts

@@ -42,6 +42,28 @@ export interface EntityRef {
 	name: string;
 }
 
+/**
+ * The type of user entity.
+ *
+ * - `'human'` — A human user.
+ * - `'agent'` — An AI agent.
+ */
+export type UserType = 'human' | 'agent';
+
+/**
+ * A reference to a user entity with type discrimination.
+ * Extends {@link EntityRef} with a {@link UserEntityRef.type | type} field
+ * to distinguish between human users and AI agents.
+ */
+export interface UserEntityRef extends EntityRef {
+	/**
+	 * The type of user. Defaults to `'human'` if not specified.
+	 *
+	 * @default 'human'
+	 */
+	type?: UserType;
+}
+
 /**
  * A work item in the task management system.
  *
@@ -130,13 +152,13 @@ export interface Task {
 	closed_id?: string;
 
 	/** Reference to the user who created the task. */
-	creator?: EntityRef;
+	creator?: UserEntityRef;
 
 	/** Reference to the user the task is assigned to. */
-	assignee?: EntityRef;
+	assignee?: UserEntityRef;
 
 	/** Reference to the user who closed the task. */
-	closer?: EntityRef;
+	closer?: UserEntityRef;
 
 	/** Reference to the project this task belongs to. */
 	project?: EntityRef;
@@ -171,7 +193,7 @@ export interface Comment {
 	user_id: string;
 
 	/** Reference to the comment author with display name. */
-	author?: EntityRef;
+	author?: UserEntityRef;
 
 	/**
 	 * The comment text content.
@@ -286,11 +308,11 @@ export interface CreateTaskParams {
 	 */
 	assigned_id?: string;
 
-	/** Reference to the user creating the task (id and name). */
-	creator?: EntityRef;
+	/** Reference to the user creating the task (id, name, and optional type). */
+	creator?: UserEntityRef;
 
 	/** Reference to the user being assigned the task. */
-	assignee?: EntityRef;
+	assignee?: UserEntityRef;
 
 	/** Reference to the project this task belongs to. */
 	project?: EntityRef;
@@ -349,10 +371,10 @@ export interface UpdateTaskParams {
 	closed_id?: string;
 
 	/** Reference to the user being assigned the task. */
-	assignee?: EntityRef;
+	assignee?: UserEntityRef;
 
 	/** Reference to the user closing the task. */
-	closer?: EntityRef;
+	closer?: UserEntityRef;
 
 	/** Reference to the project this task belongs to. */
 	project?: EntityRef;
@@ -425,6 +447,62 @@ export interface ListTasksResult {
 	offset: number;
 }
 
+/**
+ * Parameters for batch-deleting tasks by filter.
+ * At least one filter must be provided.
+ */
+export interface BatchDeleteTasksParams {
+	/** Filter by task status. */
+	status?: TaskStatus;
+
+	/** Filter by task type. */
+	type?: TaskType;
+
+	/** Filter by priority level. */
+	priority?: TaskPriority;
+
+	/** Filter by parent task ID (delete subtasks). */
+	parent_id?: string;
+
+	/** Filter by creator ID. */
+	created_id?: string;
+
+	/**
+	 * Delete tasks older than this duration.
+	 * Accepts Go-style duration strings: `'30m'`, `'24h'`, `'7d'`, `'2w'`.
+	 */
+	older_than?: string;
+
+	/**
+	 * Maximum number of tasks to delete.
+	 * @default 50
+	 * @maximum 200
+	 */
+	limit?: number;
+}
+
+/**
+ * A single task that was deleted in a batch operation.
+ */
+export interface BatchDeletedTask {
+	/** The ID of the deleted task. */
+	id: string;
+
+	/** The title of the deleted task. */
+	title: string;
+}
+
+/**
+ * Result of a batch delete operation.
+ */
+export interface BatchDeleteTasksResult {
+	/** Array of tasks that were deleted. */
+	deleted: BatchDeletedTask[];
+
+	/** Total number of tasks deleted. */
+	count: number;
+}
+
 /**
  * Paginated list of changelog entries for a task.
  */
@@ -484,7 +562,7 @@ export interface Attachment {
 	user_id: string;
 
 	/** Reference to the uploader with display name. */
-	author?: EntityRef;
+	author?: UserEntityRef;
 
 	/** Original filename of the uploaded file. */
 	filename: string;
@@ -554,8 +632,8 @@ export interface ListAttachmentsResult {
  * List of all users who have been referenced in tasks (as creators, assignees, or closers).
  */
 export interface ListUsersResult {
-	/** Array of user entity references. */
-	users: EntityRef[];
+	/** Array of user entity references with type information. */
+	users: UserEntityRef[];
 }
 
 /**
@@ -672,6 +750,15 @@ export interface TaskStorage {
 	 */
 	softDelete(id: string): Promise<Task>;
 
+	/**
+	 * Batch soft-delete tasks matching the given filters.
+	 * At least one filter must be provided.
+	 *
+	 * @param params - Filters to select which tasks to delete
+	 * @returns The list of deleted tasks and count
+	 */
+	batchDelete(params: BatchDeleteTasksParams): Promise<BatchDeleteTasksResult>;
+
 	/**
 	 * Get the changelog (audit trail) for a task.
 	 *
@@ -867,6 +954,9 @@ export interface TaskStorage {
 /** API version string used for task CRUD, comment, tag, and attachment endpoints. */
 const TASK_API_VERSION = '2026-02-24';
 
+/** Maximum number of tasks that can be deleted in a single batch request. */
+const MAX_BATCH_DELETE_LIMIT = 200;
+
 /** API version string used for the task activity analytics endpoint. */
 const TASK_ACTIVITY_API_VERSION = '2026-02-28';
 
@@ -1383,6 +1473,77 @@ export class TaskStorageService implements TaskStorage {
 		throw await toServiceException('POST', url, res.response);
 	}
 
+	/**
+	 * Batch soft-delete tasks matching the given filters.
+	 * At least one filter must be provided. The server caps the limit at 200.
+	 *
+	 * @param params - Filters to select which tasks to delete
+	 * @returns The list of deleted tasks and count
+	 * @throws {@link ServiceException} if the API request fails
+	 *
+	 * @example
+	 * ```typescript
+	 * const result = await tasks.batchDelete({ status: 'closed', older_than: '7d', limit: 50 });
+	 * console.log(`Deleted ${result.count} tasks`);
+	 * ```
+	 */
+	async batchDelete(params: BatchDeleteTasksParams): Promise<BatchDeleteTasksResult> {
+		const hasFilter =
+			params.status ||
+			params.type ||
+			params.priority ||
+			params.parent_id ||
+			params.created_id ||
+			params.older_than;
+		if (!hasFilter) {
+			throw new Error('At least one filter is required for batch delete');
+		}
+		if (params.limit !== undefined && params.limit > MAX_BATCH_DELETE_LIMIT) {
+			throw new Error(
+				`Batch delete limit must not exceed ${MAX_BATCH_DELETE_LIMIT} (got ${params.limit})`
+			);
+		}
+
+		const url = buildUrl(this.#baseUrl, `/task/delete/batch/${TASK_API_VERSION}`);
+		const signal = AbortSignal.timeout(60_000);
+
+		const body: Record<string, unknown> = {};
+		if (params.status) body.status = params.status;
+		if (params.type) body.type = params.type;
+		if (params.priority) body.priority = params.priority;
+		if (params.parent_id) body.parent_id = params.parent_id;
+		if (params.created_id) body.created_id = params.created_id;
+		if (params.older_than) body.older_than = params.older_than;
+		if (params.limit !== undefined) body.limit = params.limit;
+
+		const res = await this.#adapter.invoke<TaskResponse<BatchDeleteTasksResult>>(url, {
+			method: 'POST',
+			body: safeStringify(body),
+			headers: { 'Content-Type': 'application/json' },
+			signal,
+			telemetry: {
+				name: 'agentuity.task.batchDelete',
+				attributes: {
+					...(params.status ? { status: params.status } : {}),
+					...(params.type ? { type: params.type } : {}),
+					...(params.older_than ? { older_than: params.older_than } : {}),
+				},
+			},
+		});
+
+		if (res.ok) {
+			if (res.data.success) {
+				return res.data.data;
+			}
+			throw new TaskStorageResponseError({
+				status: res.response.status,
+				message: res.data.message,
+			});
+		}
+
+		throw await toServiceException('POST', url, res.response);
+	}
+
 	/**
 	 * Create a comment on a task.
 	 *