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

package/sdk/agent.ts

@@ -1,274 +0,0 @@
-// Public Agent class — the primary SDK surface.
-// Thin facade over the internal engine. No WASM imports here.
-
-import { EventEmitter } from "./events.ts";
-import type {
-  AgentConfig,
-  AgentInput,
-  AgentRunOptions,
-  AgentRunResult,
-  AgentEventName,
-  AgentEventHandler,
-  AgentStatus,
-  Unsubscribe,
-  AgentError,
-} from "./types.ts";
-import { createAgentError } from "./errors.ts";
-import type { HostAgent } from "./internal/engine.ts";
-import {
-  runAgentTurn,
-  resetAgentState,
-  steerAgent,
-  createEngineAgent,
-  destroyEngineAgent,
-} from "./internal/engine.ts";
-
-export class Agent {
-  private config: AgentConfig;
-  private emitter: EventEmitter;
-  private status: AgentStatus = { state: "idle" };
-  private currentRun: Promise<AgentRunResult> | null = null;
-  private currentAbortController: AbortController | null = null;
-  private disposed = false;
-  private engineAgent: HostAgent | null = null;
-
-  constructor(config: AgentConfig) {
-    this.config = config;
-    this.emitter = new EventEmitter();
-  }
-
-  on<E extends AgentEventName>(
-    event: E,
-    handler: AgentEventHandler<E>,
-  ): Unsubscribe {
-    if (this.disposed) {
-      return () => {};
-    }
-    return this.emitter.on(event, handler);
-  }
-
-  async run(
-    input: string | AgentInput,
-    options?: AgentRunOptions,
-  ): Promise<AgentRunResult> {
-    if (this.disposed) {
-      const error = createAgentError(
-        "agent_disposed",
-        "Agent has been disposed",
-        { recoverable: false },
-      );
-      const result: AgentRunResult = {
-        status: "failed",
-        text: "",
-        toolCalls: [],
-        artifacts: [],
-        error,
-      };
-      this.emitter.emit("error", error);
-      this.emitter.emit("status", { state: "failed", message: error.message });
-      this.emitter.emit("done", result);
-      return result;
-    }
-
-    if (this.currentRun) {
-      const error = createAgentError(
-        "agent_busy",
-        "Agent is already running a turn",
-        { recoverable: true },
-      );
-      const result: AgentRunResult = {
-        status: "failed",
-        text: "",
-        toolCalls: [],
-        artifacts: [],
-        error,
-      };
-      this.emitter.emit("error", error);
-      this.emitter.emit("status", { state: "failed", message: error.message });
-      this.emitter.emit("done", result);
-      return result;
-    }
-
-    const abortController = new AbortController();
-    this.currentAbortController = abortController;
-
-    // Merge external signal if provided
-    if (options?.signal) {
-      if (options.signal.aborted) {
-        abortController.abort(options.signal.reason);
-      } else {
-        options.signal.addEventListener(
-          "abort",
-          () => {
-            abortController.abort(options.signal!.reason);
-          },
-          { once: true },
-        );
-      }
-    }
-
-    const runPromise = this._doRun(input, options, abortController.signal);
-    this.currentRun = runPromise;
-
-    try {
-      const result = await runPromise;
-      this.emitter.emit("done", result);
-      return result;
-    } catch (e) {
-      // Safety net: convert any unexpected throw to a failed result
-      const error = createAgentError(
-        "internal_error",
-        e instanceof Error ? e.message : String(e),
-        { cause: e, recoverable: false },
-      );
-      const failedResult: AgentRunResult = {
-        status: "failed",
-        text: "",
-        toolCalls: [],
-        artifacts: [],
-        error,
-      };
-      this.emitter.emit("error", error);
-      this.emitter.emit("status", { state: "failed", message: error.message });
-      this.emitter.emit("done", failedResult);
-      return failedResult;
-    } finally {
-      this.currentRun = null;
-      this.currentAbortController = null;
-    }
-  }
-
-  private async _doRun(
-    input: string | AgentInput,
-    options: AgentRunOptions | undefined,
-    signal: AbortSignal,
-  ): Promise<AgentRunResult> {
-    // Lazy initialization on first run
-    if (!this.engineAgent) {
-      this.engineAgent = await createEngineAgent(this.config, {
-        onEvent: (event) => this.emitter.emit(event.type as AgentEventName, event.payload),
-        onStatus: (status) => {
-          this.status = status;
-          this.emitter.emit("status", status);
-        },
-      });
-    }
-
-    try {
-      return await runAgentTurn(
-        this.engineAgent,
-        this.config,
-        input,
-        options,
-        signal,
-        {
-          onEvent: (event) =>
-            this.emitter.emit(event.type as AgentEventName, event.payload),
-          onStatus: (status) => {
-            this.status = status;
-            this.emitter.emit("status", status);
-          },
-        },
-      );
-    } catch (e) {
-      const isAbort =
-        signal.aborted ||
-        (e instanceof Error && e.name === "AbortError") ||
-        (e instanceof Error && e.message.includes("user_aborted"));
-
-      if (isAbort) {
-        const abortedResult: AgentRunResult = {
-          status: "aborted",
-          text: "",
-          toolCalls: [],
-          artifacts: [],
-        };
-        this.emitter.emit("status", {
-          state: "aborted",
-          message: "Stopped by user",
-        });
-        return abortedResult;
-      }
-
-      const code =
-        e instanceof Error && "code" in e && typeof (e as { code: unknown }).code === "string"
-          ? ((e as { code: string }).code as AgentError["code"])
-          : "internal_error";
-      const error = createAgentError(
-        code,
-        e instanceof Error ? e.message : String(e),
-        { cause: e, recoverable: false },
-      );
-      const failedResult: AgentRunResult = {
-        status: "failed",
-        text: "",
-        toolCalls: [],
-        artifacts: [],
-        error,
-      };
-      this.emitter.emit("error", error);
-      this.emitter.emit("status", { state: "failed", message: error.message });
-      return failedResult;
-    }
-  }
-
-  stop(reason?: string): void {
-    if (this.disposed || !this.currentAbortController) return;
-    this.currentAbortController.abort(reason ?? "user-requested");
-  }
-
-  async steer(input: string | AgentInput): Promise<void> {
-    if (this.disposed) {
-      throw createAgentError(
-        "agent_disposed",
-        "Agent has been disposed",
-        { recoverable: false },
-      );
-    }
-    if (!this.engineAgent) {
-      throw createAgentError(
-        "agent_not_initialized",
-        "Agent has not been run yet",
-        { recoverable: true },
-      );
-    }
-    return steerAgent(this.engineAgent, input);
-  }
-
-  async reset(): Promise<void> {
-    if (this.disposed) {
-      throw createAgentError(
-        "agent_disposed",
-        "Agent has been disposed",
-        { recoverable: false },
-      );
-    }
-    if (this.engineAgent) {
-      await resetAgentState(this.engineAgent);
-      this.engineAgent = null;
-    }
-    this.currentRun = null;
-    this.currentAbortController = null;
-    this.status = { state: "idle" };
-    this.emitter.emit("status", this.status);
-  }
-
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    if (this.currentAbortController) {
-      this.currentAbortController.abort("disposed");
-      this.currentAbortController = null;
-    }
-    if (this.engineAgent) {
-      destroyEngineAgent(this.engineAgent);
-      this.engineAgent = null;
-    }
-    this.emitter.clear();
-    this.currentRun = null;
-  }
-
-  getStatus(): AgentStatus {
-    return this.status;
-  }
-}

