@cueloop/client 0.1.0-alpha.41 → 0.1.0-alpha.43

package/src/components/terminal-pane.ts

@@ -1,17 +1,17 @@
 /**
  * An OpenTUI renderable that runs a real child process (a shell, cc, pi, codex)
  * on a PTY and paints its live screen into the box - the terminal-in-the-rail
- * primitive. It wires bun-pty (the child + tty) to a Ghostty VT emulator
+ * primitive. It wires the forkpty shim (child + tty, ../pty) to a Ghostty VT emulator
  * (ghostty-terminal.ts) and blits the emulator's cell grid every frame via
  * OptimizedBuffer.setCell. Register once with `registerTerminalPane`, then use
- * `<terminalPane command="cc" ... />` in the OpenTUI React tree.
+ * `<terminalPane command="claude" ... />` in the OpenTUI React tree.
  */
 
 import { Renderable, RGBA, createTextAttributes, type RenderContext } from "@opentui/core";
 import type { OptimizedBuffer } from "@opentui/core";
 import type { RenderableOptions } from "@opentui/core";
 import { extend } from "@opentui/react";
-import { spawn, type IPty } from "bun-pty";
+import { spawn, ptyAvailable, type IPty } from "../pty";
 import {
   loadGhosttyTerminals,
   type GhosttyColor,
@@ -26,14 +26,15 @@ function factory(): GhosttyTerminalFactory | null {
   return ghosttyFactory;
 }
 
-/** Whether the embedded terminal can run here (the platform dylib is present). */
+/** Whether the embedded terminal can run here: both native shims ship for this
+ *  platform (the Ghostty VT renderer and the forkpty PTY). */
 export function embeddedTerminalAvailable(): boolean {
-  return factory() !== null;
+  return factory() !== null && ptyAvailable();
 }
 
 /** Props for `<terminalPane>`: the child to run plus its cwd/env and a plan-context seed. */
 export interface TerminalPaneOptions extends RenderableOptions {
-  /** The program to run, e.g. "cc" / "pi" / "codex" / a shell. */
+  /** The program to run, e.g. "claude" / "pi" / "codex" / a shell. */
   command?: string;
   args?: string[];
   cwd?: string;
@@ -85,7 +86,7 @@ export class TerminalPaneRenderable extends Renderable {
       env: (this.opts.env ?? process.env) as Record<string, string>,
     });
     this.pty.onData((data) => {
-      // bun-pty streams a UTF-8-decoded string (split multibyte is handled); a
+      // 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) {
@@ -120,7 +121,7 @@ export class TerminalPaneRenderable extends Renderable {
     for (let y = 0; y < this.height; y++) {
       for (let x = 0; x < this.width; x++) {
         const cell = this.vt.readCell(x, y);
-        // width 0 = the trailing half of a wide glyph already painted at x-1: skip it.
+        // 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;
@@ -149,11 +150,17 @@ export class TerminalPaneRenderable extends Renderable {
     }
   }
 
-  protected destroySelf(): void {
+  /** Kill the child and free the VT. Idempotent - the detach path calls this
+   *  directly because the React reconciler removes a child without destroying it. */
+  shutdown(): void {
     this.pty?.kill();
     this.vt?.free();
     this.pty = null;
     this.vt = null;
+  }
+
+  protected destroySelf(): void {
+    this.shutdown();
     super.destroySelf();
   }
 }

package/src/ghostty-terminal.test.ts

@@ -42,4 +42,41 @@ describe("ghostty-terminal FFI", () => {
     expect(cursor.x).toBe(3);
     term.free();
   });
+
+  test.skipIf(!factory)(
+    "preserves the native screen contract across resize and styled text",
+    () => {
+      // Arrange
+      const term = factory!.create(8, 2)!;
+
+      // Act - resize first, then write RGB colors, every supported style, and a wide glyph
+      term.resize(6, 3);
+      term.write(
+        new TextEncoder().encode(
+          "\x1b[38;2;12;34;56;48;2;78;90;123;1;3;4;7;9mA\x1b[0m\x1b[2mF\x1b[0m\u754c",
+        ),
+      );
+
+      // Assert - the flat native ABI retains cell data and rejects coordinates outside the viewport
+      expect(term.readCell(0, 0)).toEqual({
+        codepoint: 0x41,
+        fg: { kind: "rgb", r: 12, g: 34, b: 56 },
+        bg: { kind: "rgb", r: 78, g: 90, b: 123 },
+        width: 0,
+        bold: true,
+        italic: true,
+        underline: true,
+        inverse: true,
+        faint: false,
+        strikethrough: true,
+      });
+      expect(term.readCell(1, 0)?.faint).toBe(true);
+      expect(term.readCell(2, 0)?.codepoint).toBe("\u754c".codePointAt(0));
+      expect(term.readCell(2, 0)?.width).toBe(1);
+      expect(term.readCell(3, 0)?.width).toBe(2);
+      expect(term.readCell(6, 0)).toBeNull();
+      expect(term.readCell(0, 3)).toBeNull();
+      term.free();
+    },
+  );
 });

package/src/ghostty-terminal.ts

@@ -1,6 +1,6 @@
 /**
  * A live in-process terminal emulator backed by Ghostty's VT core (libghostty-vt)
- * through a flat FFI shim (native/src/shim.c). Feed it a child process's PTY
+ * through a flat FFI shim (native/src/shim.zig). Feed it a child process's PTY
  * output with `write`, then read the rendered screen cell-by-cell with `readCell`
  * to paint it anywhere - this is what lets a real `cc`/shell render inside an
  * OpenTUI box. Load with `loadGhosttyTerminals`, which returns null when no
@@ -30,7 +30,7 @@ export interface GhosttyCell {
   codepoint: number;
   fg: GhosttyColor;
   bg: GhosttyColor;
-  /** 0 = wide-char trailing cell (skip it), 1 = normal, 2 = double-width lead. */
+  /** Ghostty width tag: 0 = normal, 1 = double-width lead, 2 = trailing cell. */
   width: number;
   bold: boolean;
   italic: boolean;

package/src/key-bindings.ts

@@ -34,6 +34,9 @@ export type HintMode =
   | "walk"
   | "read-only";
 
+/** Display glyph for the Agent-tab terminal detach chord (ctrl+], App-owned). */
+export const AGENT_DETACH_HINT = "⌃]";
+
 export interface CheatsheetEntry {
   keys: string;
   label: string;
@@ -417,6 +420,9 @@ export class KeyBindings {
       build({ overlay: "none", spanMode: true }, "span", "Selection"),
       build({ overlay: "submit", spanMode: false }, "submit", "Submit"),
       build({ overlay: "walk", spanMode: false }, "walk", "Walk"),
+      // The Agent-tab terminal chord is owned by App (not the rebindable keymap),
+      // so it is listed statically rather than resolved from the active keys.
+      { title: "Agent terminal", entries: [{ keys: AGENT_DETACH_HINT, label: "detach" }] },
     ];
     this.context = saved;
     return sections.filter((section) => section.entries.length > 0);

package/src/pty.test.ts

@@ -0,0 +1,78 @@
+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/pty.ts

@@ -0,0 +1,222 @@
+/**
+ * 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;
+/** How long the read loop sleeps when the child produced no output this tick. */
+const READ_IDLE_MS = 8;
+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);
+    while (!this.closing) {
+      const count = this.lib.cueloop_pty_read(this.handle, ptr(buffer), buffer.length);
+      if (count > 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 {
+        await new Promise((resolve) => setTimeout(resolve, READ_IDLE_MS));
+      }
+    }
+  }
+}
+
+/** 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/native/src/shim.c

@@ -1,107 +0,0 @@
-// Flat, FFI-trivial wrapper over libghostty-vt: hides the allocator vtable, the
-// by-value GhosttyPoint (which bun:ffi cannot pass), and the packed-cell decode,
-// exposing exactly what an OpenTUI paint loop needs - new/write/resize/cell/free.
-#include <stdint.h>
-#include <stddef.h>
-#include <stdbool.h>
-#include <string.h>
-#include "ghostty/vt/types.h"
-#include "ghostty/vt/allocator.h"
-#include "ghostty/vt/terminal.h"
-#include "ghostty/vt/point.h"
-#include "ghostty/vt/grid_ref.h"
-#include "ghostty/vt/screen.h"
-#include "ghostty/vt/style.h"
-#include "ghostty/vt/color.h"
-
-typedef struct {
-  uint32_t codepoint;    // 0 = blank
-  uint8_t fg_r, fg_g, fg_b, fg_kind;  // kind: 0 default, 1 palette (index in fg_r), 2 rgb
-  uint8_t bg_r, bg_g, bg_b, bg_kind;
-  uint8_t width;         // 0 (wide trailing), 1, 2
-  uint8_t flags;         // bit0 bold, 1 italic, 2 underline, 3 inverse, 4 faint, 5 strikethrough
-  uint16_t _pad;
-} CvtCell;
-
-void *cvt_new(uint16_t cols, uint16_t rows) {
-  GhosttyTerminal t = NULL;
-  // NULL allocator selects libghostty's default (libc malloc/free when linked).
-  if (ghostty_terminal_new(NULL, &t, cols, rows) != GHOSTTY_SUCCESS) return NULL;
-  return (void *)t;
-}
-
-void cvt_free(void *t) {
-  if (t) ghostty_terminal_free((GhosttyTerminal)t);
-}
-
-void cvt_write(void *t, const uint8_t *data, size_t len) {
-  ghostty_terminal_vt_write((GhosttyTerminal)t, data, len);
-}
-
-void cvt_resize(void *t, uint16_t cols, uint16_t rows) {
-  // cell pixel size is irrelevant to the character grid; pass a nominal 1x1.
-  ghostty_terminal_resize((GhosttyTerminal)t, cols, rows, 1, 1);
-}
-
-// Writes cursor state into out8: [0..1] col (u16), [2..3] row (u16), [4] visible (u8).
-void cvt_cursor(void *t, uint8_t *out8) {
-  uint16_t cx = 0, cy = 0;
-  bool vis = false;
-  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_X, &cx);
-  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_Y, &cy);
-  ghostty_terminal_get((GhosttyTerminal)t, GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE, &vis);
-  memcpy(out8, &cx, 2);
-  memcpy(out8 + 2, &cy, 2);
-  out8[4] = vis ? 1 : 0;
-}
-
-static void decode_color(const GhosttyStyleColor *c, uint8_t *r, uint8_t *g, uint8_t *b,
-                         uint8_t *kind) {
-  if (c->tag == GHOSTTY_STYLE_COLOR_RGB) {
-    *kind = 2;
-    *r = c->value.rgb.r;
-    *g = c->value.rgb.g;
-    *b = c->value.rgb.b;
-  } else if (c->tag == GHOSTTY_STYLE_COLOR_PALETTE) {
-    *kind = 1;
-    *r = (uint8_t)c->value.palette;  // palette index in r; JS maps 0-255 -> RGB
-    *g = 0;
-    *b = 0;
-  } else {
-    *kind = 0;
-  }
-}
-
-// Reads the viewport cell at (x, y). Returns 0 on success, -1 otherwise.
-int cvt_cell(void *t, uint16_t x, uint32_t y, CvtCell *out) {
-  memset(out, 0, sizeof(*out));
-  GhosttyPoint p;
-  p.tag = GHOSTTY_POINT_TAG_VIEWPORT;
-  p.value.coordinate.x = x;
-  p.value.coordinate.y = y;
-  GhosttyGridRef ref;
-  if (ghostty_terminal_grid_ref((GhosttyTerminal)t, p, &ref) != GHOSTTY_SUCCESS) return -1;
-  GhosttyCell cell;
-  if (ghostty_grid_ref_cell(&ref, &cell) != GHOSTTY_SUCCESS) return -1;
-  uint32_t cp = 0;
-  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &cp);
-  out->codepoint = cp;
-  uint32_t wide = 0;
-  ghostty_cell_get(cell, GHOSTTY_CELL_DATA_WIDE, &wide);
-  out->width = (uint8_t)wide;
-  GhosttyStyle st;
-  ghostty_style_default(&st);
-  if (ghostty_grid_ref_style(&ref, &st) == GHOSTTY_SUCCESS) {
-    decode_color(&st.fg_color, &out->fg_r, &out->fg_g, &out->fg_b, &out->fg_kind);
-    decode_color(&st.bg_color, &out->bg_r, &out->bg_g, &out->bg_b, &out->bg_kind);
-    uint8_t f = 0;
-    if (st.bold) f |= 1;
-    if (st.italic) f |= 2;
-    if (st.underline) f |= 4;
-    if (st.inverse) f |= 8;
-    if (st.faint) f |= 16;
-    if (st.strikethrough) f |= 32;
-    out->flags = f;
-  }
-  return 0;
-}