@agentuity/core 3.0.0-alpha.7 → 3.0.0-beta.1

package/src/services/oauth/token-storage.ts

@@ -112,9 +112,12 @@ function toStoredToken(token: OAuthTokenResponse): StoredToken {
  * @example
  * ```typescript
  * import { KeyValueTokenStorage } from '@agentuity/core/oauth';
+ * import { KeyValueClient } from '@agentuity/keyvalue';
+ *
+ * const kv = new KeyValueClient();
  *
  * // Create storage with auto-refresh enabled
- * const storage = new KeyValueTokenStorage(ctx.kv, {
+ * const storage = new KeyValueTokenStorage(kv, {
  *   config: { issuer: 'https://auth.example.com' },
  * });
  *

package/src/services/queue/service.ts

@@ -3,14 +3,15 @@
  *
  * 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.
+ * Used internally by `@agentuity/queue`'s `QueueClient`. App code should
+ * use `QueueClient` directly rather than reaching for these primitives.
  *
- * @example Publishing from an agent
+ * @example
  * ```typescript
- * // Inside an agent handler
- * const result = await ctx.queue.publish('order-queue', {
+ * import { QueueClient } from '@agentuity/queue';
+ *
+ * const queue = new QueueClient();
+ * const result = await queue.publish('order-queue', {
  *   orderId: 123,
  *   action: 'process',
  * });
@@ -121,7 +122,7 @@ export type QueuePublishResult = z.infer<typeof QueuePublishResultSchema>;
  *
  * @example
  * ```typescript
- * const result = await ctx.queue.createQueue('my-queue', {
+ * const result = await queue.createQueue('my-queue', {
  *   queueType: 'pubsub',
  *   settings: { defaultTtlSeconds: 86400 },
  * });
@@ -195,25 +196,23 @@ export type QueueCreateResult = z.infer<typeof QueueCreateResultSchema>;
 /**
  * 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.
+ * Provides a simple publish-only surface suitable for app handlers.
+ * Implemented by `QueueStorageService` (cloud) and `LocalQueueStorage`
+ * (local dev).
  *
- * For full queue management (create queues, consume messages, manage destinations),
- * use the `@agentuity/server` package.
+ * For full queue management (create queues, consume messages, manage
+ * destinations), use the `@agentuity/queue` package directly.
  *
  * @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 };
- *   },
+ * import { QueueClient } from '@agentuity/queue';
+ *
+ * const queue = new QueueClient();
+ *
+ * await queue.publish('notifications', {
+ *   type: 'email',
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
  * });
  * ```
  */
@@ -234,12 +233,12 @@ export interface QueueService {
 	 *
 	 * @example Publishing a simple message
 	 * ```typescript
-	 * const result = await ctx.queue.publish('my-queue', 'Hello, World!');
+	 * const result = await queue.publish('my-queue', 'Hello, World!');
 	 * ```
 	 *
 	 * @example Publishing with options
 	 * ```typescript
-	 * const result = await ctx.queue.publish('my-queue', { task: 'process' }, {
+	 * const result = await queue.publish('my-queue', { task: 'process' }, {
 	 *   metadata: { priority: 'high' },
 	 *   idempotencyKey: 'task-123',
 	 *   ttl: 3600,
@@ -265,12 +264,12 @@ export interface QueueService {
 	 *
 	 * @example Creating a worker queue
 	 * ```typescript
-	 * const result = await ctx.queue.createQueue('task-queue');
+	 * const result = await queue.createQueue('task-queue');
 	 * ```
 	 *
 	 * @example Creating a pubsub queue with settings
 	 * ```typescript
-	 * const result = await ctx.queue.createQueue('events', {
+	 * const result = await queue.createQueue('events', {
 	 *   queueType: 'pubsub',
 	 *   settings: { defaultTtlSeconds: 86400 },
 	 * });
@@ -290,7 +289,7 @@ export interface QueueService {
 	 *
 	 * @example Deleting a queue
 	 * ```typescript
-	 * await ctx.queue.deleteQueue('old-queue');
+	 * await queue.deleteQueue('old-queue');
 	 * ```
 	 */
 	deleteQueue(queueName: string): Promise<void>;
@@ -322,7 +321,7 @@ export const QueueCreateError = StructuredError('QueueCreateError');
  * @example
  * ```typescript
  * try {
- *   await ctx.queue.publish('non-existent', 'payload');
+ *   await queue.publish('non-existent', 'payload');
  * } catch (error) {
  *   if (error instanceof QueueNotFoundError) {
  *     console.error('Queue does not exist');
@@ -429,12 +428,11 @@ function unwrapApiResponse<T>(data: unknown, key: string): T {
 // ============================================================================
 
 /**
- * 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.
+ * HTTP-based implementation of the {@link QueueService} interface.
  *
- * @internal This class is instantiated by the runtime; use `ctx.queue` instead.
+ * This service communicates with the Agentuity Queue API to publish
+ * messages. App code should use `QueueClient` from `@agentuity/queue`
+ * rather than instantiating this class directly.
  */
 export class QueueStorageService implements QueueService {
 	#adapter: FetchAdapter;

package/src/services/sandbox/api-reference.ts

@@ -613,7 +613,7 @@ const service: Service = {
 			],
 			requestBody: {
 				description: 'Snapshot creation payload.',
-				fields: { schema: SnapshotCreateOptionsSchema },
+				fields: { schema: SnapshotCreateOptionsSchema.omit({ orgId: true }) },
 			},
 			responseDescription: 'Returns the created snapshot.',
 			statuses: [
@@ -887,15 +887,15 @@ const service: Service = {
 			exampleHeaders: { 'Content-Type': 'application/gzip' },
 			exampleBody: '<binary gzip data>',
 		},
-		// ── Disk Checkpoints ──────────────────────────────────────────────
+		// ── Sandbox Checkpoints ───────────────────────────────────────────
 		{
 			id: 'create-checkpoint',
 			title: 'Create Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'POST',
 			path: '/sandbox/{sandboxId}/checkpoint',
 			description:
-				'Create a named checkpoint of the sandbox filesystem. Checkpoint names must be unique — creating a checkpoint with a name that already exists returns 409 Conflict. Disk checkpoints are persisted across pause/resume cycles.',
+				'Create a named checkpoint of the sandbox filesystem. Checkpoint names must be unique — creating a checkpoint with a name that already exists returns 409 Conflict. Checkpoints are persisted across pause/resume cycles.',
 			pathParams: [
 				{ name: 'sandboxId', type: 'string', description: 'Sandbox ID', required: true },
 			],
@@ -923,11 +923,11 @@ const service: Service = {
 		{
 			id: 'list-checkpoints',
 			title: 'List Checkpoints',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'GET',
 			path: '/sandbox/checkpoints/{sandboxId}',
 			description:
-				'List checkpoints for a specific sandbox. Disk checkpoints are persisted across pause/resume cycles.',
+				'List checkpoints for a specific sandbox. Checkpoints are persisted across pause/resume cycles.',
 			pathParams: [
 				{ name: 'sandboxId', type: 'string', description: 'Sandbox ID', required: true },
 			],
@@ -947,7 +947,7 @@ const service: Service = {
 		{
 			id: 'restore-checkpoint',
 			title: 'Restore Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'POST',
 			path: '/sandbox/{sandboxId}/checkpoint/{checkpointId}/restore',
 			description: 'Restore the sandbox filesystem to a checkpoint state.',
@@ -971,7 +971,7 @@ const service: Service = {
 		{
 			id: 'delete-checkpoint',
 			title: 'Delete Checkpoint',
-			sectionTitle: 'Disk Checkpoints',
+			sectionTitle: 'Sandbox Checkpoints',
 			method: 'DELETE',
 			path: '/sandbox/{sandboxId}/checkpoint/{checkpointId}',
 			description: 'Delete a checkpoint.',

package/src/services/sandbox/client.ts

@@ -34,7 +34,7 @@ import {
 	sandboxRmDir,
 	sandboxSetEnv,
 } from './files.ts';
-import { sandboxPause } from './pause.ts';
+import { sandboxPause, type SandboxPauseResult } from './pause.ts';
 import { sandboxResume } from './resume.ts';
 import { sandboxRun } from './run.ts';
 import {
@@ -281,7 +281,7 @@ export interface SandboxInstance {
 	/**
 	 * Pause the sandbox, creating a checkpoint of its current state
 	 */
-	pause(): Promise<void>;
+	pause(): Promise<SandboxPauseResult>;
 
 	/**
 	 * Resume the sandbox from a paused or evacuated state
@@ -399,7 +399,7 @@ function createSandboxInstanceMethods(
 			return sandboxGet(client, { sandboxId, orgId });
 		},
 
-		async pause(): Promise<void> {
+		async pause(): Promise<SandboxPauseResult> {
 			return sandboxPause(client, { sandboxId, orgId });
 		},
 
@@ -725,7 +725,7 @@ export class SandboxClient {
 	 *
 	 * @param sandboxId - The sandbox ID to pause
 	 */
-	async pause(sandboxId: string): Promise<void> {
+	async pause(sandboxId: string): Promise<SandboxPauseResult> {
 		return sandboxPause(this.#client, { sandboxId, orgId: this.#orgId });
 	}
 

package/src/services/sandbox/create.ts

@@ -49,6 +49,12 @@ export const SandboxCreateRequestSchema = z
 			.object({
 				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h")'),
 				execution: z.string().optional().describe('Maximum execution time (e.g., "30m", "2h")'),
+				paused: z
+					.string()
+					.optional()
+					.describe(
+						'Maximum time sandbox can remain paused before termination (e.g., "24h", "0s" for infinite)'
+					),
 			})
 			.optional()
 			.describe('Timeout settings for the sandbox'),
@@ -139,6 +145,10 @@ export const SandboxCreateDataSchema = z
 				'failed',
 			])
 			.describe('Current status of the sandbox'),
+		executionId: z
+			.string()
+			.optional()
+			.describe('Initial execution identifier for oneshot sandbox creation'),
 		url: z
 			.string()
 			.optional()

package/src/services/sandbox/get.ts

@@ -156,7 +156,7 @@ export const SandboxInfoDataSchema = z
 		user: SandboxUserInfoSchema.optional().describe('User who created the sandbox'),
 		agent: SandboxAgentInfoSchema.optional().describe('Agent associated with the sandbox'),
 		project: SandboxProjectInfoSchema.optional().describe('Project associated with the sandbox'),
-		org: SandboxOrgInfoSchema.describe('Organization associated with the sandbox'),
+		org: SandboxOrgInfoSchema.nullish().describe('Organization associated with the sandbox'),
 		timeout: z
 			.object({
 				idle: z.string().optional().describe('Idle timeout duration (e.g., "5m", "1h").'),
@@ -164,6 +164,10 @@ export const SandboxInfoDataSchema = z
 					.string()
 					.optional()
 					.describe('Execution timeout duration (e.g., "30m", "2h").'),
+				paused: z
+					.string()
+					.optional()
+					.describe('Paused timeout duration (e.g., "24h", "0s" for infinite).'),
 			})
 			.optional()
 			.describe('Timeout configuration for the sandbox.'),
@@ -189,6 +193,16 @@ export const SandboxGetParamsSchema = z.object({
 		.boolean()
 		.optional()
 		.describe('Whether deleted sandboxes should be included in lookup'),
+	waitForStatus: z
+		.union([z.string(), z.array(z.string())])
+		.optional()
+		.describe('Optional desired status or statuses to wait for before responding'),
+	waitMs: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Maximum time in milliseconds to wait for the desired status'),
 });
 
 export type SandboxGetParams = z.infer<typeof SandboxGetParamsSchema>;
@@ -205,7 +219,7 @@ export async function sandboxGet(
 	client: APIClient,
 	params: SandboxGetParams
 ): Promise<SandboxInfo> {
-	const { sandboxId, orgId, includeDeleted } = params;
+	const { sandboxId, orgId, includeDeleted, waitForStatus, waitMs } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
@@ -213,6 +227,15 @@ export async function sandboxGet(
 	if (includeDeleted) {
 		queryParams.set('includeDeleted', 'true');
 	}
+	if (waitForStatus) {
+		queryParams.set(
+			'waitForStatus',
+			Array.isArray(waitForStatus) ? waitForStatus.join(',') : waitForStatus
+		);
+	}
+	if (waitMs != null) {
+		queryParams.set('waitMs', String(waitMs));
+	}
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${encodeURIComponent(sandboxId)}${queryString ? `?${queryString}` : ''}`;
 
@@ -222,6 +245,12 @@ export async function sandboxGet(
 	);
 
 	if (resp.success) {
+		// Newly created sandboxes can be served from the server's pending cache before
+		// the backing row and related org hydration are fully available. That response
+		// serializes `org: null`, so normalize it to a placeholder object instead of
+		// failing response validation for an otherwise valid sandbox status poll.
+		const org = resp.data.org ?? { id: orgId ?? '', name: '' };
+
 		return {
 			sandboxId: resp.data.sandboxId,
 			identifier: resp.data.identifier,
@@ -252,7 +281,7 @@ export async function sandboxGet(
 			user: resp.data.user,
 			agent: resp.data.agent,
 			project: resp.data.project,
-			org: resp.data.org,
+			org,
 			timeout: resp.data.timeout,
 			command: resp.data.command,
 		};

package/src/services/sandbox/getStatus.ts

@@ -13,6 +13,17 @@ const SandboxStatusResponseSchema = APIResponseSchema(SandboxStatusDataSchema);
 export const SandboxGetStatusParamsSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID to retrieve status for'),
 	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	waitForStatus: z
+		.union([z.string(), z.array(z.string())])
+		.optional()
+		.describe('Optional desired status or statuses to wait for before responding'),
+	waitMs: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Maximum time in milliseconds to wait for the desired status'),
+	signal: z.custom<AbortSignal>().optional().describe('abort signal for cancellation'),
 });
 
 export type SandboxGetStatusParams = z.infer<typeof SandboxGetStatusParamsSchema>;
@@ -26,17 +37,27 @@ export async function sandboxGetStatus(
 	client: APIClient,
 	params: SandboxGetStatusParams
 ): Promise<SandboxStatusResult> {
-	const { sandboxId, orgId } = params;
+	const { sandboxId, orgId, waitForStatus, waitMs, signal } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
 	}
+	if (waitForStatus) {
+		queryParams.set(
+			'waitForStatus',
+			Array.isArray(waitForStatus) ? waitForStatus.join(',') : waitForStatus
+		);
+	}
+	if (waitMs != null) {
+		queryParams.set('waitMs', String(waitMs));
+	}
 	const queryString = queryParams.toString();
 	const url = `/sandbox/status/${sandboxId}${queryString ? `?${queryString}` : ''}`;
 
 	const resp = await client.get<z.infer<typeof SandboxStatusResponseSchema>>(
 		url,
-		SandboxStatusResponseSchema
+		SandboxStatusResponseSchema,
+		signal
 	);
 
 	if (resp.success) {

package/src/services/sandbox/index.ts

@@ -52,7 +52,7 @@ export {
 	diskCheckpointRestore,
 	diskCheckpointDelete,
 } from './disk-checkpoint.ts';
-export type { SandboxPauseParams } from './pause.ts';
+export type { SandboxPauseParams, SandboxPauseResult } from './pause.ts';
 export { PauseResponseSchema, SandboxPauseParamsSchema, sandboxPause } from './pause.ts';
 export type { SandboxResumeParams } from './resume.ts';
 export { ResumeResponseSchema, SandboxResumeParamsSchema, sandboxResume } from './resume.ts';

package/src/services/sandbox/list.ts

@@ -112,6 +112,10 @@ export const SandboxInfoSchema = z
 					.string()
 					.optional()
 					.describe('Execution timeout duration (e.g., "30m", "2h").'),
+				paused: z
+					.string()
+					.optional()
+					.describe('Paused timeout duration (e.g., "24h", "0s" for infinite).'),
 			})
 			.optional()
 			.describe('Timeout configuration for the sandbox.'),
@@ -225,6 +229,7 @@ export async function sandboxList(
 				networkPort: s.networkPort,
 				url: s.url,
 				org: s.org,
+				timeout: s.timeout,
 			})),
 			total: resp.data.total,
 		};

package/src/services/sandbox/pause.ts

@@ -1,8 +1,21 @@
 import { z } from 'zod';
-import { type APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { type APIClient } from '../api.ts';
 import { throwSandboxError } from './util.ts';
 
-export const PauseResponseSchema = APIResponseSchemaNoData();
+export const PauseResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string(),
+		code: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		sandboxId: z.string(),
+		status: z.string(),
+		checkpointId: z.string().optional(),
+		terminatesAt: z.string().optional(),
+	}),
+]);
 
 export const SandboxPauseParamsSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID to pause'),
