agent-sh 0.8.0 → 0.10.0

package/examples/extensions/questionnaire.ts

@@ -0,0 +1,260 @@
+/**
+ * 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, registerInstruction }: ExtensionContext) {
+  registerInstruction("questionnaire", [
+    "# When to use the questionnaire tool",
+    "ALWAYS use the `questionnaire` tool instead of asking the user a question in plain text when:",
+    "- You need the user to choose from specific options (e.g. frameworks, approaches, yes/no decisions)",
+    "- You are unsure about a preference and can enumerate reasonable choices",
+    "- The user's answer determines a significant branch in your behavior",
+    "",
+    "Do NOT just list options in your reply prose — call the questionnaire tool so the user can select interactively.",
+    "This applies to single questions too (yes/no, pick-one).",
+  ].join("\n"));
+
+  registerTool({
+    name: "questionnaire",
+    displayName: "questionnaire",
+    description:
+      "Present the user with one or more questions with selectable options and wait for their interactive response. " +
+      "PREFER THIS over asking questions in plain text — it gives the user an interactive picker (arrow keys + enter). " +
+      "Use for: clarifying requirements, getting preferences, confirming decisions, choosing between options. " +
+      "Single question → simple option list. Multiple questions → tab-based multi-page 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/subagents.ts

@@ -8,8 +8,8 @@
  * Usage:
  *   agent-sh -e ./examples/extensions/subagents.ts
  */
