agent-sh 0.12.24 → 0.12.26

package/README.md

@@ -19,10 +19,12 @@ So I built agent-sh. Under the hood it's a normal shell on top of node-pty — y
 ~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
-I still use a proper coding harness for serious work — this doesn't replace that. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, you can swap in [pi](examples/extensions/pi-bridge/) as the backend — `agent-sh install pi-bridge` followed by `agent-sh --backend pi`.
+agent-sh is built to be agent-agnostic. You can [bring your own coding agent](#bring-your-own-agent) or use the built-in agent `ash` — a lightweight, extensible agent if you'd like to build extensions on top of it.
 
 ## Quick Start
 
+### Installation
+
 Install from npm:
 
 ```bash
@@ -41,7 +43,36 @@ 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.
+Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fish, nushell, etc.) are not yet wired up.
+
+**Windows:** the interactive shell layer is bash/zsh-only. Run agent-sh inside **WSL** for the full experience. Native Windows (cmd.exe / PowerShell) is not supported as the host shell, though headless / library / ACP-bridge usage may work — file an issue if you hit a gap.
+
+Tip — add a shell alias:
+
+```bash
+alias ash="agent-sh"
+```
+
+Once installed, pick a backend below.
+
+### Option A: Bring your own coding agent
+
+If you already use a coding agent, host it inside agent-sh — same terminal, same `>` entry point, same shell-context wiring. Three bridges ship in the box:
+
+- **pi** — [pi-mono](https://github.com/badlogic/pi-mono) coding agent
+- **claude-code** — official [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- **opencode** — [opencode](https://opencode.ai/) via `@opencode-ai/sdk`
+
+```bash
+agent-sh install pi-bridge
+agent-sh --backend pi
+```
+
+See [Bring your own agent](#bring-your-own-agent) below for full details and the other backends.
+
+### Option B: Use the built-in agent (ash)
+
+`ash` is agent-sh's own lightweight agent. It works with any OpenAI-compatible API — 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.
 
 **Hosted models via OpenRouter** (300+ models, one key):
 
@@ -77,15 +108,36 @@ Once running, switch models at any time with `/model <name>` (tab-completes; sel
 
 For richer configuration (multiple providers, extensions), run `agent-sh init` to scaffold `~/.agent-sh/settings.json` with copy-pasteable examples. See the [Usage Guide](docs/usage.md) for the full list of supported providers.
 
-Tip — add a shell alias:
+`ash` is designed to be extended. Extensions can add tools, content transforms (e.g. render LaTeX or Mermaid), themes, slash commands, or new input modes — see [Extensions](docs/extensions.md) for the full surface.
 
-```bash
-alias ash="agent-sh"
-```
+## Bring your own agent
 
-Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fish, nushell, etc.) are not yet wired up.
+The built-in agent (`ash`) is the default, but agent-sh can host a different coding agent as its backend — same terminal, same `>` entry point, same shell-context wiring. Three bridges ship in the box:
 
-**Windows:** the interactive shell layer is bash/zsh-only. Run agent-sh inside **WSL** for the full experience. Native Windows (cmd.exe / PowerShell) is not supported as the host shell, though headless / library / ACP-bridge usage may work — file an issue if you hit a gap.
+- **[pi-bridge](examples/extensions/pi-bridge/)** — runs [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`) in-process. Pi brings its own models, tools, and `~/.pi/agent/settings.json`.
+
+  ```bash
+  agent-sh install pi-bridge
+  agent-sh --backend pi
+  ```
+
+- **[claude-code-bridge](examples/extensions/claude-code-bridge/)** — runs claude-code (the official [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)) in-process. Uses claude-code's own `Read`/`Edit`/`Write`/`Bash`/`Glob`/`Grep` tools.
+
+  ```bash
+  agent-sh install claude-code-bridge
+  agent-sh --backend claude-code
+  ```
+
+- **[opencode-bridge](examples/extensions/opencode-bridge/)** — runs [opencode](https://opencode.ai/) in-process via `@opencode-ai/sdk`. Uses opencode's tools, models, and `opencode auth login` credentials.
+
+  ```bash
+  agent-sh install opencode-bridge
+  agent-sh --backend opencode
+  ```
+
+All three bridges receive agent-sh's per-query shell context (`<shell_events>`) and follow the PTY-tracked cwd, so the hosted agent sees what you ran and where you are. Switching at runtime with `/backend <name>` persists the choice across sessions automatically; the `--backend` flag above is per-session only.
+
+**Caveat:** pi, claude-code, and opencode each manage their own tool surfaces, so agent-sh extensions that register tools (or skills, instructions, etc.) for the built-in `ash` agent generally won't be visible to a hosted backend. Frontend extensions (themes, content transforms, slash commands, the TUI renderer) keep working — only the agent-side capabilities differ. Use the bridges when you want that agent's toolset; stay on `ash` when you want agent-sh's extension ecosystem.
 
 ## Key Features
 
@@ -95,7 +147,7 @@ Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fis
 
 **Context that just works.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `> fix this`, and agent-sh knows exactly what happened. Context management works like shell history — continuous, persistent across restarts, no sessions to manage. See [Context Management](docs/context-management.md).
 
-**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — `agent-sh install pi-bridge && agent-sh --backend pi` runs [pi](examples/extensions/pi-bridge/) as a drop-in backend.
+**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — bundled bridges run [pi](examples/extensions/pi-bridge/), [claude-code](examples/extensions/claude-code-bridge/), or [opencode](examples/extensions/opencode-bridge/) as a drop-in backend (see [Bring your own agent](#bring-your-own-agent)).
 
 **Extensible by design.** The entire system is built on a typed event bus. Extensions can add custom input modes, content transforms (render LaTeX as images, Mermaid as diagrams), themes, slash commands, or replace the agent backend entirely. The built-in TUI renderer is itself just an extension.
 

package/dist/agent/system-prompt.js

@@ -108,9 +108,9 @@ Extensions may register additional tools — follow their instructions.
 - Always check command exit codes for errors
 
 # Context Envelopes
-- \`<query_context>\` (e.g. \`<shell_events>\`): the user's situation when they sent this turn — ground "fix this" / "what just happened" requests with it.
+- \`<query_context>\` (contains \`<cwd>\` always, and \`<shell_events>\` when there were user shell commands since the last turn): the user's situation when they sent this turn — \`<cwd>\` anchors where they are right now, \`<shell_events>\` grounds "fix this" / "what just happened" requests. Trust the most recent \`<cwd>\` over any cwd referenced in earlier history.
 - \`<dynamic_context>\`: current system state — in-flight work, mode markers, warnings.
-Either may be absent on any turn.
+\`<dynamic_context>\` may be absent on any turn.
 
 # Preference Learning
 

package/dist/extensions/shell-context.d.ts

@@ -1,6 +1,7 @@
 /**
  * Tracks PTY commands and cwd, spills long outputs, contributes the
- * `<shell_events>` per-query envelope. Frontends without a PTY skip this
+ * per-query `<cwd>` (always) and `<shell_events>` (when there are fresh
+ * user-shell exchanges) signals. Frontends without a PTY skip this
  * built-in and the agent runs cwd-aware via core's process.cwd() default.
  */
 import type { ExtensionContext } from "../types.js";

package/dist/extensions/shell-context.js

@@ -43,15 +43,16 @@ export default function activate(ctx) {
     bus.on("shell:agent-exec-done", () => { agentShellActive = false; });
     // Override core's process.cwd() default with the PTY-tracked value.
     ctx.advise("cwd", () => currentCwd);
-    ctx.registerContextProducer("shell-events", () => {
+    ctx.registerContextProducer("shell-context", () => {
+        const cwdTag = `<cwd>${currentCwd}</cwd>`;
         const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source !== "agent");
         if (fresh.length === 0)
-            return null;
+            return cwdTag;
         lastSeq = exchanges[exchanges.length - 1].id;
         const text = fresh.map(formatExchangeTruncated).filter(Boolean).join("\n");
         if (!text)
-            return null;
-        return `<shell_events>\n${text}\n</shell_events>`;
+            return cwdTag;
+        return `${cwdTag}\n<shell_events>\n${text}\n</shell_events>`;
     }, { mode: "per-query" });
     ctx.define("shell:context-recent", (n = 25) => {
         const recent = exchanges.slice(-n);

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import { activateShell } from "./shell/index.js";
+import { activateShell, registerShellHandlers } from "./shell/index.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
 import { loadBuiltinExtensions } from "./extensions/index.js";
@@ -236,49 +236,11 @@ async function main() {
         }
         process.exit(0);
     };
-    // ── Extension context (must precede shell activation) ────────
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Setting up extensions...');
-    }
     const extCtx = core.extensionContext({ quit: cleanup });
-    // ── Shell frontend bootstrap (special-cased; see src/shell/index.ts) ──
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Creating Shell...');
-    }
-    await new Promise(resolve => setTimeout(resolve, 100));
-    shell = activateShell(extCtx, {
-        cols,
-        rows,
-        shellPath: config.shell || process.env.SHELL || "/bin/bash",
-        cwd: process.cwd(),
-        onShowAgentInfo: () => {
-            if (agentInfo) {
-                return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };
-            }
-            return { info: "" };
-        },
-    });
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Shell created');
-    }
-    // ── Input mode ───────────────────────────────────────────────
-    bus.emit("input-mode:register", {
-        id: "agent",
-        trigger: ">",
-        label: "agent",
-        promptIcon: "❯",
-        indicator: "●",
-        onSubmit(query, b) {
-            b.emit("agent:submit", { query });
-        },
-        returnToSelf: true,
-    });
-    // Load built-in extensions (individually disableable via settings.disabledBuiltins)
+    // Before loadExtensions: extensions look up shell handlers at activation.
+    registerShellHandlers(extCtx);
+    // Load before spawning the shell so PS1 lands below the banner.
     await loadBuiltinExtensions(extCtx, getSettings().disabledBuiltins);
-    // Load user extensions (may register alternative agent backends)
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Loading extensions...');
-    }
     const loadExtensionsTimeoutMs = 10000;
     let loadedExtensions = [];
     await Promise.race([
@@ -287,17 +249,9 @@ async function main() {
     ]).catch((err) => {
         console.error(`Warning: ${err.message}`);
     });
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Extensions loaded');
-    }
-    // Names ride along so backend extensions can build banner sections.
     core.bus.emit("core:extensions-loaded", { names: loadedExtensions });
-    // ── Activate agent backend ────────────────────────────────────
-    // Extensions had their chance to register via agent:register-backend.
-    // If none did, the built-in AgentLoop gets wired to bus events.
     const { names: backendNames } = core.bus.emitPipe("config:get-backends", { names: [], active: null });
     if (backendNames.length === 0) {
-        shell?.kill();
         console.error("\nagent-sh: no agent backend available.\n\n" +
             "  Export OPENROUTER_API_KEY or OPENAI_API_KEY for zero-config launch, or\n" +
             "  pass --api-key on the command line, or\n" +
@@ -306,7 +260,6 @@ async function main() {
         process.exit(1);
     }
     if (config.backend && !backendNames.includes(config.backend)) {
-        shell?.kill();
         const bridge = suggestBridgeFor(config.backend);
         const hint = bridge
             ? `  Try: agent-sh install ${bridge}\n`
@@ -316,9 +269,6 @@ async function main() {
             hint);
         process.exit(1);
     }
-    // No await: banner must out-race the shell's PS1 arriving via PTY.
-    core.activateBackend(config.backend);
-    // ── Startup banner ───────────────────────────────────────────
     const settings = getSettings();
     if (settings.startupBanner !== false) {
         const termW = process.stdout.columns || 80;
@@ -346,6 +296,32 @@ async function main() {
             "\n  " + hint + "\n" +
             borderLine + "\n\n");
     }
+    // 100ms sidesteps macOS SIGTTOU during fg-pgrp handoff.
+    await new Promise(resolve => setTimeout(resolve, 100));
+    shell = activateShell(extCtx, {
+        cols,
+        rows,
+        shellPath: config.shell || process.env.SHELL || "/bin/bash",
+        cwd: process.cwd(),
+        onShowAgentInfo: () => {
+            if (agentInfo) {
+                return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };
+            }
+            return { info: "" };
+        },
+    });
+    bus.emit("input-mode:register", {
+        id: "agent",
+        trigger: ">",
+        label: "agent",
+        promptIcon: "❯",
+        indicator: "●",
+        onSubmit(query, b) {
+            b.emit("agent:submit", { query });
+        },
+        returnToSelf: true,
+    });
+    core.activateBackend(config.backend);
     // ── Terminal lifecycle ────────────────────────────────────────
     process.on("SIGTERM", cleanup);
     process.on("SIGHUP", cleanup);

package/dist/shell/index.d.ts

@@ -27,6 +27,11 @@ export interface ShellHandle {
     /** Forward terminal size changes to the PTY. */
     resize(cols: number, rows: number): void;
 }
+/**
+ * Register shell-owned handlers extensions can `ctx.call`. Must run before
+ * `loadExtensions`; the handlers only need the bus, not the PTY.
+ */
+export declare function registerShellHandlers(ctx: ExtensionContext): void;
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically

package/dist/shell/index.js

@@ -1,6 +1,19 @@
 import { Shell } from "./shell.js";
 import { StdoutSurface } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";
+/**
+ * Register shell-owned handlers extensions can `ctx.call`. Must run before
+ * `loadExtensions`; the handlers only need the bus, not the PTY.
+ */
+export function registerShellHandlers(ctx) {
+    let terminalBufferSingleton;
+    ctx.define("terminal-buffer", () => {
+        if (terminalBufferSingleton !== undefined)
+            return terminalBufferSingleton;
+        terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
+        return terminalBufferSingleton;
+    });
+}
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically
@@ -13,14 +26,6 @@ export function activateShell(ctx, opts) {
     ctx.compositor.setDefault("agent", stdoutSurface);
     ctx.compositor.setDefault("query", stdoutSurface);
     ctx.compositor.setDefault("status", stdoutSurface);
-    // Lazy because @xterm/headless is optional; null when not installed.
-    let terminalBufferSingleton;
-    ctx.define("terminal-buffer", () => {
-        if (terminalBufferSingleton !== undefined)
-            return terminalBufferSingleton;
-        terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
-        return terminalBufferSingleton;
-    });
     const shell = new Shell({
         bus: ctx.bus,
         handlers: { define: ctx.define, call: ctx.call },

package/dist/shell/input-handler.js

@@ -229,9 +229,15 @@ export class InputHandler {
         return false;
     }
     renderModeInput() {
-        this.view.clearAutocomplete();
-        this.drawPrompt();
-        this.updateAutocomplete();
+        this.view.beginFrame();
+        try {
+            this.view.clearAutocomplete();
+            this.drawPrompt();
+            this.updateAutocomplete();
+        }
+        finally {
+            this.view.endFrame();
+        }
     }
     updateAutocomplete() {
         const buf = this.editor.text;
@@ -278,13 +284,19 @@ export class InputHandler {
         else {
             this.editor.setText(selected.name);
         }
-        this.view.clearAutocomplete();
-        this.autocompleteActive = false;
-        this.autocompleteItems = [];
-        this.autocompleteIndex = 0;
-        this.drawPrompt();
-        if (isFileAc)
-            this.updateAutocomplete();
+        this.view.beginFrame();
+        try {
+            this.view.clearAutocomplete();
+            this.autocompleteActive = false;
+            this.autocompleteItems = [];
+            this.autocompleteIndex = 0;
+            this.drawPrompt();
+            if (isFileAc)
+                this.updateAutocomplete();
+        }
+        finally {
+            this.view.endFrame();
+        }
     }
     dismissAutocomplete() {
         this.view.clearAutocomplete();
@@ -314,11 +326,17 @@ export class InputHandler {
                 case "changed": {
                     const switchMode = this.modes.get(this.editor.text);
                     if (this.editor.text.length === 1 && switchMode && switchMode !== this.activeMode) {
-                        this.dismissAutocomplete();
-                        this.view.clearPromptArea();
-                        this.activeMode = switchMode;
-                        this.editor.clear();
-                        this.drawPrompt(false);
+                        this.view.beginFrame();
+                        try {
+                            this.dismissAutocomplete();
+                            this.view.clearPromptArea();
+                            this.activeMode = switchMode;
+                            this.editor.clear();
+                            this.drawPrompt(false);
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                         break;
                     }
                     this.historyIndex = -1;
@@ -371,8 +389,14 @@ export class InputHandler {
                 }
                 case "cancel":
                     if (this.autocompleteActive) {
-                        this.dismissAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.dismissAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else {
                         this.exitMode();
@@ -393,9 +417,15 @@ export class InputHandler {
                             this.autocompleteIndex === 0
                                 ? this.autocompleteItems.length - 1
                                 : this.autocompleteIndex - 1;
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
-                        this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                            this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else if (this.history.length > 0) {
                         if (this.historyIndex === -1) {
@@ -406,8 +436,14 @@ export class InputHandler {
                             this.historyIndex--;
                         }
                         this.editor.setText(this.history[this.historyIndex]);
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     break;
                 case "arrow-down":
@@ -416,9 +452,15 @@ export class InputHandler {
                             this.autocompleteIndex === this.autocompleteItems.length - 1
                                 ? 0
                                 : this.autocompleteIndex + 1;
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
-                        this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                            this.view.drawAutocomplete({ items: this.autocompleteItems, selected: this.autocompleteIndex });
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     else if (this.historyIndex !== -1) {
                         if (this.historyIndex < this.history.length - 1) {
@@ -429,8 +471,14 @@ export class InputHandler {
                             this.historyIndex = -1;
                             this.editor.setText(this.savedBuffer);
                         }
-                        this.view.clearAutocomplete();
-                        this.drawPrompt();
+                        this.view.beginFrame();
+                        try {
+                            this.view.clearAutocomplete();
+                            this.drawPrompt();
+                        }
+                        finally {
+                            this.view.endFrame();
+                        }
                     }
                     break;
             }

package/dist/shell/tui-input-view.d.ts

@@ -26,7 +26,12 @@ export declare class TuiInputView {
     private cursorTermCol;
     private autocompleteLines;
     private readonly surface;
+    private frameBuf;
     constructor(surface?: RenderSurface);
+    beginFrame(): void;
+    endFrame(): void;
+    private emit;
+    private autoFrame;
     resetCursor(): void;
     enableModeKeys(): void;
     disableModeKeys(): void;