@steerable/agent-ui 0.2.0 → 0.2.4

package/src/state/bridgeLegacySSE.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for `bridgeLegacySSE`. The bridge is the union of the deeppath cloud
+ * legacy normaliser and the deeppath-agent local-backend normaliser; we cover
+ * the canonical shapes for each profile.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { bridgeLegacySSE } from './bridgeLegacySSE';
+
+describe('bridgeLegacySSE', () => {
+  describe('canonical SSEEvent', () => {
+    it('passes through known typed events untouched', () => {
+      const ev = bridgeLegacySSE({ type: 'content', content: 'hi' });
+      expect(ev).toEqual({ type: 'content', content: 'hi' });
+    });
+
+    it('routes tool_call payloads as-is for useChatStream to unpack', () => {
+      const ev = bridgeLegacySSE({
+        type: 'tool_call',
+        payload: { id: 'c1', name: 'get_weather', arguments: {} },
+      });
+      expect(ev?.type).toBe('tool_call');
+      expect(ev?.payload).toEqual({ id: 'c1', name: 'get_weather', arguments: {} });
+    });
+  });
+
+  describe('deeppath cloud legacy', () => {
+    it('maps bare `{content}` deltas to type:content', () => {
+      expect(bridgeLegacySSE({ content: 'Hello' })).toEqual({
+        type: 'content',
+        content: 'Hello',
+      });
+    });
+
+    it('maps bare `{error}` to type:error', () => {
+      expect(bridgeLegacySSE({ error: 'boom' })).toEqual({
+        type: 'error',
+        message: 'boom',
+      });
+    });
+
+    it('coerces bare strings (rare legacy path)', () => {
+      expect(bridgeLegacySSE('hi')).toEqual({ type: 'content', content: 'hi' });
+    });
+
+    it('drops empty bare strings', () => {
+      expect(bridgeLegacySSE('')).toBeNull();
+    });
+  });
+
+  describe('deeppath-agent local backend', () => {
+    it('completion:completed → done', () => {
+      expect(
+        bridgeLegacySSE({ type: 'completion', status: 'completed' }),
+      ).toEqual({ type: 'done', payload: { type: 'completion', status: 'completed' } });
+    });
+
+    it('completion:failed → done', () => {
+      const ev = bridgeLegacySSE({ type: 'completion', status: 'failed' });
+      expect(ev?.type).toBe('done');
+    });
+
+    it('completion:budget_exhausted → budget_exhausted', () => {
+      const ev = bridgeLegacySSE({
+        type: 'completion',
+        status: 'budget_exhausted',
+        reason: 'token limit',
+      });
+      expect(ev).toEqual({ type: 'budget_exhausted', message: 'token limit' });
+    });
+
+    it('completion:executing → agent/round_end', () => {
+      const ev = bridgeLegacySSE({ type: 'completion', status: 'executing' });
+      expect(ev?.type).toBe('agent');
+      expect(ev?.event).toBe('round_end');
+    });
+
+    it('user_message is suppressed (echo from the backend)', () => {
+      expect(
+        bridgeLegacySSE({ type: 'user_message', message: { content: 'hi' } }),
+      ).toBeNull();
+    });
+
+    it('executed_actions → agent/executed_actions', () => {
+      const ev = bridgeLegacySSE({ type: 'executed_actions', actions: [] });
+      expect(ev?.type).toBe('agent');
+      expect(ev?.event).toBe('executed_actions');
+    });
+
+    it('message_id → agent/message_id', () => {
+      const ev = bridgeLegacySSE({ type: 'message_id', messageId: 'm1' });
+      expect(ev?.type).toBe('agent');
+      expect(ev?.event).toBe('message_id');
+    });
+
+    it('typed error envelope (data.type === "error")', () => {
+      const ev = bridgeLegacySSE({ type: 'error', message: 'kaboom' });
+      expect(ev).toEqual({ type: 'error', message: 'kaboom' });
+    });
+  });
+
+  describe('event: name overrides', () => {
+    it('event=error wins over the inner payload type', () => {
+      const ev = bridgeLegacySSE({ message: 'transport-level error' }, 'error');
+      expect(ev).toEqual({ type: 'error', message: 'transport-level error' });
+    });
+  });
+
+  describe('unknown envelope passthrough', () => {
+    it('repackages unknown `type` as agent/<type> by default', () => {
+      const ev = bridgeLegacySSE({ type: 'stage-complete', stage: 'planning' });
+      expect(ev?.type).toBe('agent');
+      expect(ev?.event).toBe('stage-complete');
+      expect(ev?.payload).toEqual({ type: 'stage-complete', stage: 'planning' });
+    });
+
+    it('respects passthroughUnknownAsAgent=false', () => {
+      const ev = bridgeLegacySSE(
+        { type: 'wholly-unknown' },
+        undefined,
+        { passthroughUnknownAsAgent: false, profile: 'deeppathCloud' },
+      );
+      expect(ev).toBeNull();
+    });
+  });
+
+  describe('null inputs', () => {
+    it('returns null for non-object, non-string inputs', () => {
+      expect(bridgeLegacySSE(null)).toBeNull();
+      expect(bridgeLegacySSE(undefined)).toBeNull();
+      expect(bridgeLegacySSE(42)).toBeNull();
+    });
+  });
+});

