camouflage-tui 2.1.0-beta.1 → 2.2.2-beta.1

package/README.md

@@ -15,9 +15,9 @@ The `postinstall` script downloads a pre-built native binary for your platform (
 ```js
 import { mount } from "camouflage-tui";
 
-const cam = await mount();
+const cam = await mount({ ui: "inline" });
 
-cam.send("SessionStarted", {});
+cam.send("SessionStarted", { title: "my-agent", detail: ["model · ~/project"], accent: "orange" });
 cam.send("UserMessageCreated", { text: "investigate failing test" });
 cam.send("AssistantStreamStarted", { stream_id: "s1" });
 cam.send("AssistantTokenDelta", { stream_id: "s1", token: "Looking " });
@@ -51,9 +51,35 @@ interface MountOptions {
   env?: NodeJS.ProcessEnv;   // merged with process.env
   inheritStderr?: boolean;   // default true; false → "stderr" event
   renderToTerminal?: boolean; // true → stdout goes to terminal, responses on fd 3
+  ui?: "inline" | "fullscreen"; // default "fullscreen"; see below
 }
 ```
 
+`ui: "inline"` prints finished output into the terminal's normal scrollback
+and redraws only a small live region (the reply being streamed, the
+spinner, the input box). The transcript stays after exit, text selection
+works normally, and an idle renderer uses no CPU. It draws on the terminal
+(`/dev/tty`) even in the default piped mode, so it works with a plain
+`mount({ ui: "inline" })`.
+
+### Helpers that wait for the user
+
+`selectList`, `confirm`, `permission`, `form` and `wizard` send a prompt and
+resolve with the user's answer. If the renderer exits first they resolve
+as cancelled (`permission` resolves `{ choice: "deny" }`), so a host never
+hangs on a dead renderer.
+
+```js
+import { permission } from "camouflage-tui";
+
+const { choice } = await permission(cam, {
+  request_id: "r1",
+  tool: "edit",
+  action: "edit src/auth/session.ts",
+  diff: { path: "src/auth/session.ts", before, after },
+});
+```
+
 ### `CamouflageHandle`
 
 Extends `EventEmitter`. Send events with `send()`; subscribe to outbound events with `on()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camouflage-tui",
-  "version": "2.1.0-beta.1",
+  "version": "2.2.2-beta.1",
   "description": "High-performance terminal renderer for AI agent applications. A React Ink alternative built for streaming, persistence, and replay.",
   "license": "Apache-2.0",
   "type": "module",

package/src/__fake-argv.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Test harness only: reports the arguments it was started with as one
+// UserInputSubmitted event, so tests can check what mount() passes.
+process.stdout.write(
+  JSON.stringify({ event_type: "UserInputSubmitted", payload: { text: process.argv.slice(2).join(" ") } }) + "\n",
+);
+process.stdin.resume();
+process.stdin.on("end", () => process.exit(0));

package/src/binding.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import type { Event } from "./types.js";
+import type { Event, EventType, PayloadOf, PermissionRequested, TodoItem } from "./types.js";
 
 export interface MountOptions {
   /** Executable name or path. Defaults to "camouflage-tui" (PATH lookup). */
@@ -28,6 +28,11 @@ export interface MountOptions {
    *  compatible programmatic mode where both directions ride on the
    *  pipes the binding manages. */
   renderToTerminal?: boolean;
+  /** Renderer UI. `"inline"` prints finished output into the terminal's
+   *  normal scrollback and redraws only a small live region at the bottom;
+   *  it draws on the terminal even in the default piped mode. Default
+   *  `"fullscreen"` (the v2 alternate-screen UI). */
+  ui?: "inline" | "fullscreen";
 }
 
 export interface PermissionResponseEvent {
@@ -188,9 +193,10 @@ export interface ExitEvent {
 
 export interface CamouflageHandle extends EventEmitter {
   /** Send one event INTO the renderer. */
-  send(event_type: string, payload?: object): boolean;
+  /** Send one event to the renderer. The payload is typed per event. */
+  send<T extends EventType>(event_type: T, payload?: PayloadOf<T>): boolean;
   /** Send a pre-built Event object. */
-  sendEvent(ev: { event_type: string; payload?: object }): boolean;
+  sendEvent(ev: Event): boolean;
   /** Gracefully close: end stdin, wait for child exit, resolve with code. */
   close(): Promise<number>;
   /** Force-kill the renderer. */
@@ -226,3 +232,12 @@ export interface CamouflageHandle extends EventEmitter {
  *   await cam.close();
  */
 export function mount(opts?: MountOptions): Promise<CamouflageHandle>;
+
+/**
+ * Ask the user for permission and resolve to their answer. Resolves with
+ * `{ choice: "deny" }` if the renderer exits first, so a caller never hangs.
+ */
+export function permission(cam: CamouflageHandle, spec: PermissionRequested): Promise<PermissionResponseEvent>;
+
+/** Replace the agent's plan checklist. Pass an empty array to clear it. */
+export function tasksSet(cam: CamouflageHandle, todos: TodoItem[]): void;

package/src/binding.js

@@ -231,7 +231,7 @@ export async function mount(opts = {}) {
     defaultArgs = ["--stdin-events", "--responses-fd", "3"];
     stdio = ["pipe", "inherit", "inherit", "pipe"];
   } else {
-    defaultArgs = ["--stdin-events", "--emit-responses"];
+    defaultArgs = ["--stdin-events", "--emit-responses=true"];
     stdio = ["pipe", "pipe", stderrMode];
   }
   // Brand the header with the host app's name (explicit > auto-detected).
@@ -245,7 +245,8 @@ export async function mount(opts = {}) {
       titleArgs.push("--app-title", title);
     }
   }
-  const args = [...defaultArgs, ...titleArgs, ...userArgs];
+  const uiArgs = opts.ui && !opts.skipDefaultArgs && !userArgs.includes("--ui") ? ["--ui", opts.ui] : [];
+  const args = [...defaultArgs, ...uiArgs, ...titleArgs, ...userArgs];
 
   const child = spawn(bin, args, {
     stdio,
@@ -267,6 +268,13 @@ export async function mount(opts = {}) {
 
   const handle = new CamouflageHandle(child, child.stdin);
 
+  // If the renderer exits, writes to its stdin fail with EPIPE. Unhandled,
+  // that 'error' event would crash the host process; treat it as closed.
+  child.stdin.on("error", (err) => {
+    handle._closed = true;
+    if (err && err.code !== "EPIPE") handle.emit("invalid", { line: "", error: String(err) });
+  });
+
   // Stream outbound events (UserInputSubmitted, PermissionResponse) from
   // whichever stream the renderer is writing them to. In renderToTerminal
   // mode that's fd 3 (child.stdio[3]); otherwise it's stdout.
@@ -352,45 +360,82 @@ export async function mount(opts = {}) {
   return handle;
 }
 
+/**
+ * Resolve with the first `eventName` response whose id matches, or with
+ * `onExit` if the renderer exits first, so callers never hang on a dead
+ * renderer.
+ */
+function awaitResponse(cam, eventName, matches, onExit) {
+  return new Promise((resolve) => {
+    if (cam._closed) {
+      resolve(onExit);
+      return;
+    }
+    const cleanup = () => {
+      cam.off(eventName, listener);
+      cam.off("exit", exitListener);
+    };
+    const listener = (resp) => {
+      if (!matches(resp)) return;
+      cleanup();
+      resolve(resp);
+    };
+    const exitListener = () => {
+      cleanup();
+      resolve(onExit);
+    };
+    cam.on(eventName, listener);
+    cam.on("exit", exitListener);
+  });
+}
+
 /**
  * Convenience helper: emit a ShowSelectList and resolve to the user's
- * SelectListResponse for that id. Subscribes once, unsubscribes after
- * the response arrives.
+ * SelectListResponse for that id. Resolves `{ cancelled: true }` if the
+ * renderer exits first.
  *
  * @param {CamouflageHandle} cam
  * @param {{id: string, prompt: string, options: object[], default?: string, allow_filter?: boolean, allow_cancel?: boolean}} spec
  * @returns {Promise<{id: string, value?: string, cancelled: boolean}>}
  */
 export function selectList(cam, spec) {
-  return new Promise((resolve) => {
-    const listener = (resp) => {
-      if (resp.id !== spec.id) return;
-      cam.off("selectListResponse", listener);
-      resolve(resp);
-    };
-    cam.on("selectListResponse", listener);
-    cam.send("ShowSelectList", spec);
-  });
+  const done = awaitResponse(cam, "selectListResponse", (r) => r.id === spec.id, { id: spec.id, cancelled: true });
+  cam.send("ShowSelectList", spec);
+  return done;
 }
 
 /**
  * Convenience helper: emit a ShowConfirm and resolve to the user's
- * ConfirmResponse for that id.
+ * ConfirmResponse for that id. Resolves `{ cancelled: true }` if the
+ * renderer exits first.
  *
  * @param {CamouflageHandle} cam
  * @param {{id: string, prompt: string, yes_label?: string, no_label?: string, default?: "yes"|"no", allow_cancel?: boolean}} spec
  * @returns {Promise<{id: string, value?: boolean, cancelled: boolean}>}
  */
 export function confirm(cam, spec) {
-  return new Promise((resolve) => {
-    const listener = (resp) => {
-      if (resp.id !== spec.id) return;
-      cam.off("confirmResponse", listener);
-      resolve(resp);
-    };
-    cam.on("confirmResponse", listener);
-    cam.send("ShowConfirm", spec);
-  });
+  const done = awaitResponse(cam, "confirmResponse", (r) => r.id === spec.id, { id: spec.id, cancelled: true });
+  cam.send("ShowConfirm", spec);
+  return done;
+}
+
+/**
+ * Ask the user for permission and resolve to their answer. Resolves
+ * `{ choice: "deny" }` if the renderer exits first.
+ *
+ * @param {CamouflageHandle} cam
+ * @param {{request_id: string, tool: string, action: string, detail?: string, diff?: object}} spec
+ * @returns {Promise<{request_id: string, choice: "allow_once"|"allow_session"|"deny", feedback?: string}>}
+ */
+export function permission(cam, spec) {
+  const done = awaitResponse(
+    cam,
+    "permissionResponse",
+    (r) => r.request_id === spec.request_id,
+    { request_id: spec.request_id, choice: "deny", feedback: "" },
+  );
+  cam.send("PermissionRequested", spec);
+  return done;
 }
 
 /**
@@ -422,15 +467,9 @@ export function keyValueView(cam, spec) {
  * @returns {Promise<{id: string, values?: Record<string, string>, cancelled: boolean}>}
  */
 export function form(cam, spec) {
-  return new Promise((resolve) => {
-    const listener = (resp) => {
-      if (resp.id !== spec.id) return;
-      cam.off("formResponse", listener);
-      resolve(resp);
-    };
-    cam.on("formResponse", listener);
-    cam.send("ShowForm", spec);
-  });
+  const done = awaitResponse(cam, "formResponse", (r) => r.id === spec.id, { id: spec.id, cancelled: true });
+  cam.send("ShowForm", spec);
+  return done;
 }
 
 /**
@@ -444,25 +483,13 @@ export function form(cam, spec) {
  * @returns {Promise<{id: string, results?: Record<string, any>, cancelled?: boolean, at_step?: number}>}
  */
 export function wizard(cam, spec) {
-  return new Promise((resolve) => {
-    const onCompleted = (resp) => {
-      if (resp.id !== spec.id) return;
-      cleanup();
-      resolve(resp);
-    };
-    const onCancelled = (resp) => {
-      if (resp.id !== spec.id) return;
-      cleanup();
-      resolve({ id: resp.id, cancelled: true, at_step: resp.at_step });
-    };
-    const cleanup = () => {
-      cam.off("wizardCompleted", onCompleted);
-      cam.off("wizardCancelled", onCancelled);
-    };
-    cam.on("wizardCompleted", onCompleted);
-    cam.on("wizardCancelled", onCancelled);
-    cam.send("ShowWizard", spec);
-  });
+  const completed = awaitResponse(cam, "wizardCompleted", (r) => r.id === spec.id, null);
+  const cancelled = awaitResponse(cam, "wizardCancelled", (r) => r.id === spec.id, null);
+  cam.send("ShowWizard", spec);
+  return Promise.race([
+    completed.then((r) => r ?? { id: spec.id, cancelled: true, at_step: 0 }),
+    cancelled.then((r) => ({ id: spec.id, cancelled: true, at_step: r?.at_step ?? 0 })),
+  ]);
 }
 
 /**

package/src/binding.test.js

@@ -2,7 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { mount, selectList, confirm } from "./index.js";
+import { mount, selectList, confirm, permission } from "./index.js";
 
 const FAKE = join(dirname(fileURLToPath(import.meta.url)), "__fake-renderer.js");
 
@@ -72,10 +72,12 @@ test("permissionResponse convenience event fires", async () => {
   await cam.close();
 });
 
-test("send() throws after close()", async () => {
+test("send() after close() is a no-op that returns false", async () => {
+  // Hosts send a final StatusUpdate/SessionEnded during cleanup, often after
+  // the renderer has exited; throwing there would crash the host (496035a).
   const cam = await mountFake();
   await cam.close();
-  assert.throws(() => cam.send("SessionStarted", {}), /after close/);
+  assert.equal(cam.send("SessionStarted", {}), false);
 });
 
 test("close() resolves with the child's exit code", async () => {
@@ -135,3 +137,47 @@ async function waitUntil(predicate, deadlineMs) {
     await new Promise((r) => setTimeout(r, 10));
   }
 }
+
+test("helpers settle instead of hanging when the renderer exits", async () => {
+  const cam = await mountFake();
+  const pending = [
+    selectList(cam, { id: "pick", prompt: "Pick", options: [] }),
+    confirm(cam, { id: "ok", prompt: "OK?" }),
+    permission(cam, { request_id: "r1", tool: "bash", action: "run npm test" }),
+  ];
+  // The fake echoes inbound events back; kill it before anyone answers.
+  cam.kill("SIGKILL");
+  const [sel, conf, perm] = await Promise.all(pending);
+  assert.deepEqual(sel, { id: "pick", cancelled: true });
+  assert.deepEqual(conf, { id: "ok", cancelled: true });
+  assert.equal(perm.choice, "deny");
+});
+
+test("permission() resolves with the user's answer", async () => {
+  const cam = await mountFake();
+  const answer = permission(cam, { request_id: "r2", tool: "edit", action: "edit a.ts" });
+  // Stand in for the user: the fake echoes this response back to us.
+  cam.send("PermissionResponse", { request_id: "r2", choice: "allow_session", feedback: "" });
+  assert.equal((await answer).choice, "allow_session");
+  await cam.close();
+});
+
+test("ui option passes --ui to the renderer", async () => {
+  const fakeArgv = join(dirname(fileURLToPath(import.meta.url)), "__fake-argv.js");
+  const cam = await mount({ bin: fakeArgv, ui: "inline", appTitle: "demo" });
+  const text = await new Promise((resolve) => cam.on("userInput", resolve));
+  assert.match(text, /--ui inline/);
+  await cam.close();
+});
+
+test("a renderer that exits at startup doesn't crash the host", async () => {
+  const cam = await mount({ bin: process.execPath, args: ["-e", "process.exit(3)"], skipDefaultArgs: true });
+  const exited = new Promise((resolve) => cam.on("exit", resolve));
+  // Keep writing while (and after) the child dies; nothing may throw.
+  for (let i = 0; i < 50; i++) {
+    cam.send("AssistantTokenDelta", { stream_id: "s", token: "x".repeat(1000) });
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  await exited;
+  assert.equal(cam.send("SessionEnded", {}), false);
+});

package/src/index.d.ts

@@ -59,6 +59,13 @@ export {
   WizardStepResult,
   WizardCompleted,
   WizardCancelled,
+  SessionStarted,
+  Splash,
+  ShowToast,
+  DiffPayload,
+  TodoItem,
+  TodoListUpdate,
+  PayloadOf,
   // Tagged union
   Event,
   // Helpers
@@ -71,6 +78,8 @@ export {
   mount,
   selectList,
   confirm,
+  permission,
+  tasksSet,
   table,
   keyValueView,
   form,

package/src/index.js

@@ -15,4 +15,4 @@ export {
   encode,
 } from "./types.js";
 
-export { mount, selectList, confirm, table, keyValueView, form, wizard } from "./binding.js";
+export { mount, selectList, confirm, permission, table, keyValueView, form, wizard, tasksSet } from "./binding.js";

package/src/types.d.ts

@@ -48,7 +48,10 @@ export type EventType =
   | "WizardCompleted"
   | "WizardCancelled"
   | "ModeChangeRequested"
-  | "CancelRequested";
+  | "CancelRequested"
+  | "TranscriptCleared"
+  | "Splash"
+  | "ShowToast";
 
 export type Direction = "inbound" | "outbound";
 
@@ -65,11 +68,38 @@ export interface EnvelopeMeta {
 export type UserMessage = { text: string };
 export type AssistantStreamStarted = { stream_id: string };
 export type AssistantTokenDelta = { stream_id: string; token: string };
-export type AssistantMessageCompleted = { stream_id: string };
+export type AssistantMessageCompleted = {
+  stream_id: string;
+  /** Optional final text; replaces what was streamed (e.g. after cleanup). */
+  text?: string;
+};
 
-export type ToolStarted = { tool_id: string; tool: string; command: string };
+export type ToolStarted = {
+  tool_id: string;
+  /** Tool name shown in bold, e.g. "Read" or "Bash". */
+  tool: string;
+  /** Arguments shown after the name, e.g. a path or a command line. */
+  command: string;
+  /** When the tool started (epoch ms). Defaults to when the event arrives. */
+  started_at_ms?: number;
+};
 export type ToolOutput = { tool_id: string; chunk: string };
-export type ToolFinished = { tool_id: string; exit_code: number };
+export type ToolFinished = {
+  tool_id: string;
+  exit_code: number;
+  /** Overrides the status derived from exit_code. */
+  status?: "done" | "error" | "cancelled" | "rejected";
+  /** One-line result under the tool row, e.g. "142 lines" or "14 passed". */
+  summary?: string;
+  /** Full output; replaces anything streamed via ToolExecutionStdout. */
+  output?: string;
+  /** Output lines shown before "ctrl+o to expand". Default 0 (12 on error). */
+  preview?: number;
+  /** Highlight the output as this language (e.g. "ts" for a written file). */
+  output_lang?: string;
+  /** Show this diff under the tool row. */
+  diff?: DiffPayload;
+};
 
 export type PatchProposed = {
   path: string;
@@ -83,8 +113,11 @@ export type PatchApplied = { path: string };
 export type PermissionRequested = {
   request_id: string;
   tool: string;
+  /** Prompt title, e.g. "edit src/auth/session.ts". */
   action: string;
   detail?: string;
+  /** Diff preview for edits. */
+  diff?: DiffPayload;
 };
 export type PermissionGranted = { request_id: string };
 export type PermissionDenied = { request_id: string };
@@ -104,6 +137,14 @@ export type RuntimeError = {
   cta?: Cta;
 };
 
+/**
+ * Status segments. Well-known keys: `mode` ("edit" | "plan" | "auto"),
+ * `phase` ("thinking" | "streaming" | "tool" | "running" shows the spinner;
+ * anything else, e.g. "idle", ends the turn and settles spinners),
+ * `activity` (spinner verb, e.g. "Reading files"), `model`, `tokens`,
+ * `cost`, `branch`, `warn`. Other keys are shown in the footer. An empty
+ * value removes a segment.
+ */
 export type StatusUpdate = {
   segments: Record<string, string>;
 };
@@ -261,11 +302,42 @@ export type ModeChangeRequested = {
   direction: "next" | "prev";
 };
 
+/** Optional welcome and branding for the inline renderer. */
+export type SessionStarted = {
+  /** First welcome line, shown in the accent color. Defaults to the app title. */
+  title?: string;
+  /** Dim lines under the title (model, directory, hints). */
+  detail?: string[];
+  /** Accent color: a terminal color name ("orange", "blue", …) or "#rrggbb". */
+  accent?: string;
+  /** Your agent's name, used in prompts like "tell <name> what to do". */
+  assistant_label?: string;
+  user_label?: string;
+};
+
+/** Multi-line text (may contain ANSI colors) printed as-is, e.g. a logo. */
+export type Splash = { text: string };
+
+/** A short message shown in the footer (inline) or as a toast (full screen). */
+export type ShowToast = {
+  text: string;
+  kind?: "info" | "warn" | "error" | "success";
+  ttl_ms?: number;
+};
+
+/** A diff to show inline: full before/after text, or a unified diff. */
+export type DiffPayload = {
+  path: string;
+  before?: string;
+  after?: string;
+  unified?: string;
+};
+
 // Tagged union --------------------------------------------------------------
 
 export type Event = EnvelopeMeta &
   (
-    | { event_type: "SessionStarted"; payload?: Record<string, never> }
+    | { event_type: "SessionStarted"; payload?: SessionStarted }
     | { event_type: "SessionEnded"; payload?: Record<string, never> }
     | { event_type: "SessionCompacted"; payload: SessionCompacted }
     | { event_type: "UserMessageCreated"; payload: UserMessage }
@@ -303,8 +375,14 @@ export type Event = EnvelopeMeta &
     | { event_type: "WizardCancelled"; payload: WizardCancelled }
     | { event_type: "ModeChangeRequested"; payload: ModeChangeRequested }
     | { event_type: "CancelRequested"; payload?: Record<string, never> }
+    | { event_type: "TranscriptCleared"; payload?: Record<string, never> }
+    | { event_type: "Splash"; payload: Splash }
+    | { event_type: "ShowToast"; payload: ShowToast }
   );
 
+/** The payload type for a given event type, e.g. `PayloadOf<"ShowToast">`. */
+export type PayloadOf<T extends EventType> = Extract<Event, { event_type: T }> extends { payload?: infer P } ? P : never;
+
 // Reader --------------------------------------------------------------------
 
 import type { Readable } from "node:stream";

package/src/types.js

@@ -13,7 +13,7 @@ const KNOWN_TYPES = new Set([
   "ToolExecutionStarted", "ToolExecutionStdout", "ToolExecutionStderr", "ToolExecutionFinished",
   "PatchProposed", "PatchApplied",
   "PermissionRequested", "PermissionGranted", "PermissionDenied",
-  "RuntimeError", "StatusUpdate", "BackgroundTaskUpdate", "ViewportMarker",
+  "RuntimeError", "StatusUpdate", "BackgroundTaskUpdate", "TodoListUpdate", "ViewportMarker",
   "UserInputSubmitted", "PermissionResponse",
   "SlashCommandsRegistered", "MentionCandidatesRegistered",
   "ShowSelectList", "SelectListResponse",
@@ -22,6 +22,7 @@ const KNOWN_TYPES = new Set([
   "ShowForm", "FormResponse",
   "ShowWizard", "WizardCompleted", "WizardCancelled",
   "ModeChangeRequested", "CancelRequested",
+  "TranscriptCleared", "Splash", "ShowToast",
 ]);
 
 /**