agent-sh 0.2.0 → 0.3.0

package/dist/utils/line-editor.js

@@ -5,12 +5,22 @@
  * terminal input bytes and receive high-level actions back. Buffer and
  * cursor state are public for rendering.
  */
+// ── Kitty protocol keycode → readable name ──────────────────────
+const KITTY_KEY_NAMES = {
+    9: "tab", 13: "enter", 27: "escape", 127: "backspace",
+};
 // ── Line editor ─────────────────────────────────────────────────
 export class LineEditor {
     buffer = "";
     cursor = 0;
+    pendingSeq = ""; // buffered incomplete escape sequence
     /** Process raw terminal input, return actions for the consumer. */
     feed(data) {
+        // If we had a pending incomplete escape sequence, prepend it
+        if (this.pendingSeq) {
+            data = this.pendingSeq + data;
+            this.pendingSeq = "";
+        }
         const actions = [];
         let i = 0;
         while (i < data.length) {
@@ -18,16 +28,66 @@ export class LineEditor {
             // ── Escape sequences ────────────────────────────────
             if (ch === "\x1b") {
                 const next = data[i + 1];
-                // Bare Escape (nothing follows in this chunk)
+                // Incomplete escape — buffer and wait for next feed()
                 if (next == null) {
-                    actions.push({ action: "cancel" });
+                    this.pendingSeq = "\x1b";
                     i++;
                     continue;
                 }
                 // CSI sequence: \x1b[...
                 if (next === "[") {
-                    const { consumed } = this.handleCSI(data, i, actions);
-                    i += consumed;
+                    const { consumed, incomplete } = this.handleCSI(data, i, actions);
+                    if (incomplete) {
+                        this.pendingSeq = data.slice(i, i + consumed);
+                        i += consumed;
+                    }
+                    else {
+                        i += consumed;
+                    }
+                    continue;
+                }
+                // SS3 sequence: \x1bO... (application cursor mode — arrow keys, Home, End)
+                if (next === "O") {
+                    const ss3Final = data[i + 2];
+                    if (ss3Final == null) {
+                        // Incomplete — buffer for next feed()
+                        this.pendingSeq = data.slice(i, i + 2);
+                        i += 2;
+                        continue;
+                    }
+                    i += 3; // consume \x1b O <final>
+                    switch (ss3Final) {
+                        case "A":
+                            actions.push({ action: "arrow-up" });
+                            break;
+                        case "B":
+                            actions.push({ action: "arrow-down" });
+                            break;
+                        case "C":
+                            if (this.cursor < this.buffer.length) {
+                                this.cursor++;
+                                actions.push({ action: "changed" });
+                            }
+                            break;
+                        case "D":
+                            if (this.cursor > 0) {
+                                this.cursor--;
+                                actions.push({ action: "changed" });
+                            }
+                            break;
+                        case "H": // Home
+                            if (this.cursor > 0) {
+                                this.cursor = 0;
+                                actions.push({ action: "changed" });
+                            }
+                            break;
+                        case "F": // End
+                            if (this.cursor < this.buffer.length) {
+                                this.cursor = this.buffer.length;
+                                actions.push({ action: "changed" });
+                            }
+                            break;
+                    }
                     continue;
                 }
                 // Alt/Option + key: \x1b followed by char
@@ -56,98 +116,10 @@ export class LineEditor {
                 continue;
             }
             // ── Control characters ──────────────────────────────
-            if (ch === "\r") {
-                actions.push({ action: "submit", buffer: this.buffer });
-                i++;
-                continue;
-            }
-            if (ch === "\x03") {
-                actions.push({ action: "cancel" });
-                i++;
-                continue;
-            }
-            if (ch === "\t") {
-                actions.push({ action: "tab" });
-                i++;
-                continue;
-            }
-            if (ch === "\x7f" || ch === "\b") {
-                // Backspace
-                if (this.buffer.length === 0) {
-                    actions.push({ action: "delete-empty" });
-                }
-                else if (this.cursor > 0) {
-                    this.buffer = this.buffer.slice(0, this.cursor - 1) + this.buffer.slice(this.cursor);
-                    this.cursor--;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-A: home
-            if (ch === "\x01") {
-                if (this.cursor > 0) {
-                    this.cursor = 0;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-E: end
-            if (ch === "\x05") {
-                if (this.cursor < this.buffer.length) {
-                    this.cursor = this.buffer.length;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-B: back one char
-            if (ch === "\x02") {
-                if (this.cursor > 0) {
-                    this.cursor--;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-F: forward one char
-            if (ch === "\x06") {
-                if (this.cursor < this.buffer.length) {
-                    this.cursor++;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-U: delete to start of line
-            if (ch === "\x15") {
-                if (this.cursor > 0) {
-                    this.buffer = this.buffer.slice(this.cursor);
-                    this.cursor = 0;
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-K: delete to end of line
-            if (ch === "\x0b") {
-                if (this.cursor < this.buffer.length) {
-                    this.buffer = this.buffer.slice(0, this.cursor);
-                    actions.push({ action: "changed" });
-                }
-                i++;
-                continue;
-            }
-            // Ctrl-W: delete word backward
-            if (ch === "\x17") {
-                if (this.deleteWordBackward())
-                    actions.push({ action: "changed" });
-                i++;
-                continue;
-            }
-            // Other control chars — ignore
-            if (ch.charCodeAt(0) < 0x20) {
+            if (ch.charCodeAt(0) < 0x20 || ch === "\x7f") {
+                const action = this.handleControl(ch);
+                if (action)
+                    actions.push(action);
                 i++;
                 continue;
             }
@@ -159,14 +131,123 @@ export class LineEditor {
         }
         return actions;
     }
+    /** Check if there's a pending incomplete escape sequence. */
+    hasPendingEscape() {
+        return this.pendingSeq.length > 0;
+    }
+    /** Flush a pending sequence — treat bare \x1b as cancel, discard incomplete CSI. */
+    flushPendingEscape() {
+        if (!this.pendingSeq)
+            return [];
+        const wasBarEscape = this.pendingSeq === "\x1b";
+        this.pendingSeq = "";
+        return wasBarEscape ? [{ action: "cancel" }] : [];
+    }
     clear() {
         this.buffer = "";
         this.cursor = 0;
+        this.pendingSeq = "";
+    }
+    // ── Key bindings ────────────────────────────────────────────
+    //
+    // Single source of truth for all keybindings. Both legacy control
+    // characters and kitty protocol sequences resolve to a key name
+    // and look it up here. To add a binding, add one entry.
+    bindings = {
+        "enter": () => ({ action: "submit", buffer: this.buffer }),
+        "ctrl+c": () => ({ action: "cancel" }),
+        "tab": () => ({ action: "tab" }),
+        "backspace": () => this.deleteBackward(),
+        "ctrl+d": () => this.buffer.length === 0 ? { action: "delete-empty" } : this.deleteForward(),
+        "ctrl+a": () => this.moveTo(0),
+        "ctrl+e": () => this.moveTo(this.buffer.length),
+        "ctrl+b": () => this.moveTo(this.cursor - 1),
+        "ctrl+f": () => this.moveTo(this.cursor + 1),
+        "ctrl+u": () => this.deleteRange(0, this.cursor),
+        "ctrl+k": () => this.deleteRange(this.cursor, this.buffer.length),
+        "ctrl+w": () => this.deleteWordBackward() ? { action: "changed" } : null,
+        "shift+enter": () => this.insertAt("\n"),
+        "shift+tab": () => ({ action: "shift+tab" }),
+    };
+    /** Resolve a key name from the bindings table and execute it. */
+    dispatch(key) {
+        return this.bindings[key]?.() ?? null;
+    }
+    // ── Legacy control character mapping ───────────────────────
+    /** Map a legacy control character to a key name. */
+    static CTRL_MAP = {
+        "\r": "enter", "\x03": "ctrl+c", "\t": "tab",
+        "\x7f": "backspace", "\b": "backspace",
+        "\x01": "ctrl+a", "\x02": "ctrl+b", "\x04": "ctrl+d",
+        "\x05": "ctrl+e", "\x06": "ctrl+f", "\x0b": "ctrl+k",
+        "\x15": "ctrl+u", "\x17": "ctrl+w",
+    };
+    handleControl(ch) {
+        const key = LineEditor.CTRL_MAP[ch];
+        return key ? this.dispatch(key) : null;
+    }
+    // ── Kitty keyboard protocol ────────────────────────────────
+    /** Handle a kitty protocol CSI u sequence. Params format: "keycode;modifier". */
+    handleKittyKey(params) {
+        const [kc, mod] = params.split(";").map(Number);
+        const keycode = kc;
+        const mods = (mod ?? 1) - 1; // kitty modifier bits
+        // Build key name from modifier + keycode
+        const modNames = [];
+        if (mods & 4)
+            modNames.push("ctrl");
+        if (mods & 1)
+            modNames.push("shift");
+        if (mods & 2)
+            modNames.push("alt");
+        const keyName = KITTY_KEY_NAMES[keycode] ?? String.fromCharCode(keycode);
+        const fullName = [...modNames, keyName].join("+");
+        // Try exact binding first, then fall back to ctrl char mapping
+        return this.dispatch(fullName)
+            ?? ((mods & 4) && keycode >= 97 && keycode <= 122
+                ? this.dispatch(`ctrl+${String.fromCharCode(keycode)}`)
+                : null)
+            ?? (mods === 0 ? this.handleControl(String.fromCharCode(keycode)) : null);
+    }
+    // ── Editing primitives ─────────────────────────────────────
+    insertAt(ch) {
+        this.buffer = this.buffer.slice(0, this.cursor) + ch + this.buffer.slice(this.cursor);
+        this.cursor++;
+        return { action: "changed" };
+    }
+    moveTo(pos) {
+        const clamped = Math.max(0, Math.min(pos, this.buffer.length));
+        if (clamped === this.cursor)
+            return null;
+        this.cursor = clamped;
+        return { action: "changed" };
+    }
+    deleteBackward() {
+        if (this.buffer.length === 0)
+            return { action: "delete-empty" };
+        if (this.cursor <= 0)
+            return null;
+        this.buffer = this.buffer.slice(0, this.cursor - 1) + this.buffer.slice(this.cursor);
+        this.cursor--;
+        return { action: "changed" };
+    }
+    deleteForward() {
+        if (this.cursor >= this.buffer.length)
+            return null;
+        this.buffer = this.buffer.slice(0, this.cursor) + this.buffer.slice(this.cursor + 1);
+        return { action: "changed" };
+    }
+    deleteRange(start, end) {
+        if (start >= end)
+            return null;
+        this.buffer = this.buffer.slice(0, start) + this.buffer.slice(end);
+        this.cursor = start;
+        return { action: "changed" };
     }
     // ── CSI sequence handling ───────────────────────────────────
     /**
      * Parse and handle a CSI sequence (\x1b[...) starting at `start`.
-     * Returns the number of bytes consumed.
+     * Returns the number of bytes consumed and whether the sequence was incomplete.
      */
     handleCSI(data, start, actions) {
         // Skip \x1b[
@@ -177,8 +258,12 @@ export class LineEditor {
             params += data[j];
             j++;
         }
-        const final = j < data.length ? data[j] : "";
-        const consumed = j - start + (final ? 1 : 0);
+        // If we ran out of data before the final byte, sequence is incomplete
+        if (j >= data.length) {
+            return { consumed: j - start, incomplete: true };
+        }
+        const final = data[j];
+        const consumed = j - start + 1;
         // Dispatch on final byte
         switch (final) {
             case "A": // Up arrow
@@ -223,6 +308,15 @@ export class LineEditor {
                     actions.push({ action: "changed" });
                 }
                 break;
+            case "Z": // Shift+Tab (legacy CSI sequence)
+                actions.push({ action: "shift+tab" });
+                break;
+            case "u": { // Kitty keyboard protocol: \x1b[<keycode>;<modifier>u
+                const action = this.handleKittyKey(params);
+                if (action)
+                    actions.push(action);
+                break;
+            }
             case "~": // Extended keys: Delete (3~), etc.
                 if (params === "3") {
                     // Delete key: delete char under cursor

package/dist/utils/markdown.js

@@ -108,13 +108,13 @@ export class MarkdownRenderer {
         }
     }
     printTopBorder() {
-        const w = Math.min(this.contentWidth, 40);
-        process.stdout.write(`${p.dim}${p.accent}${"─".repeat(w)}${p.reset}\n`);
+        const termW = process.stdout.columns || 80;
+        process.stdout.write(`${p.dim}${p.accent}${"─".repeat(termW)}${p.reset}\n`);
         this.firstLine = true;
     }
     printBottomBorder() {
-        const w = Math.min(this.contentWidth, 40);
-        process.stdout.write(`${p.dim}${p.accent}${"─".repeat(w)}${p.reset}\n`);
+        const termW = process.stdout.columns || 80;
+        process.stdout.write(`${p.dim}${p.accent}${"─".repeat(termW)}${p.reset}\n`);
     }
     processBuffer() {
         const lines = this.buffer.split("\n");

package/dist/utils/tool-display.d.ts

@@ -38,5 +38,7 @@ export declare function createSpinner(): SpinnerState;
  */
 export declare function startSpinner(label: string, opts?: {
     color?: string;
+    hint?: string;
+    startTime?: number;
 }): SpinnerState;
 export declare function stopSpinner(state: SpinnerState): void;

package/dist/utils/tool-display.js

@@ -61,28 +61,53 @@ export function renderToolCall(tool, width) {
         return [`${p.warning}${text}${p.reset}`];
     }
     const lines = [];
-    lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}`);
+    // Build a compact detail string to append after the title
+    let detail = "";
     if (mode === "full") {
-        // Show file locations if available
-        if (tool.locations && tool.locations.length > 0) {
-            for (const loc of tool.locations) {
-                const lineInfo = loc.line ? `:${loc.line}` : "";
-                lines.push(`  ${p.dim}${loc.path}${lineInfo}${p.reset}`);
-            }
-        }
-        // Show command string for terminal tools
         if (tool.command) {
-            const maxCmdW = Math.max(1, width - 4);
-            const cmd = tool.command.length > maxCmdW
-                ? tool.command.slice(0, maxCmdW - 1) + "…"
-                : tool.command;
-            lines.push(`  ${p.dim}$ ${cmd}${p.reset}`);
+            detail = `$ ${tool.command}`;
+        }
+        else if (tool.locations && tool.locations.length > 0) {
+            const loc = tool.locations[0];
+            const lineInfo = loc.line ? `:${loc.line}` : "";
+            detail = `${loc.path}${lineInfo}`;
+        }
+        else if (tool.rawInput) {
+            const raw = tool.rawInput;
+            if (raw && typeof raw === "object") {
+                if (typeof raw.command === "string") {
+                    detail = `$ ${raw.command}`;
+                }
+                else if (typeof raw.operation === "string") {
+                    detail = raw.operation;
+                    if (raw.ids && Array.isArray(raw.ids)) {
+                        detail += ` #${raw.ids.join(",")}`;
+                    }
+                    if (typeof raw.query === "string") {
+                        detail += ` "${raw.query}"`;
+                    }
+                }
+                else {
+                    detail = formatRawInput(tool.rawInput, width - tool.title.length - 6);
+                }
+            }
         }
-        // Show raw input args for non-terminal, non-file tools
-        if (!tool.command && !tool.locations?.length && tool.rawInput) {
-            const detail = formatRawInput(tool.rawInput, width - 4);
-            if (detail)
-                lines.push(`  ${p.dim}${detail}${p.reset}`);
+    }
+    // Render as single line: ► title: detail
+    const maxDetailW = Math.max(1, width - tool.title.length - 6);
+    if (detail) {
+        if (detail.length > maxDetailW)
+            detail = detail.slice(0, maxDetailW - 1) + "…";
+        lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}${p.dim}: ${detail}${p.reset}`);
+    }
+    else {
+        lines.push(`${p.warning}${p.bold}${icon} ${tool.title}${p.reset}`);
+    }
+    // Show additional file locations on separate lines (if more than one)
+    if (mode === "full" && tool.locations && tool.locations.length > 1) {
+        for (const loc of tool.locations.slice(1)) {
+            const lineInfo = loc.line ? `:${loc.line}` : "";
+            lines.push(`  ${p.dim}${loc.path}${lineInfo}${p.reset}`);
         }
     }
     return lines;
@@ -168,12 +193,15 @@ export function createSpinner() {
  */
 export function startSpinner(label, opts) {
     const state = createSpinner();
+    if (opts?.startTime)
+        state.startTime = opts.startTime;
     const color = opts?.color ?? p.accent;
+    const hint = opts?.hint ? ` ${p.dim}${opts.hint}${p.reset}` : "";
     state.interval = setInterval(() => {
         const frame = SPINNER_FRAMES[state.frame % SPINNER_FRAMES.length];
         const elapsed = formatElapsed(Date.now() - state.startTime);
         const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
-        process.stdout.write(`\r  ${color}${frame} ${label}...${p.reset}${timer}\x1b[K`);
+        process.stdout.write(`\r  ${color}${frame} ${label}...${p.reset}${timer}${hint}\x1b[K`);
         state.frame++;
     }, 80);
     return state;

package/examples/pi-agent-sh.ts

@@ -0,0 +1,166 @@
+/**
+ * Pi extension: agent-sh tools (user_shell + shell_recall).
+ *
+ * When running inside agent-sh, registers tools that communicate with
+ * the user's live terminal via a Unix domain socket (JSON-RPC 2.0).
+ *
+ * - user_shell:   execute commands in the user's live PTY
+ * - shell_recall:  search/expand/browse session exchange history
+ *
+ * Socket path comes from the AGENT_SH_SOCKET env var.
+ * When not running inside agent-sh, the extension silently does nothing.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { createConnection } from "node:net";
+
+const SOCKET_PATH = process.env.AGENT_SH_SOCKET;
+
+export default function (pi: ExtensionAPI): void {
+  if (!SOCKET_PATH) return; // Not running inside agent-sh
+
+  pi.registerTool({
+    name: "shell_cwd",
+    label: "Shell CWD",
+    description:
+      "Get the user's current working directory in their live shell. " +
+      "IMPORTANT: Your internal working directory may differ from the user's actual shell cwd — " +
+      "the user may have cd'd after your session started. Call this tool to get the real cwd " +
+      "before file operations if you're unsure.",
+    promptSnippet:
+      "Get the user's real shell cwd (may differ from your internal cwd).",
+    parameters: Type.Object({}),
+
+    async execute() {
+      const result = (await callSocket("shell/cwd", {})) as { cwd: string };
+      return {
+        content: [{ type: "text", text: `User's current working directory: ${result.cwd}` }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "user_shell",
+    label: "User Shell",
+    description:
+      "Execute a command in the user's live terminal session. " +
+      "Use this for commands that should affect the user's shell state: " +
+      "cd, export, source, pushd/popd, alias, etc. " +
+      "The command runs in the user's actual shell with their full environment " +
+      "(aliases, functions, PATH), not an isolated subprocess. " +
+      "NOTE: Your internal cwd may be stale — the user may have cd'd. " +
+      "Check the shell context for [shell cwd:...] labels or call shell_cwd " +
+      "to determine the real working directory. Use absolute paths when possible.",
+    promptSnippet:
+      "Run commands in the user's live shell (cd, export, source — affects their session). " +
+      "Your internal cwd may be stale — check shell context or use shell_cwd for the real cwd.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Shell command to execute in the user's live terminal" }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const result = (await callSocket("shell/exec", { command: params.command })) as {
+        output: string;
+        cwd: string;
+      };
+      return {
+        content: [{ type: "text", text: result.output || "(no output)" }],
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "shell_recall",
+    label: "Shell Recall",
+    description:
+      "Retrieve past shell commands, agent responses, and tool executions from the session history. " +
+      "Use this to look up truncated output, search for previous commands or errors, " +
+      "or browse recent exchanges. Each entry shows [shell cwd:...] so you can see " +
+      "which directory commands were run in. Operations: " +
+      '"browse" lists recent exchange summaries with line counts, ' +
+      '"search" finds exchanges matching a regex query, ' +
+      '"expand" retrieves content by exchange ID (use start/end for specific line ranges).',
+    promptSnippet:
+      "Look up session history — search past commands/output, expand truncated exchanges, or browse recent activity.",
+    parameters: Type.Object({
+      operation: Type.Optional(
+        Type.Union([Type.Literal("search"), Type.Literal("expand"), Type.Literal("browse")], {
+          description: 'Operation to perform (default: "browse")',
+        }),
+      ),
+      query: Type.Optional(
+        Type.String({ description: 'Search query — supports regex (required for "search")' }),
+      ),
+      ids: Type.Optional(
+        Type.Array(Type.Number(), {
+          description: 'Exchange IDs to expand (required for "expand")',
+        }),
+      ),
+      start: Type.Optional(
+        Type.Number({ description: "Start line number, 1-indexed (optional, for expand)" }),
+      ),
+      end: Type.Optional(
+        Type.Number({ description: "End line number, inclusive (optional, for expand)" }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const result = (await callSocket("shell/recall", {
+        operation: params.operation || "browse",
+        query: params.query,
+        ids: params.ids,
+        start: params.start,
+        end: params.end,
+      })) as { result: string };
+      return {
+        content: [{ type: "text", text: result.result || "(no results)" }],
+      };
+    },
+  });
+}
+
+// -- agent-sh socket client (JSON-RPC 2.0) --
+
+let rpcId = 0;
+
+function callSocket(method: string, params?: Record<string, unknown>): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const conn = createConnection(SOCKET_PATH!);
+    let buffer = "";
+
+    conn.on("connect", () => {
+      const msg = { jsonrpc: "2.0", id: ++rpcId, method, params: params ?? {} };
+      conn.write(JSON.stringify(msg) + "\n");
+    });
+
+    conn.on("data", (chunk) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf("\n");
+      if (newlineIdx === -1) return;
+
+      const line = buffer.slice(0, newlineIdx).trim();
+      conn.destroy();
+
+      try {
+        const response = JSON.parse(line);
+        if (response.error) {
+          reject(new Error(response.error.message || "RPC error"));
+        } else {
+          resolve(response.result);
+        }
+      } catch {
+        reject(new Error(`Invalid response from agent-sh: ${line}`));
+      }
+    });
+
+    conn.on("error", (err) => {
+      reject(new Error(`Failed to connect to agent-sh: ${err.message}`));
+    });
+
+    conn.setTimeout(35_000, () => {
+      conn.destroy();
+      reject(new Error("Connection to agent-sh timed out"));
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A shell-first terminal where any ACP-compatible AI agent is one keystroke away",
   "type": "module",
   "main": "dist/core.js",