agent-sh 0.14.0 → 0.14.2

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
 ```
 
-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.
+agent-sh is built to be agent-agnostic. The recommended path is the built-in agent `ash` — a lightweight agent designed so extensions can plug into the same tool surface. If you'd rather host an existing coding agent (pi, claude-code, opencode), you can [bring your own](#bring-your-own-agent) — with the trade-off that it manages its own separate tools.
 
 ## Quick Start
 
@@ -55,24 +55,9 @@ alias ash="agent-sh"
 
 Once installed, pick a backend below.
 
-### Option A: Bring your own coding agent
+### Option A: Use the built-in agent (ash) — recommended
 
-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. The built-in providers (openrouter, openai, openai-compatible, deepseek) register on startup; ash activates the first one with a usable key.
+`ash` is agent-sh's own lightweight agent, and the path most users should start with: it shares its tool surface with the rest of the system, so extensions you install (new tools, content transforms, slash commands, themes) compose with it directly. It works with any OpenAI-compatible API — pick one of the zero-config paths below, no settings file needed. The built-in providers (openrouter, openai, openai-compatible, deepseek) register on startup; ash activates the first one with a usable key.
 
 **Quickest path** — store a key once via the auth subcommand:
 
@@ -121,6 +106,10 @@ For richer configuration (multiple providers, extensions), run `agent-sh init` t
 
 `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.
 
