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

package/sdk/internal/tools/registry.ts

@@ -0,0 +1,174 @@
+// ToolRegistryBuilder — converts SDK AgentTools[] into WASM ToolMap and LLM ToolDefinition[].
+// Uses zod-to-json-schema for schema conversion.
+// Detects duplicate tool names and throws AgentError.
+// Preserves details field in ToolResult.
+
+import type { ToolCall, ToolDefinition, ToolResult } from "../../../pi_host_web.js";
+import type { AgentTools, AgentToolDefinition } from "../../types.ts";
+import { createAgentError } from "../../errors.ts";
+import { createArtifactToolRegistry } from "./service.ts";
+import type { ArtifactStore } from "../engine.ts";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+export type ToolMap = Record<string, (call: ToolCall) => Promise<ToolResult> | ToolResult>;
+
+export class ToolRegistryBuilder {
+  /**
+   * Build a WASM ToolMap from AgentTools packs.
+   * Artifact tools are wired with the store at build time.
+   */
+  build(
+    tools: AgentTools[],
+    artifactStore?: ArtifactStore,
+    sessionId?: string,
+  ): ToolMap {
+    const toolMap: ToolMap = {};
+    const seenNames = new Set<string>();
+
+    for (const pack of tools) {
+      for (const def of pack.definitions) {
+        if (seenNames.has(def.name)) {
+          throw createAgentError(
+            "tool_duplicate",
+            `Duplicate tool name: ${def.name}`,
+            { recoverable: false },
+          );
+        }
+        seenNames.add(def.name);
+
+        const handler = pack.getHandler(def.name);
+        if (handler) {
+          toolMap[def.name] = async (call: ToolCall) => {
+            try {
+              let parsedInput: unknown;
+              if (def.inputSchema && isZodSchema(def.inputSchema)) {
+                const schema = def.inputSchema as z.ZodTypeAny;
+                const parseResult = schema.safeParse(call.arguments);
+                if (!parseResult.success) {
+                  return {
+                    content: [{ type: "text", text: `Invalid input: ${parseResult.error.message}` }],
+                    error: true,
+                  };
+                }
+                parsedInput = parseResult.data;
+              } else {
+                parsedInput = call.arguments;
+              }
+
+              const output = await handler(parsedInput);
+
+              // If output is already a ToolResult, preserve it (including details)
+              if (isToolResult(output)) {
+                return output;
+              }
+
+              // Otherwise wrap the output
+              const text = typeof output === "string" ? output : JSON.stringify(output, null, 2);
+              const result: ToolResult = {
+                content: [{ type: "text", text }],
+              };
+
+              // Preserve details if the definition provides a details function
+              if (def.details) {
+                result.details = def.details(output);
+              }
+
+              return result;
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              return {
+                content: [{ type: "text", text: message }],
+                details: { error: true },
+              };
+            }
+          };
+        }
+      }
+    }
+
+    // Wire artifact tools with store if any artifact pack was provided
+    const hasArtifactTools = tools.some((p) =>
+      p.definitions.some((d) => d.name === "artifact_read" || d.name === "artifact_search"),
+    );
+    if (hasArtifactTools) {
+      const artifactRegistry = createArtifactToolRegistry(
+        () => 0,
+        artifactStore,
+        () => sessionId,
+      );
+      for (const [name, handler] of Object.entries(artifactRegistry)) {
+        if (seenNames.has(name)) {
+          throw createAgentError(
+            "tool_duplicate",
+            `Duplicate tool name: ${name}`,
+            { recoverable: false },
+          );
+        }
+        toolMap[name] = handler;
+      }
+    }
+
+    return toolMap;
+  }
+
+  /**
+   * Convert AgentToolDefinition[] to WASM ToolDefinition[] for the LLM.
+   * Uses zod-to-json-schema for Zod schemas; passes plain objects through.
+   */
+  getLlmTools(tools: AgentTools[]): ToolDefinition[] {
+    const llmTools: ToolDefinition[] = [];
+    const seenNames = new Set<string>();
+
+    for (const pack of tools) {
+      for (const def of pack.definitions) {
+        if (seenNames.has(def.name)) {
+          throw createAgentError(
+            "tool_duplicate",
+            `Duplicate tool name: ${def.name}`,
+            { recoverable: false },
+          );
+        }
+        seenNames.add(def.name);
+
+        let parameters: object;
+        if (isZodSchema(def.inputSchema)) {
+          parameters = zodToJsonSchema(def.inputSchema as z.ZodTypeAny, { name: def.name }) as object;
+        } else if (typeof def.inputSchema === "object" && def.inputSchema !== null) {
+          parameters = def.inputSchema as object;
+        } else {
+          parameters = { type: "object", properties: {} };
+        }
+
+        llmTools.push({
+          name: def.name,
+          label: def.name,
+          description: def.description,
+          parameters,
+          execution_mode: "parallel",
+        });
+      }
+    }
+
+    return llmTools;
+  }
+}
+
+function isToolResult(value: unknown): value is ToolResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "content" in value &&
+    Array.isArray((value as ToolResult).content)
+  );
+}
+
+function isZodSchema(value: unknown): value is z.ZodTypeAny {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "_def" in value &&
+    typeof (value as { _def: unknown })._def === "object" &&
+    !!(value as { _def: { typeName?: string } })._def?.typeName?.startsWith("Zod")
+  );
+}