-import type { ExtensionContext } from "../../src/types.js";
-import { runSubagent } from "../../src/agent/subagent.js";
+import type { ExtensionContext } from "agent-sh/types";
+import { runSubagent } from "agent-sh/agent/subagent";
 
 export default function activate(ctx: ExtensionContext): void {
   const { bus, llmClient, contextManager } = ctx;
@@ -17,6 +17,12 @@ export default function activate(ctx: ExtensionContext): void {
 
   const allToolNames = () => ctx.getTools().map(t => t.name);
 
+  ctx.registerInstruction("subagent-guide", [
+    "You have a spawn_agent tool for delegating work to a subagent with its own context.",
+    "The subagent inherits your session history, so write a short directive (what to do), not a briefing (what happened).",
+    "Use it for tasks that need multiple tool calls you don't need to see — research, exploration, independent implementation.",
+  ].join("\n"));
+
   ctx.registerTool({
     name: "spawn_agent",
     description:
@@ -44,8 +50,15 @@ export default function activate(ctx: ExtensionContext): void {
 
     getDisplayInfo: () => ({
       kind: "execute",
+      icon: "⤵",
     }),
 
+    formatCall: (args) => {
+      const task = String(args.task ?? "");
+      const max = 80;
+      return task.length > max ? task.slice(0, max - 1) + "…" : task;
+    },
+
     async execute(args) {
       const task = args.task as string;
       const toolNames = args.tools as string[] | undefined;
@@ -56,9 +69,12 @@ export default function activate(ctx: ExtensionContext): void {
         ? allTools.filter(t => toolNames.includes(t.name))
         : allTools.filter(t => t.name !== "spawn_agent");
 
+      const nuclearSummary = bus.emitPipe("agent:get-nuclear-summary", { summary: null }).summary;
+
       const systemPrompt =
         `You are a focused subagent. Complete the task and return a clear, concise result.\n` +
-        `Working directory: ${contextManager.getCwd()}`;
+        `Working directory: ${contextManager.getCwd()}` +
+        (nuclearSummary ? `\n\n[Parent session history]\n${nuclearSummary}` : "");
 
       try {
         const result = await runSubagent({
@@ -66,7 +82,6 @@ export default function activate(ctx: ExtensionContext): void {
           tools,
           systemPrompt,
           task,
-          bus,
           maxIterations: 25,
         });
 

package/examples/extensions/terminal-buffer.ts

@@ -1,11 +1,6 @@
 /**
  * Terminal buffer extension.
  *
- * Maintains a headless xterm.js terminal fed from raw PTY data.
- * Provides an accurate, clean-text snapshot of the terminal screen
- * that the agent can use for context — handling ANSI codes, cursor
- * movement, alternate screen (vim/htop), and line wrapping correctly.
- *
  * Registers two agent tools:
  *   - terminal_read: get the current screen contents + cursor position
  *   - terminal_keys: send raw keystrokes into the user's live PTY
@@ -13,22 +8,15 @@
  * Together these let the agent operate inside interactive programs
  * (vim, htop, less, etc.) by reading the screen and typing keys.
  *
- * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
- *
- * Usage:
- *   agent-sh -e ./examples/extensions/terminal-buffer.ts
+ * Requires xterm in the extension directory:
+ *   npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
  *
- *   # Or copy to ~/.agent-sh/extensions/ for permanent use:
- *   cp examples/extensions/terminal-buffer.ts ~/.agent-sh/extensions/
+ * Core already loads xterm lazily (for floating-panel compositing), so
+ * installing these deps anywhere on the NODE_PATH is enough.
  */
 import type { ExtensionContext } from "agent-sh/types";
 
-/** Wait for PTY output to settle after sending keystrokes. */
-function settle(ms = 100): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/** Interpret C-style escape sequences in a string (e.g. \r → CR, \x1b → ESC). */
+/** Interpret C-style escape sequences (e.g. \r → CR, \x1b → ESC). */
 function interpretEscapes(str: string): string {
   return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq: string) => {
     if (seq === "r") return "\r";
@@ -41,27 +29,32 @@ function interpretEscapes(str: string): string {
   });
 }
 
-export default function activate({ bus, terminalBuffer: tb, registerTool }: ExtensionContext): void {
-  if (!tb) {
-    console.warn("terminal-buffer: @xterm/headless not installed — extension disabled");
-    return;
-  }
+function settle(ms = 100): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
-  // ── Agent tools ─────────────────────────────────────────────
-  // Context injection is intentionally NOT done here — the terminal
-  // buffer content would bloat every agent message.  The agent can
-  // call terminal_read on demand, and the overlay extension injects
-  // context only when the overlay is active.
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, terminalBuffer: tb, registerTool, registerInstruction } = ctx;
+  if (!tb) return; // @xterm/headless not installed
 
   registerTool({
     name: "terminal_read",
     description:
-      "Read the current terminal screen contents. Returns clean text (ANSI stripped) " +
+      "Read what is currently visible on the user's terminal screen. Returns clean text (ANSI stripped) " +
       "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
-      "Use this to see what the user sees before sending keystrokes with terminal_keys.",
+      "Use this to observe what the user sees — helpful for answering questions about terminal output, " +
+      "diagnosing errors on screen, or checking state before/after sending keystrokes with terminal_keys.",
     input_schema: {
       type: "object",
-      properties: {},
+      properties: {
+        include_scrollback: {
+          type: "boolean",
+          description:
+            "If true, include scrollback buffer (content that scrolled off screen) " +
+            "in addition to the visible viewport. Useful for capturing output from " +
+            "long-running or streaming commands. Default: false.",
+        },
+      },
     },
     showOutput: true,
 
@@ -71,8 +64,9 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
       locations: [],
     }),
 
-    async execute() {
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
+    async execute(args) {
+      const includeScrollback = (args.include_scrollback as boolean) ?? false;
+      const { text, altScreen, cursorX, cursorY } = tb.readScreen({ includeScrollback });
       const info = [
         altScreen ? "mode: alternate screen" : "mode: normal",
         `cursor: row=${cursorY} col=${cursorX}`,
@@ -89,8 +83,10 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
   registerTool({
     name: "terminal_keys",
     description:
-      "Send keystrokes to the user's live terminal. The keys are written directly to the PTY " +
-      "as if the user typed them. Use escape sequences for special keys:\n" +
+      "Send keystrokes directly into the user's live terminal PTY, as if the user typed them. " +
+      "Use this to interact with programs already running in the terminal (vim, htop, less, ssh, REPLs, etc.) " +
+      "or to type commands at the shell prompt. This types directly into whatever is currently on screen.\n\n" +
+      "Escape sequences for special keys:\n" +
       "  - Escape: \\x1b\n" +
       "  - Enter/Return: \\r\n" +
       "  - Tab: \\t\n" +
@@ -121,7 +117,7 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
     },
     showOutput: false,
 
-    getDisplayInfo: (args) => ({
+    getDisplayInfo: () => ({
       kind: "execute" as const,
       icon: "⌨",
       locations: [],
@@ -129,8 +125,6 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
 
     formatCall: (args) => {
       const keys = args.keys as string;
-      // Show a readable version of the keys — handle both literal
-      // escape strings (\\x1b) and actual bytes (\x1b)
       return keys
         .replace(/\\x1b|\x1b/g, "ESC")
         .replace(/\\r|\r/g, "⏎")
@@ -146,17 +140,13 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
       const keys = interpretEscapes(raw);
       const settleMs = (args.settle_ms as number) ?? 150;
 
-      // Force PTY output visible so the user sees the program's response.
-      // Stays visible for the rest of agent processing — Shell resets
-      // paused=false on processing-done anyway.
       bus.emit("shell:stdout-show", {});
       process.stdout.write("\n");
       bus.emit("shell:pty-write", { data: keys });
 
-      // Wait for the terminal to process the keystrokes and render
       await settle(settleMs);
+      bus.emit("shell:stdout-hide", {});
 
-      // Return the screen state after the keystrokes
       const { text, altScreen, cursorX, cursorY } = tb.readScreen();
       const info = [
         altScreen ? "mode: alternate screen" : "mode: normal",
@@ -170,15 +160,4 @@ export default function activate({ bus, terminalBuffer: tb, registerTool }: Exte
       };
     },
   });
-
-  // ── Bus snapshot for other extensions ───────────────────────
-
-  bus.on("shell:buffer-request", () => {
-    const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-    bus.emit("shell:buffer-snapshot", {
-      text,
-      altScreen,
-      cursor: { x: cursorX, y: cursorY },
-    });
-  });
 }