agent-sh 0.12.1 → 0.12.2

package/README.md

@@ -23,16 +23,22 @@ I still use Claude Code and pi for serious coding work — this doesn't replace
 
 ## Quick Start
 
-Install the latest from GitHub (recommended — development moves faster than npm releases):
+Install from npm:
 
 ```bash
-npm install -g github:guanyilun/agent-sh
+npm install -g agent-sh
 ```
 
-Or the last published npm release:
+Re-run the same command to update. Patch releases ship frequently; `npm update -g agent-sh` works too.
+
+For unreleased changes on `main`, clone and link locally — this avoids `npm install -g github:...`, which builds on your machine and requires a working TypeScript toolchain:
 
 ```bash
-npm install -g agent-sh
+git clone https://github.com/guanyilun/agent-sh.git
+cd agent-sh
+npm install        # installs devDependencies (typescript, etc.)
+npm run build      # produces dist/
+npm link           # exposes `agent-sh` globally
 ```
 
 Pick one of the zero-config paths below — no settings file needed. agent-sh auto-activates a built-in provider when it sees a known key.

package/dist/agent/agent-loop.js

@@ -29,6 +29,16 @@ import { discoverGlobalSkills, discoverProjectSkills } from "./skills.js";
  * the LLM via the API `tools` param (or via load_tool in deferred-
  * lookup mode) — this only trims the always-visible catalog.
  */
