@agentuity/core 0.1.16 → 0.1.18

package/src/services/keyvalue.ts

@@ -2,6 +2,21 @@ import { FetchAdapter } from './adapter';
 import { buildUrl, toServiceException, toPayload } from './_util';
 import { StructuredError } from '../error';
 
+/**
+ * Minimum TTL value in seconds (1 minute)
+ */
+export const KV_MIN_TTL_SECONDS = 60;
+
+/**
+ * Maximum TTL value in seconds (90 days)
+ */
+export const KV_MAX_TTL_SECONDS = 7776000;
+
+/**
+ * Default TTL value in seconds (7 days) - used when namespace is auto-created or no TTL specified
+ */
+export const KV_DEFAULT_TTL_SECONDS = 604800;
+
 /**
  * the result of a data operation when the data is found
  */
@@ -49,6 +64,23 @@ export interface KeyValueStorageSetParams {
 	contentType?: string;
 }
 
+/**
+ * Parameters for creating a namespace
+ */
+export interface CreateNamespaceParams {
+	/**
+	 * Default TTL for keys in this namespace (in seconds).
+	 * - If undefined/omitted: uses server default (7 days / 604,800 seconds)
+	 * - If 0: keys will not expire by default
+	 * - If 60-7,776,000: custom TTL in seconds (1 minute to 90 days)
+	 *
+	 * Keys can override this default by specifying TTL in the set() call.
+	 * Active keys are automatically extended (sliding expiration) when read
+	 * if their remaining TTL is less than 50% of the original TTL.
+	 */
+	defaultTTLSeconds?: number;
+}
+
 /**
  * Statistics for a key-value store namespace
  */
@@ -70,6 +102,46 @@ export interface KeyValueItemWithMetadata<T = unknown> {
 	updated_at: string;
 }
 
