@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/pty.ts

@@ -0,0 +1,245 @@
+/**
+ * A pseudo-terminal for the embedded Agent-tab terminal, over cueloop's own
+ * forkpty(3) FFI shim (native/src/pty.zig). `spawn` returns a `Pty` with
+ * `onData`/`onExit` events and `write`/`resize`/`kill`; a poll loop drains the
+ * child's output and decodes it as streaming UTF-8. `ptyAvailable()` returns
+ * false when no prebuilt shim ships for this platform, so callers fall back to a
+ * herdr split, exactly like the Ghostty VT loader.
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+/** Shortest read-loop sleep, used while the child is actively streaming - keeps output snappy. */
+const READ_IDLE_MS = 8;
+/** Longest read-loop sleep, reached after the child sits quiet - stops the loop burning a core at idle. */
+const READ_IDLE_MAX_MS = 100;
+const READ_BUFFER_BYTES = 4096;
+/** cueloop_pty_read's sentinel: the child has exited and its output is drained. */
+const CHILD_EXITED = -2;
+
+export interface PtyForkOptions {
+  name?: string;
+  cols?: number;
+  rows?: number;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface ExitEvent {
+  exitCode: number;
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+/** The pseudo-terminal surface the embedded terminal consumes. */
+export interface IPty {
+  readonly pid: number;
+  readonly cols: number;
+  readonly rows: number;
+  readonly onData: (listener: (data: string) => void) => Disposable;
+  readonly onExit: (listener: (event: ExitEvent) => void) => Disposable;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+const PTY_SYMBOLS = {
+  cueloop_pty_spawn: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.ptr, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  cueloop_pty_write: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_read: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_resize: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_kill: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_pid: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_exit_code: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_close: { args: [FFIType.i32], returns: FFIType.void },
+} as const;
+
+type PtyLib = ReturnType<typeof dlopen<typeof PTY_SYMBOLS>>["symbols"];
+
+/** The prebuilt pty shim for this platform, or null when none ships for it. */
+function nativeLibraryPath(): string | null {
+  const suffix = process.platform === "darwin" ? "dylib" : "so";
+  const dir = `${process.platform}-${process.arch}`;
+  const path = join(import.meta.dir, "..", "native", dir, `libcuelooppty.${suffix}`);
+
+  return existsSync(path) ? path : null;
+}
+
+/** One shared load of the pty shim; null when no dylib ships for the platform. */
+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) {
+    console.error(`cueloop: failed to load ${path}:`, error);
+    ptyLib = null;
+  }
+
+  return ptyLib;
+}
+
+/** True when this platform ships a prebuilt pty shim (embedding is possible). */
+export function ptyAvailable(): boolean {
+  return library() !== null;
+}
+
+class EventEmitter<T> {
+  private listeners: ((value: T) => void)[] = [];
+  readonly event = (listener: (value: T) => void): Disposable => {
+    this.listeners.push(listener);
+
+    return {
+      dispose: () => {
+        const index = this.listeners.indexOf(listener);
+
+        if (index !== -1) this.listeners.splice(index, 1);
+      },
+    };
+  };
+  fire(value: T): void {
+    for (const listener of this.listeners) listener(value);
+  }
+}
+
+/** Pack tokens into the C shim's "tok\0tok\0...\0\0" (double-NUL-terminated) form. */
+function packTokens(tokens: string[]): Buffer {
+  return Buffer.from(tokens.map((token) => `${token}\0`).join("") + "\0", "utf8");
+}
+
+class Pty implements IPty {
+  private handle: number;
+  private processId: number;
+  private columns: number;
+  private rowCount: number;
+  private closing = false;
+  private reading = false;
+  private readonly decoder = new TextDecoder("utf-8");
+  private readonly dataEvent = new EventEmitter<string>();
+  private readonly exitEvent = new EventEmitter<ExitEvent>();
+
+  constructor(
+    private readonly lib: PtyLib,
+    file: string,
+    args: string[],
+    options: PtyForkOptions,
+  ) {
+    this.columns = options.cols ?? DEFAULT_COLS;
+    this.rowCount = options.rows ?? DEFAULT_ROWS;
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env
+      ? Object.entries(options.env).map(([key, value]) => `${key}=${value}`)
+      : [];
+
+    const argvPacked = packTokens([file, ...args]);
+    const envPacked = packTokens(env);
+
+    this.handle = lib.cueloop_pty_spawn(
+      ptr(argvPacked),
+      Buffer.from(`${cwd}\0`, "utf8"),
+      ptr(envPacked),
+      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());
+  }
+
+  get pid(): number {
+    return this.processId;
+  }
+  get cols(): number {
+    return this.columns;
+  }
+  get rows(): number {
+    return this.rowCount;
+  }
+  get onData() {
+    return this.dataEvent.event;
+  }
+  get onExit() {
+    return this.exitEvent.event;
+  }
+
+  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);
+  }
+
+  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);
+  }
+
+  kill(): void {
+    if (this.closing) return;
+    this.closing = true;
+    this.lib.cueloop_pty_kill(this.handle);
+    this.lib.cueloop_pty_close(this.handle);
+    this.exitEvent.fire({ exitCode: 0 });
+  }
+
+  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
+    // ramps from an 8ms hot poll up to a 100ms idle poll instead of spinning a core forever
+    let idlePolls = 0;
+
+    while (!this.closing) {
+      const count = this.lib.cueloop_pty_read(this.handle, ptr(buffer), buffer.length);
+
+      if (count > 0) {
+        idlePolls = 0;
+        // Stream mode buffers a multibyte char split across reads (box-drawing etc.).
+        const text = this.decoder.decode(buffer.subarray(0, count), { stream: true });
+
+        if (text) this.dataEvent.fire(text);
+      } else if (count === CHILD_EXITED || count < 0) {
+        // Both the drained-exit sentinel and a hard read error end the session:
+        // flush the decoder, reap for the code, close, and fire the exit once.
+        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);
+        this.closing = true;
+        this.exitEvent.fire({ exitCode });
+      } else {
+        const delay = Math.min(READ_IDLE_MAX_MS, READ_IDLE_MS * 2 ** Math.min(idlePolls, 5));
+        idlePolls += 1;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+}
+
+/** Spawn `file` with `args` on a fresh PTY. Throws when no shim ships (gate on ptyAvailable). */
+export function spawn(file: string, args: string[], options: PtyForkOptions = {}): IPty {
+  const lib = library();
+
+  if (!lib) throw new Error("cueloop: no pty shim for this platform");
+
+  return new Pty(lib, file, args, options);
+}