package/src/state/bridgeLegacySSE.ts

@@ -0,0 +1,134 @@
+/**
+ * `bridgeLegacySSE` — turn the heterogeneous wire envelopes that deeppath's
+ * Next.js API and deeppath-agent's local backend speak into the canonical
+ * `SSEEvent` consumed by `useChatStream`.
+ *
+ * Lifted from:
+ *   - deeppath/apps/web/src/lib/utils/framework-sse-bridge.ts (normalize())
+ *   - deeppath-agent/apps/web/src/lib/chat-transport.ts (normaliseLocalPayload())
+ *
+ * The two implementations are merged here, with deeppath-agent's richer
+ * `completion` / `executed_actions` / `user_message` / `message_id` handling
+ * promoted as the default and the older deeppath wire shapes added as
+ * `EnvelopeProfile.deeppathCloud`. A consumer picks a profile (or "auto"),
+ * and the bridge does the rest.
+ *
+ * The bridge is intentionally pure — no I/O, no DOM, no electron — so it can
+ * back any transport (fetch SSE, IPC streaming, mocked fixtures, JSON-RPC).
+ */
+
+import type { SSEEvent } from '@steerable/agent-protocol';
+
+export type EnvelopeProfile =
+  | 'auto'
+  /** Next.js `/api/chats/:id/send` legacy wire — `{content}` deltas, `{error}` envelopes. */
+  | 'deeppathCloud'
+  /** Electron local-backend wire — typed completion/executed_actions/user_message. */
+  | 'deeppathLocal';
+
+export interface BridgeLegacySSEOptions {
+  profile?: EnvelopeProfile;
+  /**
+   * If we see a typed event with `type` outside the canonical SSEEvent union
+   * (e.g. `stage-complete`, `executed_actions`), repackage it as an `agent`
+   * event whose `payload` is the raw envelope. Defaults to `true` so the
+   * framework `useChatStream`'s `onUnknownEvent` channel sees them.
+   */
+  passthroughUnknownAsAgent?: boolean;
+}
+
+const KNOWN_EVENT_TYPES = new Set<SSEEvent['type']>([
+  'content',
+  'error',
+  'agent',
+  'orchestration',
+  'loader-hint',
+  'keepalive',
+  'done',
+  'budget_exhausted',
+  'tool_call',
+  'tool_result',
+]);
+
+/**
+ * Convert one parsed envelope (the JSON value of `data:` plus the optional
+ * `event:` name) into zero or one `SSEEvent`. Returns null if the envelope is
+ * deliberately suppressed (e.g. `user_message` echoes, since useChatStream
+ * already appends the user message locally).
+ */
+export function bridgeLegacySSE(
+  parsed: unknown,
+  eventName?: string,
+  options: BridgeLegacySSEOptions = {},
+): SSEEvent | null {
+  const profile = options.profile ?? 'auto';
+  const passthroughUnknown = options.passthroughUnknownAsAgent ?? true;
+
+  if (typeof parsed === 'string') {
+    return parsed.length > 0 ? { type: 'content', content: parsed } : null;
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    return null;
+  }
+  const data = parsed as Record<string, unknown>;
+
+  if (eventName === 'error') {
+    return {
+      type: 'error',
+      message: typeof data.message === 'string' ? data.message : 'unknown error',
+    };
+  }
+
+  // Legacy: `{ content: '...' }` carries an incremental token (deeppath cloud).
+  if (typeof data.content === 'string' && !('type' in data)) {
+    return { type: 'content', content: data.content };
+  }
+
+  // Legacy: `{ error: '...' }` is an inline error envelope (deeppath cloud).
+  if (typeof data.error === 'string' && !('type' in data)) {
+    return { type: 'error', message: data.error };
+  }
+
+  // Canonical typed events.
+  if (typeof data.type === 'string') {
+    if (KNOWN_EVENT_TYPES.has(data.type as SSEEvent['type'])) {
+      return data as unknown as SSEEvent;
+    }
+    if (profile === 'deeppathLocal' || profile === 'auto') {
+      const mapped = mapLocalBackendEnvelope(data);
+      if (mapped !== undefined) return mapped;
+    }
+    if (passthroughUnknown) {
+      return { type: 'agent', event: data.type, payload: data };
+    }
+  }
+  return null;
+}
+
+function mapLocalBackendEnvelope(
+  data: Record<string, unknown>,
+): SSEEvent | null | undefined {
+  switch (data.type as string) {
+    case 'completion': {
+      const status = data.status as string;
+      if (status === 'completed' || status === 'failed') {
+        return { type: 'done', payload: data };
+      }
+      if (status === 'budget_exhausted') {
+        return {
+          type: 'budget_exhausted',
+          message: typeof data.reason === 'string' ? data.reason : undefined,
+        };
+      }
+      return { type: 'agent', event: 'round_end', payload: data };
+    }
+    case 'executed_actions':
+      return { type: 'agent', event: 'executed_actions', payload: data };
+    case 'user_message':
+      return null;
+    case 'message_id':
+      return { type: 'agent', event: 'message_id', payload: data };
+    default:
+      return undefined;
+  }
+}

