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

package/sdk/snapshot.ts

@@ -0,0 +1,25 @@
+// SnapshotSerializer: converts between internal PersistData and public AgentSnapshot.
+// Validates version and rejects unknown versions (returns null).
+
+import type { AgentSnapshot } from "./types.ts";
+
+const CURRENT_VERSION = 1;
+
+export class SnapshotSerializer {
+  serialize(data: unknown): AgentSnapshot {
+    return {
+      version: CURRENT_VERSION,
+      data,
+    };
+  }
+
+  deserialize(snapshot: AgentSnapshot): unknown | null {
+    if (snapshot.version !== CURRENT_VERSION) {
+      console.warn(
+        `Snapshot version mismatch: expected ${CURRENT_VERSION}, got ${snapshot.version}. Starting fresh.`,
+      );
+      return null;
+    }
+    return snapshot.data;
+  }
+}

package/sdk/stores.ts

@@ -0,0 +1,72 @@
+// Public store API for the pi-oxide SDK.
+// Stores persist opaque snapshots; they do not interpret transcript internals.
+
+import { indexedDbStore as internalIndexedDbStore } from "./internal/stores/indexedDb.ts";
+import type { AgentStore, AgentSnapshot } from "./types.ts";
+
+export { type AgentStore, type AgentSnapshot } from "./types.ts";
+
+/**
+ * Store backed by IndexedDB. Durable across page reloads.
+ */
+export function indexedDbStore(): AgentStore {
+  return internalIndexedDbStore();
+}
+
+/**
+ * In-memory store. Session data is lost when the page reloads.
+ */
+export function memoryStore(): AgentStore {
+  const sessions = new Map<string, AgentSnapshot>();
+
+  return {
+    async loadSession(sessionId: string): Promise<AgentSnapshot | null> {
+      return sessions.get(sessionId) ?? null;
+    },
+
+    async saveSession(sessionId: string, snapshot: AgentSnapshot): Promise<void> {
+      sessions.set(sessionId, snapshot);
+    },
+  };
+}
+
+/**
+ * Store backed by localStorage. Simple but limited by storage quotas.
+ */
+export function localStorageStore(): AgentStore {
+  return {
+    async loadSession(sessionId: string): Promise<AgentSnapshot | null> {
+      const raw = localStorage.getItem(`pi-oxide-session-${sessionId}`);
+      if (!raw) return null;
+      return JSON.parse(raw) as AgentSnapshot;
+    },
+
+    async saveSession(sessionId: string, snapshot: AgentSnapshot): Promise<void> {
+      localStorage.setItem(`pi-oxide-session-${sessionId}`, JSON.stringify(snapshot));
+    },
+  };
+}
+
+/**
+ * Store backed by an HTTP API.
+ * Expects endpoints at `${baseUrl}/sessions/${sessionId}`.
+ */
+export function httpStore(config: { baseUrl: string }): AgentStore {
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+
+  return {
+    async loadSession(sessionId: string): Promise<AgentSnapshot | null> {
+      const resp = await fetch(`${baseUrl}/sessions/${sessionId}`);
+      if (!resp.ok) return null;
+      return resp.json() as Promise<AgentSnapshot>;
+    },
+
+    async saveSession(sessionId: string, snapshot: AgentSnapshot): Promise<void> {
+      await fetch(`${baseUrl}/sessions/${sessionId}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(snapshot),
+      });
+    },
+  };
+}

package/sdk/tools.ts

@@ -0,0 +1,47 @@
+// Public tool API for the pi-oxide SDK.
+// Tools are easy to declare and strongly typed at the boundary.
+
+import type { ZodType } from "zod";
+import type { AgentToolDefinition, AgentTools } from "./types.ts";
+
+export interface ToolConfig<Input, Output> {
+  description: string;
+  input: ZodType<Input>;
+  run: (input: Input) => Promise<Output> | Output;
+  details?: (output: Output) => Record<string, unknown>;
+}
+
+/**
+ * Declare a single tool definition with a Zod schema for input validation.
+ * The `name` is filled in by `defineTools()`.
+ */
+export function tool<Input, Output>(config: ToolConfig<Input, Output>): AgentToolDefinition {
+  return {
+    name: "",
+    description: config.description,
+    inputSchema: config.input,
+    run: config.run as (input: unknown) => Promise<unknown> | unknown,
+    details: config.details
+      ? (config.details as (output: unknown) => Record<string, unknown>)
+      : undefined,
+  };
+}
+
+/**
+ * Build a mergeable AgentTools pack from a record of tool definitions.
+ * Multiple packs can be composed as an array in AgentConfig.tools.
+ */
+export function defineTools(tools: Record<string, AgentToolDefinition>): AgentTools {
+  const entries = Object.entries(tools).map(([name, def]) => ({
+    ...def,
+    name,
+  }));
+
+  return {
+    definitions: entries,
+    getHandler(name: string) {
+      const def = entries.find((d) => d.name === name);
+      return def?.run ?? null;
+    },
+  };
+}

package/sdk/types.ts

@@ -0,0 +1,252 @@
+// Public type definitions for the pi-oxide SDK.
+// No WASM imports in this file — these are pure TypeScript contracts.
+
+import type {
+  AgentArtifact,
+  AgentArtifactRef,
+  ArtifactPolicy,
+  ArtifactSearchQuery,
+  ArtifactSearchResult,
+} from "./artifacts.ts";
+
+export type {
+  AgentArtifact,
+  AgentArtifactRef,
+  ArtifactPolicy,
+  ArtifactSearchQuery,
+  ArtifactSearchResult,
+} from "./artifacts.ts";
+
+export interface AgentConfig {
+  sessionId: string;
+  model: AgentModel;
+  tools?: AgentTools | AgentTools[];
+  store?: AgentStore;
+  instructions?: string;
+  context?: AgentContextPolicy;
+  artifacts?: ArtifactPolicy;
+  telemetry?: AgentTelemetry;
+}
+
+export type AgentInput =
+  | string
+  | {
+      text: string;
+      attachments?: AgentAttachment[];
+      metadata?: Record<string, unknown>;
+    };
+
+export interface AgentAttachment {
+  type: string;
+  content: string | Uint8Array;
+  mimeType?: string;
+}
+
+export interface AgentRunOptions {
+  signal?: AbortSignal;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentRunResult {
+  status: "completed" | "aborted" | "failed";
+  message?: AgentMessage;
+  text: string;
+  toolCalls: AgentToolRun[];
+  artifacts: AgentArtifactRef[];
+  usage?: TokenUsage;
+  error?: AgentError;
+}
+
+export type AgentEventName =
+  | "messageStart"
+  | "text"
+  | "messageEnd"
+  | "toolStart"
+  | "toolUpdate"
+  | "toolEnd"
+  | "artifact"
+  | "status"
+  | "done"
+  | "error"
+  | "debug";
+
+export type AgentEventHandler<E extends AgentEventName> =
+  E extends "messageStart" ? (message: AgentMessage) => void :
+  E extends "text" ? (delta: string) => void :
+  E extends "messageEnd" ? (message: AgentMessage) => void :
+  E extends "toolStart" ? (tool: AgentToolRun) => void :
+  E extends "toolUpdate" ? (tool: AgentToolRun) => void :
+  E extends "toolEnd" ? (tool: AgentToolRun) => void :
+  E extends "artifact" ? (artifact: AgentArtifactRef) => void :
+  E extends "status" ? (status: AgentStatus) => void :
+  E extends "done" ? (result: AgentRunResult) => void :
+  E extends "error" ? (error: AgentError) => void :
+  E extends "debug" ? (event: unknown) => void :
+  never;
+
+export interface AgentMessage {
+  id: string;
+  role: "user" | "assistant" | "tool_result";
+  content: AgentContentBlock[];
+  timestamp?: number;
+  tool_call_id?: string;
+}
+
+export type AgentContentBlock =
+  | { type: "text"; text: string }
+  | { type: "tool_call"; id: string; name: string; arguments: unknown }
+  | { type: "image"; mimeType: string; data: string }
+  | { type: "file"; mimeType: string; data: string };
+
+export interface AgentToolRun {
+  id: string;
+  name: string;
+  title?: string;
+  input: unknown;
+  output?: unknown;
+  status: "running" | "completed" | "failed" | "cancelled";
+  startedAt: number;
+  endedAt?: number;
+  error?: AgentError;
+}
+
+export interface AgentStatus {
+  state:
+    | "idle"
+    | "loading"
+    | "thinking"
+    | "calling_model"
+    | "running_tool"
+    | "saving"
+    | "completed"
+    | "aborted"
+    | "failed";
+  message?: string;
+}
+
+export interface AgentModel {
+  id?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  capabilities?: {
+    vision?: boolean;
+    jsonMode?: boolean;
+    functionCalling?: boolean;
+    streaming?: boolean;
+  };
+  generate(request: ModelRequest): Promise<ModelResponse>;
+  summarize?(messages: AgentMessage[], signal?: AbortSignal): Promise<string>;
+}
+
+export interface ModelRequest {
+  instructions: string;
+  messages: AgentMessage[];
+  tools: AgentToolDefinition[];
+  signal?: AbortSignal;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ModelResponse {
+  content: AgentContentBlock[];
+  stopReason: "end" | "tool_call" | "length" | "error";
+  usage?: TokenUsage;
+  model?: string;
+  raw?: unknown;
+}
+
+export interface ModelEvent {
+  type: "text_delta" | "tool_call_delta" | "done";
+  payload: unknown;
+}
+
+export interface AgentTools {
+  definitions: AgentToolDefinition[];
+  getHandler(name: string): ((input: unknown) => Promise<unknown> | unknown) | null;
+}
+
+export interface AgentToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: unknown; // ZodType, but we avoid importing zod in public types
+  run: (input: unknown) => Promise<unknown> | unknown;
+  details?: (output: unknown) => Record<string, unknown>;
+}
+
+export interface AgentStore {
+  loadSession(sessionId: string): Promise<AgentSnapshot | null>;
+  saveSession(sessionId: string, snapshot: AgentSnapshot): Promise<void>;
+  saveArtifact?(sessionId: string, artifact: AgentArtifact): Promise<void>;
+  loadArtifact?(sessionId: string, artifactId: string): Promise<AgentArtifact | null>;
+  searchArtifacts?(sessionId: string, query: ArtifactSearchQuery): Promise<ArtifactSearchResult[]>;
+}
+
+export interface AgentSnapshot {
+  version: number;
+  data: unknown;
+}
+
+export interface AgentContextPolicy {
+  maxTokens?: number;
+  toolResultLimit?: number;
+  strategy?:
+    | { type: "keep_full" }
+    | { type: "head"; tokens: number }
+    | { type: "tail"; tokens: number }
+    | { type: "head_tail"; headTokens: number; tailTokens: number }
+    | { type: "drop_if_old"; maxAgeMs: number };
+  summarize?: boolean | AgentSummarizer;
+}
+
+export interface AgentSummarizer {
+  summarize(messages: AgentMessage[]): Promise<string>;
+}
+
+export interface AgentTelemetry {
+  onEvent?(event: { type: string; payload: unknown }): void;
+  onMetric?(name: string, value: number, metadata?: Record<string, unknown>): void;
+}
+
+export interface AgentError {
+  code:
+    | "model_auth_failed"
+    | "model_rate_limited"
+    | "model_unavailable"
+    | "tool_input_invalid"
+    | "tool_failed"
+    | "tool_duplicate"
+    | "store_load_failed"
+    | "store_save_failed"
+    | "store_artifact_unsupported"
+    | "snapshot_invalid"
+    | "aborted"
+    | "internal_error"
+    | "agent_disposed"
+    | "agent_busy"
+    | "agent_not_initialized";
+  message: string;
+  cause?: unknown;
+  recoverable: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cache_read: number;
+  cache_write: number;
+  total_tokens: number;
+}
+
+export interface UseAgentResult {
+  send(input: string | AgentInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+  stop(reason?: string): void;
+  steer(input: string | AgentInput): Promise<void>;
+  reset(): Promise<void>;
+  status: AgentStatus;
+  messages: AgentMessage[];
+  toolCalls: AgentToolRun[];
+  artifacts: AgentArtifactRef[];
+  error: AgentError | null;
+}
+
+export type Unsubscribe = () => void;