@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.100

package/src/thread/tree-view.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import {
+  appendEntry,
+  createBranch,
+  historyFromLinear,
+  labelTip,
+  navigateTo,
+  switchBranch,
+  tipOf,
+  type SessionHistory,
+} from "@cueloop/schema";
+import { entryTarget, treeRows } from "./tree-view";
+
+const AT = "2026-09-01T10:00:00.000Z";
+const LATER = "2026-09-01T11:00:00.000Z";
+
+/** rev1 -> comment a1 on main; a branch "alt" off a1 with its own comment; main continues with rev2. */
+function forked(): SessionHistory {
+  let history = historyFromLinear({
+    id: "ses_1",
+    revisions: [{ revision: 1, content: "v1", submittedAt: AT }],
+    annotations: [],
+    message: null,
+    createdAt: AT,
+  });
+
+  history = appendEntry(history, { type: "comment", annotationId: "a1", createdAt: AT }).history;
+  history = labelTip(history, "start");
+  history = createBranch(history, "alt");
+  history = appendEntry(history, { type: "comment", annotationId: "b1", createdAt: AT }).history;
+  history = switchBranch(history, "main");
+  history = appendEntry(history, {
+    type: "revision",
+    by: "agent",
+    content: "v2",
+    createdAt: LATER,
+  }).history;
+
+  return history;
+}
+
+describe("treeRows", () => {
+  test("the current branch is the trunk; other segments indent under the entry they grew from", () => {
+    // Act
+    const rows = treeRows(forked());
+
+    // Assert: rev1, a1 (labelled, alt hangs off it), the alt comment indented, then rev2 as main's tip
+    expect(rows.map((row) => [row.depth, row.text, row.onPath])).toEqual([
+      [0, "revision 1", true],
+      [0, "comment", true],
+      [1, "comment", false],
+      [0, "revision 2", true],
+    ]);
+    expect(rows[1]!.label).toBe("start");
+    expect(rows[2]!.tips).toEqual(["alt"]);
+    expect(rows[3]!.tips).toEqual(["main"]);
+    expect(rows[3]!.isCurrentTip).toBe(true);
+  });
+
+  test("on the other branch the trunk follows it and main's continuation indents", () => {
+    // Act
+    const rows = treeRows(switchBranch(forked(), "alt"));
+
+    // Assert
+    expect(rows.map((row) => [row.depth, row.text, row.onPath])).toEqual([
+      [0, "revision 1", true],
+      [0, "comment", true],
+      [1, "revision 2", false],
+      [0, "comment", true],
+    ]);
+    expect(rows[3]!.isCurrentTip).toBe(true);
+  });
+
+  test("a branch summary reads as a return with its text", () => {
+    // Arrange
+    const history = navigateTo(forked(), forked().entries[0]!.id, { summary: "too early" });
+
+    // Act
+    const rows = treeRows(history);
+
+    // Assert: the summary hangs under rev1 as the trunk, the abandoned segment indents
+    expect(rows.find((row) => row.glyph === "↩")?.text).toBe('"too early"');
+    expect(rows.find((row) => row.glyph === "↩")?.isCurrentTip).toBe(true);
+  });
+});
+
+describe("entryTarget", () => {
+  test("the tip is here, another tip is a switch, an ancestor is a navigate on its branch", () => {
+    // Arrange
+    const history = forked();
+    const [rev1, a1, altComment, rev2] = history.entries;
+
+    // Assert
+    expect(entryTarget(history, rev2!.id)).toEqual({ kind: "here" });
+    expect(entryTarget(history, altComment!.id)).toEqual({ kind: "switch", branch: "alt" });
+    expect(entryTarget(history, a1!.id)).toEqual({
+      kind: "navigate",
+      entryId: a1!.id,
+      branch: "main",
+    });
+    expect(entryTarget(history, rev1!.id)?.kind).toBe("navigate");
+    expect(tipOf(history)).toBe(rev2!.id);
+  });
+
+  test("an entry only another branch reaches is a navigate on that branch", () => {
+    // Arrange: alt gets a second comment so its first is no longer a tip
+    let history = switchBranch(forked(), "alt");
+
+    history = appendEntry(history, {
+      type: "comment",
+      annotationId: "b2",
+      createdAt: LATER,
+    }).history;
+    const altFirst = history.entries.find(
+      (entry) => entry.type === "comment" && entry.annotationId === "b1",
+    )!;
+
+    history = switchBranch(history, "main");
+
+    // Assert
+    expect(entryTarget(history, altFirst.id)).toEqual({
+      kind: "navigate",
+      entryId: altFirst.id,
+      branch: "alt",
+    });
+    expect(entryTarget(history, "e_nope")).toBeNull();
+  });
+});

