Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

17.5 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { LiveText } from './bits.tsx';
import { inFlight } from './lanes.ts';
import { LatencyTracker } from './latency.ts';
import { type ClientLoaders, type DemoClient, type DriveChange, type EventView, isSessionNotFound, type Mode, type RawClientLoaders, type SessionRow, type SessionView } from './view.ts';

export type ClientEntry =
  | { status: 'loading' }
  | { status: 'ready'; client: DemoClient }
  | { status: 'error'; error: string };

/**
 * One client per mode (and per durability: `server:off` is the raw Function
 * client), created on first use and never disposed, so a session driving in
 * this tab keeps going while another mode is on screen.
 */
export function useClients(
  loaders: ClientLoaders,
  rawLoaders: RawClientLoaders = {},
  nativeLoaders: RawClientLoaders = {},
  /** Clients under their own key (`server:pi-durable`), outside the mode/durability grid. */
  extraLoaders: Partial<Record<string, () => Promise<{ createClient(): Promise<DemoClient> }>>> = {}
) {
  const [entries, setEntries] = useState<Partial<Record<string, ClientEntry>>>({});
  const started = useRef(new Set<string>());
  const loaderFor = useCallback(
    (key: string) => {
      if (extraLoaders[key]) return extraLoaders[key];
      const [mode, durability] = key.split(':') as [Mode, string | undefined];
      return durability === 'off' ? rawLoaders[mode] : durability === 'native' ? nativeLoaders[mode] : loaders[mode];
    },
    [loaders, rawLoaders, nativeLoaders, extraLoaders]
  );
  const load = useCallback(
    (key: string) => {
      if (started.current.has(key)) return;
      const loader = loaderFor(key);
      if (!loader) return;
      started.current.add(key);
      setEntries((e) => ({ ...e, [key]: { status: 'loading' } }));
      const durability = key.split(':')[1];
      loader()
        .then((m) => m.createClient(durability === 'run-ahead' ? { durability: 'run-ahead' } : undefined))
        .then(
          (client) => setEntries((e) => ({ ...e, [key]: { status: 'ready', client } })),
          (error) => {
            console.error(`[demo] ${key} client failed`, error);
            started.current.delete(key);
            setEntries((e) => ({ ...e, [key]: { status: 'error', error: messageOf(error) } }));
          }
        );
    },
    [loaderFor]
  );
  const prefetch = useCallback((key: string) => void loaderFor(key)?.().catch(() => {}), [loaderFor]);
  return { entries, load, prefetch };
}

/** The busy poll when the client pushes updates (hints, or live marks for every commit). */
export const PUSHED_POLL_MS = 5000;

/**
 * How long the open session waits before its next read: backing off after
 * failures; otherwise the page's poll, which is only a fallback (at least
 * `PUSHED_POLL_MS`) when the client pushes updates.
 */
export function refreshDelay({ fails, pushed, pollMs }: { fails: number; pushed: boolean; pollMs: number }): number {
  if (fails >= 2) return Math.min(5000, 1000 * 2 ** (fails - 2));
  return pushed ? Math.max(PUSHED_POLL_MS, pollMs) : pollMs;
}

const trackers = new WeakMap<DemoClient, Map<string, LatencyTracker>>();
/** The latency tracker of one session, as seen from this page. */
export function trackerFor(client: DemoClient, id: string): LatencyTracker {
  let byId = trackers.get(client);
  if (!byId) trackers.set(client, (byId = new Map()));
  let t = byId.get(id);
  if (!t) byId.set(id, (t = new LatencyTracker()));
  return t;
}

/** Re-render when a session's latency tracker changes. */
export function useTracker(client: DemoClient | undefined, id: string | undefined): LatencyTracker | undefined {
  const tracker = client && id ? trackerFor(client, id) : undefined;
  const [, setN] = useState(0);
  useEffect(() => {
    if (!tracker) return;
    let raf = 0;
    return tracker.subscribe(() => {
      if (raf) return;
      raf = requestAnimationFrame(() => {
        raf = 0;
        setN((n) => n + 1);
      });
    });
  }, [tracker]);
  return tracker;
}

export const messageOf = (error: unknown) => (error instanceof Error ? error.message : String(error));

