@agentuity/runtime 0.0.105 → 0.0.106

package/src/services/sandbox/http.ts

@@ -0,0 +1,215 @@
+import {
+	APIClient,
+	sandboxCreate,
+	sandboxDestroy,
+	sandboxExecute,
+	sandboxGet,
+	sandboxList,
+	sandboxRun,
+	sandboxWriteFiles,
+	sandboxReadFile,
+} from '@agentuity/server';
+import type {
+	SandboxService,
+	Sandbox,
+	SandboxInfo,
+	SandboxCreateOptions,
+	SandboxRunOptions,
+	SandboxRunResult,
+	ListSandboxesParams,
+	ListSandboxesResponse,
+	ExecuteOptions,
+	Execution,
+	StreamReader,
+	SandboxStatus,
+	FileToWrite,
+} from '@agentuity/core';
+import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+
+const TRACER_NAME = 'agentuity.sandbox';
+
+async function withSpan<T>(
+	name: string,
+	attributes: Record<string, string | number | boolean>,
+	fn: () => Promise<T>
+): Promise<T> {
+	const tracer = trace.getTracer(TRACER_NAME);
+	const currentContext = context.active();
+	const span = tracer.startSpan(name, { attributes, kind: SpanKind.CLIENT }, currentContext);
+	const spanContext = trace.setSpan(currentContext, span);
+
+	try {
+		const result = await context.with(spanContext, fn);
+		span.setStatus({ code: SpanStatusCode.OK });
+		return result;
+	} catch (err) {
+		const e = err as Error;
+		span.recordException(e);
+		span.setStatus({ code: SpanStatusCode.ERROR, message: e?.message ?? String(err) });
+		throw err;
+	} finally {
+		span.end();
+	}
+}
+
+function createStreamReader(id: string | undefined, baseUrl: string): StreamReader {
+	const streamId = id ?? '';
+	const url = streamId ? `${baseUrl}/${streamId}` : '';
+
+	return {
+		id: streamId,
+		url,
+		readonly: true as const,
+		getReader(): ReadableStream<Uint8Array> {
+			if (!url) {
+				return new ReadableStream({
+					start(controller) {
+						controller.close();
+					},
+				});
+			}
+			return new ReadableStream({
+				async start(controller) {
+					try {
+						const response = await fetch(url);
+						if (!response.ok || !response.body) {
+							controller.close();
+							return;
+						}
+						const reader = response.body.getReader();
+						while (true) {
+							const { done, value } = await reader.read();
+							if (done) break;
+							controller.enqueue(value);
+						}
+						controller.close();
+					} catch {
+						controller.close();
+					}
+				},
+			});
+		},
+	};
+}
+
+function createSandboxInstance(
+	client: APIClient,
+	sandboxId: string,
+	status: SandboxStatus,
+	streamBaseUrl: string,
+	stdoutStreamId?: string,
+	stderrStreamId?: string
+): Sandbox {
+	const interleaved = !!(stdoutStreamId && stderrStreamId && stdoutStreamId === stderrStreamId);
+	return {
+		id: sandboxId,
+		status,
+		stdout: createStreamReader(stdoutStreamId, streamBaseUrl),
+		stderr: createStreamReader(stderrStreamId, streamBaseUrl),
+		interleaved,
+
+		async execute(options: ExecuteOptions): Promise<Execution> {
+			return withSpan(
+				'agentuity.sandbox.execute',
+				{
+					'sandbox.id': sandboxId,
+					'sandbox.command': options.command?.join(' ') ?? '',
+				},
+				() => sandboxExecute(client, { sandboxId, options, signal: options.signal })
+			);
+		},
+
+		async writeFiles(files: FileToWrite[]): Promise<void> {
+			await withSpan(
+				'agentuity.sandbox.writeFiles',
+				{
+					'sandbox.id': sandboxId,
+					'sandbox.files.count': files.length,
+				},
+				() => sandboxWriteFiles(client, { sandboxId, files })
+			);
+		},
+
+		async readFile(path: string): Promise<ReadableStream<Uint8Array>> {
+			return withSpan(
+				'agentuity.sandbox.readFile',
+				{
+					'sandbox.id': sandboxId,
+					'sandbox.file.path': path,
+				},
+				() => sandboxReadFile(client, { sandboxId, path })
+			);
+		},
+
+		async destroy(): Promise<void> {
+			await withSpan('agentuity.sandbox.destroy', { 'sandbox.id': sandboxId }, () =>
+				sandboxDestroy(client, { sandboxId })
+			);
+		},
+	};
+}
+
+export class HTTPSandboxService implements SandboxService {
+	private client: APIClient;
+	private streamBaseUrl: string;
+
+	constructor(client: APIClient, streamBaseUrl: string) {
+		this.client = client;
+		this.streamBaseUrl = streamBaseUrl;
+	}
+
+	async run(options: SandboxRunOptions): Promise<SandboxRunResult> {
+		return withSpan(
+			'agentuity.sandbox.run',
+			{
+				'sandbox.command': options.command?.exec?.join(' ') ?? '',
+				'sandbox.mode': 'oneshot',
+			},
+			() => sandboxRun(this.client, { options })
+		);
+	}
+
+	async create(options?: SandboxCreateOptions): Promise<Sandbox> {
+		return withSpan(
+			'agentuity.sandbox.create',
+			{
+				'sandbox.network': options?.network?.enabled ?? false,
+				'sandbox.snapshot': options?.snapshot ?? '',
+			},
+			async () => {
+				const response = await sandboxCreate(this.client, { options });
+				return createSandboxInstance(
+					this.client,
+					response.sandboxId,
+					response.status,
+					this.streamBaseUrl,
+					response.stdoutStreamId,
+					response.stderrStreamId
+				);
+			}
+		);
+	}
+
+	async get(sandboxId: string): Promise<SandboxInfo> {
+		return withSpan('agentuity.sandbox.get', { 'sandbox.id': sandboxId }, () =>
+			sandboxGet(this.client, { sandboxId })
+		);
+	}
+
+	async list(params?: ListSandboxesParams): Promise<ListSandboxesResponse> {
+		return withSpan(
+			'agentuity.sandbox.list',
+			{
+				'sandbox.status': params?.status ?? '',
+				'sandbox.limit': params?.limit ?? 50,
+			},
+			() => sandboxList(this.client, params)
+		);
+	}
+
+	async destroy(sandboxId: string): Promise<void> {
+		return withSpan('agentuity.sandbox.destroy', { 'sandbox.id': sandboxId }, () =>
+			sandboxDestroy(this.client, { sandboxId })
+		);
+	}
+}