package/src/state/index.ts

@@ -0,0 +1,82 @@
+/**
+ * `@steerable/agent-ui/state` — chat-state primitives lifted out of deeppath
+ * and deeppath-agent. Composes with the existing `hooks/` exports.
+ *
+ * Subpath import recommended:
+ *
+ *   import { useChatSession, MockChatStreamTransport } from '@steerable/agent-ui/state';
+ *
+ * but the same identifiers are also re-exported from the package root for
+ * back-compat.
+ */
+
+export { SSEParser, parseSSEData } from './parseSSE.js';
+export type { SSEFrame, SSEParserOptions } from './parseSSE.js';
+
+export { bridgeLegacySSE } from './bridgeLegacySSE.js';
+export type { EnvelopeProfile, BridgeLegacySSEOptions } from './bridgeLegacySSE.js';
+
+export { MockChatStreamTransport } from './MockChatStreamTransport.js';
+export type {
+  MockScript,
+  MockScriptStep,
+  MockChatStreamTransportOptions,
+} from './MockChatStreamTransport.js';
+
+export { useChatComposer } from './useChatComposer.js';
+export type {
+  UseChatComposerOptions,
+  UseChatComposerReturn,
+} from './useChatComposer.js';
+
+export { useChatList } from './useChatList.js';
+export type {
+  ChatListTransport,
+  UseChatListOptions,
+  UseChatListReturn,
+} from './useChatList.js';
+
+export { useChatSession } from './useChatSession.js';
+export type {
+  UseChatSessionOptions,
+  UseChatSessionReturn,
+} from './useChatSession.js';
+
+export {
+  ChatSessionProvider,
+  useChatSessionContext,
+  useOptionalChatSession,
+  useChatSessionSlice,
+} from './ChatSessionProvider.js';
+export type {
+  ChatSessionContextValue,
+  ChatSessionProviderProps,
+} from './ChatSessionProvider.js';
+
+export {
+  useToolCallStream,
+  useToolCallStatus,
+} from './useToolCallStream.js';
+export type {
+  ToolCallEntry,
+  UseToolCallStreamOptions,
+  UseToolCallStreamReturn,
+} from './useToolCallStream.js';
+
+export { useScrollLock } from './useScrollLock.js';
+export type {
+  UseScrollLockOptions,
+  UseScrollLockReturn,
+} from './useScrollLock.js';
+
+// Re-export the canonical chat-stream surface so callers can stay on a single
+// import root if they don't want to think about subpaths.
+export {
+  useChatStream,
+} from '../hooks/useChatStream.js';
+export type {
+  UseChatStreamOptions,
+  UseChatStreamReturn,
+  ChatStreamSendInput,
+  ChatStreamTransport,
+} from '../hooks/useChatStream.js';