+/** Reject on abort; orphaned `p` keeps running but its result is dropped. */
+function raceAbort(p, signal) {
+    if (signal.aborted)
+        return Promise.reject(new Error("cancelled"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error("cancelled"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then((v) => { signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { signal.removeEventListener("abort", onAbort); reject(e); });
+    });
+}
 function summarizeDescription(desc) {
     const firstLine = desc.split("\n", 1)[0];
     const sentenceEnd = firstLine.search(/[.!?](\s|$)/);
@@ -817,12 +827,11 @@ export class AgentLoop {
             this.conversation.addSystemNote(text);
             this.bus.emit("conversation:message-appended", { role: "system", content: text });
         });
+        // Fires on user-abort; extensions advise per tool name for cleanup.
+        h.define("tool:cancel", (_ctx) => { });
         // Wraps each tool call: permission → execute → emit events.
-        // Extensions advise to add safe-mode, logging, metrics, custom policies.
-        // The ctx.onChunk callback is exposed so advisors can wrap it to
-        // intercept/transform streamed tool output (e.g. secret redaction).
         h.define("tool:execute", async (ctx) => {
-            const { name, id, args, tool } = ctx;
+            const { name, id, args, tool, signal } = ctx;
             // Validate required input fields before display/permission/execute.
             // Some models emit wrong arg names (e.g. `file_path` instead of `path`),
             // and downstream helpers assume required strings are present.
@@ -918,16 +927,21 @@ export class AgentLoop {
             const onChunk = (tool.showOutput !== false && !diffShown)
                 ? ctx.onChunk
                 : undefined;
-            const toolCtx = this.compositor
-                ? { ui: createToolUI(this.bus, this.compositor.surface("agent")) }
-                : undefined;
-            // Surface thrown errors as tool results so the agent can self-correct
-            // instead of the throw killing the whole turn.
+            const toolCtx = { signal };
+            if (this.compositor) {
+                toolCtx.ui = createToolUI(this.bus, this.compositor.surface("agent"));
+            }
             let result;
             try {
-                result = await tool.execute(args, onChunk, toolCtx);
+                result = await raceAbort(tool.execute(args, onChunk, toolCtx), signal);
             }
             catch (err) {
+                if (signal.aborted) {
+                    try {
+                        this.handlers.call("tool:cancel", { name, args, reason: "user-aborted" });
+                    }
+                    catch { }
+                }
                 const message = err instanceof Error ? err.message : String(err);
                 result = { content: message, exitCode: 1, isError: true };
             }
@@ -1169,7 +1183,8 @@ export class AgentLoop {
                     this.bus.emit("agent:tool-output-chunk", { chunk });
                 };
                 const result = await this.handlers.call("tool:execute", { name: tc.name, id: tc.id, args, tool, onChunk: defaultOnChunk,
-                    batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined });
+                    batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined,
+                    signal });
                 // Truncate large outputs to avoid blowing context
                 let content = result.content;
                 const maxBytes = 16_384; // ~4k tokens

package/dist/agent/conversation-state.d.ts

@@ -38,6 +38,7 @@ export declare class ConversationState {
     private nextSeq;
     private lastApiTokenCount;
     private lastApiMessageCount;
+    private pendingNotes;
     constructor(handlers?: HandlerFunctions, instanceId?: string);
     /** Get JSON.stringify of messages, cached until next mutation. */
     private getMessagesJson;
@@ -53,7 +54,10 @@ export declare class ConversationState {
     addToolResult(toolCallId: string, content: string, isError?: boolean): void;
     /** Add tool results as a user message (for inline tool protocol). */
     addToolResultInline(content: string): void;
+    /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
     addSystemNote(text: string): void;
+    private hasOpenToolCalls;
+    private flushPendingNotes;
     getMessages(): ChatCompletionMessageParam[];
     /**
      * If a stream was interrupted mid-tool-execution, an assistant message

package/dist/agent/conversation-state.js

@@ -56,6 +56,10 @@ export class ConversationState {
     nextSeq = 1;
     lastApiTokenCount = null;
     lastApiMessageCount = 0;
+    // Notes queued when addSystemNote fires mid-tool-pair; flushed once
+    // the trailing tool_result lands. Splicing into the gap breaks
+    // reasoning_content pairing and is rejected by strict providers.
+    pendingNotes = [];
     constructor(handlers, instanceId = "0000") {
         this.handlers = handlers ?? null;
         this.instanceId = instanceId;
@@ -100,16 +104,54 @@ export class ConversationState {
         if (isError)
             this.toolErrors.add(toolCallId);
         this.invalidateMessagesCache();
+        this.flushPendingNotes();
     }
     /** Add tool results as a user message (for inline tool protocol). */
     addToolResultInline(content) {
         this.messages.push({ role: "user", content });
         this.invalidateMessagesCache();
+        this.flushPendingNotes();
     }
+    /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
     addSystemNote(text) {
+        if (this.hasOpenToolCalls()) {
+            this.pendingNotes.push(text);
+            return;
+        }
         this.messages.push({ role: "user", content: text });
         this.invalidateMessagesCache();
     }
+    hasOpenToolCalls() {
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const msg = this.messages[i];
+            if (msg.role === "tool")
+                continue;
+            if (msg.role !== "assistant")
+                return false;
+            if (!("tool_calls" in msg) || !msg.tool_calls)
+                return false;
+            const answered = new Set();
+            for (let j = i + 1; j < this.messages.length; j++) {
+                const m = this.messages[j];
+                if (m.role !== "tool")
+                    break;
+                answered.add(m.tool_call_id);
+            }
+            return msg.tool_calls.some((tc) => !answered.has(tc.id));
+        }
+        return false;
+    }
+    flushPendingNotes() {
+        if (this.pendingNotes.length === 0)
+            return;
+        if (this.hasOpenToolCalls())
+            return;
+        for (const text of this.pendingNotes) {
+            this.messages.push({ role: "user", content: text });
+        }
+        this.pendingNotes = [];
+        this.invalidateMessagesCache();
+    }
     getMessages() {
         return this.normalizeReasoningConsistency(this.stubDanglingToolCalls(this.messages));
     }
@@ -175,6 +217,7 @@ export class ConversationState {
         this.invalidateMessagesCache();
         this.lastApiTokenCount = null;
         this.lastApiMessageCount = 0;
+        this.flushPendingNotes();
     }
     pruneToolErrors() {
         if (this.toolErrors.size === 0)
@@ -474,6 +517,7 @@ export class ConversationState {
         this.nuclearEntries = [];
         this.nuclearBySeq.clear();
         this.recallArchive.clear();
+        this.pendingNotes = [];
         this.invalidateMessagesCache();
         this.lastApiTokenCount = null;
         this.lastApiMessageCount = 0;

package/dist/agent/tools/bash.js

@@ -1,4 +1,4 @@
-import { executeCommand } from "../../executor.js";
+import { executeCommand, killSession } from "../../executor.js";
 export function createBashTool(opts) {
     return {
         name: "bash",
@@ -33,7 +33,7 @@ export function createBashTool(opts) {
             icon: "▶",
             locations: [],
         }),
-        async execute(args, onChunk) {
+        async execute(args, onChunk, ctx) {
             const command = args.command;
             const timeout = (args.timeout ?? 60) * 1000;
             // Let extensions intercept before execution
@@ -57,7 +57,14 @@ export function createBashTool(opts) {
                 timeout,
                 onOutput: onChunk,
             });
-            await done;
+            const onAbort = () => killSession(session);
+            ctx?.signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                await done;
+            }
+            finally {
+                ctx?.signal?.removeEventListener("abort", onAbort);
+            }
             const content = session.truncated
                 ? `[output truncated, showing last portion]\n${session.output}`
                 : session.output;

package/dist/agent/types.d.ts

@@ -64,7 +64,9 @@ export interface ToolUI {
 }
 /** Context passed to tool execute() as optional third parameter. */
 export interface ToolExecutionContext {
-    ui: ToolUI;
+    ui?: ToolUI;
+    /** Aborted on Ctrl-C — tools with subprocess work should listen and clean up. */
+    signal?: AbortSignal;
 }
 export interface ToolDefinition {
     name: string;

package/dist/core.d.ts

@@ -33,6 +33,8 @@ export interface AgentShellCore {
     contextManager: ContextManager;
     /** Handler registry for define/advise/call. */
     handlers: HandlerRegistry;
+    /** Unique id for this agent process; used for shell-marker tagging and lineage tracking. */
+    instanceId: string;
     /** Activate the agent backend (call after extensions load). */
     activateBackend(): void;
     /** Convenience: emit agent:submit and await the response. */

package/dist/core.js

@@ -107,6 +107,7 @@ export function createCore(config) {
         bus,
         contextManager,
         handlers,
+        instanceId,
         activateBackend() {
             // Silent — backend info is shown in the startup banner.
             // Runtime switches (config:switch-backend) still emit ui:info.

package/dist/index.js

@@ -218,6 +218,7 @@ async function main() {
         rows,
         shell: config.shell || process.env.SHELL || "/bin/bash",
         cwd: process.cwd(),
+        instanceId: core.instanceId,
         onShowAgentInfo: () => {
             if (agentInfo) {
                 return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };

package/dist/shell/output-parser.d.ts

@@ -6,11 +6,12 @@ import type { EventBus } from "../event-bus.js";
 export declare class OutputParser {
     private bus;
     private cwd;
+    private ownTag;
     private currentOutputCapture;
     private lastCommand;
     private foregroundBusy;
     private promptReady;
-    constructor(bus: EventBus, initialCwd: string);
+    constructor(bus: EventBus, initialCwd: string, ownTag: string);
     /** Process a chunk of PTY output data. */
     processData(data: string): void;
     /** Called when user presses Enter on a non-empty line. */

package/dist/shell/output-parser.js

@@ -1,4 +1,9 @@
 import { stripAnsi } from "../utils/ansi.js";
+// Self-emitted form: \e]<num>;id=<own>;<body>\a — only this is honored.
+// Anything else (mismatched tag, untagged) is ignored as opaque foreground output.
+const PROMPT_RE = /\x1b\]9999;(?:id=([a-f0-9]+);)?PROMPT\x07/;
+const PREEXEC_RE = /\x1b\]9997;(?:id=([a-f0-9]+);)?([^\x07]*)\x07/;
+const READY_RE = /\x1b\]9998;(?:id=([a-f0-9]+);)?READY\x07/;
 /**
  * Parses PTY output to detect command boundaries, track cwd,
  * and emit shell events. Owns the command lifecycle state.
@@ -6,13 +11,16 @@ import { stripAnsi } from "../utils/ansi.js";
 export class OutputParser {
     bus;
     cwd;
+    ownTag;
     currentOutputCapture = "";
     lastCommand = "";
     foregroundBusy = false;
     promptReady = false;
-    constructor(bus, initialCwd) {
+    constructor(bus, initialCwd, ownTag) {
         this.bus = bus;
         this.cwd = initialCwd;
+        // Strip the "id=" prefix; we compare the value alone.
+        this.ownTag = ownTag.startsWith("id=") ? ownTag.slice(3) : ownTag;
     }
     /** Process a chunk of PTY output data. */
     processData(data) {
@@ -49,24 +57,22 @@ export class OutputParser {
      * completion. Returns data with the OSC stripped out.
      */
     handlePreexec(data) {
-        const marker = "\x1b]9997;";
-        const idx = data.indexOf(marker);
-        if (idx === -1)
+        const match = PREEXEC_RE.exec(data);
+        if (!match)
             return data;
-        const endIdx = data.indexOf("\x07", idx + marker.length);
-        if (endIdx === -1)
-            return data; // incomplete OSC, wait for next chunk
-        const command = data.slice(idx + marker.length, endIdx);
-        // Authoritative command from the shell — override any lineBuffer guess
+        if (match[1] !== this.ownTag) {
+            // Nested instance or untagged foreign emission — strip and ignore.
+            return data.slice(0, match.index) + data.slice(match.index + match[0].length);
+        }
+        const command = match[2];
         this.lastCommand = command;
-        this.currentOutputCapture = ""; // discard echoed text accumulated before preexec
+        this.currentOutputCapture = ""; // discard echo accumulated before preexec
         if (!this.foregroundBusy) {
             this.foregroundBusy = true;
             this.bus.emit("shell:foreground-busy", { busy: true });
         }
         this.bus.emit("shell:command-start", { command, cwd: this.cwd });
-        // Return only data after the OSC — everything before was the echo
-        return data.slice(endIdx + 1);
+        return data.slice(match.index + match[0].length);
     }
     parseOSC7(data) {
         const match = data.match(/\x1b\]7;file:\/\/[^/]*(\/[^\x07\x1b]*)/);
@@ -83,9 +89,15 @@ export class OutputParser {
      * Each time a prompt appears, we finalize the previous command's output.
      */
     parsePromptMarker(data) {
-        const marker = "\x1b]9999;PROMPT\x07";
-        const markerIdx = data.indexOf(marker);
-        if (markerIdx !== -1) {
+        const match = PROMPT_RE.exec(data);
+        if (match) {
+            if (match[1] !== this.ownTag) {
+                // Nested instance or untagged foreign emission — treat as opaque
+                // foreground output, do not finalize our own command.
+                this.currentOutputCapture += data;
+                return;
+            }
+            const markerIdx = match.index;
             // Capture any output that arrived in the same chunk before the marker
             if (markerIdx > 0) {
                 this.currentOutputCapture += data.slice(0, markerIdx);
@@ -125,9 +137,12 @@ export class OutputParser {
      * and the shell is ready for input.
      */
     parsePromptEnd(data) {
-        if (data.includes("\x1b]9998;READY\x07")) {
-            this.promptReady = true;
-        }
+        const match = READY_RE.exec(data);
+        if (!match)
+            return;
+        if (match[1] !== this.ownTag)
+            return;
+        this.promptReady = true;
     }
     removeEchoedCommand(output, command) {
         const lines = output.split("\n");

package/dist/shell/shell.d.ts

@@ -28,6 +28,7 @@ export declare class Shell implements InputContext {
         rows: number;
         shell: string;
         cwd: string;
+        instanceId: string;
     });
     isForegroundBusy(): boolean;
     getCwd(): string;

package/dist/shell/shell.js

@@ -43,8 +43,10 @@ export class Shell {
         }
         const shellBin = (isZsh || isBash) ? opts.shell : "/bin/bash";
         let shellArgs;
+        // Per-instance tag so nested agent-sh hooks don't cross-trigger.
+        const instanceTag = `id=${opts.instanceId}`;
         const osc7Cmd = 'printf "\\e]7;file://%s%s\\a" "$(hostname)" "$PWD"';
-        const promptMarker = 'printf "\\e]9999;PROMPT\\a"';
+        const promptMarker = `printf "\\e]9999;${instanceTag};PROMPT\\a"`;
         const titleCmd = 'printf "\\e]0;⚡ agent-sh: %s\\a" "${PWD/#$HOME/~}"';
         this.isZsh = isZsh;
         const settings = getSettings();
@@ -69,11 +71,11 @@ export class Shell {
                 "# Preexec hook: emit actual command text so agent-sh can track",
                 "# history-recalled and tab-completed commands accurately",
                 "__agent_sh_preexec() {",
-                '  printf "\\e]9997;%s\\a" "$1"',
+                `  printf "\\e]9997;${instanceTag};%s\\a" "$1"`,
                 "}",
                 "preexec_functions+=(__agent_sh_preexec)",
             ];
-            zshrcLines.push("", "# End-of-prompt marker via zle-line-init (fires after prompt is rendered)", "# Chain onto existing widget (p10k uses zle-line-init) rather than clobbering", 'if (( ${+widgets[zle-line-init]} )); then', "  zle -A zle-line-init __agent_sh_orig_line_init", "  __agent_sh_line_init() {", "    zle __agent_sh_orig_line_init", '    printf "\\e]9998;READY\\a"', "  }", "else", "  __agent_sh_line_init() {", '    printf "\\e]9998;READY\\a"', "  }", "fi", "zle -N zle-line-init __agent_sh_line_init", "", "# Hidden widget to trigger prompt redraw from Node.js side", "# Bound to an unused escape sequence that no real key produces", "__agent_sh_redraw() {", "  zle reset-prompt", "}", "zle -N __agent_sh_redraw", "bindkey '\\e[9999~' __agent_sh_redraw");
+            zshrcLines.push("", "# End-of-prompt marker via zle-line-init (fires after prompt is rendered)", "# Chain onto existing widget (p10k uses zle-line-init) rather than clobbering", 'if (( ${+widgets[zle-line-init]} )); then', "  zle -A zle-line-init __agent_sh_orig_line_init", "  __agent_sh_line_init() {", "    zle __agent_sh_orig_line_init", `    printf "\\e]9998;${instanceTag};READY\\a"`, "  }", "else", "  __agent_sh_line_init() {", `    printf "\\e]9998;${instanceTag};READY\\a"`, "  }", "fi", "zle -N zle-line-init __agent_sh_line_init", "", "# Hidden widget to trigger prompt redraw from Node.js side", "# Bound to an unused escape sequence that no real key produces", "__agent_sh_redraw() {", "  zle reset-prompt", "}", "zle -N __agent_sh_redraw", "bindkey '\\e[9999~' __agent_sh_redraw");
             fs.writeFileSync(path.join(this.tmpDir, ".zshrc"), zshrcLines.join("\n") + "\n");
             env.ZDOTDIR = this.tmpDir;
             shellArgs = ["--no-globalrcs"];
@@ -106,12 +108,12 @@ export class Shell {
                 "  __agent_sh_preexec_ran=1",
                 "  local this_cmd",
                 `  this_cmd=$(HISTTIMEFORMAT='' builtin history 1 | command sed 's/^ *[0-9]* *//')`,
-                `  printf '\\e]9997;%s\\a' "$this_cmd"`,
+                `  printf '\\e]9997;${instanceTag};%s\\a' "$this_cmd"`,
                 "}",
                 "trap '__agent_sh_emit_preexec' DEBUG",
                 "",
                 "# End-of-prompt marker: append to PS1 (\\[...\\] marks it zero-width)",
-                'case "$PS1" in *9998*) ;; *) PS1="${PS1}\\[\\e]9998;READY\\a\\]";; esac',
+                `case "$PS1" in *9998*) ;; *) PS1="\${PS1}\\[\\e]9998;${instanceTag};READY\\a\\]";; esac`,
                 "",
                 "# Mirrors the zsh \\e[9999~ reset-prompt widget — used by agent-sh",
                 "# to repaint the prompt in place. All keymaps so `set -o vi` works.",
@@ -155,7 +157,7 @@ export class Shell {
         }
         this.bus = opts.bus;
         this.handlers = opts.handlers;
-        this.outputParser = new OutputParser(opts.bus, opts.cwd);
+        this.outputParser = new OutputParser(opts.bus, opts.cwd, instanceTag);
         // Ensure temp dir cleanup on abnormal exit (SIGKILL won't fire this,
         // but it covers uncaught exceptions and normal process.exit paths)
         if (this.tmpDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -127,6 +127,8 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@xterm/addon-serialize": "^0.13.0",
+    "@xterm/headless": "^5.5.0",
     "cli-highlight": "^2.1.11",
     "diff": "^9.0.0",
     "marked": "^17.0.6",