@cueloop/client 0.1.0-alpha.101 → 0.1.0-alpha.103

package/src/settings/use-thread-harness-setting.test.tsx

@@ -0,0 +1,87 @@
+import { expect, test } from "bun:test";
+import React, { useState } from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { ThreadAgentClient } from "../thread/use-thread-agent";
+import type { ThreadAgentState } from "@cueloop/schema";
+import { clickText, isolateUserConfig, waitForText } from "../testing/test-support";
+import { useThreadHarnessSetting } from "./use-thread-harness-setting";
+
+function TestHarnessSwitchQueue({ client }: { client: ThreadAgentClient }) {
+  const [preferred, setPreferred] = useState("pending");
+  const setting = useThreadHarnessSetting({
+    thread: { id: "switch-queue" },
+    enabled: true,
+    owner: true,
+    preferred: "pi",
+    client,
+    onState() {},
+    onPreferred: setPreferred,
+    onError: (message) => setPreferred(message),
+  });
+
+  return (
+    <box>
+      <text onMouseDown={() => setting.switchHarness("fx")}>Select fx</text>
+      <text onMouseDown={() => setting.switchHarness("pi")}>Select pi</text>
+      <text>Preference: {preferred}</text>
+    </box>
+  );
+}
+
+test("a delayed switch cannot overtake the latest click or persist an older preference", async () => {
+  const home = mkdtempSync(join(tmpdir(), "cueloop-switch-queue-"));
+  const restore = isolateUserConfig(home);
+  const started = Promise.withResolvers<void>();
+  const release = Promise.withResolvers<void>();
+  const calls: string[] = [];
+  const state: ThreadAgentState = {
+    threadId: "switch-queue",
+    phase: { kind: "idle" },
+    messages: [],
+    comments: [],
+    tools: [],
+  };
+  const setup = await testRender(
+    <TestHarnessSwitchQueue
+      client={{
+        agentGet: async () => state,
+        agentPrompt: async () => state,
+        agentCancel: async () => state,
+        agentComment: async () => state,
+        agentPermission: async () => state,
+        async agentConfigure(params) {
+          calls.push(params.value!);
+
+          if (calls.length === 1) {
+            started.resolve();
+            await release.promise;
+          }
+
+          return state;
+        },
+      }}
+    />,
+    { width: 60, height: 10 },
+  );
+
+  try {
+    await waitForText(setup, "Select fx");
+    await clickText(setup, "Select fx");
+    await started.promise;
+    await clickText(setup, "Select pi");
+    await clickText(setup, "Select fx");
+    await clickText(setup, "Select pi");
+    expect(calls).toEqual(["fx"]);
+    release.resolve();
+    await waitForText(setup, "Preference: pi");
+    expect(calls).toEqual(["fx", "pi"]);
+  } finally {
+    release.resolve();
+    setup.renderer.destroy();
+    restore();
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/settings/use-thread-harness-setting.ts

@@ -0,0 +1,86 @@
+import { useRef, useEffect } from "react";
+import { DaemonClient } from "@cueloop/daemon/client";
+import type { ThreadAgentState, Thread } from "@cueloop/schema";
+import type { ThreadAgentClient } from "../thread/use-thread-agent";
+import { persistThreadHarness } from "./config";
+
+interface ThreadHarnessSettingOptions {
+  home?: string;
+  thread?: Pick<Thread, "id"> | null;
+  enabled: boolean;
+  owner: boolean;
+  state?: ThreadAgentState;
+  preferred: "pi" | "fx";
+  client?: ThreadAgentClient;
+  onState: (state: ThreadAgentState) => void;
+  onPreferred: (harness: "pi" | "fx") => void;
+  onError: (message: string) => void;
+}
+
+/** Preferences apply to new Threads; a bound Thread switches through the owner's daemon. */
+export function useThreadHarnessSetting(options: ThreadHarnessSettingOptions) {
+  const latest = useRef(options);
+  const generation = useRef(0);
+  const pending = useRef(Promise.resolve());
+
+  useEffect(() => {
+    latest.current = options;
+  });
+  const threadId = options.thread?.id;
+  const current = options.state?.threadId === threadId ? options.state : undefined;
+  const selected =
+    current?.handoff?.requestedTarget ??
+    current?.handoff?.target ??
+    current?.harness?.id ??
+    options.preferred;
+
+  return {
+    enabled: options.enabled && options.owner,
+    harness: selected === "fx" ? ("fx" as const) : ("pi" as const),
+    switchHarness(harness: "pi" | "fx") {
+      const request = latest.current;
+      const requestedId = request.thread?.id;
+
+      if (!request.enabled || !request.owner) return;
+
+      const requestedGeneration = ++generation.current;
+
+      pending.current = pending.current.then(async () => {
+        if (generation.current !== requestedGeneration) return;
+
+        let connection: DaemonClient | undefined;
+
+        try {
+          if (requestedId) {
+            const api =
+              request.client ??
+              (connection = await DaemonClient.connect({ home: request.home, autostart: true }));
+
+            if (generation.current !== requestedGeneration) return;
+
+            if (!api.agentConfigure) throw new Error("Thread harness switching is unavailable");
+
+            const state = await api.agentConfigure({
+              id: requestedId,
+              configId: "harness",
+              value: harness,
+            });
+
+            if (generation.current !== requestedGeneration) return;
+
+            if (latest.current.thread?.id === requestedId) latest.current.onState(state);
+          }
+
+          persistThreadHarness(harness);
+          latest.current.onPreferred(harness);
+        } catch (failure) {
+          if (generation.current !== requestedGeneration) return;
+
+          latest.current.onError(failure instanceof Error ? failure.message : String(failure));
+        } finally {
+          connection?.close();
+        }
+      });
+    },
+  };
+}

package/src/stories/stories.test.tsx

@@ -18,6 +18,7 @@ const stories = await loadStories();
 /** Hex of a painted color; undefined for unpainted (transparent) spans. */
 function hexOf(color: RGBA | null | undefined): string | undefined {
   if (!color) return undefined;
+
   const [red, green, blue] = color.toInts();
 
   return "#" + [red, green, blue].map((part) => part!.toString(16).padStart(2, "0")).join("");
@@ -52,6 +53,7 @@ describe("stories catalog", () => {
 
       // Assert
       expect(frame).toMatchSnapshot(`${moduleTitle}/${storyName}`);
+
       if (story.expectedColors?.length) {
         const seenColors = new Set<string>();
 
@@ -61,6 +63,7 @@ describe("stories catalog", () => {
             const backgroundHex = hexOf(span.bg);
 
             if (foregroundHex) seenColors.add(foregroundHex);
+
             if (backgroundHex) seenColors.add(backgroundHex);
           }
         }
@@ -68,6 +71,7 @@ describe("stories catalog", () => {
           expect(seenColors).toContain(expectedColor.toLowerCase());
         }
       }
+
       setup.renderer.destroy();
     });
   }

package/src/stories/story.ts

@@ -65,6 +65,7 @@ async function collectStories(
 
     for (const [exportName, exported] of Object.entries(moduleExports)) {
       if (exportName === "meta" || !isStory(exported)) continue;
+
       loaded.push({ section, moduleTitle, storyName: exportName, story: exported });
     }
   }
@@ -88,6 +89,7 @@ interface StoryTreeFolder extends TreeNode {
 function hoistSingleStoryFolders(nodes: TreeNode[]): TreeNode[] {
   return nodes.map((node) => {
     if (node.children === undefined) return node;
+
     const children = hoistSingleStoryFolders(node.children);
     const onlyChild = children.length === 1 ? children[0] : undefined;
 
@@ -126,6 +128,7 @@ export function buildStoryTree(stories: LoadedStory[]): TreeNode[] {
         foldersByPath.set(path, folder);
         siblings.push(folder);
       }
+
       siblings = folder.children;
     }
 
@@ -143,8 +146,11 @@ export function componentFilesMissingStories(): string[] {
 
   for (const file of files) {
     if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+
     if (file.endsWith(".prototype.tsx")) continue;
+
     if (file === "stories-app.tsx") continue;
+
     const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
 
     if (!files.includes(storiesSibling)) missing.push(file);

package/src/terminal/ansi-screen.ts

@@ -12,6 +12,7 @@ export function ansiScreenToLines(ansi: string, cols: number, rows: number): str
 
   const put = (character: string): void => {
     if (row >= 0 && row < rows && column >= 0 && column < cols) grid[row]![column] = character;
+
     column += 1;
   };
 
@@ -31,6 +32,7 @@ export function ansiScreenToLines(ansi: string, cols: number, rows: number): str
       });
       continue;
     }
+
     if (character === "\n") {
       row += 1;
       column = 0;
@@ -39,6 +41,7 @@ export function ansiScreenToLines(ansi: string, cols: number, rows: number): str
     } else {
       put(character);
     }
+
     index += 1;
   }
 
@@ -53,7 +56,9 @@ function consumeEscape(ansi: string, start: number, apply: EscapeEffect): number
 
     return bell === -1 ? ansi.length : bell + 1;
   }
+
   if (ansi.slice(start, start + CSI.length) !== CSI) return start + 1;
+
   let index = start + CSI.length;
 
   while (index < ansi.length && !/[A-Za-z]/.test(ansi[index]!)) index += 1;

package/src/terminal/components/terminal-pane.ts

@@ -78,9 +78,11 @@ export class TerminalPaneRenderable extends Renderable {
     const terminals = factory();
 
     if (!terminals) return;
+
     const vt = terminals.create(cols, rows);
 
     if (!vt) return; // no emulator, no visible screen - do not spawn a blind child
+
     this.vt = vt;
     this.cols = cols;
     this.rows = rows;
@@ -96,10 +98,12 @@ export class TerminalPaneRenderable extends Renderable {
       // the shim streams a UTF-8-decoded string (split multibyte is handled); a
       // rare non-UTF-8 byte arrives as U+FFFD - acceptable for agent TUIs.
       this.vt?.write(encoder.encode(data));
+
       if (this.pendingSeed !== undefined) {
         this.pty?.write(this.pendingSeed);
         this.pendingSeed = undefined;
       }
+
       this.requestRender();
     });
     this.pty.onExit(({ exitCode }) => this.opts.onExit?.(exitCode));
@@ -112,12 +116,15 @@ export class TerminalPaneRenderable extends Renderable {
 
   protected onResize(width: number, height: number): void {
     if (width <= 0 || height <= 0) return;
+
     if (!this.pty) {
       this.start(width, height);
 
       return;
     }
+
     if (width === this.cols && height === this.rows) return;
+
     this.cols = width;
     this.rows = height;
     this.vt?.resize(width, height);
@@ -126,17 +133,20 @@ export class TerminalPaneRenderable extends Renderable {
 
   protected renderSelf(buffer: OptimizedBuffer): void {
     if (!this.vt) return;
+
     for (let y = 0; y < this.height; y++) {
       for (let x = 0; x < this.width; x++) {
         const cell = this.vt.readCell(x, y);
 
         // Skip an empty normal-width cell; the buffer already starts blank.
         if (cell && cell.width === 0 && cell.codepoint === 0) continue;
+
         const char = cell && cell.codepoint ? String.fromCodePoint(cell.codepoint) : " ";
         let fg = cell ? resolveColor(cell.fg, DEFAULT_FG) : DEFAULT_FG;
         let bg = cell ? resolveColor(cell.bg, TRANSPARENT) : TRANSPARENT;
 
         if (cell?.inverse) [fg, bg] = [bg, fg];
+
         const attributes = cell
           ? createTextAttributes({
               bold: cell.bold,
@@ -181,6 +191,7 @@ export class TerminalPaneRenderable extends Renderable {
 /** Map a Ghostty cell color to an OpenTUI RGBA, using `fallback` for the terminal default. */
 function resolveColor(color: GhosttyColor, fallback: RGBA): RGBA {
   if (color.kind === "rgb") return RGBA.fromInts(color.r, color.g, color.b, 255);
+
   if (color.kind === "palette") return RGBA.fromIndex(color.index);
 
   return fallback;
@@ -191,6 +202,7 @@ let registered = false;
 /** Register `<terminalPane>` with the OpenTUI React reconciler (idempotent). */
 export function registerTerminalPane(): void {
   if (registered) return;
+
   registered = true;
   extend({ terminalPane: TerminalPaneRenderable });
 }

package/src/terminal/ghostty-terminal.ts

@@ -68,9 +68,11 @@ let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
  */
 export function loadGhosttyTerminals(): GhosttyTerminalFactory | null {
   if (ghosttyFactory !== undefined) return ghosttyFactory;
+
   const path = nativeLibraryPath();
 
   if (!path) return (ghosttyFactory = null);
+
   try {
     const lib = dlopen(path, CVT_SYMBOLS);
 
@@ -121,19 +123,23 @@ export class GhosttyTerminal {
   /** Process a chunk of the child's PTY output into the screen state. */
   write(bytes: Uint8Array): void {
     if (this.freed || bytes.length === 0) return;
+
     this.lib.cvt_write(this.handle, ptr(bytes), BigInt(bytes.length));
   }
 
   /** Resize the screen (and the child's tty, via the caller) to cols x rows. */
   resize(cols: number, rows: number): void {
     if (this.freed) return;
+
     this.lib.cvt_resize(this.handle, cols, rows);
   }
 
   /** The rendered cell at viewport (x, y), or null when out of range. */
   readCell(x: number, y: number): GhosttyCell | null {
     if (this.freed) return null;
+
     if (this.lib.cvt_cell(this.handle, x, y, ptr(this.out)) !== 0) return null;
+
     const flags = this.out[13]!;
 
     return {
@@ -161,6 +167,7 @@ export class GhosttyTerminal {
       const cell = this.readCell(x, y);
 
       if (cell === null || cell.width === 2) continue;
+
       line += cell.codepoint === 0 ? " " : String.fromCodePoint(cell.codepoint);
     }
 
@@ -170,6 +177,7 @@ export class GhosttyTerminal {
   /** The cursor's current viewport position and visibility. */
   readCursor(): GhosttyCursor {
     if (this.freed) return { x: 0, y: 0, visible: false };
+
     this.lib.cvt_cursor(this.handle, ptr(this.cursorOut));
     const view = new DataView(this.cursorOut.buffer);
 
@@ -183,6 +191,7 @@ export class GhosttyTerminal {
   /** Release the terminal; further calls are no-ops. Call once on teardown. */
   free(): void {
     if (this.freed) return;
+
     this.freed = true;
     this.lib.cvt_free(this.handle);
   }
@@ -191,6 +200,7 @@ export class GhosttyTerminal {
 /** Decode the shim's (kind, r, g, b) color triple; palette carries its index in r. */
 function decodeColor(kind: number, r: number, g: number, b: number): GhosttyColor {
   if (kind === 2) return { kind: "rgb", r, g, b };
+
   if (kind === 1) return { kind: "palette", index: r };
 
   return { kind: "default" };

package/src/terminal/kitty-image.ts

@@ -71,6 +71,7 @@ function placementKeys(imageId: number, region: CellRegion): string {
 // cannot pre-place a symlink at the screenshot path and redirect the write.
 function writeTempPng(png: Uint8Array): string {
   if (!privateTempDir) privateTempDir = mkdtempSync(join(tmpdir(), "cueloop-prototype-"));
+
   const path = join(privateTempDir, `${tempFileCounter++}.png`);
 
   writeFileSync(path, png, { flag: "wx" });
@@ -119,6 +120,7 @@ export function transmitKittyImage(
   medium: TransmitMedium = "base64",
 ): void {
   if (region.columns < 1 || region.rows < 1) return;
+
   const body =
     medium === "file" ? fileTransmit(png, region, imageId) : base64Transmit(png, region, imageId);
 
@@ -128,6 +130,7 @@ export function transmitKittyImage(
 /** Re-place the already-transmitted image over its region, cheaply (a=p, no data). */
 export function placeKittyImage(write: OrderedWrite, region: CellRegion, imageId: number): void {
   if (region.columns < 1 || region.rows < 1) return;
+
   write(atRegion(region, graphicsCommand(`a=p,${placementKeys(imageId, region)}`, "")));
 }
 

package/src/terminal/pty.ts

@@ -79,9 +79,11 @@ let ptyLib: PtyLib | null | undefined;
 
 function library(): PtyLib | null {
   if (ptyLib !== undefined) return ptyLib;
+
   const path = nativeLibraryPath();
 
   if (!path) return (ptyLib = null);
+
   try {
     ptyLib = dlopen(path, PTY_SYMBOLS).symbols;
   } catch (error) {
@@ -154,7 +156,9 @@ class Pty implements IPty {
       this.columns,
       this.rowCount,
     );
+
     if (this.handle < 0) throw new Error("PTY spawn failed");
+
     this.processId = lib.cueloop_pty_get_pid(this.handle);
     // Let the caller attach onData/onExit before the first bytes arrive.
     queueMicrotask(() => void this.readLoop());
@@ -178,6 +182,7 @@ class Pty implements IPty {
 
   write(data: string): void {
     if (this.closing) return;
+
     const buffer = Buffer.from(data, "utf8");
 
     this.lib.cueloop_pty_write(this.handle, ptr(buffer), buffer.length);
@@ -185,6 +190,7 @@ class Pty implements IPty {
 
   resize(cols: number, rows: number): void {
     if (this.closing) return;
+
     this.columns = cols;
     this.rowCount = rows;
     this.lib.cueloop_pty_resize(this.handle, cols, rows);
@@ -192,6 +198,7 @@ class Pty implements IPty {
 
   kill(): void {
     if (this.closing) return;
+
     this.closing = true;
     this.lib.cueloop_pty_kill(this.handle);
     this.lib.cueloop_pty_close(this.handle);
@@ -200,6 +207,7 @@ class Pty implements IPty {
 
   private async readLoop(): Promise<void> {
     if (this.reading) return;
+
     this.reading = true;
     const buffer = Buffer.allocUnsafe(READ_BUFFER_BYTES);
     // consecutive empty reads; the idle sleep backs off exponentially so a quiet agent prompt
@@ -221,6 +229,7 @@ class Pty implements IPty {
         const tail = this.decoder.decode();
 
         if (tail) this.dataEvent.fire(tail);
+
         const exitCode = this.lib.cueloop_pty_get_exit_code(this.handle);
 
         this.lib.cueloop_pty_close(this.handle);

package/src/testing/test-support.test.ts

@@ -46,6 +46,7 @@ describe("isolateUserConfig", () => {
     } finally {
       if (priorEnv === undefined) delete process.env.CUELOOP_CONFIG;
       else process.env.CUELOOP_CONFIG = priorEnv;
+
       rmSync(home, { recursive: true, force: true });
     }
   });
@@ -69,6 +70,7 @@ describe("isolateUserConfig", () => {
       expect(process.env.CUELOOP_CONFIG).toBeUndefined();
     } finally {
       if (priorEnv !== undefined) process.env.CUELOOP_CONFIG = priorEnv;
+
       rmSync(home, { recursive: true, force: true });
     }
   });

package/src/testing/test-support.ts

@@ -41,6 +41,7 @@ export async function renderReadyApp(
   options: TestRendererOptions,
 ): Promise<TestRendererSetup> {
   if (!isValidElement<AppProps>(element)) throw new Error("renderReadyApp needs an App element");
+
   const probe = appReadyProbe();
   const setup = await testRender(cloneElement(element, { onReady: probe.onReady }), options);
 
@@ -122,7 +123,9 @@ export async function settle(setup: TestRendererSetup): Promise<void> {
     const frame = paintedFrame(setup);
 
     quietTurns = frame === previous ? quietTurns + 1 : 0;
+
     if (quietTurns >= SETTLE_QUIET_TURNS) return;
+
     previous = frame;
   }
 }
@@ -137,6 +140,7 @@ export async function press(setup: TestRendererSetup, key: string): Promise<void
   else if (key === "up") setup.mockInput.pressKey("ARROW_UP");
   else if (key === "down") setup.mockInput.pressKey("ARROW_DOWN");
   else return typeText(setup, key);
+
   await settle(setup);
 }
 
@@ -164,6 +168,7 @@ export async function navCommand(setup: TestRendererSetup, key: string): Promise
   await press(setup, "escape");
   await new Promise((resolve) => setTimeout(resolve, 40));
   await settle(setup);
+
   // a single letter is a discrete keypress (nav command); named keys route through press
   if (key.length === 1) await pressKey(setup, key);
   else await press(setup, key);
@@ -280,11 +285,14 @@ async function waitForFramePredicate(
     const frame = setup.captureCharFrame();
 
     polls++;
+
     if (frame !== lastFrame) {
       frameChanges++;
       lastFrame = frame;
     }
+
     if (predicate(frame)) return frame;
+
     const now = Date.now();
 
     if (now > deadline) {
@@ -294,12 +302,14 @@ async function waitForFramePredicate(
         `waitFor ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
       );
     }
+
     if (now - lastLog >= PROGRESS_LOG_MS) {
       lastLog = now;
       console.error(
         `[waitFor] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes\n${frameTail(frame)}`,
       );
     }
+
     await yieldEventLoop();
   }
 }
@@ -320,15 +330,19 @@ export async function waitForState(
 
   for (;;) {
     if (predicate()) return;
+
     await setup.renderOnce();
     const frame = setup.captureCharFrame();
 
     polls++;
+
     if (frame !== lastFrame) {
       frameChanges++;
       lastFrame = frame;
     }
+
     if (predicate()) return;
+
     const now = Date.now();
 
     if (now > deadline) {
@@ -338,12 +352,14 @@ export async function waitForState(
         `waitForState ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
       );
     }
+
     if (now - lastLog >= PROGRESS_LOG_MS) {
       lastLog = now;
       console.error(
         `[waitForState] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes`,
       );
     }
+
     await yieldEventLoop();
   }
 }

package/src/thread/agent-continuation.test.ts

@@ -22,7 +22,9 @@ test("only a completed reply in an idle conversation offers continuation", () =>
   const completed: AgentContinuation = agentContinuation({ ...state, messages: [message] });
 
   expect(completed.kind).toBe("ready");
+
   if (completed.kind === "ready") expect(completed.replyId).toBe("answer");
+
   expect(agentContinuation({ ...state, phase: { kind: "running" }, messages: [message] })).toEqual({
     kind: "waiting",
   });