package/sdk/artifacts.ts

@@ -1,35 +0,0 @@
-// Artifact types for the pi-oxide SDK.
-// These are public objects, not leaked host internals.
-
-export interface AgentArtifact {
-  id: string;
-  kind: "text" | "json" | "binary";
-  content: string | Uint8Array | unknown;
-  mimeType?: string;
-  title?: string;
-  metadata?: Record<string, unknown>;
-  createdAt: number;
-}
-
-export interface AgentArtifactRef {
-  id: string;
-  kind: AgentArtifact["kind"];
-  title?: string;
-  mimeType?: string;
-}
-
-export interface ArtifactPolicy {
-  mode: "inline" | "external";
-}
-
-export interface ArtifactSearchQuery {
-  text: string;
-  limit?: number;
-}
-
-export interface ArtifactSearchResult {
-  artifact: AgentArtifactRef;
-  snippet?: string;
-  score?: number;
-  matchCount?: number;
-}

package/sdk/context.ts

@@ -1,4 +0,0 @@
-// Context policy types for the pi-oxide SDK.
-// Re-exported from types.ts for a cleaner public API surface.
-
-export type { AgentContextPolicy, AgentSummarizer } from "./types.ts";

package/sdk/errors.ts

@@ -1,24 +0,0 @@
-// AgentError interface and factory.
-// AgentError is an interface, NOT a class — it is a plain object.
-
-import type { AgentError } from "./types.ts";
-
-export type { AgentError } from "./types.ts";
-
-export function createAgentError(
-  code: AgentError["code"],
-  message: string,
-  options?: {
-    cause?: unknown;
-    recoverable?: boolean;
-    metadata?: Record<string, unknown>;
-  },
-): AgentError {
-  return {
-    code,
-    message,
-    cause: options?.cause,
-    recoverable: options?.recoverable ?? false,
-    metadata: options?.metadata,
-  };
-}