package/src/services/sandbox/index.ts

@@ -0,0 +1 @@
+export { HTTPSandboxService } from './http';

package/src/services/session/http.ts

@@ -13,7 +13,10 @@ import { internal } from '../../logger/internal';
 const SessionResponseError = StructuredError('SessionResponseError');
 
 /**
- * An implementation of the SessionEventProvider which uses HTTP for delivery
+ * An implementation of the SessionEventProvider which uses HTTP for delivery.
+ *
+ * This provider checks that the event has required fields (orgId, projectId for start events)
+ * before sending to the backend. If required fields are missing, the event is silently skipped.
  */
 export class HTTPSessionEventProvider implements SessionEventProvider {
 	private apiClient: APIClient;
@@ -24,12 +27,33 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 		this.logger = logger;
 	}
 
+	/**
+	 * Check if a start event has all required fields for HTTP delivery
+	 */
+	private canSendStartEvent(event: SessionStartEvent): boolean {
+		// orgId and projectId are required for the backend
+		if (!event.orgId || !event.projectId) {
+			internal.info(
+				'[session-http] skipping start event - missing required fields: orgId=%s, projectId=%s',
+				event.orgId ?? 'missing',
+				event.projectId ?? 'missing'
+			);
+			return false;
+		}
+		return true;
+	}
+
 	/**
 	 * called when the session starts
 	 *
 	 * @param event SessionStartEvent
 	 */
 	async start(event: SessionStartEvent): Promise<void> {
+		// Check required fields before sending
+		if (!this.canSendStartEvent(event)) {
+			return;
+		}
+
 		internal.info('[session-http] sending start event: %s', event.id);
 		this.logger.debug('Sending session start event: %s', event.id);
 		const resp = await this.apiClient.post(
@@ -41,18 +65,32 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 		if (resp.success) {
 			internal.info('[session-http] start event sent successfully: %s', event.id);
 			this.logger.debug('Session start event sent successfully: %s', event.id);
+			this.startedSessions.add(event.id);
 			return;
 		}
 		internal.info('[session-http] start event failed: %s - %s', event.id, resp.message);
 		throw new SessionResponseError({ message: resp.message });
 	}
 
+	/**
+	 * Track session IDs that have been started (to know if we should send complete)
+	 */
+	private startedSessions = new Set<string>();
+
 	/**
 	 * called when the session completes
 	 *
 	 * @param event SessionCompleteEvent
 	 */
 	async complete(event: SessionCompleteEvent): Promise<void> {
+		// Only send complete if we successfully sent a start event
+		// This prevents sending orphaned complete events when start was skipped
+		if (!this.startedSessions.has(event.id)) {
+			internal.info('[session-http] skipping complete event - no matching start: %s', event.id);
+			return;
+		}
+		this.startedSessions.delete(event.id);
+
 		internal.info(
 			'[session-http] sending complete event: %s, userData: %s',
 			event.id,

package/src/services/thread/local.ts

@@ -5,6 +5,7 @@ import type { Env } from '../../app';
 import {
 	DefaultThread,
 	DefaultThreadIDProvider,
+	parseThreadData,
 	validateThreadIdOrThrow,
 	type Thread,
 	type ThreadIDProvider,
@@ -54,15 +55,17 @@ export class LocalThreadProvider implements ThreadProvider {
 		const row = this.db
 			.query<{ state: string }, [string]>('SELECT state FROM threads WHERE id = ?')
 			.get(threadId);
-		const initialStateJson = row?.state;
 
-		// Create thread with restored state
-		const thread = new DefaultThread(this, threadId, initialStateJson);
+		// Parse the stored data, handling both old (flat) and new ({ state, metadata }) formats
+		const { flatStateJson, metadata } = parseThreadData(row?.state);
+
+		// Create thread with restored state and metadata
+		const thread = new DefaultThread(this, threadId, flatStateJson, metadata);
 
 		// Populate thread state from restored data
-		if (initialStateJson) {
+		if (flatStateJson) {
 			try {
-				const data = JSON.parse(initialStateJson);
+				const data = JSON.parse(flatStateJson);
 				for (const [key, value] of Object.entries(data)) {
 					thread.state.set(key, value);
 				}

package/src/session.ts

@@ -8,6 +8,39 @@ import { getServiceUrls } from '@agentuity/server';
 import { internal } from './logger/internal';
 import { timingSafeEqual } from 'node:crypto';
 
+/**
+ * Result of parsing serialized thread data.
+ * @internal
+ */
+export interface ParsedThreadData {
+	flatStateJson?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Parse serialized thread data, handling both old (flat state) and new ({ state, metadata }) formats.
+ * @internal
+ */
+export function parseThreadData(raw: string | undefined): ParsedThreadData {
+	if (!raw) {
+		return {};
+	}
+
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === 'object' && ('state' in parsed || 'metadata' in parsed)) {
+			return {
+				flatStateJson: parsed.state ? JSON.stringify(parsed.state) : undefined,
+				metadata:
+					parsed.metadata && typeof parsed.metadata === 'object' ? parsed.metadata : undefined,
+			};
+		}
+		return { flatStateJson: raw };
+	} catch {
+		return { flatStateJson: raw };
+	}
+}
+
 export type ThreadEventName = 'destroyed';
 export type SessionEventName = 'completed';
 
@@ -271,6 +304,10 @@ export interface ThreadIDProvider {
  * The default implementation (DefaultThreadProvider) stores threads in-memory
  * with cookie-based identification and 1-hour expiration.
  *
+ * Thread state is serialized using `getSerializedState()` which returns a JSON
+ * envelope: `{ "state": {...}, "metadata": {...} }`. Use `parseThreadData()` to
+ * correctly parse both old (flat) and new (envelope) formats on restore.
+ *
  * @example
  * ```typescript
  * class RedisThreadProvider implements ThreadProvider {
@@ -283,19 +320,29 @@ export interface ThreadIDProvider {
  *   async restore(ctx: Context<Env>): Promise<Thread> {
  *     const threadId = ctx.req.header('x-thread-id') || getCookie(ctx, 'atid') || generateId('thrd');
  *     const data = await this.redis.get(`thread:${threadId}`);
- *     const thread = new DefaultThread(this, threadId);
- *     if (data) {
- *       thread.state = new Map(JSON.parse(data));
+ *
+ *     // Parse stored data, handling both old and new formats
+ *     const { flatStateJson, metadata } = parseThreadData(data);
+ *     const thread = new DefaultThread(this, threadId, flatStateJson, metadata);
+ *
+ *     // Populate state from parsed data
+ *     if (flatStateJson) {
+ *       const stateObj = JSON.parse(flatStateJson);
+ *       for (const [key, value] of Object.entries(stateObj)) {
+ *         thread.state.set(key, value);
+ *       }
  *     }
  *     return thread;
  *   }
  *
  *   async save(thread: Thread): Promise<void> {
- *     await this.redis.setex(
- *       `thread:${thread.id}`,
- *       3600,
- *       JSON.stringify([...thread.state])
- *     );
+ *     if (thread instanceof DefaultThread && thread.isDirty()) {
+ *       await this.redis.setex(
+ *         `thread:${thread.id}`,
+ *         3600,
+ *         thread.getSerializedState()
+ *       );
+ *     }
  *   }
  *
  *   async destroy(thread: Thread): Promise<void> {
@@ -1256,31 +1303,10 @@ export class DefaultThreadProvider implements ThreadProvider {
 				internal.info('[thread] restoring state from WebSocket');
 				const restoredData = await this.wsClient.restore(threadId);
 				if (restoredData) {
-					initialStateJson = restoredData;
 					internal.info('[thread] restored state: %d bytes', restoredData.length);
-					// Parse to check if it includes metadata
-					try {
-						const parsed = JSON.parse(restoredData);
-						// New format: { state?: {...}, metadata?: {...} }
-						if (
-							parsed &&
-							typeof parsed === 'object' &&
-							('state' in parsed || 'metadata' in parsed)
-						) {
-							if (parsed.metadata) {
-								restoredMetadata = parsed.metadata;
-							}
-							// Update initialStateJson to be just the state part for backwards compatibility
-							if (parsed.state) {
-								initialStateJson = JSON.stringify(parsed.state);
-							} else {
-								initialStateJson = undefined;
-							}
-						}
-						// else: Old format (just state object), keep as-is
-					} catch {
-						// Keep original if parse fails
-					}
+					const { flatStateJson, metadata } = parseThreadData(restoredData);
+					initialStateJson = flatStateJson;
+					restoredMetadata = metadata;
 				} else {
 					internal.info('[thread] no existing state found');
 				}

package/src/workbench.ts

@@ -112,20 +112,19 @@ export const createWorkbenchExecutionRoute = (): Handler => {
 				ctx.var.logger?.warn('Thread not available in workbench execution route');
 			}
 
-			// Handle cases where result might be undefined/null
-			if (result === undefined || result === null) {
-				return ctx.json({ success: true, result: null });
-			}
-
-			return ctx.json(result);
+			return ctx.json({ success: true, data: result ?? null });
 		} catch (error) {
-			return ctx.json(
-				{
-					error: 'Internal server error',
-					message: error instanceof Error ? error.message : String(error),
+			const err = error instanceof Error ? error : new Error(String(error));
+			// Return 200 with wrapped error so UI can display it properly
+			return ctx.json({
+				success: false,
+				error: {
+					message: err.message,
+					stack: err.stack,
+					code: 'code' in err && typeof err.code === 'string' ? err.code : 'EXECUTION_ERROR',
+					cause: err.cause,
 				},
-				{ status: 500 }
-			);
+			});
 		}
 	};
 };