@somewhatintelligent/cc-ws-client 0.1.0

package/src/shell.ts

@@ -0,0 +1,272 @@
+// Bash exchange XML — single source of truth for the format the bridge
+// replays back when a `bash_command` frame runs. Three shapes ride the
+// `user` content channel:
+//   input-only   <bash-input>cmd</bash-input>
+//   output-only  <bash-stdout>…</bash-stdout><bash-stderr>…</bash-stderr><bash-exit-code>0</bash-exit-code>
+//   merged       both, plus arbitrary trailing user text (drain-synthesis)
+// Both the lib's outbound writer (handleShellReplay) and any UI that
+// renders bash exchanges parse the same shape — keep them in lockstep
+// here.
+
+import { atom, type WritableAtom } from "nanostores";
+import { isSystemFrame, isUserFrame, type InboundFrame } from "./protocol";
+import type { WsClient } from "./ws";
+
+export function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function decodeXml(s: string): string {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+const RE_INPUT = /<bash-input>([\s\S]*?)<\/bash-input>/;
+const RE_STDOUT = /<bash-stdout>([\s\S]*?)<\/bash-stdout>/;
+const RE_STDERR = /<bash-stderr>([\s\S]*?)<\/bash-stderr>/;
+const RE_EXIT = /<bash-exit-code>([\s\S]*?)<\/bash-exit-code>/;
+
+export type BashFrame =
+  | { kind: "input"; command: string }
+  | { kind: "output"; stdout: string; stderr: string; exit: string }
+  | { kind: "merged"; command: string; stdout: string; stderr: string; exit: string; trailing: string };
+
+export function parseBashFrame(text: string): BashFrame | null {
+  const inMatch = text.match(RE_INPUT);
+  const outMatch = text.match(RE_STDOUT);
+  const errMatch = text.match(RE_STDERR);
+  const exitMatch = text.match(RE_EXIT);
+  const hasInput = inMatch != null;
+  const hasOutput = outMatch != null || errMatch != null || exitMatch != null;
+  if (!hasInput && !hasOutput) return null;
+
+  if (hasInput && hasOutput) {
+    return {
+      kind: "merged",
+      command: decodeXml(inMatch![1]!),
+      stdout: outMatch ? decodeXml(outMatch[1]!) : "",
+      stderr: errMatch ? decodeXml(errMatch[1]!) : "",
+      exit: exitMatch ? decodeXml(exitMatch[1]!) : "",
+      trailing: text
+        .replace(RE_INPUT, "")
+        .replace(RE_STDOUT, "")
+        .replace(RE_STDERR, "")
+        .replace(RE_EXIT, "")
+        .trim(),
+    };
+  }
+  if (hasInput) {
+    return { kind: "input", command: decodeXml(inMatch![1]!) };
+  }
+  return {
+    kind: "output",
+    stdout: outMatch ? decodeXml(outMatch[1]!) : "",
+    stderr: errMatch ? decodeXml(errMatch[1]!) : "",
+    exit: exitMatch ? decodeXml(exitMatch[1]!) : "",
+  };
+}
+
+// Reconstruct the merged-frame XML the lib drains into the next user
+// message. Encoding mirrors what the binary sends back so the round-trip
+// is lossless.
+export function buildBashXml(command: string, stdoutXml: string, stderrXml: string): string {
+  return (
+    `<bash-input>${escapeXml(command)}</bash-input>\n` +
+    `<bash-stdout>${stdoutXml}</bash-stdout>` +
+    `<bash-stderr>${stderrXml}</bash-stderr>`
+  );
+}
+
+// ---------- runtime controller ----------
+
+export type ShellSource = "context" | "sideChannel";
+
+export type ShellEntry = {
+  id: string;
+  command: string;
+  source: ShellSource;
+  chunks: string[];
+  // For context-shell: the exchange has run on the bridge but the
+  // <bash-input>/<bash-stdout> XML hasn't been sent to claude yet — it
+  // gets prepended to the user's next sendMessage() (matches the TUI's
+  // shouldQuery:false flow). Cleared when drained.
+  pending?: boolean;
+};
+
+export type ShellController = {
+  shellEntries: WritableAtom<ShellEntry[]>;
+  // Frame ingestion side-effects (return false intentionally for the
+  // user-replay path — see handleShellReplay below).
+  handleShellReplay: (frame: InboundFrame) => boolean;
+  handleLocalCommandOutput: (frame: InboundFrame) => boolean;
+  // Public ops.
+  sendShellContext: (command: string, followUp?: string) => void;
+  sendBashSideChannel: (command: string) => void;
+  dismissShellEntry: (id: string) => void;
+  // Drain pending bash exchanges into outbound text + clear their entries.
+  // Returns the rewritten payload for sendMessage to wire-send.
+  drainPending: (text: string) => string;
+  hasPending: () => boolean;
+  reset: () => void;
+};
+
+export function createShellController(args: {
+  ws: WsClient;
+  // sendMessage is back-injected because a queued follow-up text fires
+  // sendMessage(followUp) after the bash exchange's XML is buffered, and
+  // sendMessage in turn drains via drainPending().
+  sendMessage: (text: string) => void;
+}): ShellController {
+  const { ws, sendMessage } = args;
+  const shellEntries = atom<ShellEntry[]>([]);
+
+  // bash_command replay frames don't carry a correlation id, but the
+  // binary processes them in the order received and replies in the same
+  // order. So we keep a FIFO of in-flight captures: each call to
+  // sendShellContext / sendBashSideChannel pushes; each output-replay
+  // frame shifts. Two bash sends in quick succession used to clobber
+  // each other when we tracked a single `activeShellId` global.
+  const captureQueue: {
+    entryId: string;
+    command: string;
+    source: ShellSource;
+    sawInputEcho: boolean;
+  }[] = [];
+  // Buffered <bash-input>/<bash-stdout>/<bash-stderr> XML, FIFO. Filled
+  // when a context-shell capture's output replay arrives; drained by
+  // sendMessage() which prepends to the user's next prompt. The TUI-`!cmd`
+  // parity workaround: bash_command's replay frames are NOT injected
+  // into claude's transcript by the binary (verified empirically).
+  const pendingBashExchanges: { entryId: string; xml: string }[] = [];
+  // Optional follow-up user prompts queued from sendShellContext (the
+  // multi-line `!cmd\n<followup>` form). Fires sendMessage(followUp)
+  // after the bash exchange's XML is buffered, so the followUp goes out
+  // as the user message that drains the buffer.
+  const pendingFollowUps = new Map<string, string>();
+
+  // Side-effect-only: scrape bash-* replay frames for shellEntries chunks
+  // + build the buffered XML that rides out on the next sendMessage.
+  // Always returns false so the frame still flows into messagesCtrl for
+  // chat-side rendering.
+  function handleShellReplay(frame: InboundFrame): boolean {
+    if (!isUserFrame(frame) || !frame.isReplay) return false;
+    const c = frame.message.content;
+    if (typeof c !== "string") return false;
+    const parsed = parseBashFrame(c);
+    if (!parsed) return false;
+
+    if (parsed.kind === "input") {
+      // First replay frame for the head capture: the binary acked the
+      // command. Output is still pending.
+      const head = captureQueue[0];
+      if (head) head.sawInputEcho = true;
+      return false;
+    }
+    // Both "output" (output-only replay) and "merged" (some bridges emit
+    // input + output in one frame) close the head capture in FIFO order.
+    const cap = captureQueue.shift();
+    if (!cap) return false;
+    const parts: string[] = [];
+    if (parsed.stdout) parts.push(parsed.stdout);
+    if (parsed.stderr) parts.push("[stderr] " + parsed.stderr);
+    if (parsed.exit && parsed.exit !== "0") parts.push(`[exit ${parsed.exit}]`);
+    const chunk = parts.join("\n");
+    shellEntries.set(
+      shellEntries.get().map((s) => (s.id === cap.entryId ? { ...s, chunks: [...s.chunks, chunk] } : s)),
+    );
+    if (cap.source === "context") {
+      // Re-encode for the buffered XML — parseBashFrame decodes the
+      // entities; the outbound payload needs them re-escaped.
+      const stdoutXml = escapeXml(parsed.stdout);
+      const stderrXml = escapeXml(parsed.stderr);
+      pendingBashExchanges.push({
+        entryId: cap.entryId,
+        xml: buildBashXml(cap.command, stdoutXml, stderrXml),
+      });
+      const followUp = pendingFollowUps.get(cap.entryId);
+      if (followUp) {
+        pendingFollowUps.delete(cap.entryId);
+        sendMessage(followUp);
+      }
+    }
+    return false;
+  }
+
+  function handleLocalCommandOutput(frame: InboundFrame): boolean {
+    if (!isSystemFrame(frame) || frame.subtype !== "local_command_output") return false;
+    const head = captureQueue[0];
+    if (!head) return false;
+    const content = "content" in frame ? frame.content ?? "" : "";
+    shellEntries.set(
+      shellEntries.get().map((s) => (s.id === head.entryId ? { ...s, chunks: [...s.chunks, content] } : s)),
+    );
+    return true;
+  }
+
+  function sendShellContext(command: string, followUp = "") {
+    // Route `!cmd` to the binary via the bash_command wire frame: the
+    // binary runs it (with its own bounds, sandboxing, etc) and replays
+    // <bash-input>/<bash-stdout>/<bash-stderr>/<bash-exit-code> as
+    // user/isReplay frames over the wire. Empirically these replay
+    // frames are NOT auto-injected into claude's transcript — we have
+    // to ride them out ourselves on the next user message.
+    const id = crypto.randomUUID();
+    shellEntries.set([...shellEntries.get(), { id, command, source: "context", chunks: [], pending: true }]);
+    captureQueue.push({ entryId: id, command, source: "context", sawInputEcho: false });
+    ws.send({ type: "bash_command", command });
+    // If the user typed a follow-up prompt on subsequent lines of the
+    // !cmd input, fire it right after the bash exchange completes — the
+    // drain in sendMessage will prepend the XML to the followUp text.
+    if (followUp.trim()) {
+      pendingFollowUps.set(id, followUp);
+    }
+  }
+
+  function sendBashSideChannel(command: string) {
+    const id = crypto.randomUUID();
+    shellEntries.set([...shellEntries.get(), { id, command, source: "sideChannel", chunks: [] }]);
+    captureQueue.push({ entryId: id, command, source: "sideChannel", sawInputEcho: false });
+    ws.send({ type: "bash_command", command });
+  }
+
+  function dismissShellEntry(id: string) {
+    shellEntries.set(shellEntries.get().filter((s) => s.id !== id));
+  }
+
+  function hasPending(): boolean {
+    return pendingBashExchanges.length > 0;
+  }
+
+  // Drain buffered context-shell exchanges. Drained shell entries get
+  // removed from shellEntries — the panel acts as a "queued exchange"
+  // indicator that empties when the user fires the message that flushes
+  // the buffer. The exchange remains visible in the chat scrollback.
+  function drainPending(text: string): string {
+    if (pendingBashExchanges.length === 0) return text;
+    const xml = pendingBashExchanges.map((p) => p.xml).join("\n");
+    const payload = text.trim() ? `${xml}\n\n${text}` : xml;
+    const drainedIds = new Set(pendingBashExchanges.map((p) => p.entryId));
+    shellEntries.set(shellEntries.get().filter((s) => !drainedIds.has(s.id)));
+    pendingBashExchanges.length = 0;
+    return payload;
+  }
+
+  function reset() {
+    shellEntries.set([]);
+    captureQueue.length = 0;
+    pendingBashExchanges.length = 0;
+    pendingFollowUps.clear();
+  }
+
+  return {
+    shellEntries,
+    handleShellReplay,
+    handleLocalCommandOutput,
+    sendShellContext,
+    sendBashSideChannel,
+    dismissShellEntry,
+    drainPending,
+    hasPending,
+    reset,
+  };
+}
+

package/src/tasks.ts

@@ -0,0 +1,246 @@
+// Task lifecycle: system:task_started / task_progress / task_updated /
+// task_notification, plus sub-agent fan-out (frames carrying a non-null
+// parent_tool_use_id are routed to the matching task's transcript instead
+// of the main timeline).
+
+import { atom, type WritableAtom } from "nanostores";
+import type { MessageEntry } from "./messages";
+import {
+  isSystemFrame,
+  type InboundFrame,
+  type SystemTaskNotification,
+  type SystemTaskProgress,
+  type SystemTaskStarted,
+  type SystemTaskUpdated,
+  type TaskUsageBlock,
+} from "./protocol";
+
+// task_id is the binary's local registry id and the value to pass to
+// stopTask(). tool_use_id ties the task back to the tool_use block that
+// spawned it (Bash, Agent, Task, etc) — used to render task progress
+// alongside / inside the parent's tool_use card.
+export type TaskStatus = "running" | "completed" | "failed" | "stopped";
+
+export type TaskUsage = {
+  totalTokens?: number;
+  toolUses?: number;
+  durationMs?: number;
+};
+
+export type TaskEntry = {
+  taskId: string;
+  toolUseId?: string;
+  taskType?: string;
+  description: string;
+  workflowName?: string;
+  prompt?: string;
+  status: TaskStatus;
+  startTime: number;
+  lastUpdate: number;
+  lastToolName?: string;
+  summary?: string;
+  outputFile?: string;
+  usage?: TaskUsage;
+  // Sub-agent transcript (frames received with parent_tool_use_id matching
+  // toolUseId). Populated only for tasks that emit their own frames —
+  // bash tasks won't have these.
+  transcript: MessageEntry[];
+};
+
+const TASKS_CAP = 100;
+
+export function capTasksKeepRunning<T extends { status: string }>(arr: T[], cap: number): T[] {
+  if (arr.length <= cap) return arr;
+  // Evict oldest non-running entries first; if all are running, keep all.
+  const overflow = arr.length - cap;
+  const out: T[] = [];
+  let evictBudget = overflow;
+  for (const t of arr) {
+    if (evictBudget > 0 && t.status !== "running") {
+      evictBudget--;
+      continue;
+    }
+    out.push(t);
+  }
+  return out;
+}
+
+function mapTaskUsage(u: TaskUsageBlock | undefined, prev?: TaskUsage): TaskUsage | undefined {
+  if (!u) return prev;
+  return {
+    totalTokens: u.total_tokens ?? prev?.totalTokens,
+    toolUses: u.tool_uses ?? prev?.toolUses,
+    durationMs: u.duration_ms ?? prev?.durationMs,
+  };
+}
+
+export type TasksController = {
+  tasks: WritableAtom<TaskEntry[]>;
+  handleTaskEvent: (frame: InboundFrame) => boolean;
+  handleSubAgentFrame: (frame: InboundFrame) => boolean;
+  reset: () => void;
+};
+
+export function createTasksController(): TasksController {
+  const tasks = atom<TaskEntry[]>([]);
+
+  function upsertTask(taskId: string, mut: (t: TaskEntry) => TaskEntry, init?: () => TaskEntry) {
+    const arr = tasks.get();
+    const idx = arr.findIndex((t) => t.taskId === taskId);
+    if (idx === -1) {
+      if (!init) return;
+      tasks.set(capTasksKeepRunning([...arr, mut(init())], TASKS_CAP));
+    } else {
+      const next = arr.slice();
+      next[idx] = mut(arr[idx]!);
+      tasks.set(capTasksKeepRunning(next, TASKS_CAP));
+    }
+  }
+
+  // task_started bookend opens a task; progress updates the running entry;
+  // task_notification closes it with terminal status.
+  function handleTaskEvent(frame: InboundFrame): boolean {
+    if (!isSystemFrame(frame)) return false;
+
+    if (frame.subtype === "task_started") {
+      const f = frame as SystemTaskStarted;
+      if (!f.task_id) return false;
+      const now = Date.now();
+      upsertTask(
+        f.task_id,
+        (t) => ({
+          ...t,
+          toolUseId: f.tool_use_id ?? t.toolUseId,
+          taskType: f.task_type ?? t.taskType,
+          description: f.description ?? t.description,
+          workflowName: f.workflow_name ?? t.workflowName,
+          prompt: f.prompt ?? t.prompt,
+          status: "running",
+          lastUpdate: now,
+        }),
+        () => ({
+          taskId: f.task_id,
+          toolUseId: f.tool_use_id,
+          taskType: f.task_type,
+          description: f.description ?? "",
+          workflowName: f.workflow_name,
+          prompt: f.prompt,
+          status: "running",
+          startTime: now,
+          lastUpdate: now,
+          transcript: [],
+        }),
+      );
+      return true;
+    }
+
+    if (frame.subtype === "task_progress") {
+      const f = frame as SystemTaskProgress;
+      if (!f.task_id) return false;
+      upsertTask(f.task_id, (t) => ({
+        ...t,
+        description: f.description ?? t.description,
+        lastToolName: f.last_tool_name ?? t.lastToolName,
+        summary: f.summary ?? t.summary,
+        usage: mapTaskUsage(f.usage, t.usage),
+        lastUpdate: Date.now(),
+      }));
+      return true;
+    }
+
+    // task_updated is the binary's immediate state-change frame (stop_task
+    // → status:"killed"). The bookend task_notification arrives later;
+    // flip status NOW so a killed task doesn't render as still-running.
+    if (frame.subtype === "task_updated") {
+      const f = frame as SystemTaskUpdated;
+      if (!f.task_id || !f.patch) return false;
+      const rawStatus = f.patch.status;
+      const mapped: TaskStatus | undefined =
+        rawStatus === "killed" ? "stopped" :
+        rawStatus === "completed" || rawStatus === "failed" || rawStatus === "stopped" ? rawStatus :
+        undefined;
+      upsertTask(f.task_id, (t) => ({
+        ...t,
+        status: mapped ?? t.status,
+        lastUpdate: Date.now(),
+      }));
+      return true;
+    }
+
+    if (frame.subtype === "task_notification") {
+      const f = frame as SystemTaskNotification;
+      if (!f.task_id) return false;
+      const status: TaskStatus =
+        f.status === "completed" || f.status === "failed" || f.status === "stopped" ? f.status : "completed";
+      upsertTask(
+        f.task_id,
+        (t) => ({
+          ...t,
+          status,
+          summary: f.summary ?? t.summary,
+          outputFile: f.output_file ?? t.outputFile,
+          usage: mapTaskUsage(f.usage, t.usage),
+          lastUpdate: Date.now(),
+        }),
+        () => ({
+          taskId: f.task_id,
+          toolUseId: f.tool_use_id,
+          taskType: undefined,
+          description: f.summary ?? "",
+          status,
+          startTime: Date.now(),
+          lastUpdate: Date.now(),
+          transcript: [],
+        }),
+      );
+      return true;
+    }
+
+    return false;
+  }
+
+  // Sub-agent frames must be checked BEFORE messagesCtrl.ingest in the
+  // dispatch chain — the messages controller eats stream_event / assistant
+  // unconditionally, which would otherwise pollute the main timeline with
+  // sub-agent bubbles and starve the per-task transcript.
+  function handleSubAgentFrame(frame: InboundFrame): boolean {
+    const parent =
+      "parent_tool_use_id" in frame && typeof frame.parent_tool_use_id === "string"
+        ? frame.parent_tool_use_id
+        : null;
+    if (!parent) return false;
+    const arr = tasks.get();
+    const idx = arr.findIndex((t) => t.toolUseId === parent);
+    // Race: task_started not yet observed. Fall through so the frame still
+    // appears somewhere — visible-but-misplaced beats dropped.
+    if (idx === -1) return false;
+    const next = arr.slice();
+    const cur = arr[idx]!;
+    next[idx] = {
+      ...cur,
+      transcript: [
+        ...cur.transcript,
+        {
+          kind: "frame" as const,
+          id: crypto.randomUUID(),
+          frame,
+          arrivalIdx: cur.transcript.length,
+        },
+      ],
+      lastUpdate: Date.now(),
+    };
+    tasks.set(next);
+    return true;
+  }
+
+  function reset() {
+    tasks.set([]);
+  }
+
+  return {
+    tasks,
+    handleTaskEvent,
+    handleSubAgentFrame,
+    reset,
+  };
+}

package/src/usage.ts

@@ -0,0 +1,30 @@
+// Token usage helpers. The SDK's "total tokens" is
+//   input + cache_creation + cache_read + output
+// — i.e. context-window load, not lifetime tokens (cache_read dominates
+// once a session has any history). UIs that show "ctx %" want this sum.
+
+export type UsageLike = {
+  input_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  output_tokens?: number;
+};
+
+export function sumContextTokens(u: UsageLike | null | undefined): number | null {
+  if (!u) return null;
+  const total =
+    (u.input_tokens ?? 0)
+    + (u.cache_creation_input_tokens ?? 0)
+    + (u.cache_read_input_tokens ?? 0)
+    + (u.output_tokens ?? 0);
+  return Number.isFinite(total) ? total : null;
+}
+
+// Pull the most-relevant `usage` block from a frame regardless of which
+// canonical shape it took (`assistant`/`stream_event`-derived have it on
+// `message.usage`; `result` puts it at the top level).
+export function getFrameUsage(frame: unknown): UsageLike | null {
+  if (!frame || typeof frame !== "object") return null;
+  const f = frame as { usage?: UsageLike; message?: { usage?: UsageLike } };
+  return f.usage ?? f.message?.usage ?? null;
+}

package/src/ws.ts

@@ -0,0 +1,98 @@
+// Thin WS wrapper. Does NOT auto-reconnect (deferred per LIB-DESIGN). One
+// connection per createCcSession. NDJSON framing on the wire — every send is
+// already a single JSON object; the bridge splits inbound on `\n`.
+
+import { atom, type WritableAtom } from "nanostores";
+import type { InboundFrame, OutboundFrame } from "./protocol";
+
+export type WsStatus =
+  | "idle"
+  | "connecting"
+  | "open"
+  | "respawning"
+  | "closed"
+  | "error";
+
+export type WsClient = {
+  status: WritableAtom<WsStatus>;
+  lastError: WritableAtom<string | null>;
+  connect: () => void;
+  disconnect: () => void;
+  send: (frame: OutboundFrame) => void;
+  // Internal: subscribers register here to receive parsed inbound frames.
+  // Avoids forcing a fan-out atom that would re-render every subscriber on
+  // every frame.
+  onFrame: (handler: (frame: InboundFrame) => void) => () => void;
+};
+
+export function createWsClient(opts: {
+  url: string;
+  onTrace?: (dir: "in" | "out", line: string) => void;
+}): WsClient {
+  const status = atom<WsStatus>("idle");
+  const lastError = atom<string | null>(null);
+  const handlers = new Set<(f: InboundFrame) => void>();
+  let ws: WebSocket | null = null;
+
+  function connect() {
+    if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+    status.set("connecting");
+    lastError.set(null);
+    ws = new WebSocket(opts.url);
+    ws.onopen = () => status.set("open");
+    ws.onclose = () => {
+      ws = null;
+      status.set("closed");
+    };
+    ws.onerror = () => {
+      lastError.set("ws error");
+      status.set("error");
+    };
+    ws.onmessage = (e) => {
+      const text = typeof e.data === "string" ? e.data : "";
+      if (!text) return;
+      opts.onTrace?.("in", text);
+      let parsed: InboundFrame;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        // Bad frame — drop. We don't want one bad frame to take down the session.
+        return;
+      }
+      for (const h of handlers) {
+        try {
+          h(parsed);
+        } catch (err) {
+          // A handler throwing should not stop other handlers.
+          console.error("[ws] handler error", err);
+        }
+      }
+    };
+  }
+
+  function disconnect() {
+    if (ws) {
+      try { ws.close(); } catch {}
+      ws = null;
+    }
+    status.set("closed");
+  }
+
+  function send(frame: OutboundFrame) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const line = JSON.stringify(frame);
+    opts.onTrace?.("out", line);
+    ws.send(line);
+  }
+
+  function onFrame(handler: (f: InboundFrame) => void) {
+    handlers.add(handler);
+    return () => {
+      handlers.delete(handler);
+    };
+  }
+
+  return { status, lastError, connect, disconnect, send, onFrame };
+}