camouflage-tui 2.4.0-beta.6 → 2.4.0-beta.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camouflage-tui",
-  "version": "2.4.0-beta.6",
+  "version": "2.4.0-beta.7",
   "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/binding.d.ts

@@ -69,6 +69,16 @@ export function confirm(
   },
 ): Promise<ConfirmResponseEvent>;
 
+/**
+ * Hand the terminal to a child process; resolves once the renderer has let
+ * go of it. `supported: false` means run the child without a terminal
+ * (Windows, full-screen mode, older renderers, or no answer in time).
+ */
+export function suspendTerminal(cam: CamouflageHandle, opts?: { timeoutMs?: number }): Promise<{ supported: boolean }>;
+
+/** Take the terminal back after `suspendTerminal`. */
+export function resumeTerminal(cam: CamouflageHandle): void;
+
 /** Convenience helper: show a tabular data view. Display-only. */
 export function table(
   cam: CamouflageHandle,

package/src/binding.js

@@ -344,6 +344,8 @@ export async function mount(opts = {}) {
       handle.emit("cancelRequested", {});
     } else if (ev.event_type === "MentionQuery") {
       handle.emit("mentionQuery", { query: ev.payload?.query ?? "" });
+    } else if (ev.event_type === "TerminalSuspended") {
+      handle.emit("terminalSuspended", { id: ev.payload?.id, supported: ev.payload?.supported === true });
     }
     // Always also emit the raw Event for advanced consumers.
     handle.emit("event", ev);
@@ -421,6 +423,41 @@ export function confirm(cam, spec) {
   return done;
 }
 
+/**
+ * Hand the terminal to a child process (a `!` shell command, an editor, a
+ * login prompt). The inline renderer clears its live area, leaves raw mode
+ * and stops reading keys before this resolves. Run the child with
+ * `stdio: "inherit"`, then call `resumeTerminal(cam)`.
+ *
+ * Resolves `{ supported: false }` when the renderer can't hand the terminal
+ * over (Windows, full-screen mode, renderers older than 2.4.0-beta.7, or no
+ * answer within `timeoutMs`); run the child without a terminal then.
+ *
+ * @param {CamouflageHandle} cam
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<{supported: boolean}>}
+ */
+export function suspendTerminal(cam, opts = {}) {
+  const id = `suspend-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const answer = awaitResponse(cam, "terminalSuspended", (r) => r.id === id, { id, supported: false });
+  const timeout = new Promise((resolve) => {
+    const t = setTimeout(() => resolve({ id, supported: false }), opts.timeoutMs ?? 1000);
+    t.unref?.();
+  });
+  cam.send("TerminalSuspend", { id });
+  return Promise.race([answer, timeout]).then((r) => ({ supported: r.supported === true }));
+}
+
+/**
+ * Take the terminal back after `suspendTerminal`: the renderer re-enters
+ * raw mode and redraws below whatever the child printed.
+ *
+ * @param {CamouflageHandle} cam
+ */
+export function resumeTerminal(cam) {
+  cam.send("TerminalResume", { id: "resume" });
+}
+
 /**
  * Ask the user for permission and resolve to their answer. Resolves
  * `{ choice: "deny" }` if the renderer exits first.

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, permission } from "./index.js";
+import { mount, selectList, confirm, permission, suspendTerminal, resumeTerminal } from "./index.js";
 
 const FAKE = join(dirname(fileURLToPath(import.meta.url)), "__fake-renderer.js");
 
@@ -181,3 +181,11 @@ test("a renderer that exits at startup doesn't crash the host", async () => {
   await exited;
   assert.equal(cam.send("SessionEnded", {}), false);
 });
+
+test("suspendTerminal() falls back to unsupported when the renderer doesn't answer", async () => {
+  const cam = await mountFake(); // echoes TerminalSuspend back; never sends TerminalSuspended
+  const r = await suspendTerminal(cam, { timeoutMs: 50 });
+  assert.deepEqual(r, { supported: false });
+  resumeTerminal(cam);
+  await cam.close();
+});

package/src/index.d.ts

@@ -78,6 +78,8 @@ export {
   mount,
   selectList,
   confirm,
+  suspendTerminal,
+  resumeTerminal,
   permission,
   tasksSet,
   table,

package/src/index.js

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

package/src/types.d.ts

@@ -53,7 +53,10 @@ export type EventType =
   | "Splash"
   | "ShowToast"
   | "MentionQuery"
-  | "AssistantReasoningDelta";
+  | "AssistantReasoningDelta"
+  | "TerminalSuspend"
+  | "TerminalResume"
+  | "TerminalSuspended";
 
 export type Direction = "inbound" | "outbound";
 
@@ -370,6 +373,10 @@ export type Event = EnvelopeMeta &
     | { event_type: "AssistantTokenDelta"; payload: AssistantTokenDelta }
     /** v2.4+: the model's reasoning, shown when the user presses Ctrl+R (inline UI). */
     | { event_type: "AssistantReasoningDelta"; payload: AssistantTokenDelta }
+    /** v2.4+: hand the terminal to a child process; see `suspendTerminal()`. */
+    | { event_type: "TerminalSuspend"; payload: { id: string } }
+    | { event_type: "TerminalResume"; payload: { id: string } }
+    | { event_type: "TerminalSuspended"; payload: { id: string; supported: boolean } }
     | { event_type: "AssistantMessageCompleted"; payload: AssistantMessageCompleted }
     | { event_type: "ToolExecutionStarted"; payload: ToolStarted }
     | { event_type: "ToolExecutionStdout"; payload: ToolOutput }

package/src/types.js

@@ -24,6 +24,7 @@ const KNOWN_TYPES = new Set([
   "ModeChangeRequested", "CancelRequested",
   "TranscriptCleared", "Splash", "ShowToast", "MentionQuery",
   "AssistantReasoningDelta",
+  "TerminalSuspend", "TerminalResume", "TerminalSuspended",
 ]);
 
 /**