@astralform/js 0.2.2 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @astralform/js
 
-JavaScript/TypeScript SDK for [Astralform](https://astralform.ai) — AI agent orchestration with SSE streaming, client-side tool execution, and [WebMCP](https://developer.chrome.com/docs/extensions/ai/webmcp) bridge support.
+JavaScript/TypeScript SDK for [Astralform](https://astralform.ai) — AI agent orchestration with SSE streaming and client-side tool execution.
 
 ## Install
 
@@ -20,14 +20,16 @@ const session = new ChatSession({
 
 session.on((event) => {
   switch (event.type) {
-    case "chunk":
-      process.stdout.write(event.text);
+    case "block_delta":
+      if (event.delta.channel === "text") {
+        process.stdout.write(event.delta.text);
+      }
       break;
-    case "complete":
+    case "message_stop":
       console.log("\nDone!");
       break;
     case "error":
-      console.error(event.error.message);
+      console.error(`${event.code}: ${event.message}`);
       break;
   }
 });
@@ -41,9 +43,11 @@ session.disconnect();
 
 - **SSE Streaming** — Real-time token-by-token responses via Server-Sent Events
 - **Client-Side Tools** — Register tools that the LLM can call, executed locally in your app
-- **WebMCP Bridge** — Auto-discovers browser tools from `navigator.modelContext` (Chrome 146+)
+- **Approval-Gated Tools** — Respond to `tool_approval_requested` events before execution
+- **UI Protocols** — Pluggable renderers for MCP-style embedded resources (A2UI, etc.)
 - **Multi-Agent** — Route messages to specific agents or let the supervisor choose
 - **Conversation Management** — Create, switch, delete, and resume conversations
+- **Event Replay** — Translate persisted wire events back into `ChatEvent`s
 - **Zero Dependencies** — Uses only native APIs (`fetch`, `ReadableStream`, `crypto`)
 - **Universal** — ESM + CJS, works in browsers and Node.js 18+
 
@@ -62,7 +66,7 @@ const session = new ChatSession({
 
 ## Events
 
-Subscribe to events with `.on()`, which returns an unsubscribe function:
+Subscribe to events with `.on()`, which returns an unsubscribe function. The SDK forwards a typed `ChatEvent` for every wire event — consumers build their own block / message state from the stream.
 
 ```ts
 const unsubscribe = session.on((event) => {
@@ -70,35 +74,73 @@ const unsubscribe = session.on((event) => {
     case "connected":
       // Session connected, project status and tools loaded
       break;
-    case "chunk":
-      // Streaming text chunk: event.text
+
+    // --- Turn lifecycle ---
+    case "message_start":
+      // New turn: event.turnId, event.model, event.agentDisplayName
+      break;
+    case "block_start":
+      // A content block opened: event.kind ("text" | "thinking" | "tool_use" | ...)
       break;
-    case "complete":
-      // Response finished: event.content, event.conversationId, event.title
+    case "block_delta":
+      // Streaming chunk. Narrow by event.delta.channel:
+      //   - "text": event.delta.text
+      //   - "thinking": event.delta.text
+      //   - "input" / "input_arg": partial tool input
+      //   - "output": interpreter stdout/stderr/progress
+      //   - "status": "executing" | "awaiting_client_result" | "awaiting_approval" | "denied"
       break;
-    case "tool_call":
-      // Tool invoked: event.request.toolName, event.request.arguments
+    case "block_stop":
+      // Block finished. event.status === "awaiting_client_result" means
+      // a client-side tool is ready to run (see "Client-Side Tools" below).
+      break;
+    case "message_stop":
+      // Turn complete: event.stopReason, event.usage, event.totalMs, event.jobId
+      break;
+
+    // --- Custom events (typed variants) ---
+    case "subagent_start":
+    case "subagent_stop":
+      // event.agent (AgentIdentity), event.taskCallId
       break;
-    case "tool_executing":
-      // Tool running: event.name
+    case "todo_update":
+      // event.todos (TodoItem[])
       break;
-    case "tool_completed":
-      // Tool finished: event.name, event.result
+    case "title_generated":
+      // event.title
       break;
-    case "agent_start":
-      // Agent began processing: event.agentName, event.agentDisplayName
+    case "context_warning":
+      // event.severity, event.utilizationPct, event.remainingTokens, ...
       break;
-    case "agent_end":
-      // Agent finished: event.agentName
+    case "memory_recall":
+    case "memory_update":
+      // Backend memory subsystem surfaced to the UI
       break;
-    case "model_info":
-      // LLM model identified: event.name
+    case "tool_approval_requested":
+      // Respond via client.submitToolApproval(...)
+      break;
+    case "asset_created":
+    case "attachment_staged":
+    case "workspace_ready":
+    case "desktop_stream":
+      // Workspace / asset pipeline events
+      break;
+    case "state_changed":
+      // event.state ("queued" | "running" | "waiting_for_tool" | ...)
+      break;
+    case "custom":
+      // Unknown custom event — forward-compat passthrough
+      break;
+
+    // --- Transport / errors ---
+    case "retry":
+    case "stall":
+    case "keepalive":
       break;
     case "error":
-      // Error occurred: event.error
+      // event.code, event.message, event.blockPath
       break;
     case "disconnected":
-      // Session disconnected
       break;
   }
 });
@@ -135,41 +177,64 @@ await session.send("What time is it in Tokyo?");
 
 The tool execution flow is handled automatically:
 
-1. LLM requests a client tool call via SSE
-2. SDK executes the tool handler locally
-3. SDK posts the result to `/v1/tool-result`
-4. SDK continues the SSE stream for the LLM's final response
+1. LLM requests a client tool (wire: `block_start(kind="tool_use")`, then streaming `block_delta(channel="input")`)
+2. Backend signals ready-to-run with `block_stop(status="awaiting_client_result")` — `final.call_id`, `final.tool_name`, and `final.input` carry the parsed arguments
+3. SDK invokes the registered handler locally
+4. SDK posts the result to `/v1/tool-result`
+5. SDK continues the SSE stream for the LLM's final response
 
-## WebMCP Bridge
+Observers can show "running…" UIs by watching `block_start(kind="tool_use")` and `block_stop(status="awaiting_client_result")` directly.
 
-On Chrome 146+ with WebMCP support, the SDK auto-discovers browser-registered tools:
+### Approval-gated tools
 
-```ts
-await session.connect(); // Automatically calls navigator.modelContext.tools.list()
+When a tool requires user approval, the backend emits a `tool_approval_requested` event instead of proceeding to `awaiting_client_result`. Respond with `client.submitToolApproval(...)`:
 
-console.log("WebMCP available:", session.webMCP.isAvailable());
+```ts
+session.on(async (event) => {
+  if (event.type === "tool_approval_requested") {
+    const ok = confirm(`Allow ${event.toolName}? (${event.reason ?? ""})`);
+    await session.client.submitToolApproval({
+      job_id: session.currentJobId ?? "",
+      call_id: event.callId,
+      decision: ok ? "allow" : "deny",
+      scope: "once", // "once" | "conversation" | "always"
+    });
+  }
+});
 ```
 
-You can also register tools that appear in both WebMCP and Astralform:
+## UI Protocols
+
+When the backend renders rich UI surfaces (A2UI today, other protocols in the future), tool output arrives wrapped as an MCP-style embedded resource. Register a framework-specific renderer keyed by MIME type:
 
 ```ts
-session.webMCP.registerTool(
-  "page_content",
-  "Get the current page content",
-  {
-    type: "object",
-    properties: {
-      selector: { type: "string", description: "CSS selector" },
+import { ChatSession, parseEmbeddedResource } from "@astralform/js";
+
+await session.connect();
+
+// Gate registration on the project's configured protocol.
+if (session.projectStatus?.uiComponents.enabled) {
+  session.protocols.register({
+    mimeType: session.projectStatus.uiComponents.mimeType!,
+    render: (payload) => {
+      /* framework-specific render */
     },
-  },
-  async (args) => {
-    const el = document.querySelector((args.selector as string) || "body");
-    return el?.textContent ?? "Not found";
-  },
-);
+  });
+}
+
+// Inside your tool-result block handler:
+session.on((event) => {
+  if (event.type === "block_stop" && event.final) {
+    const resource = parseEmbeddedResource(event.final.output);
+    if (resource) {
+      const adapter = session.protocols.get(resource.mimeType);
+      adapter?.render(resource.payload);
+    }
+  }
+});
 ```
 
-WebMCP tools are registered with the `mcp_webmcp_` prefix in the tool manifest sent to the backend.
+The SDK never imports a renderer — adapters are opaque handles that the consumer narrows on read. Adapters are dropped on `disconnect()`.
 
 ## Multi-Agent
 
@@ -206,18 +271,25 @@ session.conversations;    // All conversations
 session.messages;         // Messages in current conversation
 ```
 
-## Toggle Tools
+## Enabling Client Tools
+
+Client tools registered via `session.toolRegistry.registerTool(...)` only run when their name is in the session's enabled set:
 
 ```ts
-// Toggle platform tools (e.g. web search)
-session.toggleTool("search"); // Returns true if now enabled, false if disabled
+// Enable / disable a registered client tool
+session.toggleClientTool("mcp_get_current_time"); // returns true if now enabled
+
+// Inspect the enabled set
+session.enabledClientTools; // Set<string>
+```
 
-// Toggle MCP tools
-session.toggleMcp("github__list_repos");
+Platform-level features (web search, plan mode) are enabled per-request via the `send` options:
 
-// Check enabled state
-session.enabledTools; // Set<string>
-session.enabledMcp;   // Set<string>
+```ts
+await session.send("Research the latest on WebGPU", {
+  enableSearch: true,
+  planMode: true,
+});
 ```
 
 ## Low-Level Client
@@ -236,8 +308,6 @@ const client = new AstralformClient({
 const status = await client.getProjectStatus();
 const conversations = await client.getConversations();
 const messages = await client.getMessages("conversation-id");
-const tools = await client.getTools();
-const mcpTools = await client.getMcpTools();
 const agents = await client.getAgents();
 const skills = await client.getSkills();
 
@@ -245,7 +315,7 @@ const skills = await client.getSkills();
 const job = await client.createJob({ message: "Hello" });
 for await (const event of client.streamJobEvents(job.job_id)) {
   const data = JSON.parse(event.data);
-  if (data.type === "content_block_delta") {
+  if (data.type === "block_delta" && data.delta.channel === "text") {
     process.stdout.write(data.delta.text);
   }
 }
@@ -275,22 +345,35 @@ const session = new ChatSession(config, myStorage);
 
 ## Error Handling
 
-The SDK throws typed errors:
+HTTP calls (`connect`, `submitToolApproval`, `createJob`, …) throw typed errors:
 
 ```ts
 import {
-  AuthenticationError,  // 401 — invalid API key
-  RateLimitError,       // 429 — rate limit exceeded
+  AuthenticationError, // 401 — invalid API key
+  RateLimitError, // 429 — rate limit exceeded
   LLMNotConfiguredError, // LLM provider not set up
-  ServerError,          // 5xx or unexpected errors
-  ConnectionError,      // Network failures
-  StreamAbortedError,   // Stream cancelled via disconnect()
+  ServerError, // 5xx or unexpected errors
+  ConnectionError, // Network failures
+  StreamAbortedError, // Stream cancelled via disconnect()
 } from "@astralform/js";
 
+try {
+  await session.connect();
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // Redirect to login
+  }
+}
+```
+
+Errors that arrive over the SSE stream fire as a typed `error` event with a structured shape — no `Error` instance is wrapped:
+
+```ts
 session.on((event) => {
   if (event.type === "error") {
-    if (event.error instanceof AuthenticationError) {
-      // Redirect to login
+    // event.code, event.message, event.blockPath
+    if (event.code === "rate_limit_exceeded") {
+      // Show backoff UI
     }
   }
 });
@@ -315,12 +398,16 @@ function useChat(apiKey: string, userId: string) {
 
     session.on((event: ChatEvent) => {
       switch (event.type) {
-        case "chunk":
-          setStreaming((s) => s + event.text);
+        case "block_delta":
+          if (event.delta.channel === "text") {
+            setStreaming((s) => s + event.delta.text);
+          }
           break;
-        case "complete":
-          setMessages((m) => [...m, event.content]);
-          setStreaming("");
+        case "message_stop":
+          setStreaming((s) => {
+            setMessages((m) => [...m, s]);
+            return "";
+          });
           break;
       }
     });