export function useVisible(): boolean {
  const [visible, setVisible] = useState(() => typeof document === 'undefined' || !document.hidden);
  useEffect(() => {
    const on = () => setVisible(!document.hidden);
    document.addEventListener('visibilitychange', on);
    return () => document.removeEventListener('visibilitychange', on);
  }, []);
  return visible;
}

export function useSessionList(client: DemoClient | undefined) {
  // Rows are kept with the client that listed them, so right after a mode
  // switch the previous mode's rows are never mistaken for this mode's.
  const [state, setState] = useState<{ client?: DemoClient; rows?: SessionRow[]; error?: string }>({});
  const visible = useVisible();
  const clientRef = useRef(client);
  clientRef.current = client;
  const refresh = useCallback(async () => {
    const c = clientRef.current;
    if (!c) return;
    try {
      const next = await c.list();
      if (clientRef.current !== c) return;
      setState((prev) =>
        prev.client === c && prev.rows && sameRows(prev.rows, next) && !prev.error ? prev : { client: c, rows: next }
      );
    } catch (e) {
      if (clientRef.current === c) setState((prev) => ({ client: c, rows: prev.client === c ? prev.rows : undefined, error: messageOf(e) }));
    }
  }, []);
  useEffect(() => {
    if (client) void refresh();
  }, [client, refresh]);
  const failing = state.client === client && !!state.error;
  useEffect(() => {
    if (!client || !visible) return;
    // While the server is unreachable, look for it every 3s.
    const id = setInterval(refresh, failing ? 3000 : 10_000);
    return () => clearInterval(id);
  }, [client, visible, refresh, failing]);
  const mine = state.client === client && client !== undefined;
  return { rows: mine ? state.rows : undefined, error: mine ? state.error : undefined, refresh };
}

const sameRows = (a: SessionRow[], b: SessionRow[]) =>
  a.length === b.length && a.every((r, i) => r.id === b[i]!.id && r.status === b[i]!.status);

/**
 * A fetch that never reached the server (it is down, or the network is). A
 * proxy in front of a dead server answers 502/503/504 instead (the Vite dev
 * server's /api proxy does), which means the same thing.
 */
export const isNetworkError = (message: string | undefined) =>
  !!message && (/failed to fetch|networkerror|load failed|network request failed|fetch failed/i.test(message) || /\s50[234]$/.test(message));

export interface SessionData {
  view?: SessionView;
  events: EventView[];
  error?: string;
  /** The session's own read said its World does not have it (a 404): nothing will ever load. */
  notFound: boolean;
  /** Consecutive failed reads (the server went away). */
  failures: number;
  /**
   * A drive of this session is working right now, by its live marks (its
   * `drive.start` came, its `idle` has not): a turn whose writes trail the
   * agent can be running before the log shows any of it.
   */
  driving: boolean;
  live: LiveText;
  /** A `sandbox()` session's mutating calls on its Drive this page saw on the live stream (`drive_files`), newest last: what changed since the Drive's last snapshot. */
  driveChanges: DriveChange[];
  refresh(): void;
}

/** What the page already read of a session: reopening it reads only what's new. */
interface SessionCache {
  log: EventView[];
  seen: Set<string>;
  cursor?: string;
  view?: SessionView;
}
const caches = new WeakMap<DemoClient, Map<string, SessionCache>>();
function cacheFor(client: DemoClient, id: string): SessionCache {
  let byId = caches.get(client);
  if (!byId) caches.set(client, (byId = new Map()));
  let c = byId.get(id);
  if (!c) byId.set(id, (c = { log: [], seen: new Set() }));
  return c;
}
const NO_EVENTS: EventView[] = [];
const NO_CHANGES: DriveChange[] = [];

interface Snapshot {
  key: string;
  view?: SessionView;
  events: EventView[];
  error?: string;
  failures: number;
  notFound?: boolean;
  driving?: boolean;
  driveChanges?: DriveChange[];
}

/** A read that says the session does not exist (as opposed to one that failed). */
const notFoundError = (e: unknown) => isSessionNotFound(e) || (!!e && typeof e === 'object' && (e as { name?: unknown }).name === 'WorkflowRunNotFoundError');

/**
 * The open session: the fold (`inspect`) plus the raw log, read
 * incrementally. Reads are event-driven (a live event triggers one, never
 * more than one in flight) with a fallback poll whose interval the page
 * decides (`pollMs`: fast while something is in flight, slow when idle),
 * none while the tab is hidden.
 *
 * State is keyed by session, so the frame after a switch never shows the
 * previous session's rows; a session read before comes back from the cache
 * at once and only its new events are fetched.
 */
