agent-sh 0.12.23 → 0.12.24

package/README.md

@@ -19,7 +19,7 @@ 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.
+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`.
 
 ## Quick Start
 
@@ -95,7 +95,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 — `agent-sh install pi-bridge && agent-sh --backend pi` runs [pi](examples/extensions/pi-bridge/) as a drop-in backend.
 
 **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/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/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);
@@ -280,24 +301,37 @@ async function main() {
         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)) {
+        shell?.kill();
+        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();
+    core.activateBackend(config.backend);
     // ── 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) {

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/package.json

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