agent-sh 0.3.1 → 0.5.0

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

@@ -0,0 +1,198 @@
+/**
+ * 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 with a custom user_shell MCP tool for PTY access. Claude Code
+ * handles its own model selection, tool execution, and permissions.
+ *
+ * Setup:
+ *   npm install @anthropic-ai/claude-agent-sdk
+ *
+ * Usage:
+ *   agent-sh -e examples/extensions/claude-code-bridge
+ *
+ * Requires: Claude Code CLI installed and authenticated (claude login).
+ */
+import {
+  query,
+  tool,
+  createSdkMcpServer,
+  type Query,
+} from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import type { ExtensionContext } from "../../src/types.js";
+import type { EventBus } from "../../src/event-bus.js";
+
+// ── user_shell MCP tool ───────────────────────────────────────────
+function createUserShellTool(bus: EventBus) {
+  let liveCwd = process.cwd();
+  bus.on("shell:cwd-change", ({ cwd }) => { liveCwd = cwd; });
+
+  return tool(
+    "user_shell",
+    "Run a command in the user's live shell (visible in terminal). " +
+    "Use for cd, export, source, or commands the user wants to see. " +
+    "Set return_output=true only if you need to inspect the result.",
+    {
+      command: z.string().describe("Command to execute in user's shell"),
+      return_output: z.boolean().optional().describe(
+        "Whether to return the command output. Default false.",
+      ),
+    },
+    async (args) => {
+      const result = await bus.emitPipeAsync("shell:exec-request", {
+        command: args.command,
+        output: "",
+        cwd: liveCwd,
+        done: false,
+      });
+
+      const text = args.return_output
+        ? result.output || "(no output)"
+        : "Command executed.";
+
+      return { content: [{ type: "text" as const, text }] };
+    },
+  );
+}
+
+// ── Extension entry point ─────────────────────────────────────────
+export default function activate(ctx: ExtensionContext): void {
+  const { bus } = ctx;
+
+  const shellTool = createUserShellTool(bus);
+  const shellServer = createSdkMcpServer({
+    name: "agent-sh",
+    version: "1.0.0",
+    tools: [shellTool],
+  });
+
+  let activeQuery: Query | null = null;
+  const listeners: Array<{ event: string; fn: Function }> = [];
+
+  const wireListeners = () => {
+    const onSubmit = async ({ query: userQuery, modeInstruction, modeLabel }: any) => {
+      const prompt = modeInstruction
+        ? `${modeInstruction}\n${userQuery}`
+        : userQuery;
+
+      bus.emit("agent:query", { query: userQuery, modeLabel });
+      bus.emit("agent:processing-start", {});
+
+      let fullResponseText = "";
+      let streamed = false;
+
+      try {
+        activeQuery = query({
+          prompt,
+          options: {
+            cwd: process.cwd(),
+            systemPrompt: {
+              type: "preset",
+              preset: "claude_code",
+              append:
+                "You are running inside agent-sh, a terminal wrapper.\n" +
+                "EXECUTE mode ('>'): Use your standard tools. Do NOT use user_shell.\n" +
+                "HELP mode ('?'): Run the command via mcp__agent-sh__user_shell. Just run it, no explanation.\n" +
+                "Each prompt includes a per-query mode instruction — follow it.",
+            },
+            mcpServers: { "agent-sh": shellServer },
+            allowedTools: [
+              "mcp__agent-sh__user_shell",
+              "Read", "Edit", "Write", "Bash", "Glob", "Grep",
+            ],
+            permissionMode: "acceptEdits",
+            includePartialMessages: true,
+          },
+        });
+
+        for await (const message of activeQuery) {
+          switch (message.type) {
+            case "stream_event": {
+              streamed = true;
+              const event = message.event;
+              if (event.type === "content_block_delta") {
+                const delta = event.delta as any;
+                if (delta.type === "text_delta" && delta.text) {
+                  bus.emitTransform("agent:response-chunk", {
+                    blocks: [{ type: "text" as const, text: delta.text }],
+                  });
+                  fullResponseText += delta.text;
+                } else if (delta.type === "thinking_delta" && delta.thinking) {
+                  bus.emit("agent:thinking-chunk", { text: delta.thinking });
+                }
+              }
+              break;
+            }
+
+            case "assistant": {
+              const msg = message.message;
+              for (const block of msg.content) {
+                const b = block as any;
+                if (b.type === "text" && b.text && !streamed) {
+                  bus.emitTransform("agent:response-chunk", {
+                    blocks: [{ type: "text" as const, text: b.text }],
+                  });
+                  fullResponseText += b.text;
+                } else if (b.type === "tool_use") {
+                  bus.emit("agent:tool-started", {
+                    title: b.name,
+                    toolCallId: b.id,
+                    kind: b.name.includes("shell") || b.name === "Bash"
+                      ? "execute"
+                      : "read",
+                  });
+                }
+              }
+              break;
+            }
+
+            case "result":
+              break;
+          }
+        }
+
+        bus.emitTransform("agent:response-done", {
+          response: fullResponseText,
+        });
+      } catch (err) {
+        bus.emit("agent:error", {
+          message: err instanceof Error ? err.message : String(err),
+        });
+      } finally {
+        activeQuery = null;
+        bus.emit("agent:processing-done", {});
+      }
+    };
+
+    const onCancel = () => { activeQuery?.interrupt(); };
+    const onReset = () => { /* each query() is a new session */ };
+
+    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;
+  };
+
+  // ── Register as backend ───────────────────────────────────────
+  bus.emit("agent:register-backend", {
+    name: "claude-code",
+    start: async () => {
+      wireListeners();
+      bus.emit("agent:info", { name: "claude-code", version: "1.0" });
+    },
+    kill: () => {
+      activeQuery?.interrupt();
+      unwireListeners();
+    },
+  });
+}