+### Option B: Bring your own coding agent
+
+If you already use pi, claude-code, or opencode, agent-sh can host it as the backend instead — see [Bring your own agent](#bring-your-own-agent) just below for the full setup and the trade-offs.
+
 ## Bring your own agent
 
 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:

package/dist/agent/agent-loop.d.ts

@@ -15,7 +15,7 @@ import type { EventBus } from "../core/event-bus.js";
 import type { AgentMode } from "./host-types.js";
 import type { LlmClient } from "./llm-client.js";
 import type { HandlerFunctions } from "../utils/handler-registry.js";
-import type { AgentBackend, ToolDefinition } from "./types.js";
+import { type AgentBackend, type ToolDefinition } from "./types.js";
 import { type HistoryAdapter } from "./history-file.js";
 import type { Compositor } from "../utils/compositor.js";
 export interface AgentLoopConfig {

package/dist/agent/agent-loop.js

@@ -1,5 +1,6 @@
 import { setMaxListeners } from "node:events";
 import * as path from "node:path";
+import { contentText } from "./types.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { normalizeToolArgs } from "./normalize-args.js";
 import { ConversationState } from "./conversation-state.js";
@@ -244,9 +245,9 @@ export class AgentLoop {
             this.conversation = new ConversationState(this.handlers, this.instanceId);
             this.lastProjectSkillNames.clear();
         });
-        on("agent:compact-request", () => {
+        on("agent:compact-request", async () => {
             // Force compaction. Strategy lives behind `conversation:compact`.
-            const stats = this.compactWithHooks(0, 0, true);
+            const stats = await this.compactWithHooks(0, 0, true);
             if (stats) {
                 this.bus.emit("ui:info", {
                     message: `(compacted: ~${stats.before.toLocaleString()} → ~${stats.after.toLocaleString()} tokens)`,
@@ -454,13 +455,13 @@ export class AgentLoop {
      * compaction, emit `conversation:after-compact` so listeners
      * (metrics, UI, agent-awareness notes) can react.
      */
-    compactWithHooks(target, keepRecent, force, strategy) {
-        const stats = this.handlers.call("conversation:compact", {
+    async compactWithHooks(target, keepRecent, force, strategy) {
+        const stats = (await this.handlers.call("conversation:compact", {
             target,
             keepRecent,
             force: !!force,
             strategy,
-        });
+        }));
         if (stats) {
             this.bus.emit("conversation:after-compact", {
                 beforeTokens: stats.before,
@@ -597,7 +598,7 @@ export class AgentLoop {
             },
             formatResult: (args, result) => {
                 const action = args.action;
-                const text = result.content;
+                const text = contentText(result.content);
                 if (result.isError)
                     return { summary: "error" };
                 if (action === "search") {
@@ -658,6 +659,13 @@ export class AgentLoop {
             if (extensionSections.length > 0) {
                 parts.push("# Extension Instructions\n\n" + extensionSections.join("\n\n"));
             }
+            if (this.currentMode.modalities?.includes("image")) {
+                parts.push("# Image Support\n\n"
+                    + "This model supports image input. When you need visual information, "
+                    + "you can read image files (PNG, JPEG, GIF, WebP) with read_file — "
+                    + "they will be shown to you directly. Use this to inspect screenshots, "
+                    + "diagrams, UI mockups, charts, or any visual content relevant to the task.");
+            }
             return parts.join("\n\n");
         });
         // ── Orthogonal core-state accessors ──────────────────────────
@@ -838,6 +846,7 @@ export class AgentLoop {
             const label = tool.displayName ?? name;
             this.bus.emit("agent:tool-started", {
                 title: typeof args.description === "string" ? `${label}: ${args.description}` : label,
+                name,
                 toolCallId: id,
                 kind: display.kind, icon: display.icon, locations: display.locations, rawInput: args,
                 displayDetail: tool.formatCall?.(args),
@@ -878,7 +887,7 @@ export class AgentLoop {
                 resultDisplay,
             });
             this.bus.emit("agent:tool-output", {
-                tool: name, output: result.content, exitCode: result.exitCode,
+                tool: name, output: contentText(result.content), exitCode: result.exitCode,
             });
             return result;
         });
@@ -959,7 +968,7 @@ export class AgentLoop {
                 // Compact deeply — shallow targets buy only 1–2 turns of runway on
                 // tool-heavy workloads.
                 const target = Math.floor(threshold * 0.25);
-                const result = this.compactWithHooks(target, 1);
+                const result = await this.compactWithHooks(target, 1);
                 if (!result) {
                     // Auto-compact fired but nothing was evictable. This can happen
                     // in short conversations with heavy tool output where the pin
@@ -1081,6 +1090,7 @@ export class AgentLoop {
                         const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
                         this.bus.emit("agent:tool-started", {
                             title: tool.displayName ?? tc.name,
+                            name: tc.name,
                             toolCallId: tc.id,
                             kind: display.kind, icon: display.icon, locations: display.locations, rawInput: args,
                             displayDetail: tool.formatCall?.(args),
@@ -1097,7 +1107,7 @@ export class AgentLoop {
                             resultDisplay,
                         });
                         this.bus.emit("agent:tool-output", {
-                            tool: tc.name, output: cached.content, exitCode: 0,
+                            tool: tc.name, output: contentText(cached.content), exitCode: 0,
                         });
                         collectedResults.push({
                             callId: tc.id, toolName: tc.name,
@@ -1114,29 +1124,30 @@ export class AgentLoop {
                 const result = await this.handlers.call("tool:execute", { name: tc.name, id: tc.id, args, tool, onChunk: defaultOnChunk,
                     batchIndex, batchTotal: batchTotal > 1 ? batchTotal : undefined,
                     signal });
-                // Truncate large outputs to avoid blowing context.
                 let content = result.content;
-                const maxBytes = tool.maxResultBytes ?? 100_000; // ~25k tokens
-                if (content.length > maxBytes) {
-                    const headBytes = Math.floor(maxBytes * 0.6);
-                    const tailBytes = maxBytes - headBytes;
-                    const lines = content.split("\n");
-                    let headEnd = 0, headLen = 0;
-                    for (let i = 0; i < lines.length && headLen + lines[i].length + 1 <= headBytes; i++) {
-                        headLen += lines[i].length + 1;
-                        headEnd = i + 1;
-                    }
-                    let tailStart = lines.length, tailLen = 0;
-                    for (let i = lines.length - 1; i >= headEnd && tailLen + lines[i].length + 1 <= tailBytes; i--) {
-                        tailLen += lines[i].length + 1;
-                        tailStart = i;
+                if (typeof content === "string") {
+                    const maxBytes = tool.maxResultBytes ?? 100_000; // ~25k tokens
+                    if (content.length > maxBytes) {
+                        const headBytes = Math.floor(maxBytes * 0.6);
+                        const tailBytes = maxBytes - headBytes;
+                        const lines = content.split("\n");
+                        let headEnd = 0, headLen = 0;
+                        for (let i = 0; i < lines.length && headLen + lines[i].length + 1 <= headBytes; i++) {
+                            headLen += lines[i].length + 1;
+                            headEnd = i + 1;
+                        }
+                        let tailStart = lines.length, tailLen = 0;
+                        for (let i = lines.length - 1; i >= headEnd && tailLen + lines[i].length + 1 <= tailBytes; i--) {
+                            tailLen += lines[i].length + 1;
+                            tailStart = i;
+                        }
+                        const omitted = tailStart - headEnd;
+                        content = [
+                            ...lines.slice(0, headEnd),
+                            `\n[… ${omitted} lines omitted (output truncated to ${Math.round(maxBytes / 1024)}KB) …]\n`,
+                            ...lines.slice(tailStart),
+                        ].join("\n");
                     }
-                    const omitted = tailStart - headEnd;
-                    content = [
-                        ...lines.slice(0, headEnd),
-                        `\n[… ${omitted} lines omitted (output truncated to ${Math.round(maxBytes / 1024)}KB) …]\n`,
-                        ...lines.slice(tailStart),
-                    ].join("\n");
                 }
                 const finalResult = {
                     callId: tc.id, toolName: tc.name,
@@ -1347,7 +1358,7 @@ export class AgentLoop {
                 if (this.isContextOverflow(e)) {
                     const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
                     const target = Math.floor((contextWindow - RESPONSE_RESERVE) * 0.6);
-                    const stats = this.compactWithHooks(target, 1);
+                    const stats = await this.compactWithHooks(target, 1);
                     // If compaction freed nothing, retrying will hit the same error.
                     // Surface the real failure instead of looping until exhaustion.
                     if (!stats || stats.after >= stats.before) {

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

@@ -1,4 +1,5 @@
 import type { ChatCompletionMessageParam } from "./llm-client.js";
+import type { ImageContent } from "./types.js";
 import { type NuclearEntry } from "./nuclear-form.js";
 import type { HandlerFunctions } from "../utils/handler-registry.js";
 /** Search hit shape returned by the `history:search` handler. */
@@ -51,7 +52,7 @@ export declare class ConversationState {
             arguments: string;
         };
     }[], extras?: Record<string, unknown>): void;
-    addToolResult(toolCallId: string, content: string, isError?: boolean): void;
+    addToolResult(toolCallId: string, content: string | ImageContent[], isError?: boolean): void;
     /** Add tool results as a user message (for inline tool protocol). */
     addToolResultInline(content: string): void;
     /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
@@ -91,7 +92,7 @@ export declare class ConversationState {
     eagerNucleateTools(results: Array<{
         toolName: string;
         args: Record<string, unknown>;
-        content: string;
+        content: string | ImageContent[];
         isError: boolean;
     }>): void;
     /** Track an entry in memory (nuclear list + recall archive). */

package/dist/agent/conversation-state.js

@@ -123,7 +123,23 @@ export class ConversationState {
         this.invalidateMessagesCache();
     }
     addToolResult(toolCallId, content, isError = false) {
-        this.messages.push({ role: "tool", tool_call_id: toolCallId, content });
+        if (typeof content === "string") {
+            this.messages.push({ role: "tool", tool_call_id: toolCallId, content });
+        }
+        else {
+            // Assembles OpenAI vision content parts for multimodal tool results.
+            // This format (array of text + image_url blocks on a tool message) is
+            // supported by OpenAI and most OpenAI-compatible providers. Providers
+            // that don't support it should not declare image modalities, so this
+            // path is only reached for providers known to handle it.
+            const parts = [];
+            for (const img of content) {
+                parts.push({ type: "image_url", image_url: { url: `data:${img.mimeType};base64,${img.data}` } });
+            }
+            const label = isError ? `Error: [${content.length} image(s)]` : `[${content.length} image(s)]`;
+            parts.unshift({ type: "text", text: label });
+            this.messages.push({ role: "tool", tool_call_id: toolCallId, content: parts });
+        }
         if (isError)
             this.toolErrors.add(toolCallId);
         this.invalidateMessagesCache();
@@ -311,11 +327,12 @@ export class ConversationState {
         const entries = [];
         for (const r of results) {
             const seq = this.nextSeq++;
-            const entry = this.handlers.call("conversation:nucleate-tool", r.toolName, r.args, r.content, r.isError, this.instanceId, seq);
+            const text = typeof r.content === "string" ? r.content : `[${r.content.length} image(s)]`;
+            const entry = this.handlers.call("conversation:nucleate-tool", r.toolName, r.args, text, r.isError, this.instanceId, seq);
             entries.push(entry);
             this.recordNuclearEntry(entry, [
                 { role: "assistant", content: null, tool_calls: [{ id: `seq_${seq}`, type: "function", function: { name: r.toolName, arguments: JSON.stringify(r.args) } }] },
-                { role: "tool", tool_call_id: `seq_${seq}`, content: r.content },
+                { role: "tool", tool_call_id: `seq_${seq}`, content: text },
             ]);
         }
         this.appendToHistory(entries);

package/dist/agent/events.d.ts

@@ -99,6 +99,8 @@ declare module "../core/event-bus.js" {
         };
         "agent:tool-started": {
             title: string;
+            /** Canonical tool name; `title` is the display label and may differ. */
+            name?: string;
             toolCallId?: string;
             kind?: string;
             icon?: string;

package/dist/agent/host-types.d.ts

@@ -51,6 +51,7 @@ export interface ProviderRegistration {
         contextWindow?: number;
         maxTokens?: number;
         echoReasoning?: boolean;
+        modalities?: ("text" | "image")[];
     })[];
     supportsReasoningEffort?: boolean;
     /** Local daemons etc. — `auth list/login` shows "no auth required". */
@@ -77,6 +78,8 @@ export interface AgentMode {
     /** Echo reasoning_content back on assistant turns. Required by DeepSeek;
      *  default off (leaky shims may forward it to the model as OOD input). */
     echoReasoning?: boolean;
+    /** Input modalities the model supports. Defaults to ["text"]. */
+    modalities?: ("text" | "image")[];
     buildReasoningParams?: (level: string) => Record<string, unknown>;
 }
 /**

package/dist/agent/index.js

@@ -61,7 +61,7 @@ function splitRegistration(p) {
         }
         else {
             ids.push(m.id);
-            caps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow, maxTokens: m.maxTokens, echoReasoning: m.echoReasoning });
+            caps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow, maxTokens: m.maxTokens, echoReasoning: m.echoReasoning, modalities: m.modalities });
         }
     }
     return { ids, caps };
@@ -287,6 +287,7 @@ export default function agentBackend(ctx) {
                     reasoning: mc?.reasoning,
                     supportsReasoningEffort: p.supportsReasoningEffort,
                     echoReasoning: mc?.echoReasoning,
+                    modalities: mc?.modalities,
                     buildReasoningParams: bindReasoning(shapeId, model),
                 });
             }

package/dist/agent/llm-client.js

@@ -16,6 +16,7 @@ function attributionHeaders(config) {
     return {
         "HTTP-Referer": config.appUrl ?? "https://agent-sh.dev",
         "X-Title": config.appName ?? "agent-sh",
+        "X-OpenRouter-Categories": "cli-agent,programming-app",
     };
 }
 export class LlmClient {

package/dist/agent/subagent.d.ts

@@ -11,7 +11,7 @@
  */
 import type { EventBus } from "../core/event-bus.js";
 import type { LlmClient } from "./llm-client.js";
-import type { ToolDefinition } from "./types.js";
+import { type ToolDefinition } from "./types.js";
 export interface SubagentOptions {
     /** LLM client to use. */
     llmClient: LlmClient;

package/dist/agent/subagent.js

@@ -1,3 +1,4 @@
+import { contentText } from "./types.js";
 import { ConversationState } from "./conversation-state.js";
 import { normalizeToolArgs } from "./normalize-args.js";
 import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
@@ -63,6 +64,7 @@ export async function runSubagent(opts) {
                 const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
                 bus.emit("agent:tool-started", {
                     title: tc.name,
+                    name: tc.name,
                     toolCallId: tc.id,
                     kind: display.kind,
                     locations: display.locations,
@@ -84,7 +86,9 @@ export async function runSubagent(opts) {
                     resultDisplay,
                 });
             }
-            const content = result.isError ? `Error: ${result.content}` : result.content;
+            const content = result.isError
+                ? `Error: ${contentText(result.content)}`
+                : result.content;
             conversation.addToolResult(tc.id, content, !!result.isError);
         }
     }

package/dist/agent/tool-protocol.d.ts

@@ -10,7 +10,7 @@
  * doesn't need to know which mode is active.
  */
 import type { ChatCompletionTool } from "./llm-client.js";
-import type { ToolDefinition } from "./types.js";
+import { type ToolDefinition } from "./types.js";
 import type { ConversationState } from "./conversation-state.js";
 export interface PendingToolCall {
     id: string;
@@ -20,7 +20,7 @@ export interface PendingToolCall {
 export interface ToolResult {
     callId: string;
     toolName: string;
-    content: string;
+    content: string | import("./types.js").ImageContent[];
     isError: boolean;
 }
 /** Streaming filter — strips tool calls from display output. */

package/dist/agent/tool-protocol.js

@@ -1,3 +1,4 @@
+import { contentText } from "./types.js";
 // ── API mode (current behavior) ──────────────────────────────────
 export class ApiToolProtocol {
     mode = "api";
@@ -33,7 +34,7 @@ export class ApiToolProtocol {
     }
     recordResults(conv, results) {
         for (const r of results) {
-            const content = r.isError ? `Error: ${r.content}` : r.content;
+            const content = r.isError ? `Error: ${contentText(r.content)}` : r.content;
             conv.addToolResult(r.callId, content, r.isError);
         }
     }
@@ -105,7 +106,7 @@ export class InlineToolProtocol {
             return;
         const parts = results.map((r) => {
             const status = r.isError ? "error" : "ok";
-            return `[${r.toolName} ${r.callId} ${status}]\n${r.content}`;
+            return `[${r.toolName} ${r.callId} ${status}]\n${contentText(r.content)}`;
         });
         conv.addToolResultInline(parts.join("\n\n"));
     }
@@ -362,7 +363,7 @@ export class DeferredToolProtocol {
     }
     recordResults(conv, results) {
         for (const r of results) {
-            const content = r.isError ? `Error: ${r.content}` : r.content;
+            const content = r.isError ? `Error: ${contentText(r.content)}` : r.content;
             conv.addToolResult(r.callId, content, r.isError);
         }
     }
@@ -455,7 +456,7 @@ export class DeferredLookupProtocol {
     }
     recordResults(conv, results) {
         for (const r of results) {
-            const content = r.isError ? `Error: ${r.content}` : r.content;
+            const content = r.isError ? `Error: ${contentText(r.content)}` : r.content;
             conv.addToolResult(r.callId, content, r.isError);
         }
     }

package/dist/agent/tools/glob.d.ts

@@ -1,2 +1,2 @@
-import type { ToolDefinition } from "../types.js";
+import { type ToolDefinition } from "../types.js";
 export declare function createGlobTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/glob.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { executeArgv } from "../../utils/executor.js";
 import { resolveRgPath } from "../../utils/ripgrep-path.js";
+import { contentText } from "../types.js";
 import { expandHome } from "./expand-home.js";
 export function createGlobTool(getCwd) {
     return {
@@ -27,9 +28,10 @@ export function createGlobTool(getCwd) {
         },
         showOutput: false,
         formatResult: (_args, result) => {
-            if (result.isError || result.content === "No files matched.")
+            const text = contentText(result.content);
+            if (result.isError || text === "No files matched.")
                 return { summary: "0 files" };
-            const lines = result.content.split("\n").filter(l => l && !l.startsWith("["));
+            const lines = text.split("\n").filter(l => l && !l.startsWith("["));
             return { summary: `${lines.length} files` };
         },
         getDisplayInfo: (args) => ({

package/dist/agent/tools/grep.d.ts

@@ -1,2 +1,2 @@
-import type { ToolDefinition } from "../types.js";
+import { type ToolDefinition } from "../types.js";
 export declare function createGrepTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/grep.js

@@ -1,5 +1,6 @@
 import { executeArgv } from "../../utils/executor.js";
 import { resolveRgPath } from "../../utils/ripgrep-path.js";
+import { contentText } from "../types.js";
 import { expandHome } from "./expand-home.js";
 export function createGrepTool(getCwd) {
     return {
@@ -58,9 +59,10 @@ export function createGrepTool(getCwd) {
         },
         showOutput: false,
         formatResult: (args, result) => {
-            if (result.isError || result.content === "No matches found.")
+            const text = contentText(result.content);
+            if (result.isError || text === "No matches found.")
                 return { summary: "0 matches" };
-            const lines = result.content.split("\n").filter(Boolean);
+            const lines = text.split("\n").filter(Boolean);
             // Strip pagination info line from count
             const resultLines = lines.filter(l => !l.startsWith("[Showing "));
             const mode = args.output_mode ?? "files_with_matches";

package/dist/agent/tools/ls.d.ts

@@ -1,2 +1,2 @@
-import type { ToolDefinition } from "../types.js";
+import { type ToolDefinition } from "../types.js";
 export declare function createLsTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/ls.js

@@ -1,5 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { contentText } from "../types.js";
 import { expandHome } from "./expand-home.js";
 function formatSize(bytes) {
     if (bytes < 1024)
@@ -33,9 +34,10 @@ export function createLsTool(getCwd) {
                 : [],
         }),
         formatResult: (_args, result) => {
-            if (result.isError || result.content === "(empty directory)")
+            const text = contentText(result.content);
+            if (result.isError || text === "(empty directory)")
                 return { summary: "0 entries" };
-            const lines = result.content.split("\n").filter(Boolean);
+            const lines = text.split("\n").filter(Boolean);
             return { summary: `${lines.length} entries` };
         },
         async execute(args) {

package/dist/agent/tools/read-file.d.ts

@@ -1,4 +1,4 @@
-import type { ToolDefinition } from "../types.js";
+import { type ToolDefinition } from "../types.js";
 /** Tracks the last-read state of a file for deduplication. */
 export interface FileReadState {
     mtimeMs: number;

package/dist/agent/tools/read-file.js

@@ -1,6 +1,14 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { contentText } from "../types.js";
 import { expandHome } from "./expand-home.js";
+const IMAGE_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
 export function createReadFileTool(getCwd, cache) {
     return {
         name: "read_file",
@@ -32,11 +40,12 @@ export function createReadFileTool(getCwd, cache) {
             locations: [{ path: args.path }],
         }),
         formatResult: (_args, result) => {
+            const text = contentText(result.content);
             if (result.isError)
                 return {};
-            if (result.content.startsWith("File unchanged"))
+            if (text.startsWith("File unchanged"))
                 return { summary: "cached" };
-            const lines = result.content.split("\n").filter(l => !l.startsWith("["));
+            const lines = text.split("\n").filter(l => !l.startsWith("["));
             return { summary: `${lines.length} lines` };
         },
         async execute(args) {
@@ -72,6 +81,25 @@ export function createReadFileTool(getCwd, cache) {
                         isError: true,
                     };
                 }
+                const ext = path.extname(absPath).toLowerCase();
+                const mimeType = IMAGE_MIME_TYPES[ext];
+                if (mimeType) {
+                    const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5MB — base64 adds ~33%
+                    if (stat.size > MAX_IMAGE_BYTES) {
+                        return {
+                            content: `Image is ${(stat.size / (1024 * 1024)).toFixed(1)}MB — too large. Images are capped at 5MB.`,
+                            exitCode: 1,
+                            isError: true,
+                        };
+                    }
+                    const buf = await fs.readFile(absPath);
+                    const data = buf.toString("base64");
+                    return {
+                        content: [{ type: "image", data, mimeType }],
+                        exitCode: 0,
+                        isError: false,
+                    };
+                }
                 const content = await fs.readFile(absPath, "utf-8");
                 const lines = content.split("\n");
                 const start = reqOffset - 1; // 1-indexed → 0-indexed

package/dist/agent/types.d.ts

@@ -15,8 +15,18 @@ export interface AgentBackend {
     start?(): Promise<void>;
     kill(): void;
 }
+/** Image content block for multimodal tool results. */
+export interface ImageContent {
+    type: "image";
+    /** Base64-encoded image data (no data: URL prefix). */
+    data: string;
+    /** MIME type (e.g. "image/png", "image/jpeg"). */
+    mimeType: string;
+}
+/** Extract the text portion of a tool result's content. Returns "" for image-only results. */
+export declare function contentText(content: string | ImageContent[]): string;
 export interface ToolResult {
-    content: string;
+    content: string | ImageContent[];
     exitCode: number | null;
     isError: boolean;
     /** When set, takes precedence over `tool.formatResult()`. */
@@ -57,8 +67,8 @@ export interface InteractiveSession<T> {
     render(width: number): string[];
     /** Handle raw input. Call done(result) to finish the session. */
     handleInput(data: string, done: (result: T) => void): void;
-    /** Called when session starts. Receives invalidate() for async re-renders. */
-    onMount?(invalidate: () => void): void;
+    /** done() lets the session resolve itself from outside handleInput. */
+    onMount?(invalidate: () => void, done: (result: T) => void): void;
     /** Called when session ends (cleanup). */
     onUnmount?(): void;
 }

package/dist/agent/types.js

@@ -1 +1,6 @@
-export {};
+/** Extract the text portion of a tool result's content. Returns "" for image-only results. */
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map(c => `[image: ${c.mimeType}]`).join("\n");
+}

package/dist/cli/args.js

@@ -3,7 +3,9 @@ const HELP_TEXT = `agent-sh — a shell-first terminal where AI is one keystroke
 
 Usage: agent-sh [options]
        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 install <spec> [--force] [--sync-deps]
+                                          Install an extension (bundled name, file:, npm:, github:)
+                                          --sync-deps rewrites a stale agent-sh pin to the host version
        agent-sh uninstall <name>          Remove an installed extension
        agent-sh list                      List installed extensions
        agent-sh auth login [provider]     Store an API key for a built-in provider

package/dist/cli/install.d.ts

@@ -1,5 +1,6 @@
 interface InstallOpts {
     force?: boolean;
+    syncDeps?: boolean;
 }
 export declare function listBundled(): string[];
 /** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */