zidane-ui 9.1.1 → 9.1.4

package/src/adapters/sse-host.ts

@@ -1,264 +0,0 @@
-/**
- * A `ChatHost` over HTTP + server-sent events, talking to `createSseHandler`
- * (protocol: `sse-protocol.ts`). Actions are POSTs; each open transcript is
- * one streaming GET, read with `fetch` (so `headers` reach it, unlike
- * `EventSource`), resumed with `Last-Event-ID` after a drop. A transcript
- * hydrates from `GET /sessions/:id/events` the first time it is watched, and
- * its stream closes when nothing watches it any more.
- */
-import type { ChatEvent, ChatHost, ChatModelProvider, ChatSession } from '../chat/headless/host';
-import { writable } from '../chat/headless/store';
-import { createLiveState } from './live';
-import { createSseParser } from './sse-parser';
-import { SSE_PROTOCOL_HEADER, SSE_PROTOCOL_VERSION, type HydrateResponse, type StreamRecord } from './sse-protocol';
-
-/** Options for {@link createSseHost}. */
-export interface SseHostOptions {
-  /** Where `createSseHandler` is mounted, e.g. `/api/chat` or `https://agent.example.com/chat`. */
-  baseUrl: string;
-  /** The `fetch` function to use. Default: the global `fetch`. */
-  fetch?: typeof fetch;
-  /** Sent with every request (auth). A function is called per request, so a token can refresh. */
-  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
-  /** First reconnect delay in ms (default 500, doubling to 10 s; a server `retry:` replaces it). */
-  reconnectMs?: number;
-  /** Called with request and stream failures (default: `console.warn`). */
-  onError?: (error: unknown) => void;
-}
-
-/** The {@link ChatHost} {@link createSseHost} returns, plus the stream controls. */
-export interface SseHost extends ChatHost {
-  /** Re-read the session list. */
-  refresh(): Promise<void>;
-  /** Close every stream. */
-  close(): void;
-}
-
-/**
- * Creates a {@link ChatHost} over HTTP and server-sent events, talking to a handler from {@link createSseHandler}. Actions are POSTs and each watched transcript is one streaming GET that resumes after a drop.
- *
- * @param options - The handler's `baseUrl` plus optional `fetch`, `headers`, reconnect delay, and error callback.
- */
-export function createSseHost(options: SseHostOptions): SseHost {
-  const base = options.baseUrl.replace(/\/+$/, '');
-  const doFetch = options.fetch ?? ((input: RequestInfo | URL, init?: RequestInit) => fetch(input, init));
-  const onError = options.onError ?? ((error: unknown) => console.warn('createSseHost:', error));
-  const streams = new Map<string, AbortController>();
-
-  const headers = async (extra?: Record<string, string>): Promise<Headers> => {
-    const h = new Headers(typeof options.headers === 'function' ? await options.headers() : options.headers);
-    h.set(SSE_PROTOCOL_HEADER, String(SSE_PROTOCOL_VERSION));
-    for (const [k, v] of Object.entries(extra ?? {})) h.set(k, v);
-    return h;
-  };
-
-  const request = async <T>(method: string, path: string, body?: unknown): Promise<T> => {
-    const response = await doFetch(`${base}${path}`, {
-      method,
-      headers: await headers(body === undefined ? undefined : { 'Content-Type': 'application/json' }),
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-    });
-    if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${await response.text().catch(() => '')}`);
-    if (response.status === 204) return undefined as T;
-    const text = await response.text();
-    return (text ? JSON.parse(text) : undefined) as T;
-  };
-
-  const sid = (id: string) => encodeURIComponent(id);
-
-  // A stream outlives its last watcher by a moment, so a remount does not reconnect.
-  const lingering = new Map<string, ReturnType<typeof setTimeout>>();
-  const state = createLiveState({
-    onOpen: (sessionId) => {
-      clearTimeout(lingering.get(sessionId));
-      lingering.delete(sessionId);
-      void open(sessionId);
-    },
-    onClose: (sessionId) => {
-      lingering.set(
-        sessionId,
-        setTimeout(() => {
-          lingering.delete(sessionId);
-          streams.get(sessionId)?.abort();
-          streams.delete(sessionId);
-        }, 1000),
-      );
-    },
-  });
-
-  const hydrate = async (sessionId: string): Promise<string> => {
-    const h = await request<HydrateResponse>('GET', `/sessions/${sid(sessionId)}/events`);
-    state.hydrate(sessionId, h.events, { running: h.running });
-    for (const i of state.pending(sessionId).get()) state.resolveInteraction(i.requestId);
-    for (const i of h.interactions) state.addInteraction(sessionId, i.request);
-    return h.cursor;
-  };
-
-  const onRecord = (sessionId: string, record: StreamRecord): boolean => {
-    switch (record.type) {
-      case 'event':
-        state.apply(sessionId, record.data.event, record.data.echo);
-        return true;
-      case 'run':
-        state.setRunning(
-          sessionId,
-          record.data.running,
-          record.data.running ? undefined : record.data.ok === false ? 'error' : 'completed',
-        );
-        return true;
-      case 'interaction':
-        state.addInteraction(sessionId, record.data.request);
-        return true;
-      case 'interaction-resolved':
-        state.resolveInteraction(record.data.requestId);
-        return true;
-      case 'session':
-        upsert(record.data.session);
-        return true;
-      case 'reset':
-        return false;
-    }
-  };
-
-  // One stream per watched session: hydrate, then stream from the cursor; reconnect from the last id.
-  const open = async (sessionId: string) => {
-    if (streams.has(sessionId)) return;
-    const controller = new AbortController();
-    streams.set(sessionId, controller);
-    let cursor: string | null = null;
-    let delay = options.reconnectMs ?? 500;
-    while (!controller.signal.aborted) {
-      try {
-        if (cursor === null) cursor = await hydrate(sessionId);
-        if (controller.signal.aborted) return;
-        const response = await doFetch(`${base}/sessions/${sid(sessionId)}/stream`, {
-          headers: await headers({ Accept: 'text/event-stream', 'Last-Event-ID': cursor }),
-          signal: controller.signal,
-        });
-        if (!response.ok || !response.body) throw new Error(`stream ${sessionId}: ${response.status}`);
-        delay = options.reconnectMs ?? 500;
-        let reset = false;
-        const parser = createSseParser((r) => {
-          if (reset) return;
-          let data: unknown;
-          try {
-            data = JSON.parse(r.data);
-          } catch {
-            return;
-          }
-          if (!onRecord(sessionId, { type: r.event, data } as StreamRecord)) reset = true;
-        }, cursor);
-        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
-        const stop = () => void reader.cancel().catch(() => undefined);
-        controller.signal.addEventListener('abort', stop, { once: true });
-        while (!reset && !controller.signal.aborted) {
-          const { value, done } = await reader.read();
-          if (done) break;
-          parser.push(value);
-        }
-        controller.signal.removeEventListener('abort', stop);
-        if (controller.signal.aborted) return;
-        if (reset) {
-          stop();
-          cursor = null;
-          continue;
-        }
-        cursor = parser.lastId() || cursor;
-        if (parser.retry() !== undefined) delay = parser.retry()!;
-      } catch (error) {
-        if (controller.signal.aborted) return;
-        onError(error);
-      }
-      if (controller.signal.aborted) return;
-      await new Promise((resolve) => setTimeout(resolve, delay));
-      delay = Math.min(delay * 2, 10_000);
-    }
-  };
-
-  const sessions = state.sessions;
-  const upsert = (session: ChatSession) =>
-    sessions.set((all) =>
-      all.some((s) => s.id === session.id) ? all.map((s) => (s.id === session.id ? session : s)) : [session, ...all],
-    );
-  const refresh = async () => {
-    sessions.set(await request<ChatSession[]>('GET', '/sessions'));
-  };
-  const models = writable<readonly ChatModelProvider[]>([]);
-  void refresh().catch(onError);
-  void request<ChatModelProvider[]>('GET', '/models')
-    .then((m) => models.set(m))
-    .catch(onError);
-
-  return {
-    sessions: {
-      list: sessions,
-      async create(input) {
-        const session = await request<ChatSession>('POST', '/sessions', {
-          ...(input?.title ? { title: input.title } : {}),
-        });
-        upsert(session);
-        return session;
-      },
-      async rename(sessionId, title) {
-        upsert(await request<ChatSession>('PATCH', `/sessions/${sid(sessionId)}`, { title }));
-      },
-      async setArchived(sessionId, archived) {
-        upsert(await request<ChatSession>('PATCH', `/sessions/${sid(sessionId)}`, { archived }));
-      },
-      async remove(sessionId) {
-        await request('DELETE', `/sessions/${sid(sessionId)}`);
-        clearTimeout(lingering.get(sessionId));
-        lingering.delete(sessionId);
-        streams.get(sessionId)?.abort();
-        streams.delete(sessionId);
-        sessions.set((all) => all.filter((s) => s.id !== sessionId));
-      },
-    },
-    transcript: (sessionId) => state.readable(sessionId),
-    async send({ sessionId, prompt, attachments, model, thinking }) {
-      state.echoPrompt(sessionId, prompt, attachments);
-      try {
-        await request('POST', `/sessions/${sid(sessionId)}/send`, {
-          prompt,
-          ...(attachments?.length ? { attachments } : {}),
-          ...(model ? { model } : {}),
-          ...(thinking ? { thinking } : {}),
-        });
-      } catch (error) {
-        state.apply(sessionId, {
-          kind: 'error',
-          text: error instanceof Error ? error.message : String(error),
-        } as ChatEvent);
-        throw error;
-      }
-    },
-    interrupt(sessionId) {
-      void request('POST', `/sessions/${sid(sessionId)}/interrupt`).catch(onError);
-    },
-    async steer(sessionId, message) {
-      return (await request<{ ok: boolean }>('POST', `/sessions/${sid(sessionId)}/steer`, { message })).ok;
-    },
-    async followUp(sessionId, message) {
-      return (await request<{ ok: boolean }>('POST', `/sessions/${sid(sessionId)}/follow-up`, { message })).ok;
-    },
-    interactions: {
-      pending: state.pending,
-      async answer(requestId, response) {
-        await request('POST', `/interactions/${encodeURIComponent(requestId)}/answer`, { response });
-        state.resolveInteraction(requestId);
-      },
-      async cancel(requestId, reason) {
-        await request('POST', `/interactions/${encodeURIComponent(requestId)}/cancel`, reason ? { reason } : {});
-        state.resolveInteraction(requestId);
-      },
-    },
-    models,
-    refresh,
-    close() {
-      for (const t of lingering.values()) clearTimeout(t);
-      lingering.clear();
-      for (const c of streams.values()) c.abort();
-      streams.clear();
-    },
-  };
-}

package/src/adapters/sse-parser.ts

@@ -1,82 +0,0 @@
-/**
- * An incremental `text/event-stream` parser (the WHATWG "event stream
- * interpretation"): feed it decoded text in any chunking, it calls `onRecord`
- * for each dispatched record. Used instead of `EventSource` so requests can
- * carry headers (auth) and the client controls reconnects.
- */
-export interface SseRecord {
-  /** The record's `id`, or the last one seen (the spec's "last event ID"). */
-  id: string;
-  /** `event` field; `'message'` when absent. */
-  event: string;
-  /** The record's `data` lines joined with newlines. */
-  data: string;
-}
-
-/** An incremental parser created by {@link createSseParser}. */
-export interface SseParser {
-  /** Feeds the next chunk of decoded text, split at any point. Calls `onRecord` for each record the chunk completes. */
-  push(chunk: string): void;
-  /** The `retry:` the server last asked for, in ms. */
-  retry(): number | undefined;
-  /** The last event ID seen so far. */
-  lastId(): string;
-}
-
-/**
- * Creates an incremental `text/event-stream` parser that follows the WHATWG interpretation. Used instead of `EventSource` so requests can carry headers.
- *
- * @param onRecord - Called with each dispatched record.
- * @param lastId - The last event ID to start from, for a resumed stream. Defaults to an empty string.
- */
-export function createSseParser(onRecord: (record: SseRecord) => void, lastId = ''): SseParser {
-  let buffer = '';
-  let id = lastId;
-  let event = '';
-  let data: string[] = [];
-  let retry: number | undefined;
-  let first = true;
-
-  const line = (text: string) => {
-    if (text === '') {
-      if (data.length) onRecord({ id, event: event || 'message', data: data.join('\n') });
-      event = '';
-      data = [];
-      return;
-    }
-    if (text.startsWith(':')) return;
-    const colon = text.indexOf(':');
-    const field = colon < 0 ? text : text.slice(0, colon);
-    let value = colon < 0 ? '' : text.slice(colon + 1);
-    if (value.startsWith(' ')) value = value.slice(1);
-    if (field === 'data') data.push(value);
-    else if (field === 'event') event = value;
-    else if (field === 'id') {
-      if (!value.includes('\0')) id = value;
-    } else if (field === 'retry' && /^\d+$/.test(value)) retry = Number(value);
-  };
-
-  return {
-    push(chunk) {
-      buffer += chunk;
-      if (first && buffer.length) {
-        if (buffer.charCodeAt(0) === 0xfeff) buffer = buffer.slice(1);
-        first = false;
-      }
-      // Lines end in \r\n, \n or \r; a trailing \r may be half of a \r\n.
-      let start = 0;
-      for (let i = 0; i < buffer.length; i++) {
-        const c = buffer[i];
-        if (c === '\n' || c === '\r') {
-          if (c === '\r' && i === buffer.length - 1) break;
-          line(buffer.slice(start, i));
-          if (c === '\r' && buffer[i + 1] === '\n') i++;
-          start = i + 1;
-        }
-      }
-      buffer = buffer.slice(start);
-    },
-    retry: () => retry,
-    lastId: () => id,
-  };
-}

package/src/adapters/sse-protocol.ts

@@ -1,118 +0,0 @@
-/**
- * The HTTP + server-sent-events protocol between `createSseHost` (browser)
- * and `createSseHandler` (`ui/src/server/sse-handler.ts`). Version 1; every
- * response carries `X-Zidane-Chat-Protocol: 1`. Paths are relative to the
- * handler's base URL; bodies are JSON.
- *
- *   GET    /sessions                        → ChatSession[]
- *   POST   /sessions          { title? }    → ChatSession
- *   PATCH  /sessions/:id      { title?, archived? } → ChatSession
- *   DELETE /sessions/:id                    → 204
- *   GET    /sessions/:id/events             → HydrateResponse (the transcript so far)
- *   GET    /sessions/:id/stream             → text/event-stream (live; `Last-Event-ID` resumes)
- *   POST   /sessions/:id/send     SendBody  → 202 { ok: true }
- *   POST   /sessions/:id/interrupt          → 204
- *   POST   /sessions/:id/steer    { message } → { ok: boolean }
- *   POST   /sessions/:id/follow-up { message } → { ok: boolean }
- *   POST   /interactions/:requestId/answer { response } → { ok: boolean }
- *   POST   /interactions/:requestId/cancel { reason? }  → { ok: boolean }
- *   GET    /models                          → ChatModelProvider[]
- *
- * Stream records: `id: <epoch>:<seq>`, `event: <type>`, `data: <json>`.
- * `seq` counts a session's records from 1 within one server process
- * (`epoch`). A client reconnecting with `Last-Event-ID` gets every record
- * after it, or `reset` when the server no longer has them (restart, or the
- * replay buffer moved on): it then hydrates again.
- */
-import type { InteractionRequest, InteractionResponse } from 'zidane/chat';
-
-import type { ChatEvent, ChatInteraction, ChatSession, SendInput } from '../chat/headless/host';
-
-/** Version of the HTTP and server-sent-events protocol between {@link createSseHost} and {@link createSseHandler}. */
-export const SSE_PROTOCOL_VERSION = 1;
-/** Name of the response header that carries the protocol version. */
-export const SSE_PROTOCOL_HEADER = 'X-Zidane-Chat-Protocol';
-
-/** Body of `GET /sessions/:id/events`: the transcript so far, plus what a client needs to start streaming. */
-export interface HydrateResponse {
-  /** The session's events so far, oldest first. */
-  events: ChatEvent[];
-  /** A run is in flight in the session. */
-  running: boolean;
-  /** Pass as `Last-Event-ID` to stream what comes after these events. */
-  cursor: string;
-  /** Requests from the agent that still wait for an answer. */
-  interactions: ChatInteraction[];
-}
-
-/** Body of `POST /sessions/:id/send`. */
-export interface SendBody {
-  /** The prompt text. */
-  prompt: string;
-  /** Previews with a `data:` URL are uploaded; others are dropped. */
-  attachments?: SendInput['attachments'];
-  /** The model to run, as `provider/model` or a bare id. Absent: the server's default. */
-  model?: string;
-  /** Reasoning effort for this run. */
-  thinking?: SendInput['thinking'];
-}
-
-/** One record of a session's event stream: a transcript `event`, a `run` state change, an `interaction` raised or resolved, a `session` update, or a `reset` that tells the client to hydrate again. */
-export type StreamRecord =
-  | { type: 'event'; data: { event: ChatEvent; echo?: boolean } }
-  | { type: 'run'; data: { running: boolean; ok?: boolean; error?: string } }
-  | { type: 'interaction'; data: { request: InteractionRequest } }
-  | { type: 'interaction-resolved'; data: { requestId: string } }
-  | { type: 'session'; data: { session: ChatSession } }
-  | { type: 'reset'; data: Record<string, never> };
-
-/** Body of `POST /interactions/:requestId/answer`. */
-export type AnswerBody = { response: InteractionResponse };
-
-/**
- * Builds a stream cursor, the `Last-Event-ID` value that names a record.
- *
- * @param epoch - Id of the server process that numbered the records.
- * @param seq - The record's sequence number within the session, from 1.
- */
-export function formatCursor(epoch: string, seq: number): string {
-  return `${epoch}:${seq}`;
-}
-
-/**
- * Parses a cursor from {@link formatCursor}. Returns `null` for a missing or malformed cursor.
- *
- * @param cursor - The cursor string, for example a `Last-Event-ID` header value.
- */
-export function parseCursor(cursor: string | null | undefined): { epoch: string; seq: number } | null {
-  if (!cursor) return null;
-  const at = cursor.lastIndexOf(':');
-  if (at <= 0) return null;
-  const seq = Number(cursor.slice(at + 1));
-  return Number.isInteger(seq) && seq >= 0 ? { epoch: cursor.slice(0, at), seq } : null;
-}
-
-/**
- * One SSE record on the wire (`data` is single-line JSON, so one `data:` field).
- *
- * @param id - The record id sent as the SSE `id` field. `null` omits it.
- * @param record - The record to encode.
- */
-export function encodeSseRecord(id: string | null, record: StreamRecord): string {
-  return `${id ? `id: ${id}\n` : ''}event: ${record.type}\ndata: ${JSON.stringify(record.data)}\n\n`;
-}
-
-/**
- * `ChatAttachment` previews → zidane's prompt attachments (base64, no data-URL prefix).
- *
- * @param attachments - The previews from a {@link SendBody}. Previews without a base64 `data:` URL are dropped.
- */
-export function attachmentsFromPreviews(
-  attachments: SendBody['attachments'],
-): { mediaType: string; data: string; name?: string }[] {
-  return (attachments ?? []).flatMap((a) => {
-    const match = a.dataUrl?.match(/^data:([^;,]+)?(;base64)?,(.*)$/s);
-    if (!match || !match[2]) return [];
-    return [{ mediaType: match[1] || a.mediaType, data: match[3]!, name: a.name }];
-  });
-}

package/src/adapters/stream-pacer.ts

@@ -1,122 +0,0 @@
-/**
- * Paces a run's live events into a transcript a frame at a time: what
- * arrives between two frames lands in one update (one render, however many
- * tokens came in), and with `smooth` the streamed reply text reveals at a
- * steady rate however unevenly it arrives (the `smoothStreaming` setting,
- * as the desktop app's `StreamProvider` paces it; the math is
- * `chat/headless/smooth-stream.ts`). Order holds: any other event first
- * reveals the reply text its owner streamed before it.
- *
- *   const pacer = createStreamPacer(run.emit, { smooth: true });
- *   onEvent: (event) => pacer.push(event),
- *   onEnd: () => pacer.flush(),
- */
-import type { ChatEvent } from '../chat/headless/host';
-import { type DeltaBucket, drainBucket, SMOOTH_TICK_MS, tickBucket } from '../chat/headless/smooth-stream';
-
-/** What {@link createStreamPacer} returns. */
-export interface StreamPacer {
-  /** Queues a live event for the next frame. */
-  push(event: ChatEvent): void;
-  /** Applies everything queued or waiting to reveal, now: the run ended. */
-  flush(): void;
-}
-
-/** Options of {@link createStreamPacer}. */
-export interface StreamPacerOptions {
-  /** Reveals streamed reply text at a steady rate. Default: false, each frame applies what arrived. */
-  smooth?: boolean;
-}
-
-/** A frame when frames run, this timer when they don't: a hidden tab throttles frames, and the text must still land. */
-const FALLBACK_MS = 50;
-
-/** An owner's reply text waiting to reveal, with the event whose tags (owner, depth, turn) its slices carry. */
-interface OwnerBucket extends DeltaBucket {
-  tags: ChatEvent;
-}
-
-/**
- * Creates a pacer that feeds `apply` (a run's `emit`, a live state's `apply`).
- *
- * @param apply - Folds one event into the transcript.
- * @param options - {@link StreamPacerOptions}.
- */
-export function createStreamPacer(
-  apply: (event: ChatEvent) => void,
-  { smooth = false }: StreamPacerOptions = {},
-): StreamPacer {
-  let queue: ChatEvent[] = [];
-  const buckets = new Map<string, OwnerBucket>();
-  let frame = 0;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let last = 0;
-
-  const reveal = (bucket: OwnerBucket, n: number) => {
-    const text = drainBucket(bucket, n);
-    if (text) apply({ ...bucket.tags, text });
-  };
-  const revealAll = (bucket: OwnerBucket | undefined) => {
-    if (!bucket?.pending) return;
-    bucket.carry = 0;
-    reveal(bucket, bucket.pending.length);
-  };
-
-  const take = () => {
-    const events = queue;
-    queue = [];
-    for (const event of events) {
-      const owner = event.childId ?? '';
-      if (smooth && event.kind === 'markdown' && event.streaming) {
-        const bucket = buckets.get(owner);
-        // The tags are the first waiting delta's, so text still waiting never takes a later turn's.
-        if (bucket?.pending) bucket.pending += event.text;
-        else buckets.set(owner, { pending: event.text, carry: 0, tags: event });
-        continue;
-      }
-      revealAll(buckets.get(owner));
-      apply(event);
-    }
-  };
-
-  const cancel = () => {
-    if (frame && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(frame);
-    clearTimeout(timer);
-    frame = 0;
-    timer = undefined;
-  };
-
-  const tick = () => {
-    cancel();
-    const now = performance.now();
-    const dt = Math.min(now - last, SMOOTH_TICK_MS * 8);
-    last = now;
-    take();
-    let waiting = false;
-    for (const bucket of buckets.values()) {
-      const n = tickBucket(bucket, dt);
-      if (n > 0) reveal(bucket, n);
-      if (bucket.pending) waiting = true;
-    }
-    if (waiting) schedule();
-  };
-
-  function schedule() {
-    if (frame || timer !== undefined) return;
-    if (typeof requestAnimationFrame === 'function') frame = requestAnimationFrame(tick);
-    timer = setTimeout(tick, FALLBACK_MS);
-  }
-
-  return {
-    push(event) {
-      if (!frame && timer === undefined && ![...buckets.values()].some((b) => b.pending)) last = performance.now();
-      queue.push(event);
-      schedule();
-    },
-    flush() {
-      cancel();
-      take();
-      for (const bucket of buckets.values()) revealAll(bucket);
-    },
-  };
-}