package/examples/extensions/claude-code-bridge/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-sh-claude-code-bridge",
+  "version": "0.1.0",
+  "description": "Claude Code agent backend for agent-sh",
+  "type": "module",
+  "main": "index.ts",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "zod": "^4.0.0"
+  }
+}

package/examples/extensions/openrouter.ts

@@ -0,0 +1,87 @@
+/**
+ * OpenRouter provider extension.
+ *
+ * Registers OpenRouter as a provider and fetches its full model catalog
+ * at startup. Models appear in /model autocomplete as "model [openrouter]"
+ * and are available for cycling with Shift+Tab.
+ *
+ * Model capabilities (reasoning, context window) are read from the
+ * OpenRouter API response — no hardcoded model lists.
+ *
+ * Setup:
+ *   export OPENROUTER_API_KEY="your-key"
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/openrouter.ts
+ *
+ *   # Or add to settings.json:
+ *   { "extensions": ["./examples/extensions/openrouter.ts"] }
+ */
+import type { ExtensionContext } from "agent-sh/types";
+
+const BASE_URL = "https://openrouter.ai/api/v1";
+const API_KEY = process.env.OPENROUTER_API_KEY ?? "";
+
+/** Curated default models — used immediately while the full catalog loads. */
+const DEFAULT_MODELS = [
+  "anthropic/claude-sonnet-4",
+  "google/gemini-2.5-pro-preview",
+  "openai/gpt-4.1",
+  "deepseek/deepseek-r1",
+  "meta-llama/llama-4-maverick",
+];
+
+interface OpenRouterModel {
+  id: string;
+  name: string;
+  context_length?: number;
+  supported_parameters?: string[];
+  pricing?: { prompt: string; completion: string };
+}
+
+export default function activate({ bus }: ExtensionContext): void {
+  if (!API_KEY) {
+    bus.emit("ui:error", {
+      message: "OpenRouter extension: OPENROUTER_API_KEY not set. Skipping.",
+    });
+    return;
+  }
+
+  // Register provider immediately with curated defaults
+  bus.emit("provider:register", {
+    id: "openrouter",
+    apiKey: API_KEY,
+    baseURL: BASE_URL,
+    defaultModel: DEFAULT_MODELS[0],
+    models: DEFAULT_MODELS,
+  });
+
+  // Fetch full model catalog in background, re-register with capabilities
+  fetchModels().then((models) => {
+    if (models.length > 0) {
+      bus.emit("provider:register", {
+        id: "openrouter",
+        apiKey: API_KEY,
+        baseURL: BASE_URL,
+        defaultModel: DEFAULT_MODELS[0],
+        supportsReasoningEffort: true,
+        models: models.map((m) => ({
+          id: m.id,
+          reasoning: m.supported_parameters?.includes("reasoning") ?? false,
+          contextWindow: m.context_length,
+        })),
+      });
+    }
+  }).catch(() => {
+    // Silently fall back to curated defaults
+  });
+}
+
+async function fetchModels(): Promise<OpenRouterModel[]> {
+  const res = await fetch(`${BASE_URL}/models`, {
+    headers: { Authorization: `Bearer ${API_KEY}` },
+  });
+  if (!res.ok) return [];
+  const data = await res.json();
+  return (data.data ?? []) as OpenRouterModel[];
+}

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

@@ -0,0 +1,35 @@
+# pi-bridge
+
+Runs [pi](https://github.com/nickarora/pi)'s full coding agent as an agent-sh backend. Uses pi's own configuration, models, tools, and extensions — agent-sh just provides the terminal.
+
+## Install
+
+```bash
+# Copy or symlink into your extensions directory
+cp -r examples/extensions/pi-bridge ~/.agent-sh/extensions/pi-bridge
+
+# Install dependencies
+cd ~/.agent-sh/extensions/pi-bridge
+npm install
+```
+
+## Configure
+
+Set as default backend in `~/.agent-sh/settings.json`:
+
+```json
+{
+  "defaultBackend": "pi"
+}
+```
+
+Or switch at runtime:
+
+```
+? /backend pi
+```
+
+## Requirements
+
+- pi must be configured separately (`~/.pi/settings.json`) with API keys and model preferences
+- agent-sh does not override pi's configuration — it uses whatever pi is set up with

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

@@ -0,0 +1,265 @@
+/**
+ * Pi bridge — runs pi's full coding agent in-process as agent-sh's backend.
+ *
+ * Uses pi's own AgentSession with its full configuration: model registry,
+ * provider settings, extensions, session management, and tool system.
+ * Agent-sh provides the shell frontend and TUI rendering.
+ *
+ * In addition to pi's built-in tools, this bridge registers `user_shell`
+ * so pi can execute commands in agent-sh's live PTY (visible to the user,
+ * affects shell state like cd/export/source).
+ *
+ * Setup:
+ *   npm install @mariozechner/pi-agent-core @mariozechner/pi-ai @mariozechner/pi-coding-agent
+ *
+ * Usage:
+ *   agent-sh -e examples/extensions/pi-bridge
+ */
+import type { AgentEvent } from "@mariozechner/pi-agent-core";
+import {
+  createAgentSessionServices,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  SessionManager,
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ExtensionContext } from "../../src/types.js";
+import type { EventBus } from "../../src/event-bus.js";
+
+// ── agent-sh context injected via tool promptGuidelines + promptSnippet ──
+
+// ── user_shell as a pi ToolDefinition ─────────────────────────────
+function createUserShellToolDef(bus: EventBus) {
+  // Track agent-sh's live cwd so user_shell always runs in the right place
+  let liveCwd = process.cwd();
+  bus.on("shell:cwd-change", ({ cwd }) => { liveCwd = cwd; });
+
+  const schema = Type.Object({
+    command: Type.String({ description: "Command to execute in user's shell" }),
+    return_output: Type.Optional(
+      Type.Boolean({
+        description:
+          "Whether to return the command output. Default false — output is shown directly to the user.",
+      }),
+    ),
+  });
+
+  return {
+    name: "user_shell",
+    label: "user_shell",
+    description:
+      "Run a command in the user's live shell (visible in terminal). " +
+      "Use for cd, export, source, or commands the user wants to see. " +
+      "Output is shown directly to the user. Set return_output=true only " +
+      "if you need to inspect the result.",
+    promptSnippet: "Execute commands in the user's live terminal (PTY). Use in HELP mode.",
+    promptGuidelines: [
+      "You are running inside agent-sh, a terminal wrapper with two interaction modes.",
+      "EXECUTE mode (triggered by '>'): Use your standard tools (bash, file ops). Do NOT use user_shell.",
+      "HELP mode (triggered by '?'): Run the command via user_shell. Do not explain or confirm — just run it.",
+      "Each prompt includes a per-query mode instruction — follow it.",
+      "user_shell executes in the user's actual shell (their aliases, env vars, cwd). Use bash for background work.",
+    ],
+    parameters: schema,
+
+    async execute(_toolCallId, params) {
+      const command = params.command;
+      const returnOutput = params.return_output ?? false;
+
+      const result = await bus.emitPipeAsync("shell:exec-request", {
+        command,
+        output: "",
+        cwd: liveCwd,
+        done: false,
+      });
+
+      const text = returnOutput
+        ? result.output || "(no output)"
+        : "Command executed.";
+
+      return { content: [{ type: "text", text }], details: undefined };
+    },
+  };
+}
+
+// ── Extension entry point ─────────────────────────────────────────
+export default function activate(ctx: ExtensionContext): void {
+  const { bus } = ctx;
+  const cwd = process.cwd();
+
+  const userShellTool = createUserShellToolDef(bus);
+
+  // ── Boot pi session (async — register backend synchronously first) ──
+  let session: any = null;
+  let runtime: any = null;
+  let booting = true;
+
+  const boot = async () => {
+    try {
+      // Pi loads its own config: ~/.pi/agent/settings.json, models, extensions
+      const services = await createAgentSessionServices({ cwd });
+      const sessionManager = SessionManager.inMemory(cwd);
+
+      // createRuntime factory — returns { session, services, ... } as expected
+      // by createAgentSessionRuntime
+      const createRuntime = async (opts: any) => {
+        const result = await createAgentSessionFromServices({
+          services,
+          sessionManager: opts.sessionManager ?? sessionManager,
+          customTools: [userShellTool],
+        });
+        return { ...result, services };
+      };
+
+      runtime = await createAgentSessionRuntime(createRuntime, {
+        cwd,
+        sessionManager,
+      });
+      session = runtime.session;
+
+      // Subscribe to pi events → agent-sh bus
+      let fullResponseText = "";
+
+      session.subscribe((event: AgentEvent) => {
+        switch (event.type) {
+          case "agent_start":
+            fullResponseText = "";
+            break;
+
+          case "message_update": {
+            const ame = (event as any).assistantMessageEvent;
+            if (ame.type === "text_delta") {
+              bus.emitTransform("agent:response-chunk", {
+                blocks: [{ type: "text" as const, text: ame.delta }],
+              });
+              fullResponseText += ame.delta;
+            } else if (ame.type === "thinking_delta") {
+              bus.emit("agent:thinking-chunk", { text: ame.delta });
+            }
+            break;
+          }
+
+          case "tool_execution_start":
+            bus.emit("agent:tool-started", {
+              title: (event as any).toolName,
+              toolCallId: (event as any).toolCallId,
+              kind: (event as any).toolName === "user_shell" || (event as any).toolName === "bash"
+                ? "execute"
+                : "read",
+            });
+            break;
+
+          case "tool_execution_update": {
+            const pr = (event as any).partialResult as
+              | { content?: Array<{ type: string; text?: string }> }
+              | undefined;
+            if (pr?.content) {
+              for (const c of pr.content) {
+                if (c.type === "text" && c.text) {
+                  bus.emit("agent:tool-output-chunk", { chunk: c.text });
+                }
+              }
+            }
+            break;
+          }
+
+          case "tool_execution_end":
+            bus.emit("agent:tool-completed", {
+              toolCallId: (event as any).toolCallId,
+              exitCode: (event as any).isError ? 1 : 0,
+              kind: (event as any).toolName === "user_shell" || (event as any).toolName === "bash"
+                ? "execute"
+                : "read",
+            });
+            break;
+
+          case "agent_end":
+            bus.emitTransform("agent:response-done", {
+              response: fullResponseText,
+            });
+            bus.emit("agent:processing-done", {});
+            break;
+        }
+      });
+
+      // Report model info
+      const model = session.model;
+      bus.emit("agent:info", {
+        name: "pi",
+        version: "0.66",
+        model: model ? `${model.provider}/${model.id}` : undefined,
+      });
+
+      booting = false;
+    } catch (err) {
+      booting = false;
+      bus.emit("ui:error", {
+        message: `pi-bridge: failed to initialize — ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  };
+
+  // ── Bus listeners (wired on start, unwired on kill) ────────────
+  const listeners: Array<{ event: string; fn: Function }> = [];
+
+  const wireListeners = () => {
+    const onSubmit = async ({ query, modeInstruction, modeLabel }: any) => {
+      if (!session) {
+        bus.emit("agent:error", {
+          message: booting ? "pi is still starting up..." : "pi session not initialized",
+        });
+        bus.emit("agent:processing-done", {});
+        return;
+      }
+
+      const prompt = modeInstruction ? `${modeInstruction}\n${query}` : query;
+      bus.emit("agent:query", { query, modeLabel });
+      bus.emit("agent:processing-start", {});
+
+      try {
+        await session.prompt(prompt);
+      } catch (err) {
+        bus.emit("agent:error", {
+          message: err instanceof Error ? err.message : String(err),
+        });
+        bus.emit("agent:processing-done", {});
+      }
+    };
+
+    const onCancel = async () => { await session?.abort(); };
+    const onReset = async () => {
+      await runtime?.newSession();
+      session = runtime?.session;
+    };
+
+    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;
+  };
+
+  // ── Register as backend ───────────────────────────────────────
+  bus.emit("agent:register-backend", {
+    name: "pi",
+    start: async () => {
+      await boot();
+      wireListeners();
+    },
+    kill: () => {
+      unwireListeners();
+      runtime?.dispose();
+      session = null;
+      runtime = null;
+      booting = true;
+    },
+  });
+}

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

@@ -0,0 +1,13 @@
+{
+  "name": "agent-sh-pi-bridge",
+  "version": "0.1.0",
+  "description": "Pi coding agent backend for agent-sh",
+  "type": "module",
+  "main": "index.ts",
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "^0.66.0",
+    "@mariozechner/pi-ai": "^0.66.0",
+    "@mariozechner/pi-coding-agent": "^0.66.0",
+    "@sinclair/typebox": "^0.34.0"
+  }
+}

package/examples/extensions/subagents.ts

@@ -0,0 +1,87 @@
+/**
+ * Subagent extension — lets the main agent spawn focused sub-agents.
+ *
+ * The main agent gets a `spawn_agent` tool that creates a fresh agent
+ * with its own context. The LLM decides how to specialize — no
+ * predefined categories, no registry, no config.
+ *
+ * Usage:
+ *   agent-sh -e ./examples/extensions/subagents.ts
+ */
+import type { ExtensionContext } from "../../src/types.js";
+import { runSubagent } from "../../src/agent/subagent.js";
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, llmClient, contextManager } = ctx;
+  if (!llmClient) return;
+
+  const allToolNames = () => ctx.getTools().map(t => t.name);
+
+  ctx.registerTool({
+    name: "spawn_agent",
+    description:
+      "Spawn a subagent with its own fresh context to handle a focused task. " +
+      "Use this to delegate work that needs investigation or multiple tool calls, " +
+      "without polluting your main conversation context. " +
+      "The subagent runs to completion and returns its result.",
+    input_schema: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "Clear description of what the subagent should do",
+        },
+        tools: {
+          type: "array",
+          items: { type: "string" },
+          description: `Tool names the subagent can use. Available: ${allToolNames().join(", ")}`,
+        },
+      },
+      required: ["task"],
+    },
+
+    showOutput: false,
+
+    getDisplayInfo: () => ({
+      kind: "execute",
+    }),
+
+    async execute(args) {
+      const task = args.task as string;
+      const toolNames = args.tools as string[] | undefined;
+
+      const allTools = ctx.getTools();
+      // Filter to requested tools, or give all tools (minus spawn_agent to prevent recursion)
+      const tools = toolNames
+        ? allTools.filter(t => toolNames.includes(t.name))
+        : allTools.filter(t => t.name !== "spawn_agent");
+
+      const systemPrompt =
+        `You are a focused subagent. Complete the task and return a clear, concise result.\n` +
+        `Working directory: ${contextManager.getCwd()}`;
+
+      try {
+        const result = await runSubagent({
+          llmClient,
+          tools,
+          systemPrompt,
+          task,
+          bus,
+          maxIterations: 25,
+        });
+
+        return {
+          content: result || "(no response)",
+          exitCode: 0,
+          isError: false,
+        };
+      } catch (err) {
+        return {
+          content: `Subagent error: ${err instanceof Error ? err.message : String(err)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+  });
+}