package/src/ready-signal.test.ts

@@ -0,0 +1,85 @@
+/** The ready signal fires once, after a frame, and writes the ready file when the env names one. */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createElement, useState } from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { READY_FILE_ENV, useReadySignal } from "./ready-signal";
+import { settle } from "./test-support";
+
+const homes: string[] = [];
+
+afterEach(() => {
+  for (const home of homes.splice(0)) rmSync(home, { recursive: true, force: true });
+  delete process.env[READY_FILE_ENV];
+});
+
+/** Hands its readiness setter to the test, so a frame can be rendered before and after the flip. */
+function ReadyProbe(props: {
+  initiallyReady: boolean;
+  onReady: () => void;
+  exposeSetter?: (setReady: (ready: boolean) => void) => void;
+}) {
+  const [ready, setReady] = useState(props.initiallyReady);
+
+  props.exposeSetter?.(setReady);
+  useReadySignal(ready, props.onReady);
+
+  return createElement("text", null, ready ? "ready" : "booting");
+}
+
+describe("useReadySignal", () => {
+  test("fires once on the first frame after ready turns true", async () => {
+    // Arrange - not ready yet
+    let fired = 0;
+    let setReady: ((ready: boolean) => void) | null = null;
+    const onReady = () => {
+      fired += 1;
+    };
+    const setup = await testRender(
+      createElement(ReadyProbe, {
+        initiallyReady: false,
+        onReady,
+        exposeSetter: (setter) => {
+          setReady = setter;
+        },
+      }),
+      { width: 20, height: 3 },
+    );
+
+    await settle(setup);
+    expect(fired).toBe(0);
+
+    // Act - ready, then let the commit, the effect, and more frames than one signal needs run
+    setReady!(true);
+    await settle(setup);
+    await settle(setup);
+
+    // Assert - exactly one signal, and the screen shows the ready tree
+    expect(fired).toBe(1);
+    expect(setup.captureCharFrame()).toContain("ready");
+    setup.renderer.destroy();
+  });
+
+  test("writes the ready file through the env channel", async () => {
+    // Arrange
+    const home = mkdtempSync(join(tmpdir(), "cueloop-ready-"));
+    const readyFile = join(home, "ready");
+
+    homes.push(home);
+    process.env[READY_FILE_ENV] = readyFile;
+    const setup = await testRender(
+      createElement(ReadyProbe, { initiallyReady: true, onReady: () => {} }),
+      { width: 20, height: 3 },
+    );
+
+    // Act
+    await settle(setup);
+
+    // Assert
+    expect(existsSync(readyFile)).toBe(true);
+    setup.renderer.destroy();
+  });
+});

package/src/ready-signal.ts