package/sdk/events.ts

@@ -1,52 +0,0 @@
-// Lightweight, type-safe EventEmitter (not Node's).
-// Maps event names to typed handlers using the SDK's AgentEventName union.
-
-import type { AgentEventName, AgentEventHandler } from "./types.ts";
-
-type AnyHandler = (payload: unknown) => void;
-
-export class EventEmitter {
-  private handlers: Partial<Record<AgentEventName, Set<AnyHandler>>> = {};
-
-  on<E extends AgentEventName>(
-    event: E,
-    handler: AgentEventHandler<E>,
-  ): () => void {
-    const set = (this.handlers[event] ??= new Set()) as Set<AnyHandler>;
-    set.add(handler as AnyHandler);
-
-    return () => {
-      set.delete(handler as AnyHandler);
-      if (set.size === 0) {
-        delete this.handlers[event];
-      }
-    };
-  }
-
-  off<E extends AgentEventName>(
-    event: E,
-    handler: AgentEventHandler<E>,
-  ): void {
-    const set = this.handlers[event];
-    if (!set) return;
-    set.delete(handler as AnyHandler);
-    if (set.size === 0) {
-      delete this.handlers[event];
-    }
-  }
-
-  emit<E extends AgentEventName>(
-    event: E,
-    payload: Parameters<AgentEventHandler<E>>[0],
-  ): void {
-    const set = this.handlers[event];
-    if (!set) return;
-    for (const handler of set) {
-      handler(payload);
-    }
-  }
-
-  clear(): void {
-    this.handlers = {};
-  }
-}

package/sdk/index.d.ts

@@ -1,29 +0,0 @@
-/**
- * High-level JS SDK for @pi-oxide/pi-host-web.
- *
- * Re-exports all raw types so consumers never need to import from ./raw.
- */
-
-export * from "../pi_host_web";
-
-export declare function ensureInit(): Promise<void>;
-
-export declare function toolResult(
-	text: string,
-	opts?: { terminate?: boolean; details?: object },
-): {
-	content: Array<{ type: "text"; text: string }>;
-	terminate?: boolean;
-	details?: object;
-};
-
-export declare class HostError extends Error {
-	code: string;
-	constructor(code: string, message: string);
-}
-
-export declare function unwrap<T>(result: {
-	ok: boolean;
-	data?: T;
-	error?: { code: string; message: string };
-}): T;

package/sdk/index.js

@@ -1,111 +0,0 @@
-/**
- * High-level JS SDK for @pi-oxide/pi-host-web.
- *
- * Hides WASM loading and numeric handles.
- * Supports streaming LLM responses and full agent lifecycle.
- *
- * Import from the package root:
- *   import { ensureInit, toolResult } from "@pi-oxide/pi-host-web";
- */
-
-import {
-	default as init,
-	initSync,
-	createHostAgent,
-	destroyHostAgent,
-	startTurn,
-	hostFeedLlmChunk,
-	hostLlmDone,
-	hostToolDone,
-	hostAcceptCompaction,
-	hostContinueTurn,
-	getHostStatePersistData,
-	restoreHostState,
-	restoreHostStateFromJson,
-	hostReadArtifact,
-	hostSearchArtifacts,
-	hostToolCancelled,
-	hostAbort,
-	getHostAgentPersistData,
-	restoreHostAgent,
-	createHostState,
-	destroyHostState,
-	hostSteer,
-	hostReset,
-	estimateTokens,
-	estimateTokensForText,
-	setLogLevel,
-} from "../pi_host_web.js";
-
-export {
-	createHostState,
-	destroyHostState,
-	createHostAgent,
-	destroyHostAgent,
-	startTurn,
-	hostFeedLlmChunk,
-	hostLlmDone,
-	hostToolDone,
-	hostAcceptCompaction,
-	hostContinueTurn,
-	getHostStatePersistData,
-	restoreHostState,
-	restoreHostStateFromJson,
-	hostReadArtifact,
-	hostSearchArtifacts,
-	hostToolCancelled,
-	hostAbort,
-	getHostAgentPersistData,
-	restoreHostAgent,
-	hostSteer,
-	hostReset,
-	estimateTokens,
-	estimateTokensForText,
-	setLogLevel,
-};
-
-let initialized = false;
-
-/** Ensure the WASM module is loaded. Safe to call multiple times. */
-export async function ensureInit() {
-	if (initialized) return;
-	if (typeof process !== "undefined" && process.versions?.node) {
-		const { readFileSync } = await import("node:fs");
-		const bytes = readFileSync(
-			new URL("../pi_host_web_bg.wasm", import.meta.url),
-		);
-		initSync({ module: bytes });
-	} else {
-		await init();
-	}
-	initialized = true;
-}
-
-export class HostError extends Error {
-	constructor(code, message) {
-		super(message);
-		this.code = code;
-		this.name = "HostError";
-	}
-}
-
-export function unwrap(result) {
-	if (!result.ok) {
-		throw new HostError(result.error.code, result.error.message);
-	}
-	return result.data;
-}
-
-/** Build a successful tool result payload. */
-export function toolResult(text, opts = {}) {
-	const payload = {
-		content: [{ type: "text", text }],
-	};
-	if (opts.terminate) {
-		payload.terminate = true;
-	}
-	if (opts.details) {
-		payload.details = opts.details;
-	}
-	return payload;
-}