package/sdk/internal/tools/service.ts

@@ -0,0 +1,157 @@
+/**
+ * Tool service — creates a tool registry for the agent run config.
+ *
+ * Pure JS, no React. Wraps browser tool execution into the SDK ToolMap shape.
+ */
+
+import type { ToolCall, ToolDefinition, ToolResult } from "../../../pi_host_web.js";
+import type { BrowserRuntime } from "./browserRuntime.ts";
+import type { ArtifactStore } from "../engine.ts";
+import {
+  BROWSER_TOOLS,
+  executeBrowserTool,
+  wrapToolHandler,
+} from "./browser.ts";
+
+// ========================================================================
+// Artifact tool schemas
+// ========================================================================
+
+const artifactReadSchema: object = {
+  type: "object",
+  properties: {
+    artifact_id: {
+      type: "string",
+      description: "The artifact id to retrieve (e.g. tool-result-abc123).",
+    },
+  },
+  required: ["artifact_id"],
+  additionalProperties: false,
+};
+
+const MAX_SEARCH_RESULTS = 50;
+
+const artifactSearchSchema: object = {
+  type: "object",
+  properties: {
+    pattern: {
+      type: "string",
+      description: "Text pattern to search for inside stored artifacts.",
+    },
+  },
+  required: ["pattern"],
+  additionalProperties: false,
+};
+
+// ========================================================================
+// Artifact tool definitions
+// ========================================================================
+
+const ARTIFACT_READ: ToolDefinition = {
+  name: "artifact_read",
+  label: "Read Artifact",
+  description:
+    "Read the full original text of a previously stored artifact by its id. " +
+    "Use this when a projected tool result references an artifact you need to inspect.",
+  parameters: artifactReadSchema,
+  execution_mode: "parallel",
+};
+
+const ARTIFACT_SEARCH: ToolDefinition = {
+  name: "artifact_search",
+  label: "Search Artifacts",
+  description:
+    "Search all stored artifacts for a text pattern. Returns up to 50 matching artifact ids, a short snippet around the first match, and the match count. Use artifact_read to retrieve the full text.",
+  parameters: artifactSearchSchema,
+  execution_mode: "parallel",
+};
+
+/** All artifact tools exposed by the host. */
+export const ARTIFACT_TOOLS: ToolDefinition[] = [
+  ARTIFACT_READ,
+  ARTIFACT_SEARCH,
+];
+
+// ========================================================================
+// Tool registry
+// ========================================================================
+
+export type ToolMap = Record<string, (call: ToolCall) => Promise<ToolResult> | ToolResult>;
+
+export function createToolRegistry(runtime: BrowserRuntime): ToolMap {
+  return Object.fromEntries(
+    BROWSER_TOOLS.map((t) => [
+      t.name,
+      wrapToolHandler((call: ToolCall) => executeBrowserTool(call, runtime)),
+    ]),
+  );
+}
+
+/**
+ * Create artifact tool handlers that read from the agent store.
+ * No host handles required — operates on AgentStore directly.
+ */
+export function createArtifactToolRegistry(
+  _getHandle: () => number,
+  artifactStore?: ArtifactStore,
+  getSessionId?: () => string | undefined,
+): ToolMap {
+  return {
+    artifact_read: wrapToolHandler(async (call: ToolCall) => {
+      const artifactId = call.arguments.artifact_id as string;
+      if (typeof artifactId !== "string" || artifactId.length === 0) {
+        throw new Error("artifact_id must be a non-empty string");
+      }
+      let text: string;
+      if (artifactStore && getSessionId) {
+        const sessionId = getSessionId();
+        if (sessionId) {
+          const stored = await artifactStore.load(sessionId, artifactId);
+          text = stored ?? "";
+        } else {
+          text = "";
+        }
+      } else {
+        text = "";
+      }
+      if (text === "") {
+        throw new Error(`artifact not found: ${artifactId}`);
+      }
+      return {
+        content: [{ type: "text", text }],
+      };
+    }),
+    artifact_search: wrapToolHandler(async (call: ToolCall) => {
+      const pattern = call.arguments.pattern as string;
+      if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new Error("pattern must be a non-empty string");
+      }
+      let results: Array<{ id: string; snippet: string; match_count: number }>;
+      if (artifactStore && getSessionId) {
+        const sessionId = getSessionId();
+        if (sessionId) {
+          results = await artifactStore.search(sessionId, pattern);
+        } else {
+          results = [];
+        }
+      } else {
+        results = [];
+      }
+      const capped = results.slice(0, MAX_SEARCH_RESULTS);
+      const text = JSON.stringify(
+        capped.map((r) => ({
+          id: r.id,
+          snippet: r.snippet,
+          match_count: r.match_count,
+        })),
+        null,
+        2,
+      );
+      return {
+        content: [{ type: "text", text }],
+      };
+    }),
+  };
+}
+
+export { BROWSER_TOOLS };