@@ -0,0 +1,52 @@
+/**
+ * The app ready signal: fired once, after the first frame that paints a
+ * usable screen (a session, the no-thread shell, or an error) has been
+ * flushed. React runs child effects before parent effects, so by the time the
+ * App-level effect arms the frame listener every keyboard handler of that
+ * first screen is already subscribed - a key sent after the signal cannot be
+ * dropped. Surfaces that mount later (a composer, a lazily loaded tab) still
+ * need their own screen predicate. Tests wait on this instead of guessing
+ * from output silence. Two channels: an
+ * `onReady` callback for in-process suites, and the file named by
+ * CUELOOP_READY_FILE for subprocess and PTY suites. Users never see either.
+ */
+
+import { writeFileSync } from "node:fs";
+import { useEffect, useRef } from "react";
+import { useRenderer } from "@opentui/react";
+
+/** The env var naming the file the app writes once it is ready; unset in normal use. */
+export const READY_FILE_ENV = "CUELOOP_READY_FILE";
+
+/** Write the ready file when CUELOOP_READY_FILE names one; a no-op otherwise, so the signal costs nothing outside tests. */
+function announceReady(): void {
+  const path = process.env[READY_FILE_ENV];
+
+  if (!path) return;
+  writeFileSync(path, "ready\n");
+}
+
+/**
+ * Fire the ready signal once, on the first rendered frame after `ready`
+ * turns true. Call it after every keyboard hook of the component so their
+ * subscriptions are in place when the signal goes out.
+ */
+export function useReadySignal(ready: boolean, onReady?: () => void): void {
+  const renderer = useRenderer();
+  const fired = useRef(false);
+
+  useEffect(() => {
+    if (!ready || fired.current) return;
+    const emit = (): void => {
+      fired.current = true;
+      announceReady();
+      onReady?.();
+    };
+
+    renderer?.once("frame", emit);
+
+    return () => {
+      renderer?.off("frame", emit);
+    };
+  }, [ready, renderer, onReady]);
+}

package/src/run.ts

@@ -10,18 +10,39 @@ export interface RunClientOptions {
   home?: string;
 }
 
