agent-sh 0.8.0 → 0.10.0

package/examples/extensions/interactive-prompts.ts

@@ -4,34 +4,71 @@
  * Adds permission gates for tool calls and file writes.
  * Without this extension, agent-sh runs in yolo mode (auto-approve).
  *
+ * Uses the interactive UI primitive for compositor-aware, themed rendering.
+ *
  * Usage:
- *   # Load by short name (built-in):
- *   agent-sh --extensions interactive-prompts
+ *   agent-sh -e ./examples/extensions/interactive-prompts.ts
  *
  *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
  *   cp examples/extensions/interactive-prompts.ts ~/.agent-sh/extensions/
- *
- *   # Or install as an npm package and load by name:
- *   agent-sh --extensions my-prompts-package
  */
 import { renderDiff } from "agent-sh/utils/diff-renderer.js";
 import { renderBoxFrame } from "agent-sh/utils/box-frame.js";
 import { palette as p } from "agent-sh/utils/palette.js";
 import type { ExtensionContext } from "agent-sh/types";
+import type { ToolUI } from "agent-sh/agent/types.js";
 
-export default function activate({ bus }: ExtensionContext) {
+export default function activate(ctx: ExtensionContext) {
   let autoApproveWrites = false;
 
+  // Advise the TUI diff renderer to add permission prompt framing.
+  // This replaces the default plain diff box with one that has a warning
+  // border and key hints, so only one diff box is shown (not two).
+  ctx.advise("tui:render-diff", (next, filePath: string, diff: any, width: number) => {
+    const boxW = Math.min(84, width);
+    const contentW = boxW - 4;
+    const MAX_DISPLAY = 25;
+
+    const stats = diff.isNewFile
+      ? `(+${diff.added} lines)`
+      : `(+${diff.added} / -${diff.removed})`;
+    const title = diff.isNewFile
+      ? `new: ${filePath}  ${stats}`
+      : `${filePath}  ${stats}`;
+
+    const diffLines = renderDiff(diff, {
+      width: contentW,
+      filePath,
+      maxLines: MAX_DISPLAY,
+      trueColor: true,
+      mode: "unified",
+    });
+    const content = ["", ...diffLines.slice(1), ""];
+
+    return renderBoxFrame(content, {
+      width: boxW,
+      style: "rounded",
+      borderColor: p.warning,
+      title,
+      footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
+    });
+  });
+
+  const { bus } = ctx;
+
   bus.onPipeAsync("permission:request", async (payload) => {
+    const ui = payload.ui as ToolUI | undefined;
+    if (!ui) return payload;
+
     switch (payload.kind) {
       case "tool-call":
-        return handleToolCallPermission(payload);
+        return handleToolCall(payload, ui);
       case "file-write": {
         if (autoApproveWrites) {
-          return { ...payload, decision: { approved: true } };
+          return { ...payload, decision: { outcome: "approved" } };
         }
-        const result = await handleFileWritePermission(payload);
-        if (result.decision.autoApprove) {
+        const result = await handleFileWrite(payload, ui);
+        if ((result.decision as any).autoApprove) {
           autoApproveWrites = true;
         }
         return result;
@@ -42,120 +79,69 @@ export default function activate({ bus }: ExtensionContext) {
   });
 }
 
-async function handleToolCallPermission(payload) {
+async function handleToolCall(payload: any, ui: ToolUI) {
   const options = payload.metadata.options;
-  const answer = await promptPermission(payload.title);
+
+  const answer = await ui.custom<"approve" | "approve_all" | "deny">({
+    render(width) {
+      const boxW = Math.min(84, width);
+      return renderBoxFrame(
+        [`${p.bold}⚠ ${payload.title}${p.reset}`],
+        {
+          width: boxW,
+          style: "rounded",
+          borderColor: p.warning,
+          title: "Permission required",
+          footer: [`  ${p.dim}[y]es / [n]o / [a]llow all${p.reset}`],
+        },
+      );
+    },
+    handleInput(data, done) {
+      const ch = data.toLowerCase();
+      if (ch === "y") done("approve");
+      else if (ch === "a") done("approve_all");
+      else if (ch === "n" || ch === "\x1b") done("deny");
+    },
+  });
 
   if (answer === "approve" || answer === "approve_all") {
-    const option = answer === "approve_all"
-      ? options.find((o) => o.kind === "allow_always") ?? options.find((o) => o.kind === "allow_once")
-      : options.find((o) => o.kind === "allow_once" || o.kind === "allow_always");
+    const kind = answer === "approve_all" ? "allow_always" : "allow_once";
+    const option = options?.find((o: any) => o.kind === kind)
+      ?? options?.find((o: any) => o.kind === "allow_once" || o.kind === "allow_always");
     if (option) {
       return { ...payload, decision: { outcome: "selected", optionId: option.optionId } };
     }
+    return { ...payload, decision: { outcome: "approved" } };
   }
   return { ...payload, decision: { outcome: "cancelled" } };
 }
 
-async function handleFileWritePermission(payload) {
-  const diff = payload.metadata.diff;
-  const filePath = payload.metadata.path;
-  const answer = await previewDiff({ path: filePath, diff });
-  if (answer === "approve") {
-    return { ...payload, decision: { approved: true } };
-  }
-  if (answer === "approve_all") {
-    return { ...payload, decision: { approved: true, autoApprove: true } };
-  }
-  return { ...payload, decision: { approved: false } };
-}
-
-async function promptPermission(title) {
-  const termW = process.stdout.columns || 80;
-  const boxW = Math.min(84, termW);
-
-  const framed = renderBoxFrame(
-    [`${p.bold}⚠ ${title}${p.reset}`],
-    {
-      width: boxW,
-      style: "rounded",
-      borderColor: p.warning,
-      title: "Permission required",
-      footer: [`  ${p.dim}[y]es / [n]o / [a]llow all${p.reset}`],
+async function handleFileWrite(payload: any, ui: ToolUI) {
+  const answer = await ui.custom<"approve" | "approve_all" | "reject">({
+    render(width) {
+      const boxW = Math.min(84, width);
+      // Just show the prompt actions — the diff itself was already rendered
+      // by our advise on "tui:render-diff".
+      return renderBoxFrame([], {
+        width: boxW,
+        style: "rounded",
+        borderColor: p.warning,
+        footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
+      });
+    },
+    handleInput(data, done) {
+      const ch = data.toLowerCase();
+      if (ch === "y") done("approve");
+      else if (ch === "a") done("approve_all");
+      else if (ch === "n" || ch === "\x1b") done("reject");
     },
-  );
-
-  process.stdout.write("\n");
-  for (const line of framed) {
-    process.stdout.write(line + "\n");
-  }
-  process.stdout.write("  ");
-
-  return new Promise((resolve) => {
-    const handler = (data) => {
-      const ch = data.toString("utf-8").toLowerCase();
-      process.stdin.removeListener("data", handler);
-      process.stdout.write("\n");
-
-      if (ch === "y") resolve("approve");
-      else if (ch === "a") resolve("approve_all");
-      else resolve(null);
-    };
-    process.stdin.on("data", handler);
-  });
-}
-
-async function previewDiff(opts) {
-  const termW = process.stdout.columns || 80;
-  const boxW = Math.min(84, termW);
-  const contentW = boxW - 4;
-  const MAX_DISPLAY = 25;
-
-  const stats = opts.diff.isNewFile
-    ? `(+${opts.diff.added} lines)`
-    : `(+${opts.diff.added} / -${opts.diff.removed})`;
-  const title = opts.diff.isNewFile
-    ? `new: ${opts.path}  ${stats}`
-    : `${opts.path}  ${stats}`;
-
-  const diffLines = renderDiff(opts.diff, {
-    width: contentW,
-    filePath: opts.path,
-    maxLines: MAX_DISPLAY,
-    trueColor: true,
-    mode: "unified",
-  });
-  const content = ["", ...diffLines.slice(1), ""];
-
-  const framed = renderBoxFrame(content, {
-    width: boxW,
-    style: "rounded",
-    borderColor: p.warning,
-    title,
-    footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
   });
 
-  process.stdout.write("\n");
-  for (const line of framed) {
-    process.stdout.write(line + "\n");
+  if (answer === "approve") {
+    return { ...payload, decision: { outcome: "approved" } };
   }
-
-  return new Promise((resolve) => {
-    const handler = (data) => {
-      const ch = data.toString("utf-8").toLowerCase();
-      process.stdin.removeListener("data", handler);
-
-      if (ch === "y") {
-        process.stdout.write(`  ${p.success}✓ Applied${p.reset}\n`);
-        resolve("approve");
-      } else if (ch === "a") {
-        process.stdout.write(`  ${p.success}✓ Applied (auto-approve on)${p.reset}\n`);
-        resolve("approve_all");
-      } else {
-        process.stdout.write(`  ${p.error}✗ Skipped${p.reset}\n`);
-        resolve("reject");
-      }
-    };
-    process.stdin.on("data", handler);
-  });
+  if (answer === "approve_all") {
+    return { ...payload, decision: { outcome: "approved", autoApprove: true } };
+  }
+  return { ...payload, decision: { outcome: "cancelled" } };
 }

package/examples/extensions/overlay-agent.ts

@@ -5,66 +5,112 @@
  * inside vim, htop, or ssh. Composites a floating response box on top
  * of the current terminal content.
  *
- * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ * Uses createRemoteSession() to route the full tui-renderer pipeline
+ * (markdown, tool grouping, spinner, diffs) into the floating panel.
+ *
+ * Install:
+ *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
  *
- * Usage:
+ * Or load directly:
  *   agent-sh -e ./examples/extensions/overlay-agent.ts
  *
- *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
- *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
+ * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
  */
-import type { ExtensionContext } from "agent-sh/types";
-import { formatScreenContext } from "agent-sh/utils/terminal-buffer.js";
+import type { ExtensionContext, RemoteSession } from "agent-sh/types";
+import type { RenderSurface } from "agent-sh/utils/compositor";
+import { FloatingPanel } from "agent-sh/utils/floating-panel";
 
-const BOLD = "\x1b[1m";
-const CYAN = "\x1b[36m";
-const RESET = "\x1b[0m";
+/** Adapt a FloatingPanel to the RenderSurface interface. */
+function createPanelSurface(panel: FloatingPanel): RenderSurface {
+  return {
+    write(text: string): void {
+      // Handle \r (carriage return) — overwrite the current line.
+      // The spinner uses "\r  <content>\x1b[K" to update in-place.
+      if (text.startsWith("\r")) {
+        // Strip \r and any erase-line sequences
+        const cleaned = text.replace(/^\r/, "").replace(/\x1b\[\d*K/g, "");
+        if (cleaned.trim()) {
+          panel.updateLastLine(() => cleaned);
+        }
+        return;
+      }
+
+      // Regular text — may contain newlines
+      panel.appendText(text);
+    },
+    writeLine(line: string): void {
+      panel.appendLine(line);
+    },
+    get columns(): number {
+      return panel.computeGeometry().contentW;
+    },
+  };
+}
 
-export default function activate({ bus, advise, createFloatingPanel, terminalBuffer }: ExtensionContext): void {
-  const panel = createFloatingPanel({
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, registerInstruction, createRemoteSession, terminalBuffer } = ctx;
+
+  const panel = new FloatingPanel(bus, {
     trigger: "\x1c", // Ctrl+\
     dimBackground: true,
-    autoDismissMs: 2000,
+    terminalBuffer: terminalBuffer ?? undefined,
   });
 
-  // ── Inject terminal buffer into agent context ──────────────
-  if (terminalBuffer) {
-    advise("context:build-extra", (next: () => string) =>
-      formatScreenContext(terminalBuffer.readScreen(), 80, next()),
-    );
-  }
+  const panelSurface = createPanelSurface(panel);
+  let session: RemoteSession | null = null;
+
+  registerInstruction("Interactive Overlay Sessions", [
+    "When the dynamic context includes `interactive-session: true`, the user has summoned you",
+    "via a hotkey overlay from inside their live terminal. They may be in the middle of using",
+    "a program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:",
+    "- Start with terminal_read if you need to understand what's on screen.",
+    "- Prefer terminal_keys to interact with whatever is currently running.",
+    "- Use user_shell only for running new, standalone commands — not for interacting with",
+    "  what's already on screen.",
+    "- Keep responses concise — the user is in the middle of a workflow.",
+  ].join("\n"));
+
+  // ── Panel lifecycle ────────────────────────────────────────────
 
-  // ── Panel lifecycle ────────────────────────────────────────
   panel.handlers.advise("panel:submit", (_next, query: string) => {
+    if (!session) {
+      session = createRemoteSession({
+        surface: panelSurface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
+    }
     panel.setActive();
-    panel.appendLine(`${CYAN}${BOLD}❯${RESET} ${query}`);
-    panel.appendLine("");
-    bus.emit("agent:submit", { query });
+    session.submit(query);
   });
 
-  // ── Stream agent response into panel ───────────────────────
-  bus.on("agent:response-chunk", (e) => {
-    if (!panel.active) return;
-    for (const block of e.blocks) {
-      if (block.type === "text" && block.text) {
-        panel.appendText(block.text);
-      }
+  panel.handlers.advise("panel:show", (_next) => {
+    // Re-establish session if panel is shown while agent is still working
+    if (panel.active && !session) {
+      session = createRemoteSession({
+        surface: panelSurface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
     }
   });
 
-  bus.on("agent:tool-started", (e) => {
-    if (!panel.active) return;
-    panel.appendLine(`▶ ${e.title}${e.displayDetail ? " " + e.displayDetail : ""}`);
-  });
-
-  bus.on("agent:tool-completed", (e) => {
-    if (!panel.active) return;
-    const mark = e.exitCode === 0 ? " ✓" : ` ✗ exit ${e.exitCode}`;
-    panel.updateLastLine((line) => line + mark);
+  // On dismiss: close session only if agent is not actively processing.
+  // If agent is still working (phase="active"), keep session alive so
+  // output buffers in the panel and agent can keep executing tools.
+  panel.handlers.advise("panel:dismiss", (next) => {
+    next();
+    if (session && !panel.processing) {
+      session.close();
+      session = null;
+    }
   });
 
   bus.on("agent:processing-done", () => {
     if (!panel.active) return;
     panel.setDone();
+    // If panel was hidden while processing (passthrough), setDone()
+    // triggers dismiss() which closes the session above.
+    // If panel is still visible, session stays for the follow-up prompt.
   });
 }