@steerable/agent-ui 0.2.3 → 0.2.5

package/src/state/MockChatStreamTransport.ts

@@ -0,0 +1,123 @@
+/**
+ * `MockChatStreamTransport` — canned-script transport for stories, tests, and
+ * the framework's runnable web-shell example.
+ *
+ * Replays a deterministic list of `SSEEvent` per call to `stream()`. Optional
+ * per-event delays make streaming feel real in demos. Loop the same script
+ * forever, or vary by index — the constructor accepts either an array (one
+ * script per turn) or a function `(turn: number) => SSEEvent[]`.
+ *
+ *   const transport = new MockChatStreamTransport({
+ *     scripts: [
+ *       [{ type: 'content', content: 'Hello, ' }, { type: 'content', content: 'world!' }, { type: 'done' }],
+ *     ],
+ *     defaultDelayMs: 25,
+ *   });
+ *
+ *   const { messages, sendUserMessage } = useChatStream({ transport });
+ */
+
+import type { SSEEvent } from '@steerable/agent-protocol';
+import type {
+  ChatStreamSendInput,
+  ChatStreamTransport,
+} from '../hooks/useChatStream.js';
+
+export type MockScriptStep =
+  | SSEEvent
+  | { event: SSEEvent; delayMs?: number };
+
+export type MockScript = MockScriptStep[];
+
+export interface MockChatStreamTransportOptions {
+  /**
+   * A list of scripts (one per turn), or a callback that returns a script for
+   * the current turn. Required.
+   */
+  scripts: MockScript[] | ((turn: number, input: ChatStreamSendInput) => MockScript);
+  /** Delay between events when the step doesn't specify one. Defaults to 0. */
+  defaultDelayMs?: number;
+  /**
+   * What to do when there are fewer scripts than turns:
+   *   - 'cycle' (default): wrap modulo `scripts.length`.
+   *   - 'last': stay on the last script.
+   *   - 'empty': emit only a `done` event.
+   */
+  exhaustionPolicy?: 'cycle' | 'last' | 'empty';
+}
+
+export class MockChatStreamTransport implements ChatStreamTransport {
+  private turn = 0;
+  /** Set of in-flight cancel signals, exposed for tests. */
+  readonly cancelled = new Set<number>();
+
+  constructor(private readonly options: MockChatStreamTransportOptions) {}
+
+  /** Reset the turn counter — useful between fixture-driven test cases. */
+  reset(): void {
+    this.turn = 0;
+    this.cancelled.clear();
+  }
+
+  async stream(
+    input: ChatStreamSendInput,
+    onEvent: (event: SSEEvent) => void,
+  ): Promise<() => void> {
+    const turn = this.turn++;
+    const script = this.resolveScript(turn, input);
+    let cancelled = false;
+    const cancel = () => {
+      cancelled = true;
+      this.cancelled.add(turn);
+    };
+    void this.run(script, onEvent, () => cancelled);
+    // Return synchronously so the framework hook can capture the cancel handle
+    // without waiting for the full script.
+    return cancel;
+  }
+
+  private resolveScript(turn: number, input: ChatStreamSendInput): MockScript {
+    const { scripts, exhaustionPolicy = 'cycle' } = this.options;
+    if (typeof scripts === 'function') return scripts(turn, input);
+    if (scripts.length === 0) return [{ type: 'done' }];
+    if (turn < scripts.length) return scripts[turn];
+    switch (exhaustionPolicy) {
+      case 'last':
+        return scripts[scripts.length - 1];
+      case 'empty':
+        return [{ type: 'done' }];
+      case 'cycle':
+      default:
+        return scripts[turn % scripts.length];
+    }
+  }
+
+  private async run(
+    script: MockScript,
+    onEvent: (event: SSEEvent) => void,
+    isCancelled: () => boolean,
+  ): Promise<void> {
+    const defaultDelay = this.options.defaultDelayMs ?? 0;
+    for (const step of script) {
+      if (isCancelled()) return;
+      const { event, delayMs } = normaliseStep(step, defaultDelay);
+      if (delayMs > 0) await sleep(delayMs);
+      if (isCancelled()) return;
+      onEvent(event);
+    }
+  }
+}
+
+function normaliseStep(
+  step: MockScriptStep,
+  defaultDelayMs: number,
+): { event: SSEEvent; delayMs: number } {
+  if ('event' in step && step.event && typeof step.event === 'object') {
+    return { event: step.event, delayMs: step.delayMs ?? defaultDelayMs };
+  }
+  return { event: step as SSEEvent, delayMs: defaultDelayMs };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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');
+  });
+});