@agentuity/core 1.0.37 → 1.0.38

package/src/services/sandbox/client.ts

@@ -1,7 +1,9 @@
 import {
 	ExecuteOptionsSchema as CoreExecuteOptionsSchema,
 	type SandboxCreateOptions,
+	type SandboxFileInfo,
 	type SandboxInfo,
+	type SandboxStatus,
 	type Execution,
 	type FileToWrite,
 	type SandboxRunOptions,
@@ -12,11 +14,21 @@ import type { Readable, Writable } from 'node:stream';
 import { z } from 'zod';
 import { APIClient } from '../api.ts';
 import { getEnv } from '../env.ts';
-import { sandboxCreate, type SandboxCreateResponse } from './create.ts';
+import { sandboxCreate } from './create.ts';
 import { sandboxDestroy } from './destroy.ts';
 import { sandboxGet } from './get.ts';
 import { sandboxExecute } from './execute.ts';
-import { sandboxWriteFiles, sandboxReadFile } from './files.ts';
+import {
+	sandboxWriteFiles,
+	sandboxReadFile,
+	sandboxListFiles,
+	sandboxMkDir,
+	sandboxRmFile,
+	sandboxRmDir,
+	sandboxSetEnv,
+} from './files.ts';
+import { sandboxPause } from './pause.ts';
+import { sandboxResume } from './resume.ts';
 import { sandboxRun } from './run.ts';
 import { executionGet, type ExecutionInfo } from './execution.ts';
 import { createMinimalLogger } from '../logger.ts';
@@ -130,7 +142,7 @@ export const SandboxClientRunIOSchema = z.object({
 export type SandboxClientRunIO = z.infer<typeof SandboxClientRunIOSchema>;
 
 /**
- * A sandbox instance returned by SandboxClient.create()
+ * A sandbox instance returned by SandboxClient.create() or SandboxClient.connect()
  */
 export interface SandboxInstance {
 	/**
@@ -139,9 +151,9 @@ export interface SandboxInstance {
 	id: string;
 
 	/**
-	 * Sandbox status at creation time
+	 * Sandbox status at creation or connection time
 	 */
-	status: SandboxCreateResponse['status'];
+	status: SandboxStatus;
 
 	/**
 	 * URL to stream stdout output
@@ -173,17 +185,171 @@ export interface SandboxInstance {
 	 */
 	readFile(path: string): Promise<ReadableStream<Uint8Array>>;
 
+	/**
+	 * List files in the sandbox workspace
+	 */
+	listFiles(path?: string): Promise<SandboxFileInfo[]>;
+
+	/**
+	 * Create a directory in the sandbox workspace
+	 */
+	mkDir(path: string, recursive?: boolean): Promise<void>;
+
+	/**
+	 * Remove a file from the sandbox workspace
+	 */
+	rmFile(path: string): Promise<void>;
+
+	/**
+	 * Remove a directory from the sandbox workspace
+	 */
+	rmDir(path: string, recursive?: boolean): Promise<void>;
+
+	/**
+	 * Set environment variables on the sandbox. Pass null to delete a variable.
+	 */
+	setEnv(env: Record<string, string | null>): Promise<Record<string, string>>;
+
 	/**
 	 * Get current sandbox information
 	 */
 	get(): Promise<SandboxInfo>;
 
+	/**
+	 * Pause the sandbox, creating a checkpoint of its current state
+	 */
+	pause(): Promise<void>;
+
+	/**
+	 * Resume the sandbox from a paused or evacuated state
+	 */
+	resume(): Promise<void>;
+
 	/**
 	 * Destroy the sandbox and release all resources
 	 */
 	destroy(): Promise<void>;
 }
 
+/**
+ * Creates the method implementations shared by both create() and connect().
+ * Modelled after the similar helper in packages/runtime/src/services/sandbox/http.ts.
+ */
+function createSandboxInstanceMethods(
+	client: APIClient,
+	sandboxId: string,
+	orgId?: string
+): Omit<
+	SandboxInstance,
+	'id' | 'status' | 'stdoutStreamUrl' | 'stderrStreamUrl' | 'auditStreamUrl'
+> {
+	return {
+		async execute(executeOptions: ExecuteOptions): Promise<Execution> {
+			const { pipe, ...coreOptions } = executeOptions;
+
+			const initialResult = await sandboxExecute(client, {
+				sandboxId,
+				options: coreOptions,
+				orgId,
+				signal: coreOptions.signal,
+			});
+
+			// If pipe options provided, stream the output to the writable streams
+			if (pipe) {
+				const streamPromises: Promise<void>[] = [];
+
+				if (pipe.stdout && initialResult.stdoutStreamUrl) {
+					streamPromises.push(
+						pipeStreamToWritable(
+							initialResult.stdoutStreamUrl,
+							pipe.stdout,
+							coreOptions.signal
+						)
+					);
+				}
+				if (pipe.stderr && initialResult.stderrStreamUrl) {
+					streamPromises.push(
+						pipeStreamToWritable(
+							initialResult.stderrStreamUrl,
+							pipe.stderr,
+							coreOptions.signal
+						)
+					);
+				}
+
+				// Wait for all streams to complete
+				if (streamPromises.length > 0) {
+					await Promise.all(streamPromises);
+				}
+			}
+
+			// Wait for execution to complete and get final result with exit code
+			const finalResult = await waitForExecution(
+				client,
+				initialResult.executionId,
+				orgId,
+				coreOptions.signal
+			);
+
+			return {
+				executionId: finalResult.executionId,
+				status: finalResult.status,
+				exitCode: finalResult.exitCode,
+				durationMs: finalResult.durationMs,
+				stdoutStreamUrl: initialResult.stdoutStreamUrl,
+				stderrStreamUrl: initialResult.stderrStreamUrl,
+			};
+		},
+
+		async writeFiles(files: FileToWrite[]): Promise<number> {
+			const result = await sandboxWriteFiles(client, { sandboxId, files, orgId });
+			return result.filesWritten;
+		},
+
+		async readFile(path: string): Promise<ReadableStream<Uint8Array>> {
+			return sandboxReadFile(client, { sandboxId, path, orgId });
+		},
+
+		async listFiles(path?: string): Promise<SandboxFileInfo[]> {
+			const result = await sandboxListFiles(client, { sandboxId, path, orgId });
+			return result.files;
+		},
+
+		async mkDir(path: string, recursive?: boolean): Promise<void> {
+			await sandboxMkDir(client, { sandboxId, path, recursive, orgId });
+		},
+
+		async rmFile(path: string): Promise<void> {
+			await sandboxRmFile(client, { sandboxId, path, orgId });
+		},
+
+		async rmDir(path: string, recursive?: boolean): Promise<void> {
+			await sandboxRmDir(client, { sandboxId, path, recursive, orgId });
+		},
+
+		async setEnv(env: Record<string, string | null>): Promise<Record<string, string>> {
+			const result = await sandboxSetEnv(client, { sandboxId, env, orgId });
+			return result.env;
+		},
+
+		async get(): Promise<SandboxInfo> {
+			return sandboxGet(client, { sandboxId, orgId });
+		},
+
+		async pause(): Promise<void> {
+			return sandboxPause(client, { sandboxId, orgId });
+		},
+
+		async resume(): Promise<void> {
+			return sandboxResume(client, { sandboxId, orgId });
+		},
+
+		async destroy(): Promise<void> {
+			return sandboxDestroy(client, { sandboxId, orgId });
+		},
+	};
+}
+
 /**
  * Convenience client for sandbox operations.
  *
@@ -284,90 +450,13 @@ export class SandboxClient {
 			orgId: this.#orgId,
 		});
 
-		const sandboxId = response.sandboxId;
-		const client = this.#client;
-		const orgId = this.#orgId;
-
 		return {
-			id: sandboxId,
+			id: response.sandboxId,
 			status: response.status,
 			stdoutStreamUrl: response.stdoutStreamUrl,
 			stderrStreamUrl: response.stderrStreamUrl,
 			auditStreamUrl: response.auditStreamUrl,
-
-			async execute(executeOptions: ExecuteOptions): Promise<Execution> {
-				const { pipe, ...coreOptions } = executeOptions;
-
-				const initialResult = await sandboxExecute(client, {
-					sandboxId,
-					options: coreOptions,
-					orgId,
-					signal: coreOptions.signal,
-				});
-
-				// If pipe options provided, stream the output to the writable streams
-				if (pipe) {
-					const streamPromises: Promise<void>[] = [];
-
-					if (pipe.stdout && initialResult.stdoutStreamUrl) {
-						streamPromises.push(
-							pipeStreamToWritable(
-								initialResult.stdoutStreamUrl,
-								pipe.stdout,
-								coreOptions.signal
-							)
-						);
-					}
-					if (pipe.stderr && initialResult.stderrStreamUrl) {
-						streamPromises.push(
-							pipeStreamToWritable(
-								initialResult.stderrStreamUrl,
-								pipe.stderr,
-								coreOptions.signal
-							)
-						);
-					}
-
-					// Wait for all streams to complete
-					if (streamPromises.length > 0) {
-						await Promise.all(streamPromises);
-					}
-				}
-
-				// Wait for execution to complete and get final result with exit code
-				const finalResult = await waitForExecution(
-					client,
-					initialResult.executionId,
-					orgId,
-					coreOptions.signal
-				);
-
-				return {
-					executionId: finalResult.executionId,
-					status: finalResult.status,
-					exitCode: finalResult.exitCode,
-					durationMs: finalResult.durationMs,
-					stdoutStreamUrl: initialResult.stdoutStreamUrl,
-					stderrStreamUrl: initialResult.stderrStreamUrl,
-				};
-			},
-
-			async writeFiles(files: FileToWrite[]): Promise<number> {
-				const result = await sandboxWriteFiles(client, { sandboxId, files, orgId });
-				return result.filesWritten;
-			},
-
-			async readFile(path: string): Promise<ReadableStream<Uint8Array>> {
-				return sandboxReadFile(client, { sandboxId, path, orgId });
-			},
-
-			async get(): Promise<SandboxInfo> {
-				return sandboxGet(client, { sandboxId, orgId });
-			},
-
-			async destroy(): Promise<void> {
-				return sandboxDestroy(client, { sandboxId, orgId });
-			},
+			...createSandboxInstanceMethods(this.#client, response.sandboxId, this.#orgId),
 		};
 	}
 
@@ -432,4 +521,46 @@ export class SandboxClient {
 			signal,
 		});
 	}
+
+	/**
+	 * Get a full sandbox instance for an existing sandbox by ID.
+	 *
+	 * Unlike `get()` which returns read-only metadata, `connect()` returns
+	 * a `SandboxInstance` with `execute()`, `writeFiles()`, and all other
+	 * interaction methods — allowing you to resume working with a sandbox
+	 * using just its ID.
+	 *
+	 * @param sandboxId - The sandbox ID to connect to
+	 * @returns A sandbox instance with all interaction methods
+	 */
+	async connect(sandboxId: string): Promise<SandboxInstance> {
+		const info = await sandboxGet(this.#client, { sandboxId, orgId: this.#orgId });
+
+		return {
+			id: info.sandboxId,
+			status: info.status,
+			stdoutStreamUrl: info.stdoutStreamUrl,
+			stderrStreamUrl: info.stderrStreamUrl,
+			auditStreamUrl: info.auditStreamUrl,
+			...createSandboxInstanceMethods(this.#client, info.sandboxId, this.#orgId),
+		};
+	}
+
+	/**
+	 * Pause a running sandbox, creating a checkpoint of its current state
+	 *
+	 * @param sandboxId - The sandbox ID to pause
+	 */
+	async pause(sandboxId: string): Promise<void> {
+		return sandboxPause(this.#client, { sandboxId, orgId: this.#orgId });
+	}
+
+	/**
+	 * Resume a paused or evacuated sandbox from its checkpoint
+	 *
+	 * @param sandboxId - The sandbox ID to resume
+	 */
+	async resume(sandboxId: string): Promise<void> {
+		return sandboxResume(this.#client, { sandboxId, orgId: this.#orgId });
+	}
 }

package/src/services/sandbox/pause.ts

@@ -25,7 +25,7 @@ export async function sandboxPause(client: APIClient, params: SandboxPauseParams
 		queryParams.set('orgId', orgId);
 	}
 	const queryString = queryParams.toString();
-	const url = `/sandbox/${sandboxId}/pause${queryString ? `?${queryString}` : ''}`;
+	const url = `/sandbox/${encodeURIComponent(sandboxId)}/pause${queryString ? `?${queryString}` : ''}`;
 
 	const resp = await client.post<z.infer<typeof PauseResponseSchema>>(
 		url,

package/src/services/sandbox/types.ts

@@ -339,11 +339,57 @@ export const SandboxSchema = z.object({
 	readFile: z
 		.custom<(path: string) => Promise<ReadableStream<Uint8Array>>>()
 		.describe('Read a file from the sandbox workspace.'),
+	/** List files in the sandbox workspace. */
+	listFiles: z
+		.custom<(path?: string) => Promise<SandboxFileInfo[]>>()
+		.describe('List files in the sandbox workspace.'),
+	/** Create a directory in the sandbox workspace. */
+	mkDir: z
+		.custom<(path: string, recursive?: boolean) => Promise<void>>()
+		.describe('Create a directory in the sandbox workspace.'),
+	/** Remove a file from the sandbox workspace. */
+	rmFile: z
+		.custom<(path: string) => Promise<void>>()
+		.describe('Remove a file from the sandbox workspace.'),
+	/** Remove a directory from the sandbox workspace. */
+	rmDir: z
+		.custom<(path: string, recursive?: boolean) => Promise<void>>()
+		.describe('Remove a directory from the sandbox workspace.'),
+	/** Set environment variables on the sandbox. Pass null to delete a variable. */
+	setEnv: z
+		.custom<(env: Record<string, string | null>) => Promise<Record<string, string>>>()
+		.describe('Set environment variables on the sandbox. Pass null to delete a variable.'),
+	/** Pause the sandbox, creating a checkpoint of its current state. */
+	pause: z
+		.custom<() => Promise<void>>()
+		.describe('Pause the sandbox, creating a checkpoint of its current state.'),
+	/** Resume the sandbox from a paused or evacuated state. */
+	resume: z
+		.custom<() => Promise<void>>()
+		.describe('Resume the sandbox from a paused or evacuated state.'),
 	/** Destroy the sandbox */
 	destroy: z.custom<() => Promise<void>>().describe('Destroy the sandbox'),
 });
 export type Sandbox = z.infer<typeof SandboxSchema>;
 
+/**
+ * File information returned by sandbox file operations.
+ * NOTE: This interface is structurally identical to FileInfo in ./files.ts.
+ * It is duplicated here to avoid circular type imports. Keep these in sync.
+ */
+export interface SandboxFileInfo {
+	/** File path relative to the listed directory */
+	path: string;
+	/** File size in bytes */
+	size: number;
+	/** Whether the entry is a directory */
+	isDir: boolean;
+	/** Unix permissions as octal string (e.g., "0644") */
+	mode: string;
+	/** Modification time in RFC3339 format */
+	modTime: string;
+}
+
 /** Information about a user who created the sandbox */
 export const SandboxUserInfoSchema = z.object({
 	/** User ID */
@@ -785,9 +831,15 @@ export type SandboxRunResult = z.infer<typeof SandboxRunResultSchema>;
 export interface SandboxService {
 	run(options: SandboxRunOptions): Promise<SandboxRunResult>;
 	create(options?: SandboxCreateOptions): Promise<Sandbox>;
+	/** Get a full Sandbox instance for an existing sandbox by ID. */
+	connect(sandboxId: string): Promise<Sandbox>;
 	get(sandboxId: string): Promise<SandboxInfo>;
 	list(params?: ListSandboxesParams): Promise<ListSandboxesResponse>;
 	destroy(sandboxId: string): Promise<void>;
+	/** Pause a running sandbox, creating a checkpoint of its current state. */
+	pause(sandboxId: string): Promise<void>;
+	/** Resume a paused or evacuated sandbox from its checkpoint. */
+	resume(sandboxId: string): Promise<void>;
 	snapshot: SnapshotService;
 }
 

package/src/services/stream/delete.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { type APIClient } from '../api.ts';
+import { StreamResponseError } from './util.ts';
+
+// --- Response schemas matching Pulse format ---
+
+const DeleteStreamResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+	}),
+]);
+
+type DeleteStreamResponse = z.infer<typeof DeleteStreamResponseSchema>;
+
+const DeleteNamespaceResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		deleted: z.number(),
+	}),
+]);
+
+type DeleteNamespaceResponse = z.infer<typeof DeleteNamespaceResponseSchema>;
+
+// --- Return types ---
+
+export interface StreamDeleteNamespaceResult {
+	deleted: number;
+}
+
+// --- Functions ---
+
+/**
+ * Delete a single stream by ID.
+ *
+ * @param client - The API client configured for Pulse
+ * @param id - The stream ID to delete
+ *
+ * @example
+ * await streamDelete(client, 'strm_abc123');
+ */
+export async function streamDelete(client: APIClient, id: string): Promise<void> {
+	const resp = await client.delete<DeleteStreamResponse>(
+		`/${encodeURIComponent(id)}`,
+		DeleteStreamResponseSchema
+	);
+
+	if (resp.success) {
+		return;
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}
+
+/**
+ * Delete all streams in a namespace (soft delete).
+ *
+ * @param client - The API client configured for Pulse
+ * @param name - The namespace name to delete
+ * @returns The number of streams that were deleted
+ *
+ * @example
+ * const result = await streamDeleteNamespace(client, 'old-logs');
+ * console.log(`Deleted ${result.deleted} streams`);
+ */
+export async function streamDeleteNamespace(
+	client: APIClient,
+	name: string
+): Promise<StreamDeleteNamespaceResult> {
+	const resp = await client.delete<DeleteNamespaceResponse>(
+		`/namespace/${encodeURIComponent(name)}`,
+		DeleteNamespaceResponseSchema
+	);
+
+	if (resp.success) {
+		return { deleted: resp.deleted };
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}

package/src/services/stream/index.ts

@@ -10,5 +10,8 @@ export {
 	type StreamListOptions,
 	streamList,
 } from './list.ts';
+export * from './namespaces.ts';
+export * from './delete.ts';
+export * from './search.ts';
 export * from './service.ts';
 export * from './util.ts';

package/src/services/stream/namespaces.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { type APIClient } from '../api.ts';
+import { StreamResponseError } from './util.ts';
+
+// --- Schemas ---
+
+export const NamespaceInfoSchema = z.object({
+	name: z.string().describe('the namespace name'),
+	count: z.number().describe('number of streams in this namespace'),
+	total_size: z.number().describe('total size in bytes across all streams'),
+	created_at: z.string().describe('ISO 8601 timestamp of the earliest stream'),
+	last_used_at: z.string().describe('ISO 8601 timestamp of the most recent activity'),
+	internal: z.boolean().describe('whether this namespace contains internal/system streams'),
+});
+
+export type NamespaceInfo = z.infer<typeof NamespaceInfoSchema>;
+
+// Response schema matching Pulse's format (NO data wrapper)
+const ListNamespacesResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		namespaces: z.array(NamespaceInfoSchema),
+		total: z.number(),
+	}),
+]);
+
+type ListNamespacesResponse = z.infer<typeof ListNamespacesResponseSchema>;
+
+export const StreamNamespaceEntrySchema = z.object({
+	id: z.string().describe('the stream entry id'),
+	name: z.string().describe('the stream namespace name'),
+	created_at: z.string().nullable().describe('ISO 8601 creation timestamp'),
+	updated_at: z.string().nullable().describe('ISO 8601 last update timestamp'),
+	org_id: z.string().describe('the organization id'),
+	project_id: z.string().nullable().describe('the project id'),
+	chunks: z.number().describe('number of chunks'),
+	completed: z.boolean().describe('whether the stream upload is completed'),
+	size_bytes: z.number().describe('size in bytes'),
+	started_at: z.string().nullable().describe('ISO 8601 stream start timestamp'),
+	ended_at: z.string().nullable().describe('ISO 8601 stream end timestamp'),
+	headers: z.record(z.string(), z.string()).nullable().optional().describe('stream headers'),
+	metadata: z.record(z.string(), z.string()).nullable().optional().describe('stream metadata'),
+	expires_at: z.string().nullable().describe('ISO 8601 expiration timestamp or null'),
+	url: z.string().describe('public URL to access the stream'),
+});
+
+export type StreamNamespaceEntry = z.infer<typeof StreamNamespaceEntrySchema>;
+
+const GetNamespaceResponseSchema = z.discriminatedUnion('success', [
+	z.object({
+		success: z.literal<false>(false),
+		message: z.string().optional(),
+	}),
+	z.object({
+		success: z.literal<true>(true),
+		name: z.string(),
+		entries: z.array(StreamNamespaceEntrySchema),
+		total: z.number(),
+		total_size: z.number(),
+	}),
+]);
+
+type GetNamespaceResponse = z.infer<typeof GetNamespaceResponseSchema>;
+
+// --- Options ---
+
+export interface StreamListNamespacesOptions {
+	limit?: number;
+	offset?: number;
+}
+
+export interface StreamGetNamespaceOptions {
+	limit?: number;
+	offset?: number;
+}
+
+// --- Return types ---
+
+export interface StreamNamespacesResult {
+	namespaces: NamespaceInfo[];
+	total: number;
+}
+
+export interface StreamNamespaceResult {
+	name: string;
+	entries: StreamNamespaceEntry[];
+	total: number;
+	totalSize: number;
+}
+
+// --- Functions ---
+
+/**
+ * List stream namespaces (aggregated view).
+ * Each namespace groups streams by name, showing count, total size, and timestamps.
+ *
+ * @param client - The API client configured for Pulse
+ * @param options - Pagination options
+ * @returns Aggregated namespace list with total count
+ *
+ * @example
+ * const result = await streamListNamespaces(client, { limit: 50 });
+ * console.log(`Found ${result.total} namespaces`);
+ */
+export async function streamListNamespaces(
+	client: APIClient,
+	options: StreamListNamespacesOptions = {}
+): Promise<StreamNamespacesResult> {
+	const resp = await client.post<ListNamespacesResponse>(
+		'/namespaces',
+		{ limit: options.limit, offset: options.offset },
+		ListNamespacesResponseSchema
+	);
+
+	if (resp.success) {
+		return { namespaces: resp.namespaces, total: resp.total };
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}
+
+/**
+ * Get entries within a specific stream namespace.
+ * Returns full detail for each stream entry in the namespace.
+ *
+ * @param client - The API client configured for Pulse
+ * @param name - The namespace name
+ * @param options - Pagination options
+ * @returns Namespace entries with total count and size
+ *
+ * @example
+ * const result = await streamGetNamespace(client, 'agent-logs', { limit: 100 });
+ * console.log(`${result.total} entries, ${result.totalSize} bytes total`);
+ */
+export async function streamGetNamespace(
+	client: APIClient,
+	name: string,
+	options: StreamGetNamespaceOptions = {}
+): Promise<StreamNamespaceResult> {
+	const resp = await client.post<GetNamespaceResponse>(
+		`/namespace/${encodeURIComponent(name)}/info`,
+		{ limit: options.limit, offset: options.offset },
+		GetNamespaceResponseSchema
+	);
+
+	if (resp.success) {
+		return {
+			name: resp.name,
+			entries: resp.entries,
+			total: resp.total,
+			totalSize: resp.total_size,
+		};
+	}
+
+	throw new StreamResponseError({ message: resp.message });
+}