@@ -11,14 +24,30 @@ export const SandboxPauseParamsSchema = z.object({
 
 export type SandboxPauseParams = z.infer<typeof SandboxPauseParamsSchema>;
 
+/** Result returned from pausing a sandbox */
+export interface SandboxPauseResult {
+	/** The sandbox ID that was paused */
+	sandboxId: string;
+	/** New status (typically "suspended") */
+	status: string;
+	/** Checkpoint ID created during pause */
+	checkpointId?: string;
+	/** ISO 8601 timestamp when sandbox will auto-terminate if not resumed (omitted if no paused timeout) */
+	terminatesAt?: string;
+}
+
 /**
  * Pauses a running sandbox, creating a checkpoint of its current state.
  *
  * @param client - The API client to use for the request
  * @param params - Parameters including the sandbox ID to pause
+ * @returns Pause result including terminatesAt if a paused timeout is configured
  * @throws {SandboxResponseError} If the sandbox is not found or pause fails
  */
-export async function sandboxPause(client: APIClient, params: SandboxPauseParams): Promise<void> {
+export async function sandboxPause(
+	client: APIClient,
+	params: SandboxPauseParams
+): Promise<SandboxPauseResult> {
 	const { sandboxId, orgId } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
@@ -34,7 +63,12 @@ export async function sandboxPause(client: APIClient, params: SandboxPauseParams
 	);
 
 	if (resp.success) {
-		return;
+		return {
+			sandboxId: resp.sandboxId,
+			status: resp.status,
+			checkpointId: resp.checkpointId,
+			terminatesAt: resp.terminatesAt,
+		};
 	}
 
 	throwSandboxError(resp, { sandboxId });