package/src/thread/tree-view.ts

@@ -0,0 +1,146 @@
+/**
+ * The session tree as rows for the rail's Tree tab. The trunk is the current
+ * branch's path (falling back to main), drawn at depth 0; every other segment
+ * indents under the entry it grew from. Rows know whether they sit on the
+ * active path, which branch tips rest on them, and the checkpoint name they
+ * carry, so the pane only paints. Pure: no controller, no daemon.
+ */
+
+import {
+  MAIN_BRANCH,
+  pathOf,
+  tipOf,
+  type SessionEntry,
+  type SessionHistory,
+} from "@cueloop/schema";
+
+export interface TreeRow {
+  entryId: string;
+  depth: number;
+  glyph: string;
+  text: string;
+  onPath: boolean;
+  tips: string[];
+  isCurrentTip: boolean;
+  label?: string;
+}
+
+/** What going to an entry means from where the reviewer stands. */
+export type EntryTarget =
+  | { kind: "here" }
+  | { kind: "switch"; branch: string }
+  | { kind: "navigate"; entryId: string; branch: string };
+
+/** The one-glyph, few-words reading of an entry a row shows. */
+export interface EntryDescription {
+  glyph: string;
+  text: string;
+}
+
+/** The entry's kind, said briefly; agent revisions count their round along the path. */
+export function describeEntry(entry: SessionEntry, round?: number): EntryDescription {
+  switch (entry.type) {
+    case "revision":
+      return entry.by === "agent"
+        ? { glyph: "◉", text: round === undefined ? "revision" : `revision ${round}` }
+        : { glyph: "○", text: "edit" };
+    case "comment":
+      return { glyph: "·", text: "comment" };
+    case "comment-removed":
+      return { glyph: "·", text: "comment removed" };
+    case "message":
+      return {
+        glyph:
+          entry.message.outcome === "approved"
+            ? "✓"
+            : entry.message.outcome === "changes_requested"
+              ? "✗"
+              : "·",
+        text: entry.message.outcome.replace("_", " "),
+      };
+    case "branch-summary":
+      return { glyph: "↩", text: entry.text ? `"${entry.text}"` : "returned" };
+  }
+}
+
+/** Rows in drawing order: trunk first at each fork, older segments before newer. */
+export function treeRows(history: SessionHistory): TreeRow[] {
+  const children = new Map<string | null, SessionEntry[]>();
+
+  for (const entry of history.entries) {
+    const siblings = children.get(entry.parentId) ?? [];
+
+    siblings.push(entry);
+    children.set(entry.parentId, siblings);
+  }
+  for (const siblings of children.values()) {
+    siblings.sort(
+      (left, right) =>
+        left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+    );
+  }
+  const onPath = new Set(pathOf(history).map((entry) => entry.id));
+  const onMain = new Set(pathOf(history, tipOf(history, MAIN_BRANCH)).map((entry) => entry.id));
+  const tipsByEntry = new Map<string, string[]>();
+
+  for (const [branch, tip] of Object.entries(history.tips)) {
+    tipsByEntry.set(tip, [...(tipsByEntry.get(tip) ?? []), branch]);
+  }
+  const currentTip = tipOf(history);
+  const rows: TreeRow[] = [];
+  // the trunk continues through the child on the active path, else on main, else the oldest
+  const trunkChild = (siblings: SessionEntry[]): SessionEntry =>
+    siblings.find((entry) => onPath.has(entry.id)) ??
+    siblings.find((entry) => onMain.has(entry.id)) ??
+    siblings[0]!;
+  const walk = (entry: SessionEntry, depth: number, round: number): void => {
+    const nextRound = entry.type === "revision" && entry.by === "agent" ? round + 1 : round;
+    const described = describeEntry(
+      entry,
+      entry.type === "revision" && entry.by === "agent" ? nextRound : undefined,
+    );
+    const label = history.labels[entry.id];
+    const row: TreeRow = {
+      entryId: entry.id,
+      depth,
+      glyph: described.glyph,
+      text: described.text,
+      onPath: onPath.has(entry.id),
+      tips: tipsByEntry.get(entry.id) ?? [],
+      isCurrentTip: entry.id === currentTip,
+    };
+
+    if (label !== undefined) row.label = label;
+    rows.push(row);
+    const siblings = children.get(entry.id) ?? [];
+
+    if (siblings.length === 0) return;
+    const trunk = trunkChild(siblings);
+
+    for (const child of siblings) if (child !== trunk) walk(child, depth + 1, nextRound);
+    walk(trunk, depth, nextRound);
+  };
+
+  for (const root of children.get(null) ?? []) walk(root, 0, 0);
+
+  return rows;
+}
+
+/**
+ * Going to an entry: nothing when it is the current tip; a switch when it is
+ * another branch's tip; otherwise a navigate on the branch whose path holds
+ * it - the current branch when it can, else the first branch that reaches it.
+ */
+export function entryTarget(history: SessionHistory, entryId: string): EntryTarget | null {
+  if (entryId === tipOf(history)) return { kind: "here" };
+  const tipBranch = Object.entries(history.tips).find(([, tip]) => tip === entryId);
+
+  if (tipBranch) return { kind: "switch", branch: tipBranch[0] };
+  const holds = (branch: string): boolean =>
+    pathOf(history, tipOf(history, branch)).some((entry) => entry.id === entryId);
+  const branch = holds(history.branch)
+    ? history.branch
+    : Object.keys(history.tips).find((candidate) => holds(candidate));
+
+  return branch === undefined ? null : { kind: "navigate", entryId, branch };
+}

