@pi-oxide/pi-host-web 0.4.0 → 0.7.0

package/sdk/internal/engine.ts

@@ -1,614 +0,0 @@
-// Engine orchestration — the only layer that knows about HostAgent, PersistData, and directives.
-// Wires all AgentConfig fields (instructions, context, artifacts, model).
-// Uses the raw WASM API directly (createHostAgent, startTurn, hostFeedLlmChunk, etc.).
-
-import {
-	type AgentEvent as RawAgentEvent,
-	type AgentMessage as WasmAgentMessage,
-	type Content,
-	type LlmChunk,
-	type LlmResult,
-	type PersistData,
-	type LlmContext,
-	type ToolCall,
-	type ToolResult,
-	type ToolDefinition,
-	type CancelReason,
-	createHostAgent,
-	destroyHostAgent,
-	startTurn,
-	hostFeedLlmChunk,
-	hostLlmDone,
-	hostToolDone,
-	hostToolCancelled,
-	hostContinueTurn,
-	hostAbort,
-	hostAcceptCompaction,
-	hostSteer,
-	hostReset,
-	getHostAgentPersistData,
-	restoreHostAgent,
-} from "../../pi_host_web.js";
-import { ensureInit, HostError } from "../init.ts";
-import { EventMapper } from "./events.ts";
-import { SnapshotSerializer } from "../snapshot.ts";
-import { ToolRegistryBuilder } from "./tools/registry.ts";
-import type {
-	AgentConfig,
-	AgentInput,
-	AgentRunOptions,
-	AgentRunResult,
-	AgentStatus,
-	AgentMessage,
-	ModelResponse,
-	TokenUsage,
-} from "../types.ts";
-import { createAgentError } from "../errors.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ArtifactStore {
-	save(sessionId: string, artifactId: string, content: string): Promise<void>;
-	load(sessionId: string, artifactId: string): Promise<string | null>;
-	search(sessionId: string, query: string): Promise<Array<{ id: string; snippet: string; match_count: number }>>;
-}
-
-export interface AgentRunConfig {
-	llm: {
-		call(context: LlmContext, signal?: AbortSignal): Promise<LlmStream> | LlmStream;
-		summarize?(messages: WasmAgentMessage[], signal?: AbortSignal): Promise<string>;
-	};
-	tools: Record<string, (call: ToolCall) => Promise<ToolResult> | ToolResult>;
-	llmTools?: ToolDefinition[];
-	onEvent?: (event: RawAgentEvent) => void;
-	signal?: AbortSignal;
-	onPersist?: (data: PersistData) => Promise<void>;
-	artifactStore?: ArtifactStore;
-}
-
-export interface LlmStream {
-	chunks: AsyncIterable<LlmChunk>;
-	result: Promise<LlmResult>;
-}
-
-export interface TurnResult {
-	aborted: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// HostAgent — thin wrapper around the WASM handle
-// ---------------------------------------------------------------------------
-
-export class HostAgent {
-	/** @internal */
-	readonly handle: number;
-	readonly sessionId: string | undefined;
-
-	constructor(handle: number, sessionId?: string) {
-		this.handle = handle;
-		this.sessionId = sessionId;
-	}
-
-	getSessionId(): string | undefined {
-		return this.sessionId;
-	}
-
-	steer(message: WasmAgentMessage): { events: RawAgentEvent[] } {
-		const result = unwrap(hostSteer(this.handle, message));
-		return { events: result.events };
-	}
-
-	getPersistData(): PersistData {
-		const result = unwrap(getHostAgentPersistData(this.handle));
-		return result.state;
-	}
-
-	destroy() {
-		destroyHostAgent(this.handle);
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Host agent lifecycle
-// ---------------------------------------------------------------------------
-
-export async function createHostAgentInstance(
-	config: AgentConfig,
-	sessionState?: PersistData,
-): Promise<HostAgent> {
-	await ensureInit();
-	const options = {
-		system_prompt: config.instructions ?? "You are a helpful assistant.",
-		model: buildModelOptions(config.model),
-		session_id: config.sessionId,
-	};
-
-	let handle: number;
-	if (sessionState) {
-		const restored = unwrap(restoreHostAgent(options, sessionState));
-		handle = restored.handle;
-	} else {
-		const result = unwrap(createHostAgent(options, buildContextBudget(config.context)));
-		handle = result.handle;
-	}
-	return new HostAgent(handle, config.sessionId);
-}
-
-export async function runTurnWithHostAgent(
-	hostAgent: HostAgent,
-	message: WasmAgentMessage,
-	config: AgentRunConfig,
-): Promise<TurnResult> {
-	const signal = config.signal;
-
-	const checkAbort = () => {
-		if (signal?.aborted) {
-			try {
-				unwrap(hostAbort(hostAgent.handle));
-			} catch (e) {
-				// ignore wrong_phase errors
-			}
-			throw new HostError("user_aborted", "Turn stopped by user");
-		}
-	};
-
-	try {
-		let step = unwrap(startTurn(hostAgent.handle, { prompt: message, tools: config.llmTools }));
-		for (const event of step.events) {
-			config.onEvent?.(event);
-		}
-
-		while (true) {
-			checkAbort();
-			const actions = step.directives ?? [];
-			if (actions.length === 0) {
-				return { aborted: false };
-			}
-
-			let stateAdvanced = false;
-			let turnFinished = false;
-
-			for (const action of actions) {
-				checkAbort();
-				switch (action.type) {
-					case "stream_llm": {
-						const stream = await config.llm.call(action.context, signal);
-						for await (const chunk of stream.chunks) {
-							checkAbort();
-							const ev = unwrap(hostFeedLlmChunk(hostAgent.handle, chunk));
-							for (const e of ev.events) config.onEvent?.(e);
-						}
-						checkAbort();
-						const result = await stream.result;
-						step = unwrap(hostLlmDone(hostAgent.handle, result));
-						for (const e of step.events) config.onEvent?.(e);
-						stateAdvanced = true;
-						break;
-					}
-
-					case "execute_tools": {
-						for (const call of action.calls) {
-							checkAbort();
-							const handler = config.tools[call.name];
-							let result: ToolResult;
-							if (handler) {
-								result = await handler(call);
-							} else {
-								result = {
-									content: [{ type: "text", text: `No handler for ${call.name}` }],
-								};
-							}
-							step = unwrap(hostToolDone(hostAgent.handle, call.id, result));
-							for (const e of step.events) config.onEvent?.(e);
-						}
-						if ((step.directives ?? []).length === 0) {
-							step = unwrap(hostContinueTurn(hostAgent.handle));
-							for (const e of step.events) config.onEvent?.(e);
-						}
-						stateAdvanced = true;
-						break;
-					}
-
-					case "cancel_tools": {
-						for (const id of action.tool_call_ids) {
-							step = unwrap(hostToolCancelled(hostAgent.handle, id, action.reason));
-							for (const e of step.events) config.onEvent?.(e);
-						}
-						stateAdvanced = true;
-						break;
-					}
-
-					case "summarize": {
-						if (!config.llm.summarize) {
-							throw new Error("Summarize directive received but no summarize function configured");
-						}
-						const summary = await config.llm.summarize(action.context.messages, signal);
-						step = unwrap(hostAcceptCompaction(hostAgent.handle, summary, []));
-						for (const e of step.events) config.onEvent?.(e);
-						stateAdvanced = true;
-						break;
-					}
-
-					case "persist": {
-						const persistData = hostAgent.getPersistData();
-						await config.onPersist?.(persistData);
-						break;
-					}
-
-					case "finished":
-						turnFinished = true;
-						break;
-
-					case "wait_for_input":
-						return { aborted: false };
-
-					default:
-						console.warn(`Unknown directive type: ${(action as { type: string }).type}`);
-						break;
-				}
-			}
-
-			// If the turn is finished, return after processing all directives in this batch
-			if (turnFinished) {
-				return { aborted: false };
-			}
-
-			// If no state was advanced and there are no new directives, continue the turn
-			if (!stateAdvanced && (step.directives ?? []).length === 0) {
-				step = unwrap(hostContinueTurn(hostAgent.handle));
-				for (const e of step.events) config.onEvent?.(e);
-			}
-		}
-	} catch (e: unknown) {
-		const isUserAbort =
-			(e instanceof HostError && e.code === "user_aborted") ||
-			(e instanceof DOMException && e.name === "AbortError");
-		if (isUserAbort) {
-			return { aborted: true };
-		}
-		throw e;
-	}
-}
-
-// ---------------------------------------------------------------------------
-// SDK engine facade
-// ---------------------------------------------------------------------------
-
-export async function createEngineAgent(
-	config: AgentConfig,
-	callbacks: {
-		onEvent: (event: { type: string; payload: unknown }) => void;
-		onStatus: (status: AgentStatus) => void;
-	},
-): Promise<HostAgent> {
-	// Load snapshot from store if available
-	let sessionState: PersistData | undefined;
-	if (config.store) {
-		const snapshot = await config.store.loadSession(config.sessionId);
-		if (snapshot) {
-			const serializer = new SnapshotSerializer();
-			sessionState = serializer.deserialize(snapshot) as PersistData | undefined;
-		}
-	}
-
-	const hostAgent = await createHostAgentInstance(config, sessionState);
-	return hostAgent;
-}
-
-export function destroyEngineAgent(hostAgent: HostAgent): void {
-	hostAgent.destroy();
-}
-
-export async function runAgentTurn(
-	hostAgent: HostAgent,
-	config: AgentConfig,
-	input: string | AgentInput,
-	options: AgentRunOptions | undefined,
-	signal: AbortSignal,
-	callbacks: {
-		onEvent: (event: { type: string; payload: unknown }) => void;
-		onStatus: (status: AgentStatus) => void;
-	},
-): Promise<AgentRunResult> {
-	// Build user message with attachments if present
-	const userMessage = buildUserMessage(input);
-
-	const eventMapper = new EventMapper();
-	const runState = eventMapper.createRunState();
-
-	// Build tool registry — supports AgentTools | AgentTools[]
-	const toolRegistry = new ToolRegistryBuilder();
-	const allTools = normalizeTools(config.tools);
-	const artifactStore = buildArtifactStore(config);
-	const toolMap = toolRegistry.build(allTools, artifactStore, config.sessionId);
-	const llmTools = toolRegistry.getLlmTools(allTools);
-
-	// Build LLM provider adapter that returns LlmStream with chunks
-	const llmProvider: AgentRunConfig["llm"] = {
-		call: async (context: LlmContext, s?: AbortSignal): Promise<LlmStream> => {
-			const effectiveSignal = s || signal;
-			callbacks.onStatus({ state: "calling_model", message: "Calling model..." });
-
-			const modelRequest = {
-				instructions: context.system_prompt,
-				messages: convertWasmMessagesToAgentMessages(context.messages),
-				tools: llmTools.map((t) => ({
-					name: t.name,
-					description: t.description,
-					inputSchema: t.parameters,
-					run: () => null, // Dummy run — LLM tools only need schema, not handler
-				})),
-				signal: effectiveSignal,
-				metadata: mergeMetadata(input, options?.metadata),
-			};
-
-			const response = await config.model.generate(modelRequest);
-
-			// Accumulate usage from model response into run state
-			if (response.usage) {
-				runState.usage = response.usage;
-			}
-
-			return modelResponseToLlmStream(response, effectiveSignal);
-		},
-		summarize: config.model.summarize
-			? async (wasmMessages: WasmAgentMessage[], sig?: AbortSignal) => {
-					const sdkMessages = convertWasmMessagesToAgentMessages(wasmMessages);
-					return config.model.summarize!(sdkMessages, sig);
-				}
-			: undefined,
-	};
-
-	try {
-		const result = await runTurnWithHostAgent(hostAgent, userMessage, {
-			llm: llmProvider,
-			tools: toolMap,
-			llmTools,
-			onEvent: (rawEvent: RawAgentEvent) => {
-				const semanticEvents = eventMapper.map(rawEvent, runState);
-				for (const ev of semanticEvents) {
-					callbacks.onEvent(ev);
-				}
-			},
-			onPersist: async (data: PersistData) => {
-				callbacks.onStatus({ state: "saving", message: "Saving session..." });
-				if (config.store) {
-					const serializer = new SnapshotSerializer();
-					const snapshot = serializer.serialize(data);
-					await config.store.saveSession(config.sessionId, snapshot);
-				}
-				callbacks.onStatus({ state: "completed" });
-			},
-			artifactStore,
-			signal,
-		});
-
-		if (result.aborted) {
-			callbacks.onStatus({ state: "aborted", message: "Stopped by user" });
-		}
-		return eventMapper.buildRunResult(runState, result);
-	} catch (e) {
-		// Let Agent.run() handle error conversion
-		throw e;
-	}
-}
-
-export async function steerAgent(hostAgent: HostAgent, input: string | AgentInput): Promise<void> {
-	const text = typeof input === "string" ? input : input.text;
-	const message: WasmAgentMessage = {
-		role: "user",
-		content: [{ type: "text", text }],
-		timestamp: Date.now(),
-	};
-	hostAgent.steer(message);
-}
-
-export async function resetAgentState(hostAgent: HostAgent): Promise<void> {
-	unwrap(hostReset(hostAgent.handle));
-	// Caller must set engineAgent = null after this
-}
-
-// --- Helpers ---
-
-function unwrap<T>(result: { ok: boolean; data?: T; error?: { code: string; message: string } }): T {
-	if (!result.ok) {
-		throw new HostError(result.error!.code, result.error!.message);
-	}
-	return result.data!;
-}
-
-function normalizeTools(tools: import("../types.ts").AgentTools | import("../types.ts").AgentTools[] | undefined): import("../types.ts").AgentTools[] {
-	if (!tools) return [];
-	if (Array.isArray(tools)) return tools;
-	return [tools];
-}
-
-function buildContextBudget(context?: import("../types.ts").AgentContextPolicy): import("../../pi_host_web.js").ContextProjectionBudget {
-	return {
-		max_tool_result_chars: context?.toolResultLimit ?? 50000,
-		max_context_tokens: context?.maxTokens ?? 100000,
-		microcompact_after_turns: 5,
-		compaction_threshold: 0.75,
-	};
-}
-
-function buildModelOptions(model: import("../types.ts").AgentModel): import("../../pi_host_web.js").Model {
-	return {
-		id: model.id ?? "custom-model",
-		name: model.id ?? "custom-model",
-		api: "anthropic",
-		provider: "anthropic",
-		reasoning: false,
-		context_window: model.contextWindow ?? 100000,
-		max_tokens: model.maxTokens ?? 4096,
-		capabilities: {
-			vision: model.capabilities?.vision ?? false,
-			json_mode: model.capabilities?.jsonMode ?? true,
-			function_calling: model.capabilities?.functionCalling ?? true,
-			streaming: model.capabilities?.streaming ?? true,
-		},
-		cost: { input: 0, output: 0, cache_read: 0, cache_write: 0 },
-	};
-}
-
-function buildArtifactStore(config: AgentConfig): ArtifactStore | undefined {
-	if (config.artifacts?.mode === "external" && config.store) {
-		const store = config.store;
-		if (typeof store.saveArtifact !== "function" || typeof store.loadArtifact !== "function") {
-			throw createAgentError(
-				"store_artifact_unsupported",
-				"Store does not support artifact operations but external artifact mode is configured",
-				{ recoverable: false },
-			);
-		}
-		return {
-			save: (sessionId: string, artifactId: string, content: string) =>
-				store.saveArtifact!(sessionId, {
-					id: artifactId,
-					kind: "text",
-					content,
-					createdAt: Date.now(),
-				}),
-			load: (sessionId: string, artifactId: string) =>
-				store.loadArtifact!(sessionId, artifactId).then((a: import("../types.ts").AgentArtifact | null) =>
-					a && typeof a.content === "string" ? a.content : null,
-				),
-			search: (sessionId: string, query: string) => {
-				if (typeof store.searchArtifacts !== "function") {
-					return Promise.resolve([]);
-				}
-				return store.searchArtifacts!(sessionId, { text: query }).then((results: import("../types.ts").ArtifactSearchResult[]) =>
-					results.map((r: import("../types.ts").ArtifactSearchResult) => ({
-						id: r.artifact.id,
-						snippet: r.snippet ?? "",
-						match_count: r.matchCount ?? 0,
-					})),
-				);
-			},
-		};
-	}
-	return undefined;
-}
-
-function mergeMetadata(
-	input: string | AgentInput,
-	runMetadata?: Record<string, unknown>,
-): Record<string, unknown> | undefined {
-	const inputMetadata = typeof input === "object" ? input.metadata : undefined;
-	if (!inputMetadata && !runMetadata) return undefined;
-	return { ...inputMetadata, ...runMetadata };
-}
-
-function buildUserMessage(input: string | AgentInput): WasmAgentMessage {
-	const text = typeof input === "string" ? input : input.text;
-	const content: Content[] = [{ type: "text", text }];
-
-	if (typeof input === "object" && input.attachments) {
-		for (const attachment of input.attachments) {
-			if (attachment.type === "image" || attachment.mimeType?.startsWith("image/")) {
-				content.push({
-					type: "image",
-					media_type: attachment.mimeType ?? "image/png",
-					data: typeof attachment.content === "string" ? attachment.content : btoa(String.fromCharCode(...new Uint8Array(attachment.content))),
-				});
-			}
-		}
-	}
-
-	return {
-		role: "user",
-		content,
-		timestamp: Date.now(),
-	};
-}
-
-function convertWasmMessagesToAgentMessages(
-	messages: WasmAgentMessage[],
-): AgentMessage[] {
-	return messages.map((msg) => ({
-		id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
-		role: msg.role,
-		content: msg.content.map((c) => {
-			if (c.type === "text") return { type: "text" as const, text: c.text };
-			if (c.type === "tool_call") return { type: "tool_call" as const, id: c.id, name: c.name, arguments: c.arguments };
-			if (c.type === "image") return { type: "image" as const, mimeType: c.media_type, data: c.data };
-			return { type: "text" as const, text: "" };
-		}),
-		timestamp: Date.now(),
-		tool_call_id: msg.role === "tool_result" ? (msg as unknown as { tool_call_id: string }).tool_call_id : undefined,
-	}));
-}
-
-function modelResponseToLlmStream(
-	response: ModelResponse,
-	signal: AbortSignal,
-): LlmStream {
-	const chunks: AsyncIterable<LlmChunk> = {
-		[Symbol.asyncIterator]: async function* () {
-			if (signal.aborted) return;
-
-			// Start chunk — stop_reason belongs on final result, not start
-			yield {
-				kind: "start",
-				content: [{ type: "text", text: "" }],
-				api: "sdk",
-				provider: "sdk",
-				model: response.model ?? "sdk-model",
-				stop_reason: "end_turn" as const,
-				error_message: undefined,
-				timestamp: Date.now(),
-				usage: {
-					input: response.usage?.input ?? 0,
-					output: response.usage?.output ?? 0,
-					cache_read: response.usage?.cache_read ?? 0,
-					cache_write: response.usage?.cache_write ?? 0,
-					total_tokens: response.usage?.total_tokens ?? 0,
-				},
-			};
-
-			// Text delta chunks for each text block
-			for (const block of response.content) {
-				if (signal.aborted) return;
-				if (block.type === "text" && block.text) {
-					// Split into words to simulate streaming
-					const words = block.text.split(/(\s+)/);
-					for (const word of words) {
-						if (signal.aborted) return;
-						if (word) {
-							yield { kind: "text_delta", text: word };
-							// Small artificial delay to simulate streaming
-							await new Promise((r) => setTimeout(r, 10));
-						}
-					}
-				}
-			}
-		},
-	};
-
-	const result: Promise<LlmResult> = Promise.resolve({
-		Ok: {
-			content: response.content.map((c: import("../types.ts").AgentContentBlock) => {
-				if (c.type === "text") return { type: "text", text: c.text };
-				if (c.type === "tool_call") return { type: "tool_call", id: c.id, name: c.name, arguments: c.arguments };
-				return { type: "text", text: "" };
-			}),
-			api: "sdk",
-			provider: "sdk",
-			model: response.model ?? "sdk-model",
-			stop_reason: response.stopReason === "tool_call" ? "tool_use" : "end_turn",
-			error_message: undefined,
-			timestamp: Date.now(),
-			usage: {
-				input: response.usage?.input ?? 0,
-				output: response.usage?.output ?? 0,
-				cache_read: response.usage?.cache_read ?? 0,
-				cache_write: response.usage?.cache_write ?? 0,
-				total_tokens: response.usage?.total_tokens ?? 0,
-			},
-		},
-	});
-
-	return { chunks, result };
-}