agent-sh 0.7.0 → 0.9.0

package/examples/extensions/questionnaire.ts

@@ -0,0 +1,249 @@
+/**
+ * Questionnaire tool — the agent can ask the user one or more questions.
+ *
+ * Single question: simple option list with arrow key navigation.
+ * Multiple questions: tab bar navigation between questions.
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/questionnaire.ts
+ */
+import type { ExtensionContext } from "agent-sh/types";
+import type { InteractiveSession, ToolExecutionContext } from "agent-sh/agent/types.js";
+import { palette as p } from "agent-sh/utils/palette.js";
+
+// ── Key matching ─────────────────────────────────────────────────
+
+function isKey(data: string, key: string): boolean {
+  switch (key) {
+    case "up":     return data === "\x1b[A" || data === "\x1bOA";
+    case "down":   return data === "\x1b[B" || data === "\x1bOB";
+    case "left":   return data === "\x1b[D" || data === "\x1bOD";
+    case "right":  return data === "\x1b[C" || data === "\x1bOC";
+    case "enter":  return data === "\r" || data === "\n";
+    case "escape": return data === "\x1b";
+    case "tab":    return data === "\t";
+    default:       return data === key;
+  }
+}
+
+// ── Types ────────────────────────────────────────────────────────
+
+interface QuestionOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+interface Question {
+  id: string;
+  label: string;
+  prompt: string;
+  options: QuestionOption[];
+}
+
+interface Answer {
+  id: string;
+  value: string;
+  label: string;
+  index: number;
+}
+
+interface QuestionnaireResult {
+  answers: Answer[];
+  cancelled: boolean;
+}
+
+// ── Extension ────────────────────────────────────────────────────
+
+export default function activate({ registerTool }: ExtensionContext) {
+  registerTool({
+    name: "questionnaire",
+    displayName: "questionnaire",
+    description:
+      "Ask the user one or more questions with selectable options. " +
+      "Use for clarifying requirements, getting preferences, or confirming decisions. " +
+      "For single questions, shows a simple option list. " +
+      "For multiple questions, shows a tab-based interface.",
+    input_schema: {
+      type: "object",
+      properties: {
+        questions: {
+          type: "array",
+          description: "Questions to ask the user",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Unique identifier" },
+              label: { type: "string", description: "Short label for tab bar (defaults to Q1, Q2)" },
+              prompt: { type: "string", description: "The full question text" },
+              options: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    value: { type: "string", description: "Value returned when selected" },
+                    label: { type: "string", description: "Display label" },
+                    description: { type: "string", description: "Optional description" },
+                  },
+                  required: ["value", "label"],
+                },
+              },
+            },
+            required: ["id", "prompt", "options"],
+          },
+        },
+      },
+      required: ["questions"],
+    },
+
+    async execute(args, _onChunk, ctx?: ToolExecutionContext) {
+      if (!ctx?.ui) {
+        return { content: "Error: interactive UI not available", exitCode: 1, isError: true };
+      }
+
+      const rawQuestions = args.questions as any[];
+      if (!rawQuestions?.length) {
+        return { content: "Error: no questions provided", exitCode: 1, isError: true };
+      }
+
+      const questions: Question[] = rawQuestions.map((q, i) => ({
+        ...q,
+        label: q.label || `Q${i + 1}`,
+      }));
+
+      const result = await ctx.ui.custom<QuestionnaireResult>(
+        createSession(questions),
+      );
+
+      if (result.cancelled) {
+        return { content: "User cancelled the questionnaire.", exitCode: 1, isError: false };
+      }
+
+      const lines = result.answers.map((a) => {
+        const q = questions.find((q) => q.id === a.id);
+        return `${q?.label ?? a.id}: ${a.index + 1}. ${a.label}`;
+      });
+
+      return { content: lines.join("\n"), exitCode: 0, isError: false };
+    },
+
+    getDisplayInfo: () => ({ kind: "execute" as const, icon: "?" }),
+
+    formatCall(args) {
+      const qs = (args.questions as any[]) ?? [];
+      const labels = qs.map((q: any) => q.label || q.id).join(", ");
+      return `${qs.length} question${qs.length !== 1 ? "s" : ""}${labels ? ` (${labels})` : ""}`;
+    },
+  });
+}
+
+// ── Interactive session ──────────────────────────────────────────
+
+function createSession(questions: Question[]): InteractiveSession<QuestionnaireResult> {
+  const isMulti = questions.length > 1;
+  let tab = 0;
+  let optionIdx = 0;
+  const answers = new Map<string, Answer>();
+
+  return {
+    render(width) {
+      const w = Math.min(80, width);
+      const lines: string[] = [];
+      const q = questions[tab];
+
+      lines.push(`${p.muted}${"─".repeat(w)}${p.reset}`);
+
+      // Tab bar for multi-question
+      if (isMulti) {
+        const tabs: string[] = [];
+        for (let i = 0; i < questions.length; i++) {
+          const answered = answers.has(questions[i].id);
+          const active = i === tab;
+          const box = answered ? "■" : "□";
+          const label = ` ${box} ${questions[i].label} `;
+          tabs.push(active
+            ? `${p.accent}${p.bold}${label}${p.reset}`
+            : `${p.muted}${label}${p.reset}`);
+        }
+        lines.push(` ${tabs.join(" ")}`);
+        lines.push("");
+      }
+
+      // Question + options
+      if (q) {
+        lines.push(` ${q.prompt}`);
+        lines.push("");
+        for (let i = 0; i < q.options.length; i++) {
+          const opt = q.options[i];
+          const sel = i === optionIdx;
+          const prefix = sel ? `${p.accent}> ${p.reset}` : "  ";
+          lines.push(`${prefix}${sel ? p.accent : ""}${i + 1}. ${opt.label}${sel ? p.reset : ""}`);
+          if (opt.description) {
+            lines.push(`     ${p.muted}${opt.description}${p.reset}`);
+          }
+        }
+      }
+
+      lines.push("");
+      lines.push(isMulti
+        ? ` ${p.dim}Tab/←→ navigate • ↑↓ select • Enter confirm • Esc cancel${p.reset}`
+        : ` ${p.dim}↑↓ navigate • Enter select • Esc cancel${p.reset}`);
+      lines.push(`${p.muted}${"─".repeat(w)}${p.reset}`);
+
+      return lines;
+    },
+
+    handleInput(data, done) {
+      const q = questions[tab];
+
+      if (isKey(data, "escape")) {
+        done({ answers: [], cancelled: true });
+        return;
+      }
+
+      // Tab navigation
+      if (isMulti) {
+        if (isKey(data, "tab") || isKey(data, "right")) {
+          tab = (tab + 1) % questions.length;
+          optionIdx = 0;
+          return;
+        }
+        if (isKey(data, "left")) {
+          tab = (tab - 1 + questions.length) % questions.length;
+          optionIdx = 0;
+          return;
+        }
+      }
+
+      if (!q) return;
+
+      if (isKey(data, "up")) {
+        optionIdx = Math.max(0, optionIdx - 1);
+        return;
+      }
+      if (isKey(data, "down")) {
+        optionIdx = Math.min(q.options.length - 1, optionIdx + 1);
+        return;
+      }
+
+      if (isKey(data, "enter")) {
+        const opt = q.options[optionIdx];
+        answers.set(q.id, { id: q.id, value: opt.value, label: opt.label, index: optionIdx });
+
+        if (!isMulti) {
+          done({ answers: Array.from(answers.values()), cancelled: false });
+          return;
+        }
+
+        // Advance to next unanswered or finish
+        const unanswered = questions.findIndex((q) => !answers.has(q.id));
+        if (unanswered === -1) {
+          done({ answers: Array.from(answers.values()), cancelled: false });
+        } else {
+          tab = unanswered;
+          optionIdx = 0;
+        }
+      }
+    },
+  };
+}