+/**
+ * Parameters for getting all namespace statistics with optional pagination
+ */
+export interface GetAllStatsParams {
+	/**
+	 * Maximum number of namespaces to return (default: 100, max: 1000)
+	 */
+	limit?: number;
+	/**
+	 * Number of namespaces to skip for pagination (default: 0)
+	 */
+	offset?: number;
+}
+
+/**
+ * Paginated response for namespace statistics
+ */
+export interface KeyValueStatsPaginated {
+	/**
+	 * Map of namespace names to their statistics
+	 */
+	namespaces: Record<string, KeyValueStats>;
+	/**
+	 * Total number of namespaces across all pages
+	 */
+	total: number;
+	/**
+	 * Number of namespaces requested per page
+	 */
+	limit: number;
+	/**
+	 * Number of namespaces skipped
+	 */
+	offset: number;
+	/**
+	 * Whether there are more namespaces available
+	 */
+	hasMore: boolean;
+}
+
 export interface KeyValueStorage {
 	/**
 	 * get a value from the key value storage
@@ -114,14 +186,20 @@ export interface KeyValueStorage {
 	/**
 	 * get statistics for all namespaces
 	 *
-	 * @returns map of namespace names to statistics
+	 * @param params - optional pagination parameters
+	 * @returns map of namespace names to statistics, or paginated response if params provided
 	 */
-	getAllStats(): Promise<Record<string, KeyValueStats>>;
+	getAllStats(params?: GetAllStatsParams): Promise<Record<string, KeyValueStats> | KeyValueStatsPaginated>;
 
 	/**
 	 * get all namespace names
 	 *
-	 * @returns array of namespace names
+	 * @returns array of namespace names (up to 1000)
+	 *
+	 * @remarks
+	 * This method returns a maximum of 1000 namespace names.
+	 * If you have more than 1000 namespaces, only the first 1000
+	 * (ordered by creation date, most recent first) will be returned.
 	 */
 	getNamespaces(): Promise<string[]>;
 
@@ -156,8 +234,9 @@ export interface KeyValueStorage {
 	 * create a new namespace
 	 *
 	 * @param name - the name of the key value storage to create
+	 * @param params - optional parameters including default TTL
 	 */
-	createNamespace(name: string): Promise<void>;
+	createNamespace(name: string, params?: CreateNamespaceParams): Promise<void>;
 }
 
 const KeyValueInvalidTTLError = StructuredError('KeyValueInvalidTTLError');
@@ -201,6 +280,21 @@ export class KeyValueStorageService implements KeyValueStorage {
 		throw await toServiceException('GET', url, res.response);
 	}
 
+	/**
+	 * set a value in the key value storage
+	 *
+	 * @param name - the name of the key value storage
+	 * @param key - the key to set the value of
+	 * @param value - the value to set in any of the supported data types
+	 * @param params - the KeyValueStorageSetParams
+	 *
+	 * @remarks
+	 * TTL behavior:
+	 * - If TTL is not specified, the key inherits the namespace's default TTL
+	 * - TTL values below 60 seconds are clamped to 60 seconds
+	 * - TTL values above 7,776,000 seconds (90 days) are clamped to 90 days
+	 * - If the namespace doesn't exist, it is auto-created with a 7-day default TTL
+	 */
 	async set<T = unknown>(
 		name: string,
 		key: string,
@@ -282,10 +376,18 @@ export class KeyValueStorageService implements KeyValueStorage {
 		throw await toServiceException('GET', url, res.response);
 	}
 
-	async getAllStats(): Promise<Record<string, KeyValueStats>> {
-		const url = buildUrl(this.#baseUrl, '/kv/2025-03-17/stats');
+	async getAllStats(params?: GetAllStatsParams): Promise<Record<string, KeyValueStats> | KeyValueStatsPaginated> {
+		const queryParams = new URLSearchParams();
+		if (params?.limit !== undefined) {
+			queryParams.set('limit', String(params.limit));
+		}
+		if (params?.offset !== undefined) {
+			queryParams.set('offset', String(params.offset));
+		}
+		const queryString = queryParams.toString();
+		const url = buildUrl(this.#baseUrl, `/kv/2025-03-17/stats${queryString ? `?${queryString}` : ''}`);
 		const signal = AbortSignal.timeout(10_000);
-		const res = await this.#adapter.invoke<Record<string, KeyValueStats>>(url, {
+		const res = await this.#adapter.invoke<Record<string, KeyValueStats> | KeyValueStatsPaginated>(url, {
 			method: 'GET',
 			signal,
 			telemetry: {
@@ -300,8 +402,20 @@ export class KeyValueStorageService implements KeyValueStorage {
 	}
 
 	async getNamespaces(): Promise<string[]> {
-		const stats = await this.getAllStats();
-		return Object.keys(stats);
+		const url = buildUrl(this.#baseUrl, '/kv/2025-03-17/namespaces');
+		const signal = AbortSignal.timeout(10_000);
+		const res = await this.#adapter.invoke<string[]>(url, {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.keyvalue.getNamespaces',
+				attributes: {},
+			},
+		});
+		if (res.ok) {
+			return res.data;
+		}
+		throw await toServiceException('GET', url, res.response);
 	}
 
 	async search<T = unknown>(
@@ -361,12 +475,18 @@ export class KeyValueStorageService implements KeyValueStorage {
 		throw await toServiceException('DELETE', url, res.response);
 	}
 
-	async createNamespace(name: string): Promise<void> {
+	async createNamespace(name: string, params?: CreateNamespaceParams): Promise<void> {
 		const url = buildUrl(this.#baseUrl, `/kv/2025-03-17/${encodeURIComponent(name)}`);
 		const signal = AbortSignal.timeout(10_000);
+
+		const body = params?.defaultTTLSeconds !== undefined
+			? JSON.stringify({ default_ttl_seconds: params.defaultTTLSeconds })
+			: undefined;
+
 		const res = await this.#adapter.invoke(url, {
 			method: 'POST',
 			signal,
+			...(body && { body, contentType: 'application/json' }),
 			telemetry: {
 				name: 'agentuity.keyvalue.createNamespace',
 				attributes: { name },

package/src/services/queue.ts

@@ -0,0 +1,384 @@
+/**
+ * @module queue
+ *
+ * Queue service for publishing messages to Agentuity queues.
+ *
+ * This module provides a simplified interface for agents to publish messages
+ * to queues. For full queue management (CRUD, consume, acknowledge), use
+ * the `@agentuity/server` package.
+ *
+ * @example Publishing from an agent
+ * ```typescript
+ * // Inside an agent handler
+ * const result = await ctx.queue.publish('order-queue', {
+ *   orderId: 123,
+ *   action: 'process',
+ * });
+ * console.log(`Published message ${result.id}`);
+ * ```
+ */
+
+import { FetchAdapter } from './adapter';
+import { buildUrl, toServiceException, toPayload } from './_util';
+import { StructuredError } from '../error';
+
+/**
+ * Parameters for publishing a message to a queue.
+ *
+ * @example
+ * ```typescript
+ * const params: QueuePublishParams = {
+ *   metadata: { priority: 'high' },
+ *   partitionKey: 'customer-123',
+ *   idempotencyKey: 'order-456-v1',
+ *   ttl: 3600, // 1 hour
+ * };
+ * ```
+ */
+export interface QueuePublishParams {
+	/**
+	 * Optional metadata to attach to the message.
+	 * Can contain any JSON-serializable data for message routing or filtering.
+	 */
+	metadata?: Record<string, unknown>;
+
+	/**
+	 * Optional partition key for message ordering.
+	 * Messages with the same partition key are guaranteed to be processed in order.
+	 */
+	partitionKey?: string;
+
+	/**
+	 * Optional idempotency key for deduplication.
+	 * If a message with the same key was recently published, it will be deduplicated.
+	 */
+	idempotencyKey?: string;
+
+	/**
+	 * Optional time-to-live in seconds.
+	 * Messages will expire and be removed after this duration.
+	 */
+	ttl?: number;
+
+	/**
+	 * Optional project ID for cross-project publishing.
+	 * If not specified, uses the current project context.
+	 */
+	projectId?: string;
+
+	/**
+	 * Optional agent ID for attribution.
+	 * If not specified, uses the current agent context.
+	 */
+	agentId?: string;
+}
+
+/**
+ * Result of publishing a message to a queue.
+ *
+ * @example
+ * ```typescript
+ * const result = await queue.publish('my-queue', payload);
+ * console.log(`Message ${result.id} published at offset ${result.offset}`);
+ * ```
+ */
+export interface QueuePublishResult {
+	/**
+	 * The unique message ID (prefixed with msg_).
+	 * Use this ID to track, acknowledge, or delete the message.
+	 */
+	id: string;
+
+	/**
+	 * The sequential offset of the message in the queue.
+	 * Offsets are monotonically increasing and can be used for log-style consumption.
+	 */
+	offset: number;
+
+	/**
+	 * ISO 8601 timestamp when the message was published.
+	 */
+	publishedAt: string;
+}
+
+/**
+ * Queue service interface for publishing messages.
+ *
+ * This is the interface available to agents via `ctx.queue`. It provides
+ * a simple publish-only interface suitable for agent workflows.
+ *
+ * For full queue management (create queues, consume messages, manage destinations),
+ * use the `@agentuity/server` package.
+ *
+ * @example
+ * ```typescript
+ * // In an agent handler
+ * export default createAgent('my-agent', {
+ *   handler: async (ctx, input) => {
+ *     // Publish a message to a queue
+ *     await ctx.queue.publish('notifications', {
+ *       type: 'email',
+ *       to: input.email,
+ *       subject: 'Welcome!',
+ *     });
+ *     return { success: true };
+ *   },
+ * });
+ * ```
+ */
+export interface QueueService {
+	/**
+	 * Publish a message to a queue.
+	 *
+	 * The payload can be a string or an object. Objects are automatically
+	 * JSON-stringified before publishing.
+	 *
+	 * @param queueName - The name of the queue to publish to
+	 * @param payload - The message payload (string or JSON-serializable object)
+	 * @param params - Optional publish parameters (metadata, TTL, etc.)
+	 * @returns The publish result with message ID and offset
+	 * @throws {QueueNotFoundError} If the queue does not exist
+	 * @throws {QueueValidationError} If validation fails (invalid name, payload too large, etc.)
+	 * @throws {QueuePublishError} If the publish operation fails
+	 *
+	 * @example Publishing a simple message
+	 * ```typescript
+	 * const result = await ctx.queue.publish('my-queue', 'Hello, World!');
+	 * ```
+	 *
+	 * @example Publishing with options
+	 * ```typescript
+	 * const result = await ctx.queue.publish('my-queue', { task: 'process' }, {
+	 *   metadata: { priority: 'high' },
+	 *   idempotencyKey: 'task-123',
+	 *   ttl: 3600,
+	 * });
+	 * ```
+	 */
+	publish(
+		queueName: string,
+		payload: string | object,
+		params?: QueuePublishParams
+	): Promise<QueuePublishResult>;
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+/**
+ * Error thrown when a publish operation fails.
+ *
+ * This is a general error for publish failures that aren't specifically
+ * validation or not-found errors.
+ */
+export const QueuePublishError = StructuredError('QueuePublishError');
+
+/**
+ * Error thrown when a queue is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await ctx.queue.publish('non-existent', 'payload');
+ * } catch (error) {
+ *   if (error instanceof QueueNotFoundError) {
+ *     console.error('Queue does not exist');
+ *   }
+ * }
+ * ```
+ */
+export const QueueNotFoundError = StructuredError('QueueNotFoundError');
+
+/**
+ * Error thrown when validation fails.
+ *
+ * Contains the field name and optionally the invalid value for debugging.
+ */
+export const QueueValidationError = StructuredError('QueueValidationError')<{
+	/** The field that failed validation */
+	field: string;
+	/** The invalid value (for debugging) */
+	value?: unknown;
+}>();
+
+// ============================================================================
+// Internal Validation
+// ============================================================================
+
+const MAX_QUEUE_NAME_LENGTH = 256;
+const MAX_PAYLOAD_SIZE = 1048576;
+const MAX_PARTITION_KEY_LENGTH = 256;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+const VALID_QUEUE_NAME_REGEX = /^[a-z_][a-z0-9_-]*$/;
+
+/** @internal */
+function validateQueueNameInternal(name: string): void {
+	if (!name || name.length === 0) {
+		throw new QueueValidationError({
+			message: 'Queue name cannot be empty',
+			field: 'queueName',
+			value: name,
+		});
+	}
+	if (name.length > MAX_QUEUE_NAME_LENGTH) {
+		throw new QueueValidationError({
+			message: `Queue name must not exceed ${MAX_QUEUE_NAME_LENGTH} characters`,
+			field: 'queueName',
+			value: name,
+		});
+	}
+	if (!VALID_QUEUE_NAME_REGEX.test(name)) {
+		throw new QueueValidationError({
+			message:
+				'Queue name must start with a letter or underscore and contain only lowercase letters, digits, underscores, and hyphens',
+			field: 'queueName',
+			value: name,
+		});
+	}
+}
+
+/** @internal */
+function validatePayloadInternal(payload: string): void {
+	if (!payload || payload.length === 0) {
+		throw new QueueValidationError({
+			message: 'Payload cannot be empty',
+			field: 'payload',
+		});
+	}
+	if (payload.length > MAX_PAYLOAD_SIZE) {
+		throw new QueueValidationError({
+			message: `Payload size exceeds ${MAX_PAYLOAD_SIZE} byte limit (${payload.length} bytes)`,
+			field: 'payload',
+			value: payload.length,
+		});
+	}
+}
+
+// ============================================================================
+// QueueStorageService Implementation
+// ============================================================================
+
+/**
+ * HTTP-based implementation of the QueueService interface.
+ *
+ * This service communicates with the Agentuity Queue API to publish messages.
+ * It is automatically configured and available via `ctx.queue` in agent handlers.
+ *
+ * @internal This class is instantiated by the runtime; use `ctx.queue` instead.
+ */
+export class QueueStorageService implements QueueService {
+	#adapter: FetchAdapter;
+	#baseUrl: string;
+
+	/**
+	 * Creates a new QueueStorageService.
+	 *
+	 * @param baseUrl - The base URL of the Queue API
+	 * @param adapter - The fetch adapter for making HTTP requests
+	 */
+	constructor(baseUrl: string, adapter: FetchAdapter) {
+		this.#adapter = adapter;
+		this.#baseUrl = baseUrl;
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	async publish(
+		queueName: string,
+		payload: string | object,
+		params?: QueuePublishParams
+	): Promise<QueuePublishResult> {
+		// Validate inputs before sending to API
+		validateQueueNameInternal(queueName);
+
+		const [body] = await toPayload(payload);
+		const payloadStr = typeof payload === 'string' ? payload : (body as string);
+		validatePayloadInternal(payloadStr);
+
+		// Validate optional params
+		if (params?.partitionKey && params.partitionKey.length > MAX_PARTITION_KEY_LENGTH) {
+			throw new QueueValidationError({
+				message: `Partition key must not exceed ${MAX_PARTITION_KEY_LENGTH} characters`,
+				field: 'partitionKey',
+				value: params.partitionKey.length,
+			});
+		}
+		if (params?.idempotencyKey && params.idempotencyKey.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+			throw new QueueValidationError({
+				message: `Idempotency key must not exceed ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`,
+				field: 'idempotencyKey',
+				value: params.idempotencyKey.length,
+			});
+		}
+		if (params?.ttl !== undefined && params.ttl < 0) {
+			throw new QueueValidationError({
+				message: 'TTL cannot be negative',
+				field: 'ttl',
+				value: params.ttl,
+			});
+		}
+
+		const url = buildUrl(
+			this.#baseUrl,
+			`/queue/messages/publish/2026-01-15/${encodeURIComponent(queueName)}`
+		);
+
+		const requestBody: Record<string, unknown> = {
+			payload: typeof payload === 'string' ? payload : body,
+		};
+
+		if (params?.metadata) {
+			requestBody.metadata = params.metadata;
+		}
+		if (params?.partitionKey) {
+			requestBody.partition_key = params.partitionKey;
+		}
+		if (params?.idempotencyKey) {
+			requestBody.idempotency_key = params.idempotencyKey;
+		}
+		if (params?.ttl !== undefined) {
+			requestBody.ttl_seconds = params.ttl;
+		}
+		if (params?.projectId) {
+			requestBody.project_id = params.projectId;
+		}
+		if (params?.agentId) {
+			requestBody.agent_id = params.agentId;
+		}
+
+		const signal = AbortSignal.timeout(30_000);
+		const res = await this.#adapter.invoke<QueuePublishResult>(url, {
+			method: 'POST',
+			signal,
+			body: JSON.stringify(requestBody),
+			contentType: 'application/json',
+			telemetry: {
+				name: 'agentuity.queue.publish',
+				attributes: {
+					queueName,
+				},
+			},
+		});
+
+		if (res.ok) {
+			const data = res.data as unknown as {
+				message: { id: string; offset: number; published_at: string };
+			};
+			return {
+				id: data.message.id,
+				offset: data.message.offset,
+				publishedAt: data.message.published_at,
+			};
+		}
+
+		if (res.response.status === 404) {
+			throw new QueueNotFoundError({
+				message: `Queue not found: ${queueName}`,
+			});
+		}
+
+		throw await toServiceException('POST', url, res.response);
+	}
+}

package/src/services/sandbox.ts

@@ -507,6 +507,11 @@ export interface SandboxInfo {
 	 */
 	runtimeIconUrl?: string;
 
+	/**
+	 * Runtime brand color (hex color code)
+	 */
+	runtimeBrandColor?: string;
+
 	/**
 	 * Snapshot ID this sandbox was created from
 	 */
@@ -522,6 +527,11 @@ export interface SandboxInfo {
 	 */
 	executions: number;
 
+	/**
+	 * Exit code from the last execution (only available for terminated/failed sandboxes)
+	 */
+	exitCode?: number;
+
 	/**
 	 * URL to the stdout output stream
 	 */