package/sdk/model.ts

@@ -0,0 +1,35 @@
+// Model exports — AgentModel interface and defineModel() factory.
+// Provider-neutral contract. Provider factories live in internal/providers/.
+
+import type { AgentModel, ModelRequest, ModelResponse } from "./types.ts";
+
+export type { AgentModel } from "./types.ts";
+
+/**
+ * Create a custom AgentModel from a user-provided generate function.
+ * Useful for wrapping arbitrary LLM providers or mocking in tests.
+ */
+export function defineModel(
+  config: {
+    id?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    capabilities?: AgentModel["capabilities"];
+    generate: AgentModel["generate"];
+    summarize?: AgentModel["summarize"];
+  },
+): AgentModel {
+  return {
+    id: config.id ?? "custom-model",
+    contextWindow: config.contextWindow ?? 100000,
+    maxTokens: config.maxTokens ?? 4096,
+    capabilities: {
+      vision: config.capabilities?.vision ?? false,
+      jsonMode: config.capabilities?.jsonMode ?? true,
+      functionCalling: config.capabilities?.functionCalling ?? true,
+      streaming: config.capabilities?.streaming ?? true,
+    },
+    generate: config.generate,
+    summarize: config.summarize,
+  };
+}

package/sdk/react/index.ts

@@ -0,0 +1 @@
+export { useAgent } from "./useAgent.ts";

package/sdk/react/useAgent.ts