package/src/thread/use-thread-agent.test.tsx

@@ -0,0 +1,208 @@
+import React, { useEffect } from "react";
+import { expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import type { ThreadAgentState } from "@cueloop/schema";
+import { useThreadAgent, type ThreadAgentClient } from "./use-thread-agent";
+import { waitForText, settle } from "../testing/test-support";
+
+const initial: ThreadAgentState = {
+  threadId: "test",
+  phase: { kind: "idle" },
+  messages: [],
+  tools: [],
+  comments: [],
+};
+
+test("late configuration and action responses cannot replace a newer accepted state", async () => {
+  let state = initial;
+  let configure: ((value: ThreadAgentState) => void) | undefined;
+  let first: ((value: ThreadAgentState) => void) | undefined;
+  let request = async () => false;
+  let calls = 0;
+  const client: ThreadAgentClient = {
+    agentGet: async () => state,
+    agentConfigure: async () =>
+      new Promise((resolve) => {
+        configure = resolve;
+      }),
+    agentPrompt: async () => {
+      if (++calls === 1)
+        return new Promise((resolve) => {
+          first = resolve;
+        });
+      state = { ...initial, phase: { kind: "running" } };
+
+      return state;
+    },
+    agentCancel: async () => state,
+    agentComment: async () => state,
+    agentPermission: async () => state,
+  };
+
+  function TestAgent(): React.ReactNode {
+    const agent = useThreadAgent("test", undefined, client);
+
+    useEffect(() => {
+      request = () => agent.act((api) => api.agentPrompt({ id: "test", text: "Prompt" }));
+    }, [agent]);
+
+    return <text>{agent.state.phase.kind}</text>;
+  }
+  const setup = await testRender(<TestAgent />, { width: 40, height: 4 });
+
+  try {
+    await waitForText(setup, "idle");
+    const pending = request();
+
+    await request();
+    await waitForText(setup, "running");
+    first!(initial);
+    await pending;
+    configure!(initial);
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("running");
+    expect(setup.captureCharFrame()).not.toContain("idle");
+  } finally {
+    setup.renderer.destroy();
+  }
+});
+
+test("production subscription shows daemon updates and reconnects without an injected client", async () => {
+  const { mkdtempSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { DaemonServer } = await import("@cueloop/daemon");
+  const { DaemonClient } = await import("@cueloop/daemon/client");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-agent-ui-subscription-"));
+  const adapter = {
+    id: "ui-subscription",
+    label: "UI subscription",
+    connect({ onEvent }: Parameters<import("@cueloop/schema").AgentHarnessAdapter["connect"]>[0]) {
+      return {
+        start: async () => "ui-session",
+        prompt: async () => {
+          onEvent({ kind: "message" as const, id: "answer", text: "Updated answer" });
+
+          return { outcome: "completed" as const };
+        },
+        cancel() {},
+        permission() {},
+        close() {},
+      };
+    },
+  };
+  const options = { home, idleExitMs: 0, threadAgent: { enabled: true, adapter } };
+  let server = new DaemonServer(options);
+
+  server.start();
+  const client = await DaemonClient.connect({ home });
+  const thread = await client.sessionCreate(
+    { repoRoot: home, branch: "main" },
+    { type: "plan", content: "Watch this", meta: {} },
+  );
+
+  function TestAgentSubscription(): React.ReactNode {
+    const agent = useThreadAgent(thread.id, home);
+
+    return (
+      <text>
+        {agent.client ? "Connected " : "Connecting "}
+        {agent.state.messages.map((message) => message.text).join(" ")}
+        {agent.error}
+      </text>
+    );
+  }
+  const setup = await testRender(<TestAgentSubscription />, { width: 80, height: 4 });
+
+  try {
+    await waitForText(setup, "Connected");
+    await client.agentPrompt({ id: thread.id, text: "Question" });
+    await waitForText(setup, "Updated answer");
+    server.stop();
+    server = new DaemonServer(options);
+    server.start();
+    const resumed = await DaemonClient.connect({ home });
+
+    try {
+      await resumed.agentPrompt({ id: thread.id, text: "Continuation" });
+    } finally {
+      resumed.close();
+    }
+    await waitForText(setup, "Continuation");
+    expect(setup.captureCharFrame()).toContain("Updated answer");
+  } finally {
+    setup.renderer.destroy();
+    client.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("reconnecting during a running turn preserves state without a configuration error", async () => {
+  const { mkdtempSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { DaemonServer } = await import("@cueloop/daemon");
+  const { DaemonClient } = await import("@cueloop/daemon/client");
+  const { createTestSdkHarness } = await import("../../../../test/helpers/sdk-harness");
+  const home = mkdtempSync(join(tmpdir(), "cueloop-agent-ui-running-"));
+  const harness = createTestSdkHarness();
+  const server = new DaemonServer({
+    home,
+    idleExitMs: 0,
+    threadAgent: { enabled: true, adapter: harness.adapter },
+  });
+
+  server.start();
+  const client = await DaemonClient.connect({ home });
+  const thread = await client.sessionCreate(
+    { repoRoot: home, branch: "main" },
+    { type: "plan", content: "Watch this", meta: {} },
+  );
+  let connection: InstanceType<typeof DaemonClient> | undefined;
+  let connections = 0;
+
+  function TestRunningSubscription(): React.ReactNode {
+    const agent = useThreadAgent(thread.id, home);
+
+    useEffect(() => {
+      if (agent.client instanceof DaemonClient && agent.client !== connection) {
+        connection = agent.client;
+        connections++;
+      }
+    }, [agent.client]);
+
+    return (
+      <text>
+        {connections} {agent.state.phase.kind} {agent.error || "No error"}
+      </text>
+    );
+  }
+  const setup = await testRender(<TestRunningSubscription />, { width: 100, height: 4 });
+
+  try {
+    await waitForText(setup, "idle");
+    await client.agentPrompt({ id: thread.id, text: "Question" });
+    await waitForText(setup, "running");
+    expect((await client.agentConfigure({ id: thread.id })).phase.kind).toBe("running");
+    const rejected = await client
+      .agentConfigure({ id: thread.id, configId: "model", value: "other" })
+      .catch((error: Error) => error);
+
+    expect(rejected).toMatchObject({
+      code: "internal",
+      message: "Thread agent configuration waits for the current turn",
+    });
+    connection!.close();
+    await waitForText(setup, "2 running");
+    harness.complete();
+    await waitForText(setup, "2 idle");
+    expect(setup.captureCharFrame()).toContain("No error");
+    expect(setup.captureCharFrame()).not.toContain("configuration waits");
+  } finally {
+    setup.renderer.destroy();
+    client.close();
+    server.stop();
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/thread/use-thread-agent.ts

@@ -0,0 +1,111 @@
+import { useEffect, useRef, useState } from "react";
+import { subscribeThreadState, connectThreadObserver } from "@cueloop/daemon/thread-subscription";
+import { DaemonClient } from "@cueloop/daemon/client";
+import type { ThreadAgentState } from "@cueloop/schema";
+
+/** Agent transport is injectable for frame tests; production uses the daemon socket. */
+export type ThreadAgentClient = Pick<
+  DaemonClient,
+  "agentGet" | "agentPrompt" | "agentCancel" | "agentComment" | "agentPermission"
+> &
+  Partial<Pick<DaemonClient, "agentConfigure">>;
+
+/** Subscribe to durable agent state; unmount closes only this client connection. */
+export function useThreadAgent(id: string, home?: string, injected?: ThreadAgentClient) {
+  const [client, setClient] = useState<ThreadAgentClient | null>(injected ?? null);
+  const [state, setState] = useState<ThreadAgentState>({
+    threadId: id,
+    phase: { kind: "idle" },
+    messages: [],
+    tools: [],
+    comments: [],
+  });
+  const revision = useRef(0);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    let cancelled = false;
+    let connection: DaemonClient | undefined;
+    let unsubscribe: (() => void) | undefined;
+
+    revision.current++;
+    const refresh = async (api: ThreadAgentClient) => {
+      const requested = ++revision.current;
+      const result = await api.agentGet(id);
+
+      if (!cancelled && requested === revision.current) setState(result);
+    };
+
+    const configure = async (api: ThreadAgentClient): Promise<void> => {
+      if (!api.agentConfigure) return;
+      const requested = ++revision.current;
+      const configured = await api.agentConfigure({ id });
+
+      if (!cancelled && requested === revision.current) setState(configured);
+      await refresh(api);
+    };
+
+    void (async () => {
+      try {
+        if (injected) {
+          await refresh(injected);
+          await configure(injected);
+
+          return;
+        }
+        unsubscribe = subscribeThreadState({
+          connect: connectThreadObserver({ home, autostart: true }),
+          matches: (event) => event.event === "agent.updated" && event.sessionId === id,
+          read: async (api, signal) => {
+            const requested = ++revision.current;
+            const state = await api.agentGet(id, { signal });
+
+            return { state, requested };
+          },
+          onConnect: (api) => {
+            connection = api;
+            setClient(api);
+            void configure(api).catch((error) => {
+              if (!cancelled) setError(String(error));
+            });
+          },
+          onValue: ({ state, requested }) => {
+            if (!cancelled && requested === revision.current) setState(state);
+          },
+          onError: (error) => {
+            if (!cancelled) setError(String(error));
+          },
+        });
+      } catch (error) {
+        if (!cancelled) setError(error instanceof Error ? error.message : String(error));
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      unsubscribe?.();
+      connection?.close();
+    };
+  }, [id, home, injected]);
+
+  const act = async (
+    request: (client: ThreadAgentClient) => Promise<ThreadAgentState>,
+  ): Promise<boolean> => {
+    if (!client) return false;
+    try {
+      const requested = ++revision.current;
+      const result = await request(client);
+
+      if (requested === revision.current) setState(result);
+      setError("");
+
+      return true;
+    } catch (error) {
+      setError(error instanceof Error ? error.message : String(error));
+
+      return false;
+    }
+  };
+
+  return { state, client, error, setError, act };
+}

package/src/ui/components/CodeBlock.stories.tsx

@@ -0,0 +1,42 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { CodeBlock } from "./CodeBlock";
+
+export const meta: StoryMeta = { title: "Primitives/CodeBlock" };
+
+const SNIPPET = `export function gate(full: number) {
+  // threshold
+  return full < 0.6 ? "blocked" : "clear";
+}`;
+
+export const Typescript: Story = {
+  render: () => <CodeBlock language="ts" content={SNIPPET} />,
+  expectedColors: [DARK.elevated],
+};
+
+export const CursorAnnotatedEdited: Story = {
+  render: () => (
+    <CodeBlock
+      language="ts"
+      content={SNIPPET}
+      isCursor
+      isAnnotated
+      changeTag="edited"
+      marginTop={1}
+    />
+  ),
+  expectedColors: [DARK.accent],
+};
+
+export const UnknownLanguage: Story = {
+  render: () => (
+    <CodeBlock language="brainfog" content={"plain verbatim lines\n  with indentation"} />
+  ),
+};
+
+/** A cut code block: struck-through gray content, no [cut] tag. */
+export const Cut: Story = {
+  render: () => <CodeBlock language="ts" content={SNIPPET} cut />,
+  expectedColors: [DARK.elevated],
+};