@somewhatintelligent/cc-ws-client 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# @somewhatintelligent/cc-ws-client
+
+Framework-agnostic reactive WebSocket client for the cc-ws Claude Code bridge protocol. Reactive state via [nanostores](https://github.com/nanostores/nanostores).
+
+```ts
+import { createCcSession } from "@somewhatintelligent/cc-ws-client";
+
+const session = createCcSession({ url: "wss://example.com/ws" });
+session.sendMessage("Hello");
+
+// Subscribe via nanostores; or use the framework adapters:
+// - @somewhatintelligent/cc-ws-react
+// - @somewhatintelligent/cc-ws-svelte (workspace-only for now)
+```
+
+See `LIB-DESIGN.md` in the source repo for the wire protocol.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@somewhatintelligent/cc-ws-client",
+  "version": "0.1.0",
+  "description": "Framework-agnostic reactive WebSocket client for the cc-ws Claude Code bridge protocol.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./protocol": "./src/protocol.ts",
+    "./modes": "./src/modes.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "nanostores": "^1.3.0"
+  }
+}

package/src/controls.ts

@@ -0,0 +1,95 @@
+// Control-request layer. Tracks every outbound control_request by request_id
+// and resolves a Promise when its matching control_response arrives. Higher
+// layers (session.ts) compose this for set_permission_mode / set_model /
+// get_settings / file_suggestions / interrupt / end_session.
+
+import {
+  isControlResponse,
+  makeRequestId,
+  type OutboundControlRequestSubtype,
+  type InboundFrame,
+} from "./protocol";
+import type { WsClient } from "./ws";
+
+// The wrapper carries the canonical control_response payload (we hand
+// both back so callers that need the request_id or subtype can dig in;
+// most just read .inner).
+export type ControlResponseResult = {
+  inner: unknown;
+  wrapper: { subtype: "success"; request_id: string; response?: unknown };
+};
+
+type Resolver = {
+  resolve: (response: ControlResponseResult) => void;
+  reject: (error: string) => void;
+  timeoutId: ReturnType<typeof setTimeout>;
+};
+
+export type ControlsClient = {
+  request: (
+    request: OutboundControlRequestSubtype,
+    opts?: { timeoutMs?: number },
+  ) => Promise<ControlResponseResult>;
+  // For frames we DIDN'T initiate (can_use_tool comes IN as control_request).
+  // Returns true if the frame was handled (we matched it to an in-flight
+  // request).
+  ingest: (frame: InboundFrame) => boolean;
+  // Reject every in-flight request with `reason`. Called from session
+  // respawn/disconnect — the bridge kills the old claude child the
+  // moment we send respawn, so any outstanding control_request would
+  // otherwise hang against a dead pipe until its timeoutMs fires.
+  abortAll: (reason: string) => void;
+};
+
+export function createControlsClient(ws: WsClient): ControlsClient {
+  const inflight = new Map<string, Resolver>();
+
+  function request(
+    body: OutboundControlRequestSubtype,
+    opts: { timeoutMs?: number } = {},
+  ): Promise<ControlResponseResult> {
+    const requestId = makeRequestId();
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    return new Promise<ControlResponseResult>((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        if (!inflight.has(requestId)) return;
+        inflight.delete(requestId);
+        reject(`timed out after ${timeoutMs}ms`);
+      }, timeoutMs);
+      inflight.set(requestId, { resolve, reject, timeoutId });
+      ws.send({
+        type: "control_request",
+        request_id: requestId,
+        request: body,
+      });
+    });
+  }
+
+  function ingest(frame: InboundFrame): boolean {
+    if (!isControlResponse(frame)) return false;
+    // Real binary wire format may put request_id either at the outer
+    // envelope OR inside response. Check both before giving up.
+    const id = frame.response.request_id ?? frame.request_id;
+    if (!id) return false;
+    const r = inflight.get(id);
+    if (!r) return false;
+    inflight.delete(id);
+    clearTimeout(r.timeoutId);
+    if (frame.response.subtype === "success") {
+      r.resolve({ inner: frame.response.response, wrapper: frame.response });
+    } else {
+      r.reject(frame.response.error ?? "unknown error");
+    }
+    return true;
+  }
+
+  function abortAll(reason: string) {
+    for (const [id, r] of inflight) {
+      clearTimeout(r.timeoutId);
+      r.reject(reason);
+      inflight.delete(id);
+    }
+  }
+
+  return { request, ingest, abortAll };
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+export { createCcSession } from "./session";
+export {
+  parseBashFrame,
+  buildBashXml,
+  escapeXml,
+  decodeXml,
+  type BashFrame,
+} from "./shell";
+export {
+  sumContextTokens,
+  getFrameUsage,
+  type UsageLike,
+} from "./usage";
+export {
+  isAssistantFrame,
+  isControlRequest,
+  isControlResponse,
+  isLocalRespawnResult,
+  isResultFrame,
+  isStreamEventFrame,
+  isSystemFrame,
+  isUserFrame,
+} from "./protocol";
+export type {
+  CcAtoms,
+  CcSession,
+  CcSessionOptions,
+  CcPersistenceOptions,
+  HookEntry,
+  InitData,
+  SessionState,
+  ShellEntry,
+  ShellSource,
+  StorageLike,
+  TaskEntry,
+  TaskStatus,
+  TaskUsage,
+} from "./session";
+export type {
+  MessageEntry,
+  LocalUserEntry,
+  FrameEntry,
+  StreamingEntry,
+  InFlightMessage,
+  StreamingBlock,
+  TextBlock,
+  ToolUseBlock,
+  ThinkingBlock,
+} from "./messages";
+export type {
+  PendingPermission,
+  PermissionDecision,
+  OnCanUseTool,
+} from "./permissions";
+export type { WsStatus } from "./ws";
+export type {
+  AssistantContentBlock,
+  AssistantFrame,
+  AssistantMessage,
+  ControlRequestFrame,
+  ControlResponseFrame,
+  HookSubtype,
+  InboundFrame,
+  ResultFrame,
+  SessionMode,
+  SessionStateValue,
+  StreamEvent,
+  StreamEventFrame,
+  SystemCompactBoundary,
+  SystemFrame,
+  SystemHook,
+  SystemInit,
+  SystemLocalCommandOutput,
+  SystemSessionStateChanged,
+  SystemStatus,
+  SystemTaskNotification,
+  SystemTaskProgress,
+  SystemTaskStarted,
+  SystemTaskUpdated,
+  TaskUpdatedPatch,
+  TaskUsageBlock,
+  TextContentBlock,
+  ThinkingContentBlock,
+  ToolResultContentBlock,
+  ToolUseContentBlock,
+  UnknownSystemFrame,
+  UsageBlock,
+  UserContentBlock,
+  UserFrame,
+  UserMessage,
+} from "./protocol";
+export {
+  PERMISSION_MODE_DEFS,
+  PERMISSION_MODE_OPTIONS,
+  KNOWN_PERMISSION_MODES,
+  CYCLE_ORDER,
+  nextCycleMode,
+  MODEL_DEFS,
+  MODEL_OPTIONS,
+  KNOWN_MODELS,
+  EFFORT_DEFS,
+  EFFORT_OPTIONS,
+  KNOWN_EFFORTS,
+} from "./modes";
+export type {
+  PermissionMode,
+  Model,
+  Effort,
+} from "./modes";

