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

package/src/terminal/kitty-image.test.ts

@@ -0,0 +1,66 @@
+/** Kitty emission guards: the image sits beneath painted cells, and every put reuses one placement id so repeated frames REPLACE the placement instead of stacking a new one each frame (the prototype's per-frame lag/ghosting regression). Transmit medium is file locally and base64 over ssh. */
+
+import { describe, expect, test } from "bun:test";
+import { placeKittyImage, resolveTransmitMedium, transmitKittyImage } from "./kitty-image";
+
+const REGION = { column: 2, row: 3, columns: 40, rows: 12 };
+
+describe("kitty image placement", () => {
+  test("places the prototype below cells with painted backgrounds", () => {
+    // Arrange
+    const writes: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => writes.push(chunk), new Uint8Array([1]), REGION, 811);
+    placeKittyImage((chunk) => writes.push(chunk), REGION, 811);
+
+    // Assert
+    expect(writes).toHaveLength(2);
+    expect(writes[0]).toContain("z=-1073741825");
+    expect(writes[1]).toContain("z=-1073741825");
+  });
+
+  test("every frame reuses one placement id, so repeated puts replace rather than stack", () => {
+    // Arrange
+    const writes: string[] = [];
+    const write = (chunk: string): void => void writes.push(chunk);
+
+    // Act - one transmit then many re-places, as the per-frame paint loop does
+    transmitKittyImage(write, new Uint8Array([1]), REGION, 811, "base64");
+    for (let frame = 0; frame < 5; frame++) placeKittyImage(write, REGION, 811);
+
+    // Assert - a stable placement id p=1 on the transmit and every place
+    expect(writes[0]).toContain("i=811,p=1");
+    for (const placement of writes.slice(1)) expect(placement).toContain("i=811,p=1");
+  });
+
+  test("base64 transmit chunks the payload; file transmit hands over a path once", () => {
+    // Arrange
+    const big = new Uint8Array(9000).fill(1);
+    const base64Writes: string[] = [];
+    const fileWrites: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => base64Writes.push(chunk), big, REGION, 811, "base64");
+    transmitKittyImage((chunk) => fileWrites.push(chunk), big, REGION, 811, "file");
+
+    // Assert - base64 inlines the data (a=T without t=), file references a temp path (t=t)
+    expect(base64Writes[0]).toContain("a=T");
+    expect(base64Writes[0]).not.toContain("t=t");
+    expect(fileWrites[0]).toContain("t=t");
+  });
+});
+
+describe("resolveTransmitMedium", () => {
+  test("defaults to base64; file transfer is opt-in and never over ssh", () => {
+    // Assert
+    expect(resolveTransmitMedium({})).toBe("base64");
+    expect(resolveTransmitMedium({ CUELOOP_KITTY_FILE: "1" })).toBe("file");
+    expect(
+      resolveTransmitMedium({
+        CUELOOP_KITTY_FILE: "1",
+        SSH_CONNECTION: "1.2.3.4 5 6 7",
+      }),
+    ).toBe("base64");
+  });
+});

package/src/terminal/kitty-image.ts