-export async function runClient(opts: RunClientOptions): Promise<number> {
-  const renderer = await createCliRenderer();
+/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
+const THEME_QUERY_TIMEOUT_MS = 200;
+
+export async function runClient(options: RunClientOptions): Promise<number> {
+  // mouse movement reporting makes multiplexers forward drags to the app,
+  // so the renderer's native selection is the drag driver
+  const renderer = await createCliRenderer({ enableMouseMovement: true });
+  const appearance =
+    (await renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
+
   return new Promise<number>((resolve) => {
+    let exited = false;
+    const shutdown = (code: number): void => {
+      if (exited) return;
+      exited = true;
+      renderer.destroy();
+      resolve(code);
+      // one microtask between destroy and exit lets the renderer flush
+      // its terminal-restore sequences before the process dies
+      queueMicrotask(() => process.exit(code));
+    };
+
+    // a closed pane/terminal hangs up (or the parent kills us); exit instead of
+    // lingering as an orphan whose pty read loop keeps burning CPU
+    process.once("SIGHUP", () => shutdown(0));
+    process.once("SIGTERM", () => shutdown(0));
+
     createRoot(renderer).render(
       React.createElement(App, {
-        home: opts.home,
-        sessionId: opts.sessionId,
-        onExit: (code: number) => {
-          renderer.destroy();
-          resolve(code);
-          process.exit(code);
-        },
+        home: options.home,
+        sessionId: options.sessionId,
+        appearance,
+        onExit: shutdown,
       }),
     );
   });

package/src/serve.test.ts

@@ -10,14 +10,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Client } from "ssh2";
 import { DaemonServer } from "@cueloop/daemon";
-import type { ReviewSession } from "@cueloop/schema";
+import type { Thread } from "@cueloop/schema";
 import { serveClient, type ServeHandle } from "./serve";
 
 const PLAN = "# Rollout Plan\n\nShip the store move behind a flag.\n";
 
 let home: string;
 let daemon: DaemonServer;
-let session: ReviewSession;
+let session: Thread;
 let handle: ServeHandle;
 
 beforeEach(async () => {
@@ -38,7 +38,11 @@ afterEach(async () => {
 });
 
 /** Connect, open a PTY shell, resolve with the bytes seen until `until` matches. */
-function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 8000): Promise<string> {
+function sshCapture(
+  port: number,
+  until: (frame: string) => boolean,
+  timeoutMs = 8000,
+): Promise<string> {
   return new Promise((resolve, reject) => {
     const conn = new Client();
     let out = "";
@@ -48,15 +52,17 @@ function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 800
       done = true;
       clearTimeout(timer);
       conn.end();
-      err ? reject(err) : resolve(out);
+      if (err) reject(err);
+      else resolve(out);
     };
     const timer = setTimeout(() => finish(new Error(`timed out; captured:\n${out}`)), timeoutMs);
+
     conn
       .on("ready", () => {
         conn.shell({ term: "xterm-256color", cols: 100, rows: 30 }, (err, stream) => {
           if (err) return finish(err);
-          stream.on("data", (d: Buffer) => {
-            out += d.toString("utf8");
+          stream.on("data", (chunk: Buffer) => {
+            out += chunk.toString("utf8");
             if (until(out)) finish();
           });
           stream.on("close", () => finish(new Error(`stream closed early; captured:\n${out}`)));
@@ -70,6 +76,7 @@ function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 800
 
 describe("cueloop serve", () => {
   test("listens on localhost, persists a host key under CUELOOP_HOME/ssh", () => {
+    // Assert
     expect(handle.host).toBe("127.0.0.1");
     expect(handle.port).toBeGreaterThan(0);
     expect(handle.fingerprints.length).toBe(1);
@@ -77,19 +84,24 @@ describe("cueloop serve", () => {
     expect(existsSync(join(home, "ssh", "host_key"))).toBe(true);
   });
 
-  test("an anonymous ssh client gets the observer TUI for the session", async () => {
-    const bytes = await sshCapture(handle.port, (s) => s.includes("Rollout Plan") && s.includes("observer"));
+  test("an anonymous ssh client gets the read-only TUI for the session", async () => {
+    // Act
+    const bytes = await sshCapture(handle.port, (frame) => frame.includes("Rollout Plan"));
+
+    // Assert - the viewer sees the session; read-only is enforced behaviorally
+    // (covered by the observer-primitives tests), not by a header badge
     expect(bytes).toContain("cueloop");
     expect(bytes).toContain("Rollout Plan");
-    // observer chrome, not the controller's mutating hint bar
-    expect(bytes).toContain("observer - read-only");
   });
 
   test("two observers can watch at once", async () => {
+    // Act
     const [a, b] = await Promise.all([
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
     ]);
+
+    // Assert
     expect(a).toContain("Rollout Plan");
     expect(b).toContain("Rollout Plan");
   });

package/src/serve.ts

@@ -1,5 +1,5 @@
 /**
- * SSH-served TUI (#22 share path): `cueloop serve` lets teammates join a
+ * SSH-served TUI: `cueloop serve` lets teammates join a
  * review session over plain ssh. Every SSH connection renders <App> in
  * observer mode (readOnly) against the same local daemon; the one writable
  * controller stays the local owner's own `cueloop` TUI.
@@ -22,6 +22,9 @@ import { createServer } from "@opentui/ssh";
 import { cueloopHome } from "@cueloop/daemon";
 import { App } from "./App";
 
+/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
+const THEME_QUERY_TIMEOUT_MS = 200;
+
 export interface ServeOptions {
   /** TCP port for the SSH listener; 0 picks an ephemeral port. Default 2222. */
   port?: number;
@@ -33,7 +36,7 @@ export interface ServeOptions {
   home?: string;
   /** Silence the @opentui/ssh startup banner (tests). Default true. */
   banner?: boolean;
-  onError?: (err: unknown) => void;
+  onError?: (cause: unknown) => void;
 }
 
 export interface ServeHandle {
@@ -44,25 +47,32 @@ export interface ServeHandle {
   close(): Promise<void>;
 }
 
-export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
-  const home = opts.home ?? cueloopHome();
+export async function serveClient(options: ServeOptions = {}): Promise<ServeHandle> {
+  const home = options.home ?? cueloopHome();
   const sshDir = join(home, "ssh");
+
   mkdirSync(sshDir, { recursive: true, mode: 0o700 });
 
   const server = createServer({
     // password-less by design; see the trust model in the module comment
     auth: "open",
     hostKey: { path: join(sshDir, "host_key") },
-    startupBanner: opts.banner ?? true,
+    startupBanner: options.banner ?? true,
     idleTimeout: "2h",
-    onError: opts.onError,
-  }).serve((session) => {
+    onError: options.onError,
+  }).serve(async (session) => {
+    // the observer's terminal reports its own background, so a light-terminal
+    // watcher gets the readable variant too
+    const appearance =
+      (await session.renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
     const root = createRoot(session.renderer);
+
     root.render(
       React.createElement(App, {
         home,
-        sessionId: opts.sessionId,
+        sessionId: options.sessionId,
         readOnly: true,
+        appearance,
         // q disconnects only this observer, never the server
         onExit: () => session.end(),
       }),
@@ -70,6 +80,7 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     session.onClose(() => root.unmount());
   });
 
-  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
+  const info = await server.listen(options.port ?? 2222, options.host ?? "127.0.0.1");
+
   return { ...info, close: () => server.close() };
 }