package/src/messages.ts

@@ -0,0 +1,312 @@
+// Conversation log. Holds:
+//   - Local user echoes (sent prompts mirrored into the chat).
+//   - Raw inbound frames (assistant, user, result, control_*, etc).
+//   - In-flight assistant messages reconstructed from `stream_event` deltas.
+//
+// The `messages` atom is the canonical timeline. Streaming messages live as
+// entries with kind:"streaming"; when the canonical `assistant` envelope
+// arrives, the streaming entry is removed and replaced by the final
+// `frame` entry (the renderer treats the assistant frame as authoritative).
+
+import { atom, type WritableAtom } from "nanostores";
+import type { InboundFrame, StreamEvent } from "./protocol";
+
+// ---------- streaming reconstruction ----------
+
+export type TextBlock = { type: "text"; text: string };
+export type ToolUseBlock = {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: unknown;
+  // partial_json deltas accumulate here, parsed into `input` on
+  // content_block_stop. _parsed flips true once parsed (or on empty input
+  // close).
+  _partialJson: string;
+  _parsed: boolean;
+};
+export type ThinkingBlock = { type: "thinking"; thinking: string };
+export type StreamingBlock = TextBlock | ToolUseBlock | ThinkingBlock;
+
+export type InFlightMessage = {
+  id: string;
+  role: "assistant";
+  model?: string;
+  content: StreamingBlock[];
+  done: boolean;
+  arrivalIdx: number;
+};
+
+// ---------- timeline entries ----------
+
+export type LocalUserEntry = {
+  kind: "local_user";
+  id: string;
+  text: string;
+  arrivalIdx: number;
+};
+
+export type FrameEntry = {
+  kind: "frame";
+  id: string;
+  frame: InboundFrame;
+  arrivalIdx: number;
+};
+
+export type StreamingEntry = {
+  kind: "streaming";
+  id: string;
+  msg: InFlightMessage;
+  arrivalIdx: number;
+};
+
+export type MessageEntry = LocalUserEntry | FrameEntry | StreamingEntry;
+
+export type MessagesController = {
+  messages: WritableAtom<MessageEntry[]>;
+  activeStreamId: WritableAtom<string | null>;
+  // Bumps on every non-streaming change (pushFrame / pushLocalUser /
+  // dropStreaming / reset / hydrate). Stays still during streaming
+  // deltas. Persistence and other "save on stable change" consumers
+  // should subscribe to this rather than `messages` to avoid paying
+  // a serialization tax once per 250ms while a turn is streaming.
+  revision: WritableAtom<number>;
+  pushLocalUser: (text: string) => void;
+  pushFrame: (frame: InboundFrame) => void;
+  // Returns true if the frame was consumed by the streaming machinery and
+  // should NOT be appended to the timeline as a frame entry.
+  ingest: (frame: InboundFrame) => boolean;
+  reset: () => void;
+  // Replace the timeline with a saved snapshot (used by persistence on
+  // reload). Streaming entries are dropped — they're transient and don't
+  // round-trip through serialization.
+  hydrate: (entries: MessageEntry[]) => void;
+};
+
+export function createMessagesController(): MessagesController {
+  const messages = atom<MessageEntry[]>([]);
+  const activeStreamId = atom<string | null>(null);
+  const revision = atom(0);
+  function bumpRevision() {
+    revision.set(revision.get() + 1);
+  }
+  // Streaming reconstructions, keyed by message id. Mutated in place; each
+  // delta bumps the messages atom by emitting a new array reference so
+  // subscribers re-render. We accept the array-replacement cost for the
+  // simpler reactivity contract — there's typically ≤1 active streaming
+  // message at a time.
+  const streaming = new Map<string, InFlightMessage>();
+  let arrivalCounter = 0;
+
+  function nextIdx() {
+    return arrivalCounter++;
+  }
+
+  function pushLocalUser(text: string) {
+    const id = crypto.randomUUID();
+    const entry: LocalUserEntry = {
+      kind: "local_user",
+      id,
+      text,
+      arrivalIdx: nextIdx(),
+    };
+    messages.set([...messages.get(), entry]);
+    bumpRevision();
+  }
+
+  function pushFrame(frame: InboundFrame) {
+    const entry: FrameEntry = {
+      kind: "frame",
+      id: crypto.randomUUID(),
+      frame,
+      arrivalIdx: nextIdx(),
+    };
+    messages.set([...messages.get(), entry]);
+    bumpRevision();
+  }
+
+  function startStreaming(id: string, msg: InFlightMessage) {
+    streaming.set(id, msg);
+    const entry: StreamingEntry = {
+      kind: "streaming",
+      id,
+      msg,
+      arrivalIdx: nextIdx(),
+    };
+    messages.set([...messages.get(), entry]);
+    activeStreamId.set(id);
+  }
+
+  function bumpStreaming(id: string) {
+    // Per-token rebump. Replace just the streaming entry's identity so
+    // subscribers re-render — the streaming entry always lives at the
+    // tail (we never push frames after a stream starts until message_stop)
+    // so we can mutate the array in place rather than scan with .map.
+    const msg = streaming.get(id);
+    if (!msg) return;
+    const arr = messages.get();
+    const last = arr.length - 1;
+    if (last < 0) return;
+    const tail = arr[last];
+    if (tail?.kind !== "streaming" || tail.id !== id) {
+      const idx = arr.findIndex((e) => e.kind === "streaming" && e.id === id);
+      if (idx === -1) return;
+      const next = arr.slice();
+      next[idx] = { ...arr[idx]!, msg: { ...msg } } as StreamingEntry;
+      messages.set(next);
+      return;
+    }
+    const next = arr.slice();
+    next[last] = { ...tail, msg: { ...msg } };
+    messages.set(next);
+  }
+
+  function dropStreaming(id: string) {
+    streaming.delete(id);
+    if (activeStreamId.get() === id) activeStreamId.set(null);
+    messages.set(messages.get().filter((e) => !(e.kind === "streaming" && e.id === id)));
+    bumpRevision();
+  }
+
+  function applyStreamEvent(ev: StreamEvent) {
+    if (ev.type === "message_start" && ev.message?.id) {
+      const id = ev.message.id;
+      const msg: InFlightMessage = {
+        id,
+        role: "assistant",
+        model: ev.message.model,
+        content: [],
+        done: false,
+        arrivalIdx: arrivalCounter,
+      };
+      startStreaming(id, msg);
+      return;
+    }
+    if (ev.type === "content_block_start") {
+      const id = activeStreamId.get();
+      const msg = id ? streaming.get(id) : null;
+      if (!msg) return;
+      const cb = ev.content_block ?? {};
+      let block: StreamingBlock;
+      if (cb.type === "tool_use") {
+        block = {
+          type: "tool_use",
+          id: cb.id ?? "",
+          name: cb.name ?? "",
+          input: cb.input ?? {},
+          _partialJson: "",
+          _parsed: false,
+        };
+      } else if (cb.type === "thinking") {
+        block = { type: "thinking", thinking: cb.thinking ?? "" };
+      } else {
+        block = { type: "text", text: cb.text ?? "" };
+      }
+      msg.content[ev.index] = block;
+      bumpStreaming(id!);
+      return;
+    }
+    if (ev.type === "content_block_delta") {
+      const id = activeStreamId.get();
+      const msg = id ? streaming.get(id) : null;
+      if (!msg) return;
+      const block = msg.content[ev.index];
+      const delta = ev.delta ?? {};
+      if (block?.type === "text" && delta.type === "text_delta" && typeof delta.text === "string") {
+        block.text += delta.text;
+      } else if (
+        block?.type === "tool_use" &&
+        delta.type === "input_json_delta" &&
+        typeof delta.partial_json === "string"
+      ) {
+        block._partialJson += delta.partial_json;
+      } else if (
+        block?.type === "thinking" &&
+        delta.type === "thinking_delta" &&
+        typeof delta.thinking === "string"
+      ) {
+        block.thinking += delta.thinking;
+      }
+      bumpStreaming(id!);
+      return;
+    }
+    if (ev.type === "content_block_stop") {
+      const id = activeStreamId.get();
+      const msg = id ? streaming.get(id) : null;
+      if (!msg) return;
+      const block = msg.content[ev.index];
+      if (block?.type === "tool_use" && !block._parsed) {
+        if (block._partialJson) {
+          try {
+            block.input = JSON.parse(block._partialJson);
+            block._parsed = true;
+          } catch (err) {
+            console.warn("[stream_event] tool_use partial_json parse failed", err, block._partialJson);
+          }
+        } else {
+          block._parsed = true;
+        }
+      }
+      bumpStreaming(id!);
+      return;
+    }
+    if (ev.type === "message_stop") {
+      const id = activeStreamId.get();
+      const msg = id ? streaming.get(id) : null;
+      if (msg) msg.done = true;
+      if (id) bumpStreaming(id);
+    }
+  }
+
+  function ingest(frame: InboundFrame): boolean {
+    if (!("type" in frame)) return false;
+    // Streaming deltas: consume and never append the raw frame.
+    if (frame.type === "stream_event" && frame.event) {
+      applyStreamEvent(frame.event);
+      return true;
+    }
+    // Canonical assistant envelope: drop any matching streaming reconstruction
+    // (the envelope is authoritative), then append the frame.
+    if (frame.type === "assistant" && frame.message?.id) {
+      const id = frame.message.id;
+      if (streaming.has(id)) dropStreaming(id);
+      pushFrame(frame);
+      return true;
+    }
+    return false;
+  }
+
+  function hydrate(entries: MessageEntry[]) {
+    streaming.clear();
+    activeStreamId.set(null);
+    const filtered = entries.filter(
+      (e): e is LocalUserEntry | FrameEntry => e.kind === "frame" || e.kind === "local_user",
+    );
+    // Reseat arrivalCounter past the last hydrated entry so subsequent
+    // pushes don't collide with restored ids in render order.
+    arrivalCounter = filtered.length > 0
+      ? Math.max(...filtered.map((e) => e.arrivalIdx)) + 1
+      : 0;
+    messages.set(filtered);
+    bumpRevision();
+  }
+
+  function reset() {
+    streaming.clear();
+    activeStreamId.set(null);
+    messages.set([]);
+    arrivalCounter = 0;
+    bumpRevision();
+  }
+
+  return {
+    messages,
+    activeStreamId,
+    revision,
+    pushLocalUser,
+    pushFrame,
+    ingest,
+    reset,
+    hydrate,
+  };
+}