@@ -0,0 +1,137 @@
+/**
+ * Direct kitty graphics protocol emission for a cell rectangle. OpenTUI's
+ * ImageRenderable does not display in every terminal, so prototype review paints
+ * the screenshot itself: transmit the PNG once under a fixed image AND placement
+ * id, then re-place that same placement after each frame over its reserved
+ * (never-repainted) cells. Reusing one placement id means each frame REPLACES
+ * the placement rather than stacking a new one, which is the protocol's
+ * flicker-free move/resize path. Locally the PNG travels out of band via a
+ * temporary file so its bytes never cross the pty; a base64 fallback covers the
+ * ssh sharing path where no shared filesystem exists.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface CellRegion {
+  column: number;
+  row: number;
+  columns: number;
+  rows: number;
+}
+
+/** Writes a raw sequence ordered against the renderer's own frame output. */
+export type OrderedWrite = (chunk: string) => void;
+
+export type TransmitMedium = "file" | "base64";
+
+const ESCAPE_STRING_TERMINATOR = "\x1b\\";
+const CHUNK_BYTES = 4096;
+// The protocol reserves values below INT32_MIN/2 for images that must sit
+// beneath cells with painted backgrounds, such as the marker popover.
+const IMAGE_Z_INDEX = -1_073_741_825;
+// One fixed placement per image: reusing it makes every put replace that
+// placement instead of accumulating a new one each frame.
+const PLACEMENT_ID = 1;
+const SYNCHRONIZED_UPDATE_START = "\x1b[?2026h";
+const SYNCHRONIZED_UPDATE_END = "\x1b[?2026l";
+
+let tempFileCounter = 0;
+let privateTempDir: string | null = null;
+
+/**
+ * base64 is the safe default: it works over the pty everywhere, including the
+ * ssh sharing path. Out-of-band file transfer (t=t) is faster for the initial
+ * transmit but depends on the terminal trusting the temp-file path, so it is
+ * opt-in via `CUELOOP_KITTY_FILE=1` and never used over ssh (no shared disk).
+ */
+export function resolveTransmitMedium(env: NodeJS.ProcessEnv = process.env): TransmitMedium {
+  if (env.CUELOOP_KITTY_FILE === "1" && !env.SSH_CONNECTION && !env.SSH_TTY) return "file";
+
+  return "base64";
+}
+
+/** Save the cursor, run the placement at the region's corner, restore it. */
+function atRegion(region: CellRegion, body: string): string {
+  const moveToCorner = `\x1b[${region.row + 1};${region.column + 1}H`;
+
+  return `\x1b7${moveToCorner}${body}\x1b8`;
+}
+
+function graphicsCommand(keys: string, payload: string): string {
+  return `\x1b_G${keys};${payload}${ESCAPE_STRING_TERMINATOR}`;
+}
+
+function placementKeys(imageId: number, region: CellRegion): string {
+  return `i=${imageId},p=${PLACEMENT_ID},q=2,C=1,z=${IMAGE_Z_INDEX},c=${region.columns},r=${region.rows}`;
+}
+
+// A per-process 0700 directory with an unpredictable name, so a local attacker
+// 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" });
+
+  return path;
+}
+
+function base64Transmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const base64 = Buffer.from(png).toString("base64");
+  const controlKeys = `a=T,f=100,${placementKeys(imageId, region)}`;
+  let sequence = "";
+
+  for (let offset = 0; offset < base64.length; offset += CHUNK_BYTES) {
+    const chunk = base64.slice(offset, offset + CHUNK_BYTES);
+    const isMore = offset + CHUNK_BYTES < base64.length ? 1 : 0;
+
+    sequence +=
+      offset === 0
+        ? graphicsCommand(`${controlKeys},m=${isMore}`, chunk)
+        : graphicsCommand(`m=${isMore}`, chunk);
+  }
+
+  return sequence;
+}
+
+function fileTransmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const path = writeTempPng(png);
+  const payload = Buffer.from(path).toString("base64");
+
+  return graphicsCommand(`a=T,f=100,t=t,${placementKeys(imageId, region)}`, payload);
+}
+
+/**
+ * Transmit a PNG and display it filling the region's cells (a=T). f=100 is PNG,
+ * C=1 keeps the cursor put so a full-region image cannot scroll the screen, and
+ * q=2 suppresses the terminal's replies. The whole write is bracketed in
+ * synchronized-update mode so the terminal composites it atomically. `file`
+ * hands over a temp path (t=t: the terminal deletes it after reading); `base64`
+ * inlines the data, chunked at 4096 bytes.
+ */
+export function transmitKittyImage(
+  write: OrderedWrite,
+  png: Uint8Array,
+  region: CellRegion,
+  imageId: number,
+  medium: TransmitMedium = "base64",
+): void {
+  if (region.columns < 1 || region.rows < 1) return;
+  const body =
+    medium === "file" ? fileTransmit(png, region, imageId) : base64Transmit(png, region, imageId);
+
+  write(SYNCHRONIZED_UPDATE_START + atRegion(region, body) + SYNCHRONIZED_UPDATE_END);
+}
+
+/** 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)}`, "")));
+}
+
+/** Remove the image so it does not linger after the sheet closes (a=d). */
+export function deleteKittyImage(write: OrderedWrite, imageId: number): void {
+  write(graphicsCommand(`a=d,d=i,i=${imageId},q=2`, ""));
+}

package/src/terminal/pty.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { ptyAvailable, spawn } from "./pty";
+
+// The forkpty shim is a per-platform prebuilt; skip where none ships (e.g. CI
+// without the built dylib), exactly as the caller degrades to a herdr split.
+const ptyTest = ptyAvailable() ? test : test.skip;
+
+/** Run a child on a PTY, collect its output, and resolve with the exit code. */
+function runOnPty(file: string, args: string[]): Promise<{ output: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const pty = spawn(file, args, { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+    const timeout = setTimeout(() => reject(new Error("pty child never exited")), 5000);
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+    pty.onExit(({ exitCode }) => {
+      clearTimeout(timeout);
+      resolve({ output, exitCode });
+    });
+  });
+}
+
+describe("pty", () => {
+  ptyTest("streams a child's output and reports its exit code", async () => {
+    // Act
+    const { output, exitCode } = await runOnPty("sh", ["-c", "printf 'PTY-OK'; exit 7"]);
+
+    // Assert
+    expect(output).toContain("PTY-OK");
+    expect(exitCode).toBe(7);
+  });
+
+  ptyTest("forwards written input to the child", async () => {
+    // Arrange - `cat` echoes stdin back through the tty until it closes
+    const pty = spawn("cat", [], { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+
+    // Act
+    pty.write("ping\n");
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    pty.kill();
+
+    // Assert - the tty echoes the written line back
+    expect(output).toContain("ping");
+  });
+
+  ptyTest("passes env through to the child", async () => {
+    // Act
+    const { output } = await runOnPty("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""]);
+
+    // Assert - a child with no inherited marker prints nothing for it
+    expect(output).not.toContain("marker-value");
+
+    // Act - now inject the marker via env
+    const withEnv = await new Promise<string>((resolve, reject) => {
+      const pty = spawn("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""], {
+        name: "xterm-256color",
+        env: { ...process.env, CUELOOP_PTY_MARKER: "marker-value" },
+      });
+      let collected = "";
+      const timeout = setTimeout(() => reject(new Error("no exit")), 5000);
+
+      pty.onData((chunk) => {
+        collected += chunk;
+      });
+      pty.onExit(() => {
+        clearTimeout(timeout);
+        resolve(collected);
+      });
+    });
+
+    // Assert
+    expect(withEnv).toContain("marker-value");
+  });
+});

package/src/terminal/pty.ts

@@ -0,0 +1,246 @@
+/**
+ * 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);
+}