package/src/state/parseSSE.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Tests for `SSEParser` and `parseSSEData`.
+ *
+ * The parser owns the wire-level framing: split on `\r?\n\r?\n`, accumulate
+ * multi-line `data:` payloads, surface `[DONE]` via `onComplete`. We cover the
+ * shapes deeppath and deeppath-agent legacy parsers handled, so the cutover
+ * doesn't lose any wire variants.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { SSEParser, parseSSEData } from './parseSSE';
+
+describe('SSEParser', () => {
+  it('emits one frame per blank-line-separated block', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('data: {"content":"foo"}\n\ndata: {"content":"bar"}\n\n');
+    expect(onFrame).toHaveBeenCalledTimes(2);
+    expect(onFrame.mock.calls[0][0].data).toBe('{"content":"foo"}');
+    expect(onFrame.mock.calls[1][0].data).toBe('{"content":"bar"}');
+  });
+
+  it('handles split chunks across frame boundaries', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('data: {"content":"hello,');
+    expect(onFrame).not.toHaveBeenCalled();
+    p.feed(' world!"}\n\n');
+    expect(onFrame).toHaveBeenCalledTimes(1);
+    expect(onFrame.mock.calls[0][0].data).toBe('{"content":"hello, world!"}');
+  });
+
+  it('joins multi-line data: per SSE spec (newline-joined)', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('data: line one\ndata: line two\n\n');
+    expect(onFrame.mock.calls[0][0].data).toBe('line one\nline two');
+  });
+
+  it('captures event:, id:, retry:', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('event: error\nid: 42\nretry: 5000\ndata: {"message":"boom"}\n\n');
+    const frame = onFrame.mock.calls[0][0];
+    expect(frame.event).toBe('error');
+    expect(frame.id).toBe('42');
+    expect(frame.retry).toBe(5000);
+    expect(frame.data).toBe('{"message":"boom"}');
+  });
+
+  it('triggers onComplete on the canonical [DONE] terminator', () => {
+    const onFrame = vi.fn();
+    const onComplete = vi.fn();
+    const p = new SSEParser({ onFrame, onComplete });
+    p.feed('data: {"content":"x"}\n\ndata: [DONE]\n\n');
+    expect(onFrame).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+
+  it('triggers onComplete on quoted "[DONE]"', () => {
+    const onComplete = vi.fn();
+    const p = new SSEParser({ onFrame: () => {}, onComplete });
+    p.feed('data: "[DONE]"\n\n');
+    expect(onComplete).toHaveBeenCalledOnce();
+  });
+
+  it('ignores comment lines (leading colon)', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed(': keep-alive comment\ndata: real\n\n');
+    expect(onFrame).toHaveBeenCalledTimes(1);
+    expect(onFrame.mock.calls[0][0].data).toBe('real');
+  });
+
+  it('flushes trailing buffered frame on end()', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('data: orphan'); // no terminator
+    expect(onFrame).not.toHaveBeenCalled();
+    p.end();
+    expect(onFrame).toHaveBeenCalledTimes(1);
+    expect(onFrame.mock.calls[0][0].data).toBe('orphan');
+  });
+
+  it('supports \\r\\n\\r\\n frame separators (Windows / some proxies)', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.feed('data: one\r\n\r\ndata: two\r\n\r\n');
+    expect(onFrame).toHaveBeenCalledTimes(2);
+    expect(onFrame.mock.calls[0][0].data).toBe('one');
+    expect(onFrame.mock.calls[1][0].data).toBe('two');
+  });
+
+  it('stops emitting after cleanup()', () => {
+    const onFrame = vi.fn();
+    const p = new SSEParser({ onFrame });
+    p.cleanup();
+    p.feed('data: ignored\n\n');
+    expect(onFrame).not.toHaveBeenCalled();
+  });
+
+  it('reports parsing exceptions via onError', () => {
+    const onError = vi.fn();
+    const p = new SSEParser({
+      onFrame: () => {
+        throw new Error('downstream blew up');
+      },
+      onError,
+    });
+    p.feed('data: x\n\n');
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0][0].message).toBe('downstream blew up');
+  });
+});
+
+describe('parseSSEData', () => {
+  it('parses JSON payloads', () => {
+    expect(parseSSEData('{"a":1}')).toEqual({ a: 1 });
+  });
+  it('returns the original string when not JSON (bare text deltas)', () => {
+    expect(parseSSEData('hello')).toBe('hello');
+  });
+});

