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

package/sdk/agent.ts

@@ -0,0 +1,274 @@
+// 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

@@ -0,0 +1,35 @@
+// 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

@@ -0,0 +1,4 @@
+// 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

@@ -0,0 +1,24 @@
+// 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

@@ -0,0 +1,52 @@
+// 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

@@ -4,48 +4,26 @@
  * Re-exports all raw types so consumers never need to import from ./raw.
  */
 
-export * from "../pi_host_web.js";
+export * from "../pi_host_web";
 
 export declare function ensureInit(): Promise<void>;
 
 export declare function toolResult(
-  text: string,
-  opts?: { terminate?: boolean }
-): { content: Array<{ type: "text"; text: string }>; terminate?: boolean };
-
-export declare function toolError(
-  code: string,
-  message: string
-): { error: { code: string; message: string } };
-
-export interface LlmStream {
-  chunks: AsyncIterable<LlmChunk>;
-  result: Promise<LlmResult>;
-}
-
-export interface LlmProvider {
-  call(context: LlmContext): Promise<LlmStream> | LlmStream;
+	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 type ToolMap = Record<
-  string,
-  (call: ToolCall) => Promise<ToolResult> | ToolResult
->;
-
-export interface AgentRunConfig {
-  llm: LlmProvider;
-  tools: ToolMap;
-  onEvent?: (event: AgentEvent) => void;
-}
-
-export declare class Agent {
-  static create(options: AgentOptions): Promise<Agent>;
-  run(promptText: string, config: AgentRunConfig): Promise<AgentAction>;
-  reset(): void;
-  state(): AgentState;
-  getSessionState(): SessionState;
-  setSessionState(sessionState: SessionState): void;
-  steer(message: AgentMessage): AgentEvent[];
-  followUp(message: AgentMessage): void;
-  destroy(): void;
-}
+export declare function unwrap<T>(result: {
+	ok: boolean;
+	data?: T;
+	error?: { code: string; message: string };
+}): T;