package/sdk/index.ts

@@ -1,53 +0,0 @@
-// Public SDK exports — the only surface normal apps should import.
-// Internal engine details are hidden in sdk/internal/.
-
-export { ensureInit, HostError, unwrap, toolResult } from "./init.ts";
-
-// SDK exports
-export { Agent } from "./agent.ts";
-export { defineModel } from "./model.ts";
-export { anthropic } from "./internal/providers/anthropic.ts";
-export { openai, openaiCompatible } from "./internal/providers/openai.ts";
-export { defineTools, tool } from "./tools.ts";
-export { browserTools } from "./internal/tools/browser.ts";
-export { artifactTools } from "./internal/tools/artifact.ts";
-export { indexedDbStore, memoryStore, localStorageStore, httpStore } from "./stores.ts";
-export { useAgent } from "./react/index.ts";
-
-export type {
-	AgentArtifact,
-	AgentArtifactRef,
-	ArtifactPolicy,
-	ArtifactSearchQuery,
-	ArtifactSearchResult,
-} from "./artifacts.ts";
-
-export type {
-	AgentConfig,
-	AgentInput,
-	AgentRunOptions,
-	AgentRunResult,
-	AgentEventName,
-	AgentEventHandler,
-	AgentMessage,
-	AgentContentBlock,
-	AgentToolRun,
-	AgentStatus,
-	AgentModel,
-	ModelRequest,
-	ModelResponse,
-	ModelEvent,
-	AgentTools,
-	AgentToolDefinition,
-	AgentStore,
-	AgentSnapshot,
-	AgentContextPolicy,
-	AgentSummarizer,
-	AgentTelemetry,
-	AgentError,
-	Unsubscribe,
-	TokenUsage,
-	UseAgentResult,
-} from "./types.ts";
-
-export { createAgentError } from "./errors.ts";

package/sdk/init.ts

@@ -1,58 +0,0 @@
-// WASM initialization and low-level helpers.
-// Kept separate from index.ts to avoid circular imports with internal modules.
-
-import {
-	default as init,
-	initSync,
-} from "../pi_host_web.js";
-
-let initialized = false;
-
-/** Ensure the WASM module is loaded. Safe to call multiple times. */
-export async function ensureInit() {
-	if (initialized) return;
-	if (typeof process !== "undefined" && process.versions?.node) {
-		const { readFileSync } = await import("node:fs");
-		const bytes = readFileSync(
-			new URL("../pi_host_web_bg.wasm", import.meta.url),
-		);
-		initSync({ module: bytes });
-	} else {
-		await init();
-	}
-	initialized = true;
-}
-
-export class HostError extends Error {
-	code: string;
-	constructor(code: string, message: string) {
-		super(message);
-		this.code = code;
-		this.name = "HostError";
-	}
-}
-
-export function unwrap(result: { ok: boolean; data?: unknown; error?: { code: string; message: string } }): unknown {
-	if (!result.ok) {
-		throw new HostError(result.error!.code, result.error!.message);
-	}
-	return result.data;
-}
-
-/** Build a successful tool result payload. */
-export function toolResult(text: string, opts: { terminate?: boolean; details?: object } = {}) {
-	const payload: {
-		content: Array<{ type: "text"; text: string }>;
-		terminate?: boolean;
-		details?: object;
-	} = {
-		content: [{ type: "text", text }],
-	};
-	if (opts.terminate) {
-		payload.terminate = true;
-	}
-	if (opts.details) {
-		payload.details = opts.details;
-	}
-	return payload;
-}