package/src/modes.ts

@@ -0,0 +1,68 @@
+// Single source of truth for permission modes / models / efforts. Mirrors the
+// canonical order found in the Claude Code v2.1.132 binary (see
+// apps/slopbox/.spec/artifacts/extracted/canonical.json — PermissionMode +
+// EffortLevel enums; getNextPermissionMode for cycle order).
+
+export const PERMISSION_MODE_DEFS = [
+  { value: "default",           label: "Default (ask)",                 inCycle: true  },
+  { value: "acceptEdits",       label: "Auto-accept edits",             inCycle: true  },
+  { value: "plan",              label: "Plan mode (no tool execution)", inCycle: true  },
+  { value: "bypassPermissions", label: "Bypass all (dangerous)",        inCycle: true  },
+  { value: "auto",              label: "Auto (classifier)",             inCycle: true  },
+  { value: "dontAsk",           label: "Don't ask",                     inCycle: false },
+] as const;
+
+export type PermissionMode = (typeof PERMISSION_MODE_DEFS)[number]["value"];
+
+export const PERMISSION_MODE_OPTIONS: { value: PermissionMode; label: string }[] =
+  PERMISSION_MODE_DEFS.map((m) => ({ value: m.value, label: m.label }));
+
+export const KNOWN_PERMISSION_MODES: readonly PermissionMode[] =
+  PERMISSION_MODE_DEFS.map((m) => m.value);
+
+export const CYCLE_ORDER: readonly PermissionMode[] = PERMISSION_MODE_DEFS
+  .filter((m) => m.inCycle)
+  .map((m) => m.value);
+
+export function nextCycleMode(current: PermissionMode): PermissionMode {
+  const idx = CYCLE_ORDER.indexOf(current);
+  if (idx === -1) return "default";
+  return CYCLE_ORDER[(idx + 1) % CYCLE_ORDER.length]!;
+}
+
+// Models the binary advertises. set_model takes the value verbatim; the
+// binary resolves aliases. Display order = array order.
+export const MODEL_DEFS = [
+  { value: "claude-opus-4-7",       label: "Opus 4.7" },
+  { value: "claude-opus-4-7[1m]",   label: "Opus 4.7 (1M)" },
+  { value: "claude-opus-4-6",       label: "Opus 4.6" },
+  { value: "claude-opus-4-6[1m]",   label: "Opus 4.6 (1M)" },
+  { value: "claude-sonnet-4-6",     label: "Sonnet 4.6" },
+  { value: "claude-sonnet-4-5",     label: "Sonnet 4.5" },
+  { value: "claude-sonnet-4-5[1m]", label: "Sonnet 4.5 (1M)" },
+  { value: "claude-haiku-4-5",      label: "Haiku 4.5" },
+] as const;
+
+export type Model = (typeof MODEL_DEFS)[number]["value"];
+
+export const MODEL_OPTIONS: { value: Model; label: string }[] =
+  MODEL_DEFS.map((m) => ({ value: m.value, label: m.label }));
+
+export const KNOWN_MODELS: readonly Model[] = MODEL_DEFS.map((m) => m.value);
+
+// Effort levels accepted by --effort. No set_effort control_request exists,
+// so changing effort mid-session triggers a respawn.
+export const EFFORT_DEFS = [
+  { value: "low",    label: "Low" },
+  { value: "medium", label: "Medium" },
+  { value: "high",   label: "High" },
+  { value: "xhigh",  label: "xHigh" },
+  { value: "max",    label: "Max" },
+] as const;
+
+export type Effort = (typeof EFFORT_DEFS)[number]["value"];
+
+export const EFFORT_OPTIONS: { value: Effort; label: string }[] =
+  EFFORT_DEFS.map((e) => ({ value: e.value, label: e.label }));
+
+export const KNOWN_EFFORTS: readonly Effort[] = EFFORT_DEFS.map((e) => e.value);