package/src/state/parseSSE.ts

@@ -0,0 +1,123 @@
+/**
+ * `parseSSE` — wire-level Server-Sent-Events parser.
+ *
+ * Feed it raw text chunks from any source (fetch ReadableStream chunks,
+ * Electron IPC `webContents.send` payloads, mocked fixtures, …). It buffers,
+ * splits on the `\r?\n\r?\n` frame terminator, and emits one
+ * `{ event?, data?, id?, retry? }` per complete frame. JSON parsing of `data`
+ * is intentionally out of scope; downstream layers like {@link bridgeLegacySSE}
+ * handle that.
+ *
+ * Replaces deeppath's `SSEParser` and deeppath-agent's `LocalBackendSseParser`
+ * with a single dependency-free implementation that compiles to both Node and
+ * the browser. Heartbeat-timeout watchdogs (deeppath had a 30 s gate) live on
+ * the transport, not here — this class is a pure parser.
+ */
+
+export interface SSEFrame {
+  /** The `event: …` field; undefined for default `message` events. */
+  event?: string;
+  /** Concatenated `data: …` lines (newline-joined per the SSE spec). */
+  data?: string;
+  /** The `id: …` field. */
+  id?: string;
+  /** The `retry: …` field, as milliseconds. */
+  retry?: number;
+}
+
+export interface SSEParserOptions {
+  onFrame: (frame: SSEFrame) => void;
+  onError?: (err: Error) => void;
+  /** Called when the stream emits the canonical `data: [DONE]` terminator. */
+  onComplete?: () => void;
+}
+
+export class SSEParser {
+  private buffer = '';
+  private completed = false;
+
+  constructor(private readonly options: SSEParserOptions) {}
+
+  /** Feed one chunk. Safe to call with partial UTF-8 strings (we don't decode). */
+  feed(chunk: string): void {
+    if (this.completed) return;
+    this.buffer += chunk;
+    const parts = this.buffer.split(/\r?\n\r?\n/);
+    this.buffer = parts.pop() ?? '';
+    for (const frame of parts) {
+      if (frame.length > 0) this.processFrame(frame);
+    }
+  }
+
+  /** Call when the source signals end-of-stream. Flushes any trailing frame. */
+  end(): void {
+    if (this.completed) return;
+    if (this.buffer.trim().length > 0) this.processFrame(this.buffer);
+    this.buffer = '';
+  }
+
+  /** Drop all state and stop emitting. */
+  cleanup(): void {
+    this.buffer = '';
+    this.completed = true;
+  }
+
+  private processFrame(raw: string): void {
+    const frame: SSEFrame = {};
+    const dataLines: string[] = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (line.length === 0) continue;
+      // Comments per the SSE spec — leading `:` lines.
+      if (line.startsWith(':')) continue;
+      const colon = line.indexOf(':');
+      const field = colon === -1 ? line : line.substring(0, colon);
+      let value = colon === -1 ? '' : line.substring(colon + 1);
+      if (value.startsWith(' ')) value = value.substring(1);
+      switch (field) {
+        case 'event':
+          frame.event = value;
+          break;
+        case 'data':
+          dataLines.push(value);
+          break;
+        case 'id':
+          frame.id = value;
+          break;
+        case 'retry': {
+          const ms = Number.parseInt(value, 10);
+          if (Number.isFinite(ms)) frame.retry = ms;
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    if (dataLines.length === 0 && frame.event === undefined && frame.id === undefined) {
+      return;
+    }
+    if (dataLines.length > 0) frame.data = dataLines.join('\n');
+
+    if (frame.data === '[DONE]' || frame.data === '"[DONE]"') {
+      this.completed = true;
+      this.options.onComplete?.();
+      return;
+    }
+    try {
+      this.options.onFrame(frame);
+    } catch (err) {
+      this.options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+}
+
+/**
+ * Tolerant JSON parser for SSE `data:` payloads — returns the raw string when
+ * the body isn't JSON, which deeppath relies on for bare-text content deltas.
+ */
+export function parseSSEData(data: string): unknown {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}