@@ -0,0 +1,334 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { Agent } from "../agent.ts";
+import type {
+  AgentConfig,
+  AgentInput,
+  AgentRunOptions,
+  AgentRunResult,
+  AgentMessage,
+  AgentToolRun,
+  AgentArtifactRef,
+  AgentStatus,
+  AgentError,
+  UseAgentResult,
+} from "../types.ts";
+import { createAgentError } from "../errors.ts";
+
+// ---------------------------------------------------------------------------
+// Shallow comparison helpers
+// ---------------------------------------------------------------------------
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  if (a === null || b === null) return false;
+
+  const aRecord = a as Record<string, unknown>;
+  const bRecord = b as Record<string, unknown>;
+  const aKeys = Object.keys(aRecord);
+  const bKeys = Object.keys(bRecord);
+  if (aKeys.length !== bKeys.length) return false;
+
+  for (const key of aKeys) {
+    if (aRecord[key] !== bRecord[key]) return false;
+  }
+  return true;
+}
+
+function shallowArrayEqual(a: unknown[], b: unknown[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function toolsEqual(
+  a: AgentConfig["tools"],
+  b: AgentConfig["tools"],
+): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return shallowArrayEqual(a, b);
+  }
+  if (!Array.isArray(a) && !Array.isArray(b)) {
+    return shallowEqual(a, b);
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// useStableConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Stabilises an `AgentConfig` reference so that the hook only sees a new
+ * object when one of the config fields actually changes (by value).
+ * Object fields (`context`, `artifacts`, `telemetry`) are compared shallowly.
+ * `tools` is compared shallowly (array or single object).
+ */
+function useStableConfig(config: AgentConfig): AgentConfig {
+  const ref = useRef<AgentConfig>(config);
+
+  const prev = ref.current;
+  const changed =
+    prev.sessionId !== config.sessionId ||
+    prev.model !== config.model ||
+    prev.instructions !== config.instructions ||
+    prev.store !== config.store ||
+    !shallowEqual(prev.context, config.context) ||
+    !shallowEqual(prev.artifacts, config.artifacts) ||
+    !shallowEqual(prev.telemetry, config.telemetry) ||
+    !toolsEqual(prev.tools, config.tools);
+
+  if (changed) {
+    ref.current = config;
+  }
+
+  return ref.current;
+}
+
+// ---------------------------------------------------------------------------
+// useAgent
+// ---------------------------------------------------------------------------
+
+export function useAgent(config: AgentConfig): UseAgentResult {
+  const stableConfig = useStableConfig(config);
+  const agentRef = useRef<Agent | null>(null);
+
+  const [messages, setMessages] = useState<AgentMessage[]>([]);
+  const [toolCalls, setToolCalls] = useState<AgentToolRun[]>([]);
+  const [artifacts, setArtifacts] = useState<AgentArtifactRef[]>([]);
+  const [status, setStatus] = useState<AgentStatus>({ state: "idle" });
+  const [error, setError] = useState<AgentError | null>(null);
+
+  // Create / re-create Agent whenever the stable config changes.
+  useEffect(() => {
+    const agent = new Agent(stableConfig);
+    agentRef.current = agent;
+
+    const unsubscribers: (() => void)[] = [];
+
+    unsubscribers.push(
+      agent.on("messageStart", (message) => {
+        setMessages((prev) => [...prev, message]);
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("text", (delta) => {
+        setMessages((prev) => {
+          const lastIndex = prev.length - 1;
+          const last = prev[lastIndex];
+          if (!last || last.role !== "assistant") return prev;
+
+          const content = [...last.content];
+          const textIndex = content.findIndex((b) => b.type === "text");
+          if (textIndex >= 0) {
+            const block = content[textIndex] as { type: "text"; text: string };
+            content[textIndex] = { ...block, text: block.text + delta };
+          } else {
+            content.push({ type: "text", text: delta });
+          }
+
+          return [...prev.slice(0, lastIndex), { ...last, content }];
+        });
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("messageEnd", (message) => {
+        setMessages((prev) => {
+          const lastIndex = prev.length - 1;
+          if (lastIndex >= 0 && prev[lastIndex].role === "assistant") {
+            return [...prev.slice(0, lastIndex), message];
+          }
+          return [...prev, message];
+        });
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("toolStart", (tool) => {
+        setToolCalls((prev) => [...prev, tool]);
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("toolUpdate", (tool) => {
+        setToolCalls((prev) => prev.map((t) => (t.id === tool.id ? tool : t)));
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("toolEnd", (tool) => {
+        setToolCalls((prev) => prev.map((t) => (t.id === tool.id ? tool : t)));
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("artifact", (artifact) => {
+        setArtifacts((prev) => [...prev, artifact]);
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("status", (newStatus) => {
+        setStatus(newStatus);
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("error", (err) => {
+        setError(err);
+      }),
+    );
+
+    unsubscribers.push(
+      agent.on("done", (result) => {
+        if (result.status === "completed") {
+          setStatus({ state: "completed" });
+        } else if (result.status === "aborted") {
+          setStatus({ state: "aborted" });
+        } else if (result.status === "failed") {
+          setStatus({ state: "failed", message: result.error?.message });
+        }
+      }),
+    );
+
+    return () => {
+      for (const unsub of unsubscribers) {
+        unsub();
+      }
+      agent.dispose();
+      agentRef.current = null;
+    };
+  }, [stableConfig]);
+
+  const send = useCallback(
+    async (
+      input: string | AgentInput,
+      options?: AgentRunOptions,
+    ): Promise<AgentRunResult> => {
+      const agent = agentRef.current;
+      if (!agent) {
+        const err = createAgentError(
+          "agent_disposed",
+          "Agent is not available",
+          { recoverable: false },
+        );
+        setError(err);
+        return {
+          status: "failed",
+          text: "",
+          toolCalls: [],
+          artifacts: [],
+          error: err,
+        };
+      }
+
+      // Prepend user message to messages state before calling run()
+      const userMessage: AgentMessage = {
+        id: `user-${Date.now()}`,
+        role: "user",
+        content: [
+          { type: "text", text: typeof input === "string" ? input : input.text },
+        ],
+        timestamp: Date.now(),
+      };
+      setMessages((prev) => [userMessage, ...prev]);
+
+      try {
+        return await agent.run(input, options);
+      } catch (e) {
+        const err = createAgentError(
+          "internal_error",
+          e instanceof Error ? e.message : String(e),
+          { cause: e, recoverable: false },
+        );
+        setError(err);
+        return {
+          status: "failed",
+          text: "",
+          toolCalls: [],
+          artifacts: [],
+          error: err,
+        };
+      }
+    },
+    [],
+  );
+
+  const stop = useCallback((reason?: string) => {
+    agentRef.current?.stop(reason);
+  }, []);
+
+  const steer = useCallback(
+    async (input: string | AgentInput): Promise<void> => {
+      const agent = agentRef.current;
+      if (!agent) {
+        const err = createAgentError(
+          "agent_disposed",
+          "Agent is not available",
+          { recoverable: false },
+        );
+        setError(err);
+        throw err;
+      }
+      try {
+        await agent.steer(input);
+      } catch (e) {
+        const err = createAgentError(
+          "internal_error",
+          e instanceof Error ? e.message : String(e),
+          { cause: e, recoverable: false },
+        );
+        setError(err);
+        throw err;
+      }
+    },
+    [],
+  );
+
+  const reset = useCallback(async (): Promise<void> => {
+    const agent = agentRef.current;
+    if (!agent) {
+      const err = createAgentError(
+        "agent_disposed",
+        "Agent is not available",
+        { recoverable: false },
+      );
+      setError(err);
+      throw err;
+    }
+    try {
+      setError(null); // Clear error BEFORE await
+      await agent.reset();
+      setMessages([]);
+      setToolCalls([]);
+      setArtifacts([]);
+    } catch (e) {
+      const err = createAgentError(
+        "internal_error",
+        e instanceof Error ? e.message : String(e),
+        { cause: e, recoverable: false },
+      );
+      setError(err);
+      // Error is NOT cleared after failure — it reflects the failure
+      throw err;
+    }
+  }, []);
+
+  return {
+    send,
+    stop,
+    steer,
+    reset,
+    status,
+    messages,
+    toolCalls,
+    artifacts,
+    error,
+  };
+}