@codespring-app/use-agent 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0 — 2026-08-30
+
+- Add origin-bound, single-use browser WebSocket ticket exchange.
+- Add durable multi-page replay and the public `AgentSession.connect` API.
+- Add contiguous cursor tracking, replay/live deduplication, gap recovery, and
+  reconnect state to the React session store.
+- Align message and tool reducers with the canonical runtime event protocol.
+- Add the reusable `AgentEventBuffer` and a production live-replay smoke.
+
+## 0.1.0 — 2026-08-30
+
+- Publish the initial public server and React SDK preview.

package/README.md

@@ -75,6 +75,12 @@ The `/browser` endpoint is intentional: it accepts only short-lived client
 tokens and is the only runtime surface with browser CORS. Server API keys stay
 on the endpoint root and must never be shipped to a browser.
 
+The React session store loads durable history, then switches to a live
+WebSocket using a 30-second, single-use ticket. It keeps one contiguous event
+cursor, removes replay/live duplicates, repairs gaps over HTTP, and reconnects
+with bounded jitter. `useAgentSession` exposes `connection` as `idle`,
+`connecting`, `live`, `reconnecting`, or `closed` for custom status UI.
+
 The default Paper experience renders assistant replies as document content on
 an edge-to-edge canvas, user messages as quiet trailing wells, tool calls as
 compact inspectable activity rows, and the live-edge composer without a shadow.
@@ -153,6 +159,28 @@ mixed with client-owned components.
 The browser entrypoint never accepts an API key. A trusted application backend
 must issue short-lived, origin-bound client tokens.
 