package/examples/extensions/tmux-pane.ts

@@ -0,0 +1,307 @@
+/**
+ * Tmux side-pane extension.
+ *
+ * Two modes:
+ *   /split  — agent output renders in the side pane, queries typed
+ *             in the main shell (> prompt).
+ *   /rsplit — reverse split: the side pane has its own input prompt,
+ *             the agent can see and control the main pane via
+ *             terminal_read / terminal_keys.
+ *
+ * Both modes use createRemoteSession() which handles compositor
+ * routing, shell lifecycle, and chrome suppression automatically.
+ *
+ * Usage:
+ *   ash -e ./examples/extensions/tmux-pane.ts
+ *
+ *   # Or install permanently
+ *   cp examples/extensions/tmux-pane.ts ~/.agent-sh/extensions/
+ */
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execSync, spawn } from "node:child_process";
+import type { ExtensionContext, RenderSurface, RemoteSession } from "agent-sh/types";
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function inTmux(): boolean {
+  return !!process.env.TMUX;
+}
+
+function tmux(...args: string[]): string {
+  return execSync(
+    "tmux " + args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(" "),
+    { encoding: "utf-8" },
+  ).trim();
+}
+
+function getPaneWidth(paneId: string): number {
+  try {
+    return parseInt(tmux("display-message", "-p", "-t", paneId, "#{pane_width}"), 10) || 80;
+  } catch {
+    return 80;
+  }
+}
+
+function paneExists(paneId: string): boolean {
+  try {
+    tmux("display-message", "-p", "-t", paneId, "#{pane_id}");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Chat client script (runs in rsplit pane) ────────────────────
+
+const CHAT_CLIENT_SCRIPT = `
+const net = require("net");
+const readline = require("readline");
+
+const sockPath = process.argv[2];
+if (!sockPath) { console.error("No socket path"); process.exit(1); }
+
+const sock = net.createConnection(sockPath);
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+sock.on("data", (data) => {
+  readline.clearLine(process.stdout, 0);
+  readline.cursorTo(process.stdout, 0);
+  process.stdout.write(data.toString());
+  rl.prompt(true);
+});
+
+sock.on("end", () => process.exit(0));
+sock.on("error", () => process.exit(1));
+
+rl.setPrompt("\\x1b[36m❯\\x1b[0m ");
+rl.prompt();
+
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) { rl.prompt(); return; }
+  sock.write(trimmed + "\\n");
+});
+
+rl.on("close", () => { sock.end(); process.exit(0); });
+`;
+
+// ── Surface factory ─────────────────────────────────────────────
+
+function createSurface(
+  paneId: string,
+  ttyFd: fs.WriteStream,
+  socketClient: () => net.Socket | undefined,
+): RenderSurface {
+  let cachedWidth = getPaneWidth(paneId);
+  let lastWidthCheck = Date.now();
+
+  return {
+    write(text: string): void {
+      // In rsplit mode, route through socket so client can manage prompt
+      const c = socketClient();
+      if (c && !c.destroyed) {
+        try { c.write(text); } catch {}
+        return;
+      }
+      // In split mode (or fallback), write directly to tty
+      if (ttyFd.destroyed) return;
+      try { ttyFd.write(text); } catch {}
+    },
+    writeLine(line: string): void {
+      this.write(line + "\n");
+    },
+    get columns(): number {
+      const now = Date.now();
+      if (now - lastWidthCheck > 2000) {
+        cachedWidth = getPaneWidth(paneId);
+        lastWidthCheck = now;
+      }
+      return cachedWidth;
+    },
+  };
+}
+
+// ── Pane state ──────────────────────────────────────────────────
+
+type PaneMode = "split" | "rsplit";
+
+interface PaneState {
+  mode: PaneMode;
+  paneId: string;
+  ttyFd: fs.WriteStream;
+  session: RemoteSession;
+  // rsplit-mode only
+  server?: net.Server;
+  client?: net.Socket;
+  sockPath?: string;
+  scriptPath?: string;
+}
+
+// ── Extension ───────────────────────────────────────────────────
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, registerCommand, registerInstruction, createRemoteSession } = ctx;
+
+  if (!inTmux()) return;
+
+  let state: PaneState | null = null;
+
+  registerInstruction("Tmux Interactive Session", [
+    "When the dynamic context includes `interactive-session: true`, the user is chatting",
+    "with you in a side pane next to their terminal. They may have a program running in",
+    "the other pane (vim, htop, a REPL, etc.). In this mode:",
+    "- Use terminal_read to see what's on their screen.",
+    "- Use terminal_keys to interact with their running program.",
+    "- Use user_shell only for standalone commands, not for interacting with what's on screen.",
+    "- Keep responses concise.",
+  ].join("\n"));
+
+  // ── Open / close ──────────────────────────────────────────────
+
+  function openSplit(): void {
+    if (state) close();
+
+    try {
+      const paneId = tmux(
+        "split-window", "-h", "-l", "45%",
+        "-P", "-F", "#{pane_id}", "cat",
+      ).trim();
+      execSync("sleep 0.1");
+
+      const tty = tmux("display-message", "-p", "-t", paneId, "#{pane_tty}");
+      const ttyFd = fs.createWriteStream(tty, { flags: "w" });
+      ttyFd.on("error", () => destroyStale());
+
+      const surface = createSurface(paneId, ttyFd, () => undefined);
+      const session = createRemoteSession({ surface });
+
+      state = { mode: "split", paneId, ttyFd, session };
+      surface.writeLine("\x1b[2m── agent output ──\x1b[0m\n");
+      bus.emit("ui:info", { message: "Split pane opened (/split to close, /rsplit for interactive)." });
+    } catch (e) {
+      bus.emit("ui:error", {
+        message: `Failed to open split: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  function openRsplit(): void {
+    if (state) close();
+
+    try {
+      const sockPath = path.join(os.tmpdir(), `agent-sh-chat-${process.pid}.sock`);
+      try { fs.unlinkSync(sockPath); } catch {}
+
+      let client: net.Socket | undefined;
+
+      const server = net.createServer((conn) => {
+        client = conn;
+        if (state) state.client = conn;
+        conn.on("data", (data) => {
+          for (const line of data.toString().split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed) session.submit(trimmed);
+          }
+        });
+        conn.on("end", () => { client = undefined; if (state) state.client = undefined; });
+        conn.on("error", () => { client = undefined; if (state) state.client = undefined; });
+      });
+      server.listen(sockPath);
+
+      const scriptPath = path.join(os.tmpdir(), `agent-sh-chat-${process.pid}.js`);
+      fs.writeFileSync(scriptPath, CHAT_CLIENT_SCRIPT);
+
+      const paneId = tmux(
+        "split-window", "-h", "-l", "45%",
+        "-P", "-F", "#{pane_id}",
+        "node", scriptPath, sockPath,
+      ).trim();
+      execSync("sleep 0.2");
+
+      const tty = tmux("display-message", "-p", "-t", paneId, "#{pane_tty}");
+      const ttyFd = fs.createWriteStream(tty, { flags: "w" });
+      ttyFd.on("error", () => destroyStale());
+
+      const surface = createSurface(paneId, ttyFd, () => client);
+      const session = createRemoteSession({
+        surface,
+        suppressQueryBox: true,
+        interactive: true,
+      });
+
+      state = { mode: "rsplit", paneId, ttyFd, session, server, client, sockPath, scriptPath };
+      bus.emit("ui:info", { message: "Reverse split opened (/rsplit to close, /split for output-only)." });
+    } catch (e) {
+      bus.emit("ui:error", {
+        message: `Failed to open rsplit: ${e instanceof Error ? e.message : String(e)}`,
+      });
+      if (state) close();
+    }
+  }
+
+  function close(): void {
+    if (!state) return;
+    const s = state;
+    state = null;
+
+    s.session.close();
+    if (s.client) { try { s.client.end(); } catch {} }
+    if (s.server) { try { s.server.close(); } catch {} }
+    try { s.ttyFd.end(); } catch {}
+    try { tmux("kill-pane", "-t", s.paneId); } catch {}
+    if (s.sockPath) { try { fs.unlinkSync(s.sockPath); } catch {} }
+    if (s.scriptPath) { try { fs.unlinkSync(s.scriptPath); } catch {} }
+  }
+
+  function destroyStale(): void {
+    if (!state) return;
+    const s = state;
+    state = null;
+
+    s.session.close();
+    if (s.client) { try { s.client.end(); } catch {} }
+    if (s.server) { try { s.server.close(); } catch {} }
+    try { s.ttyFd.end(); } catch {}
+    if (s.sockPath) { try { fs.unlinkSync(s.sockPath); } catch {} }
+    if (s.scriptPath) { try { fs.unlinkSync(s.scriptPath); } catch {} }
+  }
+
+  // ── Commands ──────────────────────────────────────────────────
+
+  registerCommand("split", "Toggle tmux side pane for agent output", (args) => {
+    const cmd = args.trim().toLowerCase();
+    if (cmd === "close") return close();
+    if (cmd === "open") return openSplit();
+    if (state?.mode === "split") close(); else openSplit();
+  });
+
+  registerCommand("rsplit", "Toggle interactive tmux side pane (reverse split)", (args) => {
+    const cmd = args.trim().toLowerCase();
+    if (cmd === "close") return close();
+    if (cmd === "open") return openRsplit();
+    if (state?.mode === "rsplit") close(); else openRsplit();
+  });
+
+  // ── Lifecycle events ──────────────────────────────────────────
+
+  // In split mode, redraw prompt immediately after query submit.
+  bus.on("agent:query", () => {
+    if (state?.mode !== "split") return;
+    setImmediate(() => bus.emit("shell:pty-write", { data: "\n" }));
+  });
+
+  // In rsplit mode, re-prompt the client after agent finishes.
+  bus.on("agent:processing-done", () => {
+    if (!state) return;
+    if (!paneExists(state.paneId)) { destroyStale(); return; }
+    if (state.mode === "rsplit" && state.client && !state.client.destroyed) {
+      state.client.write("\n");
+    }
+    state.session.surface.writeLine("");
+  });
+
+  process.on("exit", () => { if (state) close(); });
+}