export function useSession(client: DemoClient | undefined, id: string | undefined, pollMs: { current: () => number }): SessionData {
  const key = client && id ? `${client.mode}:${id}` : '';
  const [snap, setSnap] = useState<Snapshot>({ key: '', events: NO_EVENTS, failures: 0 });
  const live = useMemo(() => new LiveText(), [client, id]);
  const refreshRef = useRef<() => void>(() => {});

  const cached = client && id ? caches.get(client)?.get(id) : undefined;
  const current: Snapshot =
    snap.key === key ? snap : { key, view: cached?.view, events: cached?.log.length ? cached.log.slice() : NO_EVENTS, failures: 0 };

  useEffect(() => {
    if (!client || !id) return;
    const c = cacheFor(client, id);
    const put = (patch: Partial<Snapshot>) =>
      setSnap((prev) => ({
        ...(prev.key === key ? prev : { key, view: c.view, events: c.log.slice(), failures: 0 }),
        ...patch,
        key,
      }));
    let stopped = false;
    let inflight = false;
    let again = false;
    let timer: ReturnType<typeof setTimeout> | undefined;
    let fails = 0;
    let first = true;
    let errored = false;
    let lastCount = c.view?.eventCount ?? -1;
    let lastStatus = c.view?.status ?? '';
    // Pushed updates (hints, or marks for every commit on live) drive the
    // refreshes; the poll is only the fallback.
    const pushed = !!client.hints || !!client.livePushes;

    let resetGen = 0;
    let resetDone = 0;
    const schedule = () => {
      clearTimeout(timer);
      if (stopped || document.hidden) return;
      const ms = refreshDelay({ fails, pushed, pollMs: pollMs.current() });
      timer = setTimeout(refresh, ms);
    };

    async function refresh() {
      if (stopped) return;
      if (inflight) {
        again = true;
        return;
      }
      inflight = true;
      clearTimeout(timer);
      // A turn boundary seen before this read began: once this read's view
      // lands (the finished row has the text), the live buffer can go.
      const resetBy = resetGen;
      try {
        // The raw log first: it is incremental and cheap. The fold is read
        // only when the log grew (or on the first read), since it is a pure
        // function of the log.
        // The first read after (re)opening always folds too: in a hybrid
        // session that read is also what drives or re-watches it here.
        let v: SessionView | undefined;
        let page: Awaited<ReturnType<DemoClient['events']>>;
        if (first) [v, page] = await Promise.all([client!.inspect(id!), client!.events(id!, c.cursor)]);
        else page = await client!.events(id!, c.cursor);
        if (stopped) return;
        let grew = false;
        for (const e of page.events) {
          if (c.seen.has(e.eventId)) continue;
          c.seen.add(e.eventId);
          grew = true;
          c.log.push({ ...e, createdAt: String(e.createdAt), index: c.log.length + 1 });
        }
        if (page.cursor) c.cursor = page.cursor;
        if (!v && (grew || c.log.length > lastCount)) v = await client!.inspect(id!);
        if (stopped) return;
        const patch: Partial<Snapshot> = {};
        if (grew) patch.events = c.log.slice();
        if (v && (first || v.eventCount !== lastCount || v.status !== lastStatus)) {
          lastCount = v.eventCount;
          lastStatus = v.status;
          c.view = v;
          patch.view = v;
        } else if (v) lastCount = v.eventCount;
        first = false;
        if (fails) patch.failures = 0;
        fails = 0;
        patch.error = undefined;
        if (grew || patch.view || errored) put(patch);
        // The view shows no model call streaming any more: the finished row has the text.
        if (resetBy > resetDone && resetBy === resetGen && !c.view?.effects.some((e) => e.name === 'model' && inFlight(e))) {
          resetDone = resetBy;
          live.reset();
        }
        errored = false;
      } catch (e) {
        if (stopped) return;
        if (notFoundError(e)) {
          // Nothing to retry: the session is not on this World.
          stopped = true;
          put({ notFound: true, error: undefined });
          return;
        }
        fails++;
        errored = true;
        put({ failures: fails, error: messageOf(e) });
      } finally {
        inflight = false;
        if (again && !stopped) {
          again = false;
          void refresh();
        } else schedule();
      }
    }
    // Live events arrive in bursts (a reconnect replays the stream): one read per burst.
    let soon: ReturnType<typeof setTimeout> | undefined;
    const refreshSoon = () => {
      if (soon) return;
      soon = setTimeout(() => {
        soon = undefined;
        void refresh();
      }, 120);
    };
    refreshRef.current = () => void refresh();

    const tracker = trackerFor(client, id);
    // The latest drive that started and has not said idle (a killed drive never does; the next one replaces it).
    let driving: string | undefined;
    /** The Drive's changes this page saw (stream-only: a reload starts from the last snapshot). */
    let changes: DriveChange[] = [];
    const unlisten = client.live(id, (event) => {
      tracker.event(event);
      if (event?.type === 'drive_files' && typeof event.tool === 'string' && typeof event.callId === 'string') {
        const paths = Array.isArray(event.paths) ? event.paths.filter((p: unknown): p is string => typeof p === 'string') : undefined;
        changes = [...changes, { tool: event.tool, callId: event.callId, ...(paths?.length ? { paths } : {}), t: typeof event.t === 'number' ? event.t : Date.now() }].slice(-50);
        put({ driveChanges: changes });
      }
      if (event?.type === 'mark' && typeof event.drv === 'string') {
        if (event.name === 'drive.start' && driving !== event.drv) {
          driving = event.drv;
          put({ driving: true });
        } else if (event.name === 'idle' && event.drv === driving) {
          driving = undefined;
          put({ driving: false });
        }
      }
      if (event?.type === 'text' && typeof event.delta === 'string') {
        // New output after a boundary whose view has not landed yet: start fresh.
        if (resetGen > resetDone) {
          resetDone = resetGen;
          live.reset();
        }
        const first = !live.hasText;
        live.append(event.delta);
        if (first) refreshSoon();
        return;
      }
      // A model call ended (a tool starts, the turn is idle): keep its text
      // on screen until the next read shows the finished row, so the
      // streamed text does not blink out in between.
      if (event?.type === 'tool_start' || event?.type === 'idle') {
        const gen = ++resetGen;
        // However the reads go, the buffer does not outlive the next few seconds.
        setTimeout(() => {
          if (!stopped && resetGen === gen && resetDone < gen) {
            resetDone = gen;
            live.reset();
          }
        }, 4000);
      }
      if (event?.type === 'chaos') live.reset();
      // Run-ahead: speculative output the log does not have is retracted
      // (a rejected write rewinds the drive; it streams the turn again).
      if (event?.type === 'rewind' || event?.type === 'submit-failed') live.reset();
      // A turn a crash cut off resumed and its model answers again: the cut-off text never reached the log, so it goes; what
      // the log kept shows from the next read, and the resumed reply streams after it.
      if (event?.type === 'restart') live.reset();
      if (event?.type === 'submit-failed') {
        put({ error: `A prompt did not become durable yet (${String(event.error ?? 'write failed')}); the drive re-issues it.` });
      }
      refreshSoon();
    });
    const unhint = client.hints?.(id, refreshSoon);
    const onVisible = () => {
      if (!document.hidden) void refresh();
    };
    document.addEventListener('visibilitychange', onVisible);
    void refresh();
    return () => {
      stopped = true;
      clearTimeout(timer);
      clearTimeout(soon);
      unlisten();
      unhint?.();
      document.removeEventListener('visibilitychange', onVisible);
      refreshRef.current = () => {};
    };
    // biome-ignore lint/correctness/useExhaustiveDependencies: key follows client and id
  }, [client, id, live, pollMs]);

  const refresh = useCallback(() => refreshRef.current(), []);
  return {
    view: current.view,
    events: current.events,
    error: current.error,
    failures: current.failures,
    notFound: !!current.notFound,
    driving: !!current.driving,
    live,
    driveChanges: current.driveChanges ?? NO_CHANGES,
    refresh,
  };
}

export function useMedia(query: string): boolean {
  const [match, setMatch] = useState(() => typeof matchMedia !== 'undefined' && matchMedia(query).matches);
  useEffect(() => {
    const m = matchMedia(query);
    const on = () => setMatch(m.matches);
    on();
    m.addEventListener('change', on);
    return () => m.removeEventListener('change', on);
  }, [query]);
  return match;
}