+For a non-React browser UI, connect to the same durable stream directly:
+
+```ts
+const session = agentClient.sessions.get(sessionId);
+const connection = await session.connect({
+  after: lastAppliedCursor,
+  onEvent(event) {
+    // Persist or reduce the event, then advance lastAppliedCursor.
+  },
+  onReplayComplete(cursor) {
+    console.log("Live at", cursor);
+  },
+});
+
+connection.close();
+```
+
+The SDK performs the authenticated ticket exchange and automatically follows
+multi-page WebSocket replay. `AgentEventBuffer` is available to headless
+clients that want the same contiguous-cursor, deduplication, and gap-detection
+rules as the React store.
+
 ## Local showcase
 
 ```sh

package/dist/{chunk-FAD2XMPA.js → chunk-CC365XBZ.js}

@@ -42,6 +42,101 @@ var Transport = class {
     }
     return payload;
   }
+  async connectSession(sessionId, options) {
+    if (!this.options.browser) {
+      throw new TypeError("Browser WebSocket connections require createBrowserClient");
+    }
+    const after = options.after ?? 0;
+    if (!Number.isSafeInteger(after) || after < 0) {
+      throw new TypeError("after must be a non-negative safe integer");
+    }
+    const issued = await this.request(
+      `/v1/sessions/${encodeURIComponent(sessionId)}/websocket-tickets`,
+      {
+        method: "POST",
+        body: JSON.stringify({ after }),
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      }
+    );
+    const socketUrl = new URL(
+      `${this.endpoint}/v1/sessions/${encodeURIComponent(sessionId)}/connect`
+    );
+    socketUrl.protocol = socketUrl.protocol === "https:" ? "wss:" : "ws:";
+    socketUrl.searchParams.set("ticket", issued.ticket);
+    const createSocket = this.options.webSocket ?? defaultWebSocketFactory;
+    const socket = createSocket(socketUrl.toString());
+    let cursor = after;
+    let opened = false;
+    let settled = false;
+    return new Promise((resolve, reject) => {
+      const connection = {
+        get cursor() {
+          return cursor;
+        },
+        close: (code = 1e3, reason = "client closed") => socket.close(code, reason)
+      };
+      const failBeforeOpen = (error) => {
+        if (settled) return;
+        settled = true;
+        reject(error);
+      };
+      socket.addEventListener("open", () => {
+        opened = true;
+        if (settled) return;
+        settled = true;
+        resolve(connection);
+      });
+      socket.addEventListener("message", (message) => {
+        try {
+          const parsed = parseWebSocketServerMessage(message.data);
+          if (parsed.type === "event") {
+            cursor = Math.max(cursor, parsed.event.id);
+            options.onEvent(parsed.event);
+            return;
+          }
+          if (parsed.type === "replay.completed") {
+            cursor = Math.max(cursor, parsed.cursor);
+            if (parsed.hasMore) {
+              socket.send(JSON.stringify({ type: "replay", after: cursor }));
+            } else {
+              options.onReplayComplete?.(cursor);
+            }
+            return;
+          }
+          const error = new AgentError(parsed.message, 0, parsed.code);
+          options.onError?.(error);
+          socket.close(1008, "server rejected connection");
+        } catch (error) {
+          const normalized = error instanceof Error ? error : new Error(String(error));
+          options.onError?.(normalized);
+          socket.close(1008, "invalid server message");
+          if (!opened) failBeforeOpen(normalized);
+        }
+      });
+      socket.addEventListener("error", () => {
+        const error = new AgentError("WebSocket connection failed", 0, "websocket_failed");
+        options.onError?.(error);
+        if (!opened) failBeforeOpen(error);
+      });
+      socket.addEventListener("close", (event) => {
+        options.onClose?.(event);
+        if (!opened) {
+          failBeforeOpen(
+            new AgentError(
+              "WebSocket closed before connecting",
+              0,
+              "websocket_closed"
+            )
+          );
+        }
+      });
+      if (options.signal) {
+        const closeForAbort = () => socket.close(1e3, "request aborted");
+        if (options.signal.aborted) closeForAbort();
+        else options.signal.addEventListener("abort", closeForAbort, { once: true });
+      }
+    });
+  }
   async fetchWithToken(path, init) {
     const headers = new Headers(init.headers);
     headers.set("Accept", "application/json");
@@ -169,6 +264,9 @@ var AgentSession = class {
       }
     );
   }
+  connect(options) {
+    return this.transport.connectSession(this.id, options);
+  }
 };
 var AgentClient = class {
   constructor(transport) {
@@ -193,6 +291,7 @@ function createClient(options) {
     new Transport({
       endpoint: options.endpoint,
       token: staticTokenProvider(options.apiKey),
+      browser: false,
       ...options.fetch === void 0 ? {} : { fetch: options.fetch }
     })
   );
@@ -206,15 +305,82 @@ function createBrowserClient(options) {
         options.clientTokenTtlMs ?? 6e4,
         options.refreshSkewMs ?? 3e4
       ),
-      ...options.fetch === void 0 ? {} : { fetch: options.fetch }
+      browser: true,
+      ...options.fetch === void 0 ? {} : { fetch: options.fetch },
+      ...options.webSocket === void 0 ? {} : { webSocket: options.webSocket }
     })
   );
 }
+function defaultWebSocketFactory(url) {
+  if (typeof globalThis.WebSocket !== "function") {
+    throw new TypeError("A WebSocket implementation is required");
+  }
+  return new globalThis.WebSocket(url);
+}
+function parseWebSocketServerMessage(value) {
+  if (typeof value !== "string") throw new TypeError("WebSocket message must be JSON text");
+  const parsed = JSON.parse(value);
+  if (!isObject(parsed) || typeof parsed.type !== "string") {
+    throw new TypeError("WebSocket message is invalid");
+  }
+  if (parsed.type === "event" && isAgentEvent(parsed.event)) {
+    return { type: "event", event: parsed.event };
+  }
+  if (parsed.type === "replay.completed" && Number.isSafeInteger(parsed.cursor) && parsed.cursor >= 0 && typeof parsed.hasMore === "boolean") {
+    return {
+      type: "replay.completed",
+      cursor: parsed.cursor,
+      hasMore: parsed.hasMore
+    };
+  }
+  if (parsed.type === "error" && typeof parsed.code === "string" && typeof parsed.message === "string") {
+    return { type: "error", code: parsed.code, message: parsed.message };
+  }
+  throw new TypeError("WebSocket message is invalid");
+}
+function isAgentEvent(value) {
+  return isObject(value) && value.schemaVersion === 1 && Number.isSafeInteger(value.id) && value.id > 0 && typeof value.sessionId === "string" && Number.isSafeInteger(value.attempt) && value.attempt >= 0 && typeof value.type === "string" && typeof value.createdAt === "string" && (!("turnId" in value) || typeof value.turnId === "string");
+}
+
+// src/event-buffer.ts
+var AgentEventBuffer = class {
+  ordered = [];
+  currentCursor = 0;
+  get cursor() {
+    return this.currentCursor;
+  }
+  get events() {
+    return this.ordered;
+  }
+  merge(incoming) {
+    const accepted = [];
+    const duplicateIds = [];
+    for (const event of incoming) {
+      if (event.id <= this.currentCursor) {
+        duplicateIds.push(event.id);
+        continue;
+      }
+      const expected = this.currentCursor + 1;
+      if (event.id !== expected) {
+        return { accepted, duplicateIds, gap: { expected, received: event.id } };
+      }
+      this.ordered.push(event);
+      this.currentCursor = event.id;
+      accepted.push(event);
+    }
+    return { accepted, duplicateIds };
+  }
+  reset() {
+    this.ordered = [];
+    this.currentCursor = 0;
+  }
+};
 
 export {
   AgentError,
   AgentSession,
   AgentClient,
   createClient,
-  createBrowserClient
+  createBrowserClient,
+  AgentEventBuffer
 };

package/dist/{client-Bz3eVQXx.d.ts → client-DcCIhqkm.d.ts}

@@ -40,6 +40,47 @@ interface ListEventsResponse {
     cursor: number;
     hasMore: boolean;
 }
+interface CreateWebSocketTicketResponse {
+    ticket: string;
+    expiresAt: string;
+}
+type WebSocketServerMessage = {
+    type: "event";
+    event: AgentEvent;
+} | {
+    type: "replay.completed";
+    cursor: number;
+    hasMore: boolean;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+};
+interface AgentWebSocketEventMap {
+    open: Event;
+    message: MessageEvent;
+    error: Event;
+    close: CloseEvent;
+}
+interface AgentWebSocket {
+    readonly readyState: number;
+    addEventListener<K extends keyof AgentWebSocketEventMap>(type: K, listener: (event: AgentWebSocketEventMap[K]) => void): void;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+type AgentWebSocketFactory = (url: string) => AgentWebSocket;
+interface AgentConnectionOptions {
+    after?: number;
+    signal?: AbortSignal;
+    onEvent: (event: AgentEvent) => void;
+    onReplayComplete?: (cursor: number) => void;
+    onError?: (error: Error) => void;
+    onClose?: (event: CloseEvent) => void;
+}
+interface AgentConnection {
+    readonly cursor: number;
+    close(code?: number, reason?: string): void;
+}
 /** Tenant-scoped model profile configured in the CodeSpring control plane. */
 type ModelProfileId = string;
 interface AgentToolReference {
@@ -95,6 +136,8 @@ interface BrowserAgentClientOptions {
     /** Refresh before expiry. Defaults to 30 seconds and is bounded for short tokens. */
     refreshSkewMs?: number;
     fetch?: FetchLike;
+    /** Injectable for tests or non-DOM browser runtimes. Defaults to the global WebSocket constructor. */
+    webSocket?: AgentWebSocketFactory;
 }
 type ClientTokenResult = string | {
     token: string;
@@ -117,6 +160,8 @@ interface TransportOptions {
     endpoint: string;
     token: TokenProvider;
     fetch?: FetchLike;
+    webSocket?: AgentWebSocketFactory;
+    browser: boolean;
 }
 declare class Transport {
     private readonly options;
@@ -124,6 +169,7 @@ declare class Transport {
     readonly fetchImplementation: FetchLike;
     constructor(options: TransportOptions);
     request<T>(path: string, init?: RequestInit): Promise<T>;
+    connectSession(sessionId: string, options: AgentConnectionOptions): Promise<AgentConnection>;
     private fetchWithToken;
 }
 declare class AgentSession {
@@ -134,6 +180,7 @@ declare class AgentSession {
     submit(content: string, options?: SubmitOptions): Promise<SubmitTurnResponse>;
     events(after?: number, limit?: number, options?: RequestOptions): Promise<ListEventsResponse>;
     cancel(turnId: string, options?: RequestOptions): Promise<TurnStatusResponse>;
+    connect(options: AgentConnectionOptions): Promise<AgentConnection>;
 }
 interface TurnStatusResponse {
     sessionId: string;
@@ -153,4 +200,4 @@ declare function createClient(options: AgentClientOptions): AgentClient;
 /** Browser-safe client used by the React subpath with short-lived client tokens. */
 declare function createBrowserClient(options: BrowserAgentClientOptions): AgentClient;
 
-export { type AgentDefinition as A, type BrowserAgentClientOptions as B, type CreateAgentOptions as C, type FetchLike as F, type ListEventsResponse as L, type ModelProfileId as M, type RequestOptions as R, type SessionSnapshot as S, type TurnStatus as T, AgentClient as a, type AgentClientOptions as b, AgentError as c, type AgentEvent as d, type AgentMcpServerReference as e, AgentSession as f, type AgentSkillReference as g, type AgentToolReference as h, type ClientTokenResult as i, type CreateSessionResponse as j, type SubmitOptions as k, type SubmitTurnResponse as l, createBrowserClient as m, createClient as n };
+export { type AgentDefinition as A, type BrowserAgentClientOptions as B, type CreateAgentOptions as C, type FetchLike as F, type ListEventsResponse as L, type ModelProfileId as M, type RequestOptions as R, type SessionSnapshot as S, type TurnStatus as T, type WebSocketServerMessage as W, type AgentEvent as a, AgentClient as b, type AgentClientOptions as c, type AgentConnection as d, type AgentConnectionOptions as e, AgentError as f, type AgentMcpServerReference as g, AgentSession as h, type AgentSkillReference as i, type AgentToolReference as j, type AgentWebSocket as k, type AgentWebSocketEventMap as l, type AgentWebSocketFactory as m, type ClientTokenResult as n, type CreateSessionResponse as o, type CreateWebSocketTicketResponse as p, type SubmitOptions as q, type SubmitTurnResponse as r, createBrowserClient as s, createClient as t };

package/dist/index.d.ts

@@ -1,7 +1,25 @@
-import { C as CreateAgentOptions, A as AgentDefinition } from './client-Bz3eVQXx.js';
-export { a as AgentClient, b as AgentClientOptions, c as AgentError, d as AgentEvent, e as AgentMcpServerReference, f as AgentSession, g as AgentSkillReference, h as AgentToolReference, B as BrowserAgentClientOptions, i as ClientTokenResult, j as CreateSessionResponse, F as FetchLike, L as ListEventsResponse, M as ModelProfileId, R as RequestOptions, S as SessionSnapshot, k as SubmitOptions, l as SubmitTurnResponse, T as TurnStatus, m as createBrowserClient, n as createClient } from './client-Bz3eVQXx.js';
+import { C as CreateAgentOptions, A as AgentDefinition, a as AgentEvent } from './client-DcCIhqkm.js';
+export { b as AgentClient, c as AgentClientOptions, d as AgentConnection, e as AgentConnectionOptions, f as AgentError, g as AgentMcpServerReference, h as AgentSession, i as AgentSkillReference, j as AgentToolReference, k as AgentWebSocket, l as AgentWebSocketEventMap, m as AgentWebSocketFactory, B as BrowserAgentClientOptions, n as ClientTokenResult, o as CreateSessionResponse, p as CreateWebSocketTicketResponse, F as FetchLike, L as ListEventsResponse, M as ModelProfileId, R as RequestOptions, S as SessionSnapshot, q as SubmitOptions, r as SubmitTurnResponse, T as TurnStatus, W as WebSocketServerMessage, s as createBrowserClient, t as createClient } from './client-DcCIhqkm.js';
 
 /** Defines a portable agent revision without importing runtime implementation code. */
 declare function createAgent(options: CreateAgentOptions): AgentDefinition;
 
-export { AgentDefinition, CreateAgentOptions, createAgent };
+interface AgentEventMergeResult {
+    accepted: AgentEvent[];
+    duplicateIds: number[];
+    gap?: {
+        expected: number;
+        received: number;
+    };
+}
+/** Maintains the single contiguous durable cursor used by replay and live delivery. */
+declare class AgentEventBuffer {
+    private ordered;
+    private currentCursor;
+    get cursor(): number;
+    get events(): readonly AgentEvent[];
+    merge(incoming: readonly AgentEvent[]): AgentEventMergeResult;
+    reset(): void;
+}
+
+export { AgentDefinition, AgentEvent, AgentEventBuffer, type AgentEventMergeResult, CreateAgentOptions, createAgent };

package/dist/index.js

@@ -1,10 +1,11 @@
 import {
   AgentClient,
   AgentError,
+  AgentEventBuffer,
   AgentSession,
   createBrowserClient,
   createClient
-} from "./chunk-FAD2XMPA.js";
+} from "./chunk-CC365XBZ.js";
 
 // src/agent.ts
 var identifierPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u;
@@ -41,6 +42,7 @@ function createAgent(options) {
 export {
   AgentClient,
   AgentError,
+  AgentEventBuffer,
   AgentSession,
   createAgent,
   createBrowserClient,

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode, PropsWithChildren } from 'react';
-import { a as AgentClient, f as AgentSession, S as SessionSnapshot, d as AgentEvent, k as SubmitOptions, l as SubmitTurnResponse, B as BrowserAgentClientOptions } from './client-Bz3eVQXx.js';
-export { m as createBrowserClient } from './client-Bz3eVQXx.js';
+import { b as AgentClient, h as AgentSession, S as SessionSnapshot, a as AgentEvent, q as SubmitOptions, r as SubmitTurnResponse, B as BrowserAgentClientOptions } from './client-DcCIhqkm.js';
+export { s as createBrowserClient } from './client-DcCIhqkm.js';
 
 interface AgentTheme {
     canvas: string;
@@ -91,15 +91,17 @@ interface CreateAgentClientOptions {
     credentials?: RequestCredentials;
     clientTokenTtlMs?: number;
     refreshSkewMs?: number;
+    webSocket?: BrowserAgentClientOptions["webSocket"];
 }
 /** Creates one stable browser client with an in-memory, deduplicated client-token cache. */
-declare function createAgentClient({ endpoint, clientTokenEndpoint, fetch: fetchImplementation, credentials, clientTokenTtlMs, refreshSkewMs, }: CreateAgentClientOptions): AgentClient;
+declare function createAgentClient({ endpoint, clientTokenEndpoint, fetch: fetchImplementation, credentials, clientTokenTtlMs, refreshSkewMs, webSocket, }: CreateAgentClientOptions): AgentClient;
 declare function useAgentTheme(): AgentTheme;
 declare function useAgentCopy(): AgentCopy;
 type AgentMessageStatus = "completed" | "streaming" | "failed" | "cancelled";
 interface AgentChatMessage {
     id: string;
     turnId: string;
+    attempt: number;
     role: "user" | "assistant";
     content: string;
     status: AgentMessageStatus;
@@ -113,6 +115,7 @@ declare function reduceAgentMessages(events: readonly AgentEvent[]): AgentChatMe
 declare function reduceAgentToolCalls(events: readonly AgentEvent[]): AgentToolCall[];
 interface SessionState {
     status: "idle" | "loading" | "ready" | "error";
+    connection: "idle" | "connecting" | "live" | "reconnecting" | "closed";
     snapshot: SessionSnapshot | null;
     events: AgentEvent[];
     messages: AgentChatMessage[];
@@ -123,15 +126,24 @@ declare class SessionStore {
     readonly session: AgentSession;
     private state;
     private readonly listeners;
+    private readonly eventBuffer;
     private controller;
-    private refreshTimer;
+    private connection;
+    private reconnectTimer;
+    private generation;
+    private reconnectAttempt;
     constructor(session: AgentSession);
     subscribe: (listener: () => void) => () => void;
     getSnapshot: () => SessionState;
     getServerSnapshot: () => SessionState;
     private setState;
-    private scheduleRefresh;
     refresh(): Promise<void>;
+    private replayDurableEvents;
+    private openLiveConnection;
+    private receiveLiveEvent;
+    private publishBuffer;
+    private scheduleReconnect;
+    private stop;
     dispose(): void;
 }
 interface AgentSessionResult extends SessionState {
@@ -161,12 +173,17 @@ interface AgentToolCallProps extends StyledProps {
 interface AgentToolCall {
     id: string;
     turnId: string;
+    operationId?: string;
+    callId?: string;
+    revision?: string;
+    risk?: string;
     name: string;
     label: string;
     summary?: string;
     status: AgentToolCallStatus;
     input?: unknown;
     output?: unknown;
+    error?: unknown;
     createdAt: string;
     eventId: number;
 }

package/dist/react.js

@@ -1,6 +1,8 @@
 import {
+  AgentError,
+  AgentEventBuffer,
   createBrowserClient
-} from "./chunk-FAD2XMPA.js";
+} from "./chunk-CC365XBZ.js";
 
 // src/react.tsx
 import {
@@ -182,7 +184,8 @@ function createAgentClient({
   fetch: fetchImplementation,
   credentials = "same-origin",
   clientTokenTtlMs,
-  refreshSkewMs
+  refreshSkewMs,
+  webSocket
 }) {
   return createBrowserClient({
     endpoint,
@@ -206,7 +209,8 @@ function createAgentClient({
     },
     ...fetchImplementation === void 0 ? {} : { fetch: fetchImplementation },
     ...clientTokenTtlMs === void 0 ? {} : { clientTokenTtlMs },
-    ...refreshSkewMs === void 0 ? {} : { refreshSkewMs }
+    ...refreshSkewMs === void 0 ? {} : { refreshSkewMs },
+    ...webSocket === void 0 ? {} : { webSocket }
   });
 }
 function useAgentTheme() {
@@ -229,11 +233,13 @@ function reduceAgentMessages(events) {
   for (const event of events) {
     if (!event.turnId) continue;
     const inputId = `${event.turnId}:user`;
-    const outputId = `${event.turnId}:assistant:${event.attempt}`;
+    const itemId = stringField(event.data, "itemId");
+    const outputId = `${event.turnId}:assistant:${itemId ?? `attempt-${event.attempt}`}`;
     if (event.type === "message.input") {
       messages.set(inputId, {
         id: inputId,
         turnId: event.turnId,
+        attempt: event.attempt,
         role: "user",
         content: stringField(event.data, "content") ?? "",
         status: "completed",
@@ -246,6 +252,7 @@ function reduceAgentMessages(events) {
       messages.set(outputId, {
         id: outputId,
         turnId: event.turnId,
+        attempt: event.attempt,
         role: "assistant",
         content: "",
         status: "streaming",
@@ -270,6 +277,7 @@ function reduceAgentMessages(events) {
       messages.set(outputId, {
         id: outputId,
         turnId: event.turnId,
+        attempt: event.attempt,
         role: "assistant",
         content: stringField(event.data, "content") ?? current?.content ?? "",
         status: "completed",
@@ -279,15 +287,20 @@ function reduceAgentMessages(events) {
       continue;
     }
     if (event.type === "message.attempt_abandoned") {
-      messages.delete(outputId);
+      for (const [id, message] of messages) {
+        if (message.turnId === event.turnId && message.role === "assistant" && message.attempt === event.attempt && message.status === "streaming") {
+          messages.delete(id);
+        }
+      }
       continue;
     }
     if (event.type === "turn.failed" || event.type === "turn.cancelled") {
-      const current = [...messages.values()].filter((message) => message.turnId === event.turnId && message.role === "assistant").at(-1);
+      const current = [...messages.values()].filter((message) => message.turnId === event.turnId && message.role === "assistant" && message.attempt === event.attempt).at(-1);
       const terminalId = current?.id ?? `${event.turnId}:assistant:${event.attempt}`;
       messages.set(terminalId, {
         id: terminalId,
         turnId: event.turnId,
+        attempt: event.attempt,
         role: "assistant",
         content: current?.content ?? "",
         status: event.type === "turn.failed" ? "failed" : "cancelled",
@@ -301,30 +314,49 @@ function reduceAgentMessages(events) {
 function reduceAgentToolCalls(events) {
   const calls = /* @__PURE__ */ new Map();
   for (const event of events) {
-    if (!event.turnId || !event.type.startsWith("tool.call.")) continue;
-    const eventName = stringField(event.data, "name");
-    const callId = stringField(event.data, "toolCallId") ?? `${event.turnId}:${event.attempt}:${eventName ?? "tool"}`;
-    const current = calls.get(callId);
+    if (!event.turnId) continue;
+    const lifecycle = toolLifecycle(event.type);
+    if (!lifecycle) continue;
+    const operationId = stringField(event.data, "operationId");
+    const callId = stringField(event.data, "callId") ?? stringField(event.data, "toolCallId");
+    const eventName = stringField(event.data, "toolName") ?? stringField(event.data, "name");
+    const revision = stringField(event.data, "toolRevision");
+    const risk = stringField(event.data, "risk");
+    const id = operationId ?? callId ?? `${event.turnId}:${event.attempt}:${eventName ?? "tool"}`;
+    const current = calls.get(id);
     const name = eventName ?? current?.name ?? "tool";
     const summary = stringField(event.data, "summary");
-    const status = event.type === "tool.call.completed" ? "completed" : event.type === "tool.call.failed" ? "failed" : event.type === "tool.call.approval_required" ? "approval_required" : event.type === "tool.call.started" ? "running" : "proposed";
-    calls.set(callId, {
-      id: callId,
+    const status = lifecycle === "completed" ? "completed" : lifecycle === "failed" ? "failed" : lifecycle === "approval_required" || lifecycle === "proposed" && stringField(event.data, "approval") === "required" ? "approval_required" : lifecycle === "started" ? "running" : "proposed";
+    const input = unknownField(event.data, "arguments") ?? unknownField(event.data, "input");
+    const output = unknownField(event.data, "output");
+    const failure = unknownField(event.data, "error");
+    calls.set(id, {
+      id,
       turnId: event.turnId,
+      ...operationId === void 0 ? current?.operationId === void 0 ? {} : { operationId: current.operationId } : { operationId },
+      ...callId === void 0 ? current?.callId === void 0 ? {} : { callId: current.callId } : { callId },
+      ...revision === void 0 ? current?.revision === void 0 ? {} : { revision: current.revision } : { revision },
+      ...risk === void 0 ? current?.risk === void 0 ? {} : { risk: current.risk } : { risk },
       name,
       label: stringField(event.data, "label") ?? current?.label ?? name,
       ...summary === void 0 ? current?.summary === void 0 ? {} : { summary: current.summary } : { summary },
       status,
-      ...unknownField(event.data, "input") === void 0 ? current?.input === void 0 ? {} : { input: current.input } : { input: unknownField(event.data, "input") },
-      ...unknownField(event.data, "output") === void 0 ? current?.output === void 0 ? {} : { output: current.output } : { output: unknownField(event.data, "output") },
+      ...input === void 0 ? current?.input === void 0 ? {} : { input: current.input } : { input },
+      ...output === void 0 ? current?.output === void 0 ? {} : { output: current.output } : { output },
+      ...failure === void 0 ? current?.error === void 0 ? {} : { error: current.error } : { error: failure },
       createdAt: current?.createdAt ?? event.createdAt,
       eventId: event.id
     });
   }
   return [...calls.values()].sort((left, right) => left.eventId - right.eventId);
 }
+function toolLifecycle(type) {
+  const canonical = /^(?:tool|tool\.call)\.(proposed|started|completed|failed|approval_required)$/u.exec(type)?.[1];
+  return canonical === "proposed" || canonical === "started" || canonical === "completed" || canonical === "failed" || canonical === "approval_required" ? canonical : null;
+}
 var initialSessionState = {
   status: "idle",
+  connection: "idle",
   snapshot: null,
   events: [],
   messages: [],
@@ -338,17 +370,19 @@ var SessionStore = class {
   session;
   state = initialSessionState;
   listeners = /* @__PURE__ */ new Set();
+  eventBuffer = new AgentEventBuffer();
   controller = null;
-  refreshTimer = null;
+  connection = null;
+  reconnectTimer = null;
+  generation = 0;
+  reconnectAttempt = 0;
   subscribe = (listener) => {
     this.listeners.add(listener);
     if (this.listeners.size === 1) void this.refresh();
     return () => {
       this.listeners.delete(listener);
       if (this.listeners.size === 0) {
-        this.controller?.abort();
-        if (this.refreshTimer) clearTimeout(this.refreshTimer);
-        this.refreshTimer = null;
+        this.stop();
       }
     };
   };
@@ -358,61 +392,222 @@ var SessionStore = class {
     this.state = state;
     for (const listener of this.listeners) listener();
   }
-  scheduleRefresh() {
-    if (this.refreshTimer) clearTimeout(this.refreshTimer);
-    const isWorking = this.state.snapshot?.turns.some(
-      (turn) => turn.status === "queued" || turn.status === "running"
-    );
-    this.refreshTimer = isWorking && this.listeners.size > 0 ? setTimeout(() => void this.refresh(), 1e3) : null;
-  }
   async refresh() {
+    const generation = ++this.generation;
     this.controller?.abort();
+    this.connection?.close(1e3, "refreshing");
+    this.connection = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
     this.controller = new AbortController();
     const { signal } = this.controller;
     this.setState({
       ...this.state,
       status: this.state.snapshot ? "ready" : "loading",
+      connection: "connecting",
       error: null
     });
     try {
       const snapshot = await this.session.get({ signal });
-      const events = [];
-      let cursor = 0;
-      let hasMore = true;
-      let pages = 0;
-      while (hasMore && pages < 100) {
-        const page = await this.session.events(cursor, 100, { signal });
-        events.push(...page.events);
-        cursor = page.cursor;
-        hasMore = page.hasMore;
-        pages += 1;
+      if (snapshot.cursor < this.eventBuffer.cursor) this.eventBuffer.reset();
+      await this.replayDurableEvents(signal);
+      if (signal.aborted || generation !== this.generation) return;
+      this.publishBuffer(snapshot, "connecting");
+      await this.openLiveConnection(generation, signal);
+    } catch (error) {
+      if (signal.aborted || generation !== this.generation) return;
+      this.scheduleReconnect(error);
+    }
+  }
+  async replayDurableEvents(signal) {
+    let cursor = this.eventBuffer.cursor;
+    let hasMore = true;
+    let pages = 0;
+    while (hasMore && pages < 100) {
+      const page = await this.session.events(cursor, 100, { signal });
+      const merged = this.eventBuffer.merge(page.events);
+      if (merged.gap) {
+        throw new AgentError(
+          `Durable event gap: expected ${merged.gap.expected}, received ${merged.gap.received}`,
+          0,
+          "event_gap"
+        );
+      }
+      if (page.hasMore && page.cursor <= cursor) {
+        throw new AgentError("Durable replay did not advance", 0, "replay_stalled");
+      }
+      cursor = this.eventBuffer.cursor;
+      hasMore = page.hasMore;
+      pages += 1;
+    }
+    if (hasMore) {
+      throw new AgentError(
+        "Conversation history exceeds the current 10,000-event UI limit",
+        0,
+        "history_limit_exceeded"
+      );
+    }
+  }
+  async openLiveConnection(generation, signal) {
+    const connection = await this.session.connect({
+      after: this.eventBuffer.cursor,
+      signal,
+      onEvent: (event) => this.receiveLiveEvent(event, generation),
+      onReplayComplete: (cursor) => {
+        if (generation !== this.generation || signal.aborted) return;
+        if (cursor > this.eventBuffer.cursor) {
+          const active = this.connection;
+          this.connection = null;
+          active?.close(1012, "repairing event gap");
+          this.scheduleReconnect(
+            new AgentError("Live replay ended ahead of the local cursor", 0, "event_gap"),
+            true
+          );
+          return;
+        }
+        this.reconnectAttempt = 0;
+        this.setState({ ...this.state, connection: "live", error: null });
+      },
+      onError: (error) => {
+        if (generation === this.generation && !signal.aborted) {
+          this.setState({ ...this.state, error });
+        }
+      },
+      onClose: () => {
+        if (generation === this.generation && !signal.aborted && this.connection !== null) {
+          this.connection = null;
+          this.scheduleReconnect(
+            new AgentError("Live connection closed", 0, "websocket_closed")
+          );
+        }
       }
-      if (hasMore) throw new Error("Conversation history exceeds the current 10,000-event UI limit");
+    });
+    if (signal.aborted || generation !== this.generation) {
+      connection.close(1e3, "stale connection");
+      return;
+    }
+    this.connection = connection;
+  }
+  receiveLiveEvent(event, generation) {
+    if (generation !== this.generation) return;
+    if (event.sessionId !== this.session.id) {
+      const active = this.connection;
+      this.connection = null;
+      active?.close(1008, "wrong session event");
       this.setState({
-        status: "ready",
-        snapshot,
-        events,
-        messages: reduceAgentMessages(events),
-        toolCalls: reduceAgentToolCalls(events),
-        error: null
+        ...this.state,
+        status: "error",
+        connection: "closed",
+        error: new AgentError("Runtime returned an event for another session", 0, "invalid_event")
       });
-      this.scheduleRefresh();
-    } catch (error) {
-      if (signal.aborted) return;
+      return;
+    }
+    const merged = this.eventBuffer.merge([event]);
+    const snapshot = merged.accepted.reduce(
+      (current, accepted) => applyEventToSnapshot(current, accepted),
+      this.state.snapshot
+    );
+    this.publishBuffer(snapshot, this.state.connection);
+    if (merged.gap) {
+      const active = this.connection;
+      this.connection = null;
+      active?.close(1012, "repairing event gap");
+      this.scheduleReconnect(
+        new AgentError(
+          `Live event gap: expected ${merged.gap.expected}, received ${merged.gap.received}`,
+          0,
+          "event_gap"
+        ),
+        true
+      );
+    }
+  }
+  publishBuffer(snapshot, connection) {
+    const events = [...this.eventBuffer.events];
+    this.setState({
+      status: snapshot ? "ready" : this.state.status,
+      connection,
+      snapshot,
+      events,
+      messages: reduceAgentMessages(events),
+      toolCalls: reduceAgentToolCalls(events),
+      error: null
+    });
+  }
+  scheduleReconnect(error, immediate = false) {
+    if (this.listeners.size === 0) return;
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    if (isPermanentConnectionError(normalized)) {
       this.setState({
         ...this.state,
         status: "error",
-        error: error instanceof Error ? error : new Error(String(error))
+        connection: "closed",
+        error: normalized
       });
-      this.scheduleRefresh();
+      return;
     }
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    const exponent = Math.min(this.reconnectAttempt, 5);
+    const delay = immediate ? 0 : Math.round(Math.min(1e4, 400 * 2 ** exponent) * (0.75 + Math.random() * 0.5));
+    this.reconnectAttempt += 1;
+    this.setState({
+      ...this.state,
+      status: this.state.snapshot ? "ready" : "error",
+      connection: "reconnecting",
+      error: this.state.snapshot ? null : normalized
+    });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.refresh();
+    }, delay);
   }
-  dispose() {
+  stop() {
+    this.generation += 1;
     this.controller?.abort();
-    if (this.refreshTimer) clearTimeout(this.refreshTimer);
-    this.refreshTimer = null;
+    this.controller = null;
+    this.connection?.close(1e3, "no subscribers");
+    this.connection = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+  dispose() {
+    this.stop();
   }
 };
+function isPermanentConnectionError(error) {
+  return error instanceof AgentError && (error.status === 401 || error.status === 403 || error.status === 404);
+}
+function applyEventToSnapshot(snapshot, event) {
+  if (!snapshot) return null;
+  const status = turnStatusForEvent(event.type);
+  if (!status || !event.turnId) {
+    return event.id > snapshot.cursor ? { ...snapshot, cursor: event.id } : snapshot;
+  }
+  const existing = snapshot.turns.find((turn2) => turn2.id === event.turnId);
+  const turn = {
+    id: event.turnId,
+    status,
+    attempt: event.attempt,
+    createdAt: existing?.createdAt ?? event.createdAt,
+    updatedAt: event.createdAt
+  };
+  return {
+    ...snapshot,
+    updatedAt: event.createdAt,
+    cursor: Math.max(snapshot.cursor, event.id),
+    turns: existing ? snapshot.turns.map(
+      (candidate) => candidate.id === event.turnId ? turn : candidate
+    ) : [...snapshot.turns, turn]
+  };
+}
+function turnStatusForEvent(type) {
+  if (type === "turn.queued") return "queued";
+  if (type === "turn.started") return "running";
+  if (type === "turn.completed") return "completed";
+  if (type === "turn.failed") return "failed";
+  if (type === "turn.cancelled") return "cancelled";
+  return null;
+}
 function useAgentSession(sessionId) {
   const context = useAgentContext();
   const store = useMemo(() => {
@@ -712,7 +907,7 @@ function AgentToolCall({ toolCall, className, style, theme, copy }) {
   const labels = { ...context.copy, ...copy };
   const [expanded, setExpanded] = useState(false);
   const [hovered, setHovered] = useState(false);
-  const hasDetails = toolCall.input !== void 0 || toolCall.output !== void 0;
+  const hasDetails = toolCall.input !== void 0 || toolCall.output !== void 0 || toolCall.error !== void 0;
   const title = toolCall.label === toolCall.name ? humanizeToolName(toolCall.name) : toolCall.label;
   const summary = toolCall.summary ?? deriveToolSummary(toolCall.input);
   const statusLabel = toolCall.status === "completed" ? labels.toolCompleted : toolCall.status === "failed" ? labels.toolFailed : toolCall.status === "approval_required" ? labels.toolApprovalRequired : labels.toolRunning;
@@ -793,6 +988,10 @@ function AgentToolCall({ toolCall, className, style, theme, copy }) {
           toolCall.output !== void 0 ? /* @__PURE__ */ jsxs("div", { children: [
             /* @__PURE__ */ jsx("div", { style: { marginBottom: 2, color: colors.inkTertiary, fontFamily: colors.fontFamily }, children: "Output" }),
             /* @__PURE__ */ jsx("pre", { style: { margin: 0, whiteSpace: "pre-wrap", overflowWrap: "anywhere", font: "inherit" }, children: formatToolPayload(toolCall.output) })
+          ] }) : null,
+          toolCall.error !== void 0 ? /* @__PURE__ */ jsxs("div", { children: [
+            /* @__PURE__ */ jsx("div", { style: { marginBottom: 2, color: colors.statusBad, fontFamily: colors.fontFamily }, children: "Error" }),
+            /* @__PURE__ */ jsx("pre", { style: { margin: 0, whiteSpace: "pre-wrap", overflowWrap: "anywhere", font: "inherit" }, children: formatToolPayload(toolCall.error) })
           ] }) : null
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codespring-app/use-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Server and React SDKs for the CodeSpring Agents runtime",
   "license": "UNLICENSED",
   "repository": {
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "docs/screenshots",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -33,6 +34,7 @@
     "build": "tsup src/index.ts src/react.tsx --format esm --dts --clean --out-dir dist",
     "showcase": "vite examples/showcase --host 127.0.0.1",
     "showcase:build": "vite build examples/showcase --outDir ../../dist-showcase --emptyOutDir",
+    "example:live": "bun run examples/live-session-replay.ts",
     "test": "bun test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check": "bun run typecheck && bun run test && bun run build"