agent-sh 0.12.23 → 0.12.25

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 via a bridge extension.
+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 — [pi](examples/extensions/pi-bridge/) runs as a drop-in backend extension.
+**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/core.d.ts

@@ -37,7 +37,7 @@ export interface AgentShellCore {
     /** 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(): Promise<void>;
+    activateBackend(override?: string): Promise<void>;
     /** Convenience: emit agent:submit and await the response. */
     query(text: string): Promise<string>;
     /** Convenience: emit agent:cancel-request. */

package/dist/core.js

@@ -102,10 +102,10 @@ export function createCore(config) {
         bus,
         handlers,
         instanceId,
-        async activateBackend() {
+        async activateBackend(override) {
             if (backends.size === 0)
                 return;
-            const preferred = settings.defaultBackend;
+            const preferred = override ?? settings.defaultBackend;
             const name = preferred && backends.has(preferred) ? preferred : backends.keys().next().value;
             await activateByName(name);
         },

package/dist/event-bus.d.ts

@@ -367,6 +367,8 @@ export interface ShellEvents {
             label: string;
             items: string[];
         }>;
+        /** Name of the backend being launched. Extensions should gate per-backend sections on this rather than settings.defaultBackend. */
+        activeBackend?: string;
     };
     "autocomplete:request": {
         buffer: string;

package/dist/extensions/agent-backend.js

@@ -293,8 +293,7 @@ export default function agentBackend(ctx) {
         bus.emit("config:changed", {});
     });
     bus.onPipe("banner:collect", (e) => {
-        const settings = getSettings();
-        if (settings.defaultBackend && settings.defaultBackend !== "ash")
+        if (e.activeBackend && e.activeBackend !== "ash")
             return e;
         if (loadedExtensionNames.length > 0) {
             e.sections.push({ label: "Extensions", items: [...loadedExtensionNames] });

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

@@ -8,6 +8,7 @@ import { loadBuiltinExtensions } from "./extensions/index.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { runInit } from "./init.js";
+import { runInstall, runUninstall, runList, suggestBridgeFor } from "./install.js";
 import { PACKAGE_VERSION } from "./utils/package-version.js";
 /**
  * Capture the user's full shell environment.
@@ -78,7 +79,8 @@ function parseArgs(argv) {
     let model;
     let extensions;
     let provider;
-    const shell = process.env.SHELL || "/bin/bash";
+    let backend;
+    let shell = process.env.SHELL || "/bin/bash";
     let apiKey = process.env.OPENAI_API_KEY;
     let baseURL = process.env.OPENAI_BASE_URL;
     for (let i = 0; i < argv.length; i++) {
@@ -95,8 +97,11 @@ function parseArgs(argv) {
         else if (arg === "--provider" && argv[i + 1]) {
             provider = argv[++i];
         }
+        else if (arg === "--backend" && argv[i + 1]) {
+            backend = argv[++i];
+        }
         else if (arg === "--shell" && argv[i + 1]) {
-            return { shell: argv[++i], model, extensions, apiKey, baseURL, provider };
+            shell = argv[++i];
         }
         else if ((arg === "--extensions" || arg === "-e") && argv[i + 1]) {
             const exts = argv[++i].split(",").map(s => s.trim());
@@ -110,7 +115,10 @@ function parseArgs(argv) {
             console.log(`agent-sh — a shell-first terminal where AI is one keystroke away
 
 Usage: agent-sh [options]
-       agent-sh init [--force]    Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+       agent-sh init [--force]            Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+       agent-sh install <spec> [--force]  Install an extension (bundled name, file:, npm:, github:)
+       agent-sh uninstall <name>          Remove an installed extension
+       agent-sh list                      List installed extensions
 
 Provider Profiles:
   --provider <name>   Use a provider from ~/.agent-sh/settings.json
@@ -121,6 +129,7 @@ Direct LLM API:
   --base-url <url>    Base URL for API (or set OPENAI_BASE_URL)
 
 General Options:
+  --backend <name>    Agent backend to launch (e.g. ash, pi); overrides settings.defaultBackend for this session
   --shell <path>      Shell to use (default: $SHELL or /bin/bash)
   -e, --extensions    Extensions to load (comma-separated, repeatable)
   -h, --help          Show this help
@@ -149,7 +158,7 @@ Inside the shell:
             process.exit(0);
         }
     }
-    return { shell, model, extensions, apiKey, baseURL, provider };
+    return { shell, model, extensions, apiKey, baseURL, provider, backend };
 }
 async function main() {
     // Subcommands — handled before the shell-launch path.
@@ -158,6 +167,18 @@ async function main() {
         runInit({ force: rawArgs.includes("--force") });
         return;
     }
+    if (rawArgs[0] === "install") {
+        await runInstall(rawArgs[1] ?? "", { force: rawArgs.includes("--force") });
+        return;
+    }
+    if (rawArgs[0] === "uninstall") {
+        await runUninstall(rawArgs[1] ?? "");
+        return;
+    }
+    if (rawArgs[0] === "list") {
+        runList();
+        return;
+    }
     if (process.env.AGENT_SH) {
         console.error("agent-sh: already running inside an agent-sh session (nested sessions are not supported).");
         process.exit(1);
@@ -215,49 +236,9 @@ 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)
+    // 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([
@@ -266,38 +247,39 @@ 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" +
-            "  run `agent-sh init` for a settings.json template.\n" +
-            "  Alternatively, install a bridge extension (claude-code-bridge, pi-bridge).\n");
+            "  run `agent-sh init` for a settings.json template, or\n" +
+            "  run `agent-sh install <bridge>` (e.g. pi-bridge, claude-code-bridge) to use a non-ash backend.\n");
+        process.exit(1);
+    }
+    if (config.backend && !backendNames.includes(config.backend)) {
+        const bridge = suggestBridgeFor(config.backend);
+        const hint = bridge
+            ? `  Try: agent-sh install ${bridge}\n`
+            : `  Run \`agent-sh install\` to see bundled bridge extensions.\n`;
+        console.error(`\nagent-sh: backend "${config.backend}" is not available.\n\n` +
+            `  Available backends: ${backendNames.join(", ")}\n` +
+            hint);
         process.exit(1);
     }
-    // No await: banner must out-race the shell's PS1 arriving via PTY.
-    core.activateBackend();
-    // ── Startup banner ───────────────────────────────────────────
     const settings = getSettings();
     if (settings.startupBanner !== false) {
         const termW = process.stdout.columns || 80;
         const bannerW = Math.min(termW, 60);
         const productName = `${p.accent}${p.bold}agent-sh${p.reset}`;
-        const backendName = settings.defaultBackend && backendNames.includes(settings.defaultBackend)
-            ? settings.defaultBackend
-            : backendNames[0];
+        const backendName = config.backend && backendNames.includes(config.backend)
+            ? config.backend
+            : settings.defaultBackend && backendNames.includes(settings.defaultBackend)
+                ? settings.defaultBackend
+                : backendNames[0];
         let sections = "";
         sections += `\n\n  ${p.muted}Backend:${p.reset} ${p.dim}${backendName}${p.reset}`;
-        const extSections = bus.emitPipe("banner:collect", { sections: [] }).sections;
+        const extSections = bus.emitPipe("banner:collect", { sections: [], activeBackend: backendName }).sections;
         for (const sec of extSections) {
             sections += `\n\n  ${p.muted}${sec.label}:${p.reset}`;
             for (const item of sec.items) {
@@ -312,6 +294,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/install.d.ts

@@ -0,0 +1,10 @@
+interface InstallOpts {
+    force?: boolean;
+}
+export declare function listBundled(): string[];
+/** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */
+export declare function suggestBridgeFor(backend: string): string | null;
+export declare function runInstall(spec: string, opts?: InstallOpts): Promise<void>;
+export declare function runUninstall(name: string): Promise<void>;
+export declare function runList(): void;
+export {};

package/dist/install.js

@@ -0,0 +1,205 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { CONFIG_DIR, getSettings } from "./settings.js";
+// Kept in sync with extension-loader.ts SCRIPT_EXTS.
+const SCRIPT_EXTS = [".js", ".mjs", ".ts", ".tsx", ".mts"];
+function hasIndexFile(dir) {
+    return SCRIPT_EXTS.some((ext) => fs.existsSync(path.join(dir, `index${ext}`)));
+}
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../");
+const BUNDLED_DIR = path.join(PACKAGE_ROOT, "examples/extensions");
+const EXT_DIR = path.join(CONFIG_DIR, "extensions");
+export function listBundled() {
+    if (!fs.existsSync(BUNDLED_DIR))
+        return [];
+    return fs.readdirSync(BUNDLED_DIR).map((n) => n.replace(/\.(ts|js|mjs)$/, ""));
+}
+/** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */
+export function suggestBridgeFor(backend) {
+    const candidate = `${backend}-bridge`;
+    return listBundled().includes(candidate) ? candidate : null;
+}
+const bundledResolver = {
+    resolve: async (spec) => {
+        const candidates = [
+            { p: path.join(BUNDLED_DIR, spec), name: spec },
+            { p: path.join(BUNDLED_DIR, `${spec}.ts`), name: `${spec}.ts` },
+            { p: path.join(BUNDLED_DIR, `${spec}.js`), name: `${spec}.js` },
+        ];
+        for (const c of candidates) {
+            if (fs.existsSync(c.p)) {
+                const isDirectory = fs.statSync(c.p).isDirectory();
+                return { sourcePath: c.p, name: c.name, isDirectory };
+            }
+        }
+        const available = listBundled();
+        throw new Error(`No bundled extension named "${spec}".\n\n` +
+            `Available:\n${available.map((n) => `  ${n}`).join("\n")}`);
+    },
+};
+const npmResolver = {
+    canHandle: (spec) => spec.startsWith("npm:"),
+    resolve: async () => {
+        throw new Error("npm: source is not yet implemented");
+    },
+};
+const githubResolver = {
+    canHandle: (spec) => spec.startsWith("github:") || spec.startsWith("https://github.com/"),
+    resolve: async () => {
+        throw new Error("github: source is not yet implemented");
+    },
+};
+const fileResolver = {
+    canHandle: (spec) => spec.startsWith("file:") || spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../"),
+    resolve: async (spec) => {
+        const raw = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+        const abs = path.resolve(raw);
+        if (!fs.existsSync(abs))
+            throw new Error(`Path does not exist: ${abs}`);
+        const isDirectory = fs.statSync(abs).isDirectory();
+        return { sourcePath: abs, name: path.basename(abs), isDirectory };
+    },
+};
+const PREFIX_RESOLVERS = [npmResolver, githubResolver, fileResolver];
+function pickResolver(spec) {
+    for (const r of PREFIX_RESOLVERS)
+        if (r.canHandle?.(spec))
+            return r;
+    return bundledResolver;
+}
+function maybeNpmInstall(target) {
+    const pkgJson = path.join(target, "package.json");
+    if (!fs.existsSync(pkgJson))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
+    if (Object.keys(deps).length === 0)
+        return;
+    if (fs.existsSync(path.join(target, "node_modules")))
+        return;
+    console.log(`Running npm install in ${target}...`);
+    const result = spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+        cwd: target,
+        stdio: "inherit",
+    });
+    if (result.status !== 0) {
+        throw new Error(`npm install failed in ${target}; run it manually.`);
+    }
+}
+export async function runInstall(spec, opts = {}) {
+    if (!spec) {
+        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force]\n\n" +
+            "Bundled extensions:\n" +
+            listBundled()
+                .map((n) => `  ${n}`)
+                .join("\n"));
+        process.exit(1);
+    }
+    fs.mkdirSync(EXT_DIR, { recursive: true });
+    let resolved;
+    try {
+        resolved = await pickResolver(spec).resolve(spec);
+    }
+    catch (err) {
+        console.error(`agent-sh: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const target = path.join(EXT_DIR, resolved.name);
+    if (fs.lstatSync(target, { throwIfNoEntry: false })) {
+        if (!opts.force) {
+            console.error(`agent-sh: ${target} already exists (pass --force to overwrite)`);
+            process.exit(1);
+        }
+        fs.rmSync(target, { recursive: true, force: true });
+    }
+    if (resolved.isDirectory) {
+        fs.cpSync(resolved.sourcePath, target, { recursive: true });
+        try {
+            maybeNpmInstall(target);
+        }
+        catch (err) {
+            console.error(`agent-sh: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    else {
+        fs.copyFileSync(resolved.sourcePath, target);
+    }
+    console.log(`Installed: ${resolved.name} -> ${target}`);
+}
+export async function runUninstall(name) {
+    if (!name) {
+        console.error("Usage: agent-sh uninstall <name>");
+        process.exit(1);
+    }
+    const target = path.join(EXT_DIR, name);
+    // Refuse path-traversal: target must sit directly under EXT_DIR.
+    const resolvedTarget = path.resolve(target);
+    const resolvedExtDir = path.resolve(EXT_DIR);
+    if (!resolvedTarget.startsWith(resolvedExtDir + path.sep)) {
+        console.error(`agent-sh: refusing to uninstall outside ${EXT_DIR}`);
+        process.exit(1);
+    }
+    if (!fs.lstatSync(target, { throwIfNoEntry: false })) {
+        console.error(`agent-sh: not installed: ${name}`);
+        process.exit(1);
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`Uninstalled: ${name}`);
+}
+function listFromExtDir(disabled) {
+    if (!fs.existsSync(EXT_DIR))
+        return [];
+    const dirents = fs.readdirSync(EXT_DIR, { withFileTypes: true });
+    const out = [];
+    for (const d of dirents) {
+        if (d.name.startsWith("."))
+            continue;
+        const nameForDisable = d.name.replace(/\.[^.]+$/, "");
+        if (disabled.has(nameForDisable))
+            continue;
+        const full = path.join(EXT_DIR, d.name);
+        let isDir = d.isDirectory();
+        if (d.isSymbolicLink()) {
+            try {
+                isDir = fs.statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDir) {
+            if (!hasIndexFile(full))
+                continue;
+        }
+        else if (!SCRIPT_EXTS.some((ext) => d.name.endsWith(ext))) {
+            continue;
+        }
+        const detail = d.isSymbolicLink() ? `-> ${fs.readlinkSync(full)}` : undefined;
+        out.push({ name: d.name, source: "extensions dir", detail });
+    }
+    return out;
+}
+function listFromSettings(disabled) {
+    const specs = getSettings().extensions ?? [];
+    return specs
+        .filter((s) => !disabled.has(s.replace(/\.[^.]+$/, "")))
+        .map((s) => ({ name: s, source: "settings.json" }));
+}
+export function runList() {
+    const disabled = new Set(getSettings().disabledExtensions ?? []);
+    const items = [...listFromExtDir(disabled), ...listFromSettings(disabled)];
+    if (items.length === 0) {
+        console.log("No extensions installed.");
+        return;
+    }
+    const nameWidth = Math.max(...items.map((i) => i.name.length));
+    console.log("Installed extensions:");
+    for (const item of items) {
+        const padded = item.name.padEnd(nameWidth);
+        const detail = item.detail ? `  ${item.detail}` : "";
+        console.log(`  ${padded}  (${item.source})${detail}`);
+    }
+}

package/dist/types.d.ts

@@ -100,6 +100,8 @@ export interface AgentShellConfig {
     baseURL?: string;
     /** Named provider to use from settings.json. */
     provider?: string;
+    /** Override settings.defaultBackend for this session only (does not persist). */
+    backend?: string;
     /** Conversation history backend. Defaults to the on-disk HistoryFile. */
     history?: HistoryAdapter;
 }

package/examples/extensions/claude-code-bridge/README.md

@@ -5,12 +5,16 @@ Runs Claude Code as an agent-sh backend using the official [@anthropic-ai/claude
 ## Install
 
 ```bash
-# Copy or symlink into your extensions directory
-cp -r examples/extensions/claude-code-bridge ~/.agent-sh/extensions/claude-code-bridge
+agent-sh install claude-code-bridge
+```
+
+This copies the bundled extension into `~/.agent-sh/extensions/claude-code-bridge` and runs `npm install` for you. To overwrite an existing install, pass `--force`. To uninstall, run `agent-sh uninstall claude-code-bridge`.
 
-# Install dependencies
-cd ~/.agent-sh/extensions/claude-code-bridge
-npm install
+Manual alternative (e.g. for a development checkout you want to symlink):
+
+```bash
+cp -r examples/extensions/claude-code-bridge ~/.agent-sh/extensions/claude-code-bridge
+cd ~/.agent-sh/extensions/claude-code-bridge && npm install
 ```
 
 ## Configure
@@ -34,16 +38,12 @@ Or switch at runtime:
 - `ANTHROPIC_API_KEY` must be set in your environment
 - Claude Code manages its own model selection — no model configuration needed in agent-sh
 
-## What this bridge is
-
-A pure protocol translator between the Claude Agent SDK's event stream and agent-sh's bus events. Claude Code uses its own built-in tools exactly as the SDK ships them (`Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep`). The bridge adds no tools of its own.
+## What works under claude-code
 
-## What this bridge intentionally does NOT bundle
+agent-sh's per-query context producers (e.g. `<shell_events>` from `shell-context`) are inlined into the prompt before each query, so claude-code sees the user's recent shell activity even though the SDK doesn't subscribe to agent-sh's shell bus directly.
 
-Three PTY-access tools are left out on purpose:
+The SDK's working directory follows agent-sh's PTY-tracked cwd, so when the user `cd`s in the terminal, claude-code's tools (Bash, Read, etc.) operate in the new directory.
 
-- `terminal_read` — observe the user's live terminal screen
-- `terminal_keys` — send keystrokes to the user's PTY
-- `user_shell` — run commands in the user's live shell with lasting `cd`/`export`/`source` effects
+## What this bridge is
 
-These are opt-in capabilities that belong in their own extensions. If you want any of them with Claude Code, write a companion extension that uses the SDK's `tool()` + `createSdkMcpServer()` to expose them as MCP tools, and extend the bridge (or fork it) to attach that MCP server to the SDK's `query()` options.
+A pure protocol translator between the Claude Agent SDK's event stream and agent-sh's bus events. Claude Code uses its own built-in tools exactly as the SDK ships them (`Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep`). The bridge adds no tools of its own.

package/examples/extensions/claude-code-bridge/index.ts

@@ -1,25 +1,8 @@
 /**
  * Claude Code bridge — runs Claude Code Agent SDK in-process as agent-sh's backend.
  *
- * Uses the official @anthropic-ai/claude-agent-sdk to spawn a Claude Code
- * session. Claude Code handles its own model selection, tool execution, and
- * permissions — the bridge is a pure protocol translator between the SDK's
- * event stream and agent-sh's bus events.
- *
- * PTY-access tools (`terminal_read`, `terminal_keys`, `user_shell`) are
- * intentionally NOT bundled here. If you want Claude Code to observe or
- * drive the user's live terminal, load a companion extension that
- * registers those tools as MCP tools the SDK can consume.
- *
- * Setup (from repo root):
- *   npm run build && npm link                    # register local agent-sh globally
- *   cd examples/extensions/claude-code-bridge
- *   npm install && npm link agent-sh             # link local dev copy
- *
- * Usage:
- *   agent-sh -e examples/extensions/claude-code-bridge
- *
- * Requires: Claude Code CLI installed and authenticated (claude login).
+ * Pure protocol translator between the SDK's event stream and agent-sh's bus.
+ * Requires Claude Code CLI installed and authenticated (claude login).
  */
 import { query, type Query } from "@anthropic-ai/claude-agent-sdk";
 import { readFile } from "node:fs/promises";
@@ -29,7 +12,13 @@ import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
 
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
-  const { bus } = ctx;
+  const { bus, call } = ctx;
+
+  // PTY-tracked cwd from shell-context; falls back when no PTY frontend.
+  const cwd = (): string => {
+    const v = call("cwd");
+    return typeof v === "string" && v ? v : process.cwd();
+  };
 
   let activeQuery: Query | null = null;
   const listeners: Array<{ event: string; fn: Function }> = [];
@@ -88,11 +77,16 @@ export default function activate(ctx: ExtensionContext): void {
       /** Pre-edit file snapshots for diff display (Edit/Write tools). */
       const fileSnapshots = new Map<string, string | null>();
 
+      // Splice per-query context (e.g. <shell_events>) into the prompt — the
+      // SDK has no other channel for it. Mirrors pi-bridge.
+      const ctxText = String(call("query-context:build") ?? "").trim();
+      const finalPrompt = ctxText ? `${ctxText}\n\n${userQuery}` : userQuery;
+
       try {
         activeQuery = query({
-          prompt: userQuery,
+          prompt: finalPrompt,
           options: {
-            cwd: process.cwd(),
+            cwd: cwd(),
             systemPrompt: {
               type: "preset",
               preset: "claude_code",
@@ -155,7 +149,7 @@ export default function activate(ctx: ExtensionContext): void {
 
                   // Snapshot file content before Edit/Write modifies it
                   if ((meta.name === "Edit" || meta.name === "Write") && typeof (input as any).file_path === "string") {
-                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    const absPath = resolve(cwd(), (input as any).file_path);
                     readFile(absPath, "utf-8")
                       .then(content => fileSnapshots.set(meta.id, content))
                       .catch(() => fileSnapshots.set(meta.id, null)); // file doesn't exist yet
@@ -191,7 +185,7 @@ export default function activate(ctx: ExtensionContext): void {
 
                   // Snapshot file content before Edit/Write modifies it
                   if ((b.name === "Edit" || b.name === "Write") && typeof (input as any).file_path === "string") {
-                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    const absPath = resolve(cwd(), (input as any).file_path);
                     readFile(absPath, "utf-8")
                       .then(content => fileSnapshots.set(b.id, content))
                       .catch(() => fileSnapshots.set(b.id, null));
@@ -226,7 +220,7 @@ export default function activate(ctx: ExtensionContext): void {
                       fileSnapshots.delete(toolUseId);
                       const filePath = (pending.input as any)?.file_path as string | undefined;
                       if (filePath) {
-                        const absPath = resolve(process.cwd(), filePath);
+                        const absPath = resolve(cwd(), filePath);
                         try {
                           const newContent = await readFile(absPath, "utf-8");
                           const diff = computeDiff(oldContent, newContent);

package/examples/extensions/opencode-bridge/README.md

@@ -0,0 +1,59 @@
+# opencode-bridge
+
+Runs [opencode](https://opencode.ai/) as an agent-sh backend using the official [@opencode-ai/sdk](https://www.npmjs.com/package/@opencode-ai/sdk). opencode brings its own configuration, models, tools, and authentication — agent-sh just provides the terminal.
+
+## Install
+
+```bash
+agent-sh install opencode-bridge
+```
+
+This copies the bundled extension into `~/.agent-sh/extensions/opencode-bridge` and runs `npm install` for you. To overwrite an existing install, pass `--force`. To uninstall, run `agent-sh uninstall opencode-bridge`.
+
+Manual alternative (e.g. for a development checkout you want to symlink):
+
+```bash
+cp -r examples/extensions/opencode-bridge ~/.agent-sh/extensions/opencode-bridge
+cd ~/.agent-sh/extensions/opencode-bridge && npm install
+```
+
+## Configure
+
+Set as default backend in `~/.agent-sh/settings.json`:
+
+```json
+{
+  "defaultBackend": "opencode"
+}
+```
+
+Or switch at runtime:
+
+```
+> /backend opencode
+```
+
+opencode reads its own config from `~/.local/share/opencode/` (auth credentials) and `opencode.json` / `opencode.jsonc` in your project. Configure providers and authentication by running `opencode auth login` directly — agent-sh does not override opencode's configuration.
+
+## Requirements
+
+- opencode authenticated locally — run `opencode auth login` once before using this bridge.
+- Provider env vars (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) as required by opencode for the model you've selected.
+
+## What works under opencode
+
+agent-sh's per-query context producers (e.g. `<shell_events>` from `shell-context`) are inlined into opencode's prompt before each query, so opencode sees the user's recent shell activity even though the SDK doesn't subscribe to agent-sh's shell bus directly. The current cwd is part of that context, so opencode knows where the user is even when its tools are anchored elsewhere.
+
+## cwd handling
+
+opencode treats the `directory` query param as a project ID and routes its event stream per-project — switching project mid-session silences the SSE channel we already subscribed to (no tool events, no streaming text). Because of that, the bridge **pins the session to the directory agent-sh launched from** and does not propagate later in-shell `cd`s to opencode. opencode's tools (`Bash`, `Read`, `Edit`, etc.) operate from that pinned directory; the agent learns the user's real cwd from `<shell_events>` and can still reach other locations through absolute paths or `cd && cmd` in `Bash`.
+
+To re-anchor the agent to your current cwd, run `/reset` — it tears down the conversation and creates a fresh session in your present directory.
+
+## Permission prompts
+
+opencode supports a `permission.edit = "ask"` config in `opencode.json` that gates write/edit tools behind an approval. The bridge has no UI primitive for showing that prompt, so it **auto-approves each request once** — without this, write/edit tool calls hang forever waiting for a reply that never comes. This matches claude-code-bridge's `permissionMode: "acceptEdits"` behavior. If you want to actually gate edits, set `permission.edit` to `"allow"` (skip the prompt entirely) or run opencode standalone for the interactive flow.
+
+## What this bridge is
+
+A pure protocol translator between opencode's SSE event stream and agent-sh's bus events. opencode runs as an in-process HTTP server (booted by `createOpencode()`); the bridge consumes its global event stream, filters by the active session's ID, and translates `message.part.updated` events (text/reasoning deltas, `ToolPart.state` transitions) into agent-sh tool/response events. opencode's built-in tools (bash, edit, read, write, grep, glob, etc.) are used exactly as opencode ships them. The bridge adds no tools of its own.

package/examples/extensions/opencode-bridge/index.ts

@@ -0,0 +1,383 @@
+/**
+ * opencode bridge — runs opencode in-process as agent-sh's backend via
+ * @opencode-ai/sdk. The SDK boots an embedded HTTP server we talk to with
+ * a generated client; events stream over a single global SSE channel.
+ *
+ * Requires opencode authenticated locally (`opencode auth login`).
+ */
+import { createOpencode, type OpencodeClient, type Event, type Part, type ToolPart } from "@opencode-ai/sdk";
+import type { ExtensionContext } from "agent-sh/types";
+import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
+
+function parseUnifiedDiff(patch: string): DiffResult | null {
+  if (!patch) return null;
+  const hunks: DiffResult["hunks"] = [];
+  let current: DiffResult["hunks"][number] | null = null;
+  let oldNo = 0;
+  let newNo = 0;
+  let added = 0;
+  let removed = 0;
+
+  for (const raw of patch.split("\n")) {
+    if (raw.startsWith("Index:") || raw.startsWith("===") || raw.startsWith("--- ") || raw.startsWith("+++ ")) continue;
+    const hunkHeader = raw.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunkHeader) {
+      if (current) hunks.push(current);
+      current = { lines: [] };
+      oldNo = parseInt(hunkHeader[1]!, 10);
+      newNo = parseInt(hunkHeader[2]!, 10);
+      continue;
+    }
+    if (!current) continue;
+    if (raw.startsWith("+")) {
+      current.lines.push({ type: "added", oldNo: null, newNo, text: raw.slice(1) });
+      newNo++;
+      added++;
+    } else if (raw.startsWith("-")) {
+      current.lines.push({ type: "removed", oldNo, newNo: null, text: raw.slice(1) });
+      oldNo++;
+      removed++;
+    } else if (raw.startsWith(" ")) {
+      current.lines.push({ type: "context", oldNo, newNo, text: raw.slice(1) });
+      oldNo++;
+      newNo++;
+    }
+  }
+  if (current) hunks.push(current);
+  if (hunks.length === 0) return null;
+  return { hunks, added, removed, isIdentical: added + removed === 0, isNewFile: false };
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, call } = ctx;
+
+  const cwd = (): string => {
+    const v = call("cwd");
+    return typeof v === "string" && v ? v : process.cwd();
+  };
+
+  let runtime: { client: OpencodeClient; server: { url: string; close(): void } } | null = null;
+  let sessionId: string | null = null;
+  // opencode treats `directory` as the project ID and routes its SSE event
+  // stream per-project. If we let prompts use the user's PTY cwd freely,
+  // an in-shell `cd` switches opencode's project mid-session and our SSE
+  // (opened on the original project) goes silent — including for tool
+  // events. Pin everything to the directory captured at session.create;
+  // the agent still learns the user's real cwd via <shell_events> and
+  // can operate elsewhere through absolute paths or `cd && cmd` in Bash.
+  let sessionDirectory: string | null = null;
+  let serverAbort: AbortController | null = null;
+  let streamAbort: AbortController | null = null;
+  let booting = true;
+
+  const announcedTools = new Set<string>();
+  const completedTools = new Set<string>();
+  // message.part.delta only carries `field` ("text"), not the part's
+  // type. Cache type from message.part.updated to route deltas correctly
+  // (text → response, reasoning → thinking).
+  const partKinds = new Map<string, string>();
+  let turnText = "";
+
+  // prompt() and SSE deltas race; resolve the turn on session.idle.
+  let pendingTurnEnd: (() => void) | null = null;
+  let turnIdleSeen = false;
+
+  const listeners: Array<{ event: string; fn: Function }> = [];
+
+  function toolKind(name: string): string {
+    const n = name.toLowerCase();
+    if (n === "read") return "read";
+    if (n === "edit" || n === "patch") return "edit";
+    if (n === "write") return "write";
+    if (n === "glob" || n === "grep" || n === "list") return "search";
+    if (n === "bash" || n === "shell") return "execute";
+    return "execute";
+  }
+
+  function formatToolCall(name: string, input: Record<string, unknown>): string {
+    const str = (v: unknown) => typeof v === "string" ? v : "";
+    const n = name.toLowerCase();
+    if (n === "bash" || n === "shell") return `$ ${str(input.command)}`;
+    if (n === "read" || n === "edit" || n === "write") return str(input.filePath ?? input.file_path ?? input.path);
+    if (n === "grep" || n === "glob") return `${str(input.pattern)} ${str(input.path)}`.trim();
+    return name;
+  }
+
+  function toolLocations(input: Record<string, unknown>): { path: string; line?: number | null }[] | undefined {
+    const raw = input.filePath ?? input.file_path ?? input.path;
+    if (typeof raw !== "string") return undefined;
+    const line = (input.line_number ?? input.line ?? input.offset) as number | undefined;
+    return [{ path: raw, line: line ?? null }];
+  }
+
+  function handleToolPart(part: ToolPart): void {
+    const { callID, tool: toolName, state } = part;
+    const kind = toolKind(toolName);
+
+    if (state.status !== "pending" && !announcedTools.has(callID)) {
+      announcedTools.add(callID);
+      bus.emit("agent:tool-started", {
+        title: toolName,
+        toolCallId: callID,
+        kind,
+        locations: toolLocations(state.input ?? {}),
+        rawInput: state.input,
+        displayDetail: formatToolCall(toolName, state.input ?? {}),
+      });
+    }
+
+    if ((state.status === "completed" || state.status === "error") && !completedTools.has(callID)) {
+      completedTools.add(callID);
+      const isError = state.status === "error";
+      const rawOutput = isError ? state.error : state.output;
+
+      let resultDisplay: { summary?: string; body?: { kind: "diff"; diff: DiffResult; filePath: string } } | undefined;
+      if (!isError && state.status === "completed") {
+        const filePath = state.input?.filePath as string | undefined;
+        let diff: DiffResult | null = null;
+        if (toolName === "edit") {
+          const patch = (state.metadata as any)?.filediff?.patch as string | undefined;
+          if (patch) diff = parseUnifiedDiff(patch);
+        } else if (toolName === "write") {
+          // Overwrites of existing files render as new-file diffs —
+          // opencode doesn't surface old content.
+          const content = state.input?.content as string | undefined;
+          if (typeof content === "string") diff = computeDiff(null, content);
+        }
+        if (diff && filePath && !diff.isIdentical) {
+          const summary = diff.isNewFile
+            ? `+${diff.added}`
+            : `+${diff.added} -${diff.removed}`;
+          resultDisplay = {
+            summary,
+            body: { kind: "diff", diff, filePath },
+          };
+        }
+      }
+
+      bus.emitTransform("agent:tool-completed", {
+        toolCallId: callID,
+        exitCode: isError ? 1 : 0,
+        rawOutput,
+        kind,
+        resultDisplay,
+      });
+      bus.emit("agent:tool-output", {
+        tool: toolName,
+        output: typeof rawOutput === "string" ? rawOutput : "",
+        exitCode: isError ? 1 : 0,
+      });
+    }
+  }
+
+  function emitTextDelta(text: string): void {
+    bus.emitTransform("agent:response-chunk", {
+      blocks: [{ type: "text" as const, text }],
+    });
+    turnText += text;
+  }
+
+  function handleEvent(event: Event): void {
+    if (!sessionId) return;
+    const evType = (event as any).type as string;
+    const props = (event as any).properties ?? {};
+    const sid = props.sessionID;
+    if (typeof sid === "string" && sid !== sessionId) return;
+
+    switch (evType) {
+      // message.part.delta is undocumented in the SDK's Event union but
+      // the SSE consumer yields it. Drop chunks for unknown partIDs —
+      // misrouting bleeds reasoning into the response or vice versa.
+      case "message.part.delta": {
+        if (typeof props.delta !== "string" || !props.delta) break;
+        const kind = partKinds.get(props.partID);
+        if (kind === "reasoning") bus.emit("agent:thinking-chunk", { text: props.delta });
+        else if (kind === "text") emitTextDelta(props.delta);
+        break;
+      }
+      case "message.part.updated": {
+        const part = props.part as Part | undefined;
+        if (!part) break;
+        partKinds.set(part.id, part.type);
+        if (part.type === "tool") handleToolPart(part);
+        break;
+      }
+      case "session.idle": {
+        turnIdleSeen = true;
+        pendingTurnEnd?.();
+        break;
+      }
+      case "session.error": {
+        const err = props.error as { message?: string } | undefined;
+        bus.emit("agent:error", { message: err?.message ?? "opencode session error" });
+        break;
+      }
+      // Without a reply the gated tool hangs forever. The bridge has no
+      // interactive approval UI, so auto-approve — mirrors claude-code-
+      // bridge's permissionMode: "acceptEdits". Set permission.edit:
+      // "allow" in opencode.json to skip the round-trip entirely.
+      case "permission.asked":
+      case "permission.updated": {
+        const permissionID = props.id as string | undefined;
+        if (!permissionID || !runtime || !sessionId) break;
+        runtime.client
+          .postSessionIdPermissionsPermissionId({
+            path: { id: sessionId, permissionID },
+            query: sessionDirectory ? { directory: sessionDirectory } : undefined,
+            body: { response: "once" },
+          })
+          .catch(() => { /* approval is best-effort */ });
+        break;
+      }
+    }
+  }
+
+  async function consumeEvents(client: OpencodeClient, signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      try {
+        const result = await client.event.subscribe({ signal });
+        for await (const ev of result.stream) {
+          if (signal.aborted) return;
+          handleEvent(ev as Event);
+        }
+      } catch {
+        if (signal.aborted) return;
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    }
+  }
+
+  const wireListeners = () => {
+    const onSubmit = async ({ query: userQuery }: { query: string }) => {
+      if (!runtime || !sessionId) {
+        bus.emit("agent:error", {
+          message: booting ? "opencode is still starting up..." : "opencode session not initialized",
+        });
+        bus.emit("agent:processing-done", {});
+        return;
+      }
+
+      bus.emit("agent:query", { query: userQuery });
+      bus.emit("agent:processing-start", {});
+      turnText = "";
+      turnIdleSeen = false;
+      // Set the idle waiter BEFORE prompt() so a fast session.idle can't
+      // race in before we're listening.
+      const idlePromise = new Promise<void>((resolve) => {
+        pendingTurnEnd = () => { resolve(); pendingTurnEnd = null; };
+      });
+
+      const ctxText = String(call("query-context:build") ?? "").trim();
+      const finalPrompt = ctxText ? `${ctxText}\n\n${userQuery}` : userQuery;
+
+      try {
+        const res = await runtime.client.session.prompt({
+          path: { id: sessionId },
+          query: sessionDirectory ? { directory: sessionDirectory } : undefined,
+          body: {
+            parts: [{ type: "text", text: finalPrompt }],
+          },
+        });
+        if (!turnIdleSeen) {
+          await Promise.race([
+            idlePromise,
+            new Promise<void>((r) => setTimeout(r, 60_000)),
+          ]);
+        }
+        // Fallback if SSE never delivered text (network blip, missed
+        // partKinds entry); the prompt response always carries the final.
+        if (!turnText && res.data?.parts) {
+          for (const p of res.data.parts) {
+            if (p.type === "text" && p.text) turnText += p.text;
+          }
+          if (turnText) {
+            bus.emitTransform("agent:response-chunk", {
+              blocks: [{ type: "text" as const, text: turnText }],
+            });
+          }
+        }
+        bus.emitTransform("agent:response-done", { response: turnText });
+      } catch (err) {
+        bus.emit("agent:error", {
+          message: err instanceof Error ? err.message : String(err),
+        });
+      } finally {
+        pendingTurnEnd = null;
+        bus.emit("agent:processing-done", {});
+      }
+    };
+
+    const onCancel = async () => {
+      if (!runtime || !sessionId) return;
+      try {
+        await runtime.client.session.abort({ path: { id: sessionId } });
+      } catch { /* abort is best-effort */ }
+    };
+
+    const onReset = async () => {
+      if (!runtime) return;
+      announcedTools.clear();
+      completedTools.clear();
+      partKinds.clear();
+      // /reset is the one moment we deliberately let the project switch.
+      sessionDirectory = cwd();
+      const res = await runtime.client.session.create({ query: { directory: sessionDirectory } });
+      sessionId = res.data?.id ?? null;
+    };
+
+    bus.on("agent:submit", onSubmit);
+    bus.on("agent:cancel-request", onCancel);
+    bus.on("agent:reset-session", onReset);
+    listeners.push(
+      { event: "agent:submit", fn: onSubmit },
+      { event: "agent:cancel-request", fn: onCancel },
+      { event: "agent:reset-session", fn: onReset },
+    );
+  };
+
+  const unwireListeners = () => {
+    for (const { event, fn } of listeners) bus.off(event as any, fn as any);
+    listeners.length = 0;
+  };
+
+  bus.emit("agent:register-backend", {
+    name: "opencode",
+    start: async () => {
+      try {
+        serverAbort = new AbortController();
+        runtime = await createOpencode({ signal: serverAbort.signal });
+
+        streamAbort = new AbortController();
+        // Subscribe before creating the session so we don't miss early events.
+        void consumeEvents(runtime.client, streamAbort.signal);
+
+        sessionDirectory = cwd();
+        const res = await runtime.client.session.create({ query: { directory: sessionDirectory } });
+        sessionId = res.data?.id ?? null;
+        if (!sessionId) throw new Error("session.create returned no id");
+
+        wireListeners();
+        booting = false;
+        bus.emit("agent:info", { name: "opencode", version: "1.x" });
+      } catch (err) {
+        booting = false;
+        bus.emit("ui:error", {
+          message: `opencode-bridge: failed to initialize — ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    },
+    kill: () => {
+      unwireListeners();
+      streamAbort?.abort();
+      serverAbort?.abort();
+      runtime?.server.close();
+      runtime = null;
+      sessionId = null;
+      sessionDirectory = null;
+      announcedTools.clear();
+      completedTools.clear();
+      partKinds.clear();
+      booting = true;
+    },
+  });
+}

package/examples/extensions/opencode-bridge/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-sh-opencode-bridge",
+  "version": "0.1.0",
+  "description": "opencode agent backend for agent-sh",
+  "type": "module",
+  "main": "index.ts",
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.14.41",
+    "agent-sh": "^0.12.0"
+  }
+}

package/examples/extensions/pi-bridge/README.md

@@ -4,10 +4,17 @@ Runs [pi](https://github.com/badlogic/pi-mono) (`@mariozechner/pi-coding-agent`)
 
 ## Install
 
+```bash
+agent-sh install pi-bridge
+```
+
+This copies the bundled extension into `~/.agent-sh/extensions/pi-bridge` and runs `npm install` for you. To overwrite an existing install, pass `--force`. To uninstall, run `agent-sh uninstall pi-bridge`.
+
+Manual alternative (e.g. for a development checkout you want to symlink):
+
 ```bash
 cp -r examples/extensions/pi-bridge ~/.agent-sh/extensions/pi-bridge
-cd ~/.agent-sh/extensions/pi-bridge
-npm install
+cd ~/.agent-sh/extensions/pi-bridge && npm install
 ```
 
 ## Configure

package/package.json

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