agent-sh 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 
 Not a shell that lives in an agent — an agent that lives in a shell.
 
-agent-sh is a real terminal first. Every keystroke goes to a real PTY. `cd`, pipes, vim, job control — they all just work. But type `>` at the start of a line, and you're talking to an AI agent that has full context of what you've been doing: your working directory, recent commands, their output.
+agent-sh is a real terminal first. Every keystroke goes to a real PTY. `cd`, pipes, vim, job control — they all just work. But type `?` or `>` at the start of a line, and you're talking to an AI agent that has full context of what you've been doing: your working directory, recent commands, their output.
 
 The agent connects via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), so you can plug in **any** ACP-compatible agent: [pi](https://github.com/svkozak/pi-acp), claude-code, codex, gemini-cli, goose, etc.
 
@@ -13,15 +13,17 @@ The agent connects via the [Agent Client Protocol (ACP)](https://agentclientprot
 ⚡ src $ ls -la                          # real shell command
 ⚡ src $ cd ../tests && npm test          # real cd, env, aliases — all just work
 ⚡ src $ vim file.ts                      # opens vim in the same PTY
-⚡ src $ > refactor the auth middleware   # → sent to agent via ACP
-⚡ src $ > explain the last error         # agent sees your recent commands + output
+⚡ src $ ? explain the last error         # query mode → agent investigates using its own tools
+⚡ src $ > deploy to staging              # execute mode → agent runs it in your live shell
 ```
 
 ## Why shell-first?
 
-Most AI coding tools are agent-first: the LLM drives the experience and the shell is bolted on. That means no real PTY, no job control, no interactive commands, and fragile `cd` tracking that reimplements what bash gives you for free.
+I live mostly in a terminal. I don't just want an agent that has access to my shell — I want a shell that has access to my agent.
 
-agent-sh starts from the opposite end. The shell is the primary interface — it's your terminal, not the agent's. The agent is a tool you reach for when you need it, not the other way around.
+Most AI coding tools get this backwards: the LLM drives the experience and the shell is bolted on. That means no real PTY, no job control, no interactive commands, and fragile `cd` tracking that reimplements what bash gives you for free.
+
+agent-sh starts from the opposite end. The shell is the primary interface — it's your terminal, not the agent's. The agent is a tool you reach for when you need it, not the other way around. Two modes give you fine-grained control: `?` for questions and tasks (agent uses its own tools), `>` for commands that run directly in your live shell.
 
 ### Why ACP?
 
@@ -40,6 +42,8 @@ The [Agent Client Protocol](https://agentclientprotocol.com/) decouples the shel
 - **Real-time Streaming** — Agent responses stream live with syntax highlighting
 - **Zero Latency** — Direct PTY access, full terminal compatibility
 - **Context Aware** — Agent sees your cwd, recent commands, and their output
+- **Dual Input Modes** — `?` for questions/tasks (agent tools), `>` for live shell execution
+- **Extensible Modes** — Extensions can register custom input modes with their own triggers
 - **Multiple Agents** — Easy switching between pi-acp, claude, and other ACP agents
 - **Inline Diff Preview** — File writes show syntax-highlighted diffs inline (Ctrl+O to expand)
 - **Thinking Display** — Toggle agent thinking/reasoning text with Ctrl+T
@@ -67,22 +71,34 @@ See the [Usage Guide](docs/usage.md) for all options, model configuration, and e
 
 ## Input Modes
 
+agent-sh has two agent input modes, each triggered by a single character at the start of an empty line:
+
+| Trigger | Mode | Behavior |
+|---|---|---|
+| `?` | **Query** | Agent uses its own tools (bash, file read/write, search) to investigate and answer. Stays in query mode after each response. |
+| `>` | **Execute** | Agent runs a command in your live shell via `user_shell`. Your aliases, env vars, and cwd apply. Returns to shell after execution. |
+
+Regular shell input works as before — commands go straight to the PTY:
+
 | Input | Behavior |
 |---|---|
 | `ls -la` | Runs in real shell (PTY), output displayed normally |
 | `cd src && make` | Real shell — cd, env, aliases all just work |
 | `vim file.ts` | Opens vim in the same PTY, no hacks needed |
-| `> refactor this fn` | Sends to agent via ACP, streams response inline |
-| `> /help` | Shows available slash commands |
+| `? refactor this fn` | Query mode — agent investigates and responds |
+| `> restart the server` | Execute mode — agent runs it in your live shell |
+| `? /help` | Shows available slash commands (works in either mode) |
 | `Ctrl-C` | Standard signal to shell, or cancels active agent response |
 | `Ctrl-O` | Expand/collapse truncated diff preview |
 | `Ctrl-T` | Toggle thinking/reasoning text display |
 | `Shift-Tab` | Cycle thinking level (off → minimal → low → medium → high → xhigh) |
-| `Escape` | Exit agent input mode (when typing after `>`) |
+| `Escape` | Exit agent input mode |
+
+Modes are extensible — extensions can register new modes via the `input-mode:register` event (see [Extensions](docs/extensions.md#custom-input-modes)).
 
 ### Agent Input Keybindings
 
-When typing after `>`, full readline-style keybindings are available:
+When typing in either agent mode (`?` or `>`), full readline-style keybindings are available:
 
 | Key | Action |
 |---|---|
@@ -103,10 +119,11 @@ When typing after `>`, full readline-style keybindings are available:
 
 ### Thinking Level
 
-The agent prompt shows the current thinking level next to the model name:
+The agent prompt shows the current thinking level next to the model name, with a mode-specific indicator:
 
 ```
-pi (claude-3.5-sonnet) [medium] ● ❯
+pi (claude-sonnet-4-6) [medium] ❓ ❯    # query mode
+pi (claude-sonnet-4-6) [medium] ● ⟩     # execute mode
 ```
 
 Press **Shift-Tab** in agent input mode to cycle through levels. The levels are advertised by the agent via ACP session modes — different agents may offer different options. The spinner label reflects the mode: "Thinking" when thinking is enabled, "Working" when it's off.

package/dist/acp-client.d.ts

@@ -30,7 +30,12 @@ export declare class AcpClient {
     /**
      * Send a user query to the agent.
      */
-    sendPrompt(query: string): Promise<void>;
+    private firstPromptSent;
+    private static readonly SESSION_ORIENTATION;
+    sendPrompt(query: string, opts?: {
+        modeInstruction?: string;
+        modeLabel?: string;
+    }): Promise<void>;
     /**
      * Silently cancel the prompt after a shell tool completes.
      * Unlike user-initiated cancel(), this doesn't show "(cancelled)" —

package/dist/acp-client.js

@@ -21,7 +21,7 @@ export class AcpClient {
     terminalDonePromises = new Map();
     terminalCounter = 0;
     fileWatcher;
-    pendingToolCalls = new Map(); // toolCallId → title
+    pendingToolCalls = new Map();
     autoCancelled = false;
     pendingToolCounter = 0;
     agentInfo = null;
@@ -129,7 +129,29 @@ export class AcpClient {
     /**
      * Send a user query to the agent.
      */
-    async sendPrompt(query) {
+    firstPromptSent = false;
+    static SESSION_ORIENTATION = [
+        "You are running inside agent-sh, a terminal wrapper that gives the user two interaction modes:",
+        "",
+        "QUERY mode (triggered by '?'): The user is asking questions or requesting tasks.",
+        "Use your internal tools (bash, file operations, etc.) to accomplish tasks.",
+        "Do NOT use user_shell in this mode.",
+        "",
+        "EXECUTE mode (triggered by '>'): The user wants a command run in their live shell session.",
+        "You may use shell_recall to understand previous context and your own tools to investigate,",
+        "but the final action must be sending the command via user_shell,",
+        "which executes in the user's actual shell (with their aliases, env vars, and cwd).",
+        "Do not explain or ask for confirmation — just run it.",
+        "",
+        "Each prompt includes a per-query mode instruction — follow it.",
+        "",
+        "Available tools:",
+        "- user_shell: Runs commands in the user's live shell session (their PTY). Use in EXECUTE mode.",
+        "- shell_recall: Retrieves recent shell command history and output from the user's session.",
+        "  Use this to understand what the user has been doing before answering questions.",
+        "- Your standard tools (bash, file read/write, etc.): Use in AGENT mode.",
+    ].join("\n");
+    async sendPrompt(query, opts) {
         if (!this.connection || !this.sessionId) {
             this.bus.emit("agent:error", { message: "Not connected to agent" });
             return;
@@ -141,24 +163,25 @@ export class AcpClient {
         this.autoCancelled = false;
         let cancelled = false;
         // Emit agent query event (TUI renders echo+spinner, ContextManager records it)
-        this.bus.emit("agent:query", { query });
+        this.bus.emit("agent:query", { query, modeLabel: opts?.modeLabel });
         // Build structured context from ContextManager
         const contextBlock = this.contextManager.getContext();
         try {
             this.log("sending prompt...");
-            const promptTimeoutMs = 300000; // 5 minutes timeout for LLM response
-            const response = await Promise.race([
-                this.connection.prompt({
-                    sessionId: this.sessionId,
-                    prompt: [
-                        {
-                            type: "text",
-                            text: contextBlock + "\n" + query,
-                        },
-                    ],
-                }),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`Prompt timeout after ${promptTimeoutMs}ms`)), promptTimeoutMs)),
-            ]);
+            const promptContent = [];
+            // Send session orientation on first prompt
+            if (!this.firstPromptSent) {
+                promptContent.push({ type: "text", text: AcpClient.SESSION_ORIENTATION });
+                this.firstPromptSent = true;
+            }
+            if (opts?.modeInstruction) {
+                promptContent.push({ type: "text", text: opts.modeInstruction });
+            }
+            promptContent.push({ type: "text", text: contextBlock + "\n" + query });
+            const response = await this.connection.prompt({
+                sessionId: this.sessionId,
+                prompt: promptContent,
+            });
             this.log(`prompt resolved: stopReason=${response.stopReason}`);
             if (response.stopReason === "cancelled") {
                 cancelled = true;
@@ -176,7 +199,7 @@ export class AcpClient {
         finally {
             this.log("restoring shell mode");
             if (!cancelled) {
-                this.bus.emit("agent:response-done", {
+                this.bus.emitTransform("agent:response-done", {
                     response: this.currentResponseText,
                 });
             }
@@ -244,6 +267,7 @@ export class AcpClient {
         this.sessionId = sessionResponse.sessionId;
         this.lastResponseText = "";
         this.currentResponseText = "";
+        this.firstPromptSent = false;
         this.updateModes(sessionResponse);
     }
     /**
@@ -327,8 +351,15 @@ export class AcpClient {
     createClientHandler() {
         return {
             // Required: handle session update notifications (streaming)
+            // Errors must not propagate — the ACP SDK returns them as error
+            // responses to the agent, which can stall the stream.
             sessionUpdate: async (params) => {
-                this.handleSessionUpdate(params);
+                try {
+                    this.handleSessionUpdate(params);
+                }
+                catch (err) {
+                    this.log(`Error in sessionUpdate handler: ${err instanceof Error ? err.stack : err}`);
+                }
             },
             // Required: handle permission requests
             requestPermission: async (params) => {
@@ -370,40 +401,53 @@ export class AcpClient {
                 const content = update.content;
                 if (content.type === "text") {
                     this.currentResponseText += content.text;
-                    this.bus.emit("agent:response-chunk", { text: content.text });
+                    this.bus.emitTransform("agent:response-chunk", { text: content.text });
                 }
                 break;
             }
             case "agent_thought_chunk": {
                 const thought = update.content;
                 if (thought.type === "text" && thought.text) {
-                    this.bus.emit("agent:thinking-chunk", { text: thought.text });
+                    this.bus.emitTransform("agent:thinking-chunk", { text: thought.text });
                 }
                 break;
             }
             case "tool_call": {
                 const toolId = update.toolCallId || `tool-${this.pendingToolCounter++}`;
-                this.pendingToolCalls.set(toolId, update.title ?? "");
-                this.bus.emit("agent:tool-started", {
+                const payload = {
                     title: update.title,
                     toolCallId: toolId,
                     kind: update.kind ?? undefined,
                     locations: update.locations?.map((l) => ({ path: l.path, line: l.line })),
                     rawInput: update.rawInput,
+                };
+                const defer = this.pendingToolCalls.size > 0;
+                this.pendingToolCalls.set(toolId, {
+                    title: update.title ?? "",
+                    deferredPayload: defer ? payload : undefined,
                 });
+                if (!defer) {
+                    this.bus.emit("agent:tool-started", payload);
+                }
                 break;
             }
             case "tool_call_update": {
                 const toolId = update.toolCallId;
-                const toolTitle = toolId ? this.pendingToolCalls.get(toolId) : undefined;
+                const toolInfo = toolId ? this.pendingToolCalls.get(toolId) : undefined;
+                const toolTitle = toolInfo?.title;
                 if (update.status === "completed" || update.status === "failed") {
+                    // Emit deferred tool-started before output (parallel tools)
+                    if (toolInfo?.deferredPayload) {
+                        this.bus.emit("agent:tool-started", toolInfo.deferredPayload);
+                        toolInfo.deferredPayload = undefined;
+                    }
                     // Show content only on final status. Skip tools whose output the
                     // user already sees (user_shell → PTY) or is agent-only (shell_recall).
                     const skipOutput = toolTitle === "user_shell" || toolTitle === "shell_recall";
                     if (!skipOutput && update.content && Array.isArray(update.content)) {
                         for (const block of update.content) {
                             if (block.type === "content" && block.content?.type === "text" && block.content.text) {
-                                this.bus.emit("agent:tool-output-chunk", { chunk: block.content.text });
+                                this.bus.emitTransform("agent:tool-output-chunk", { chunk: block.content.text });
                             }
                         }
                     }

package/dist/core.js

@@ -20,17 +20,21 @@ import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
 import { AcpClient } from "./acp-client.js";
 import { setPalette } from "./utils/palette.js";
+import * as streamTransform from "./utils/stream-transform.js";
+import * as settingsMod from "./settings.js";
+import { HandlerRegistry } from "./utils/handler-registry.js";
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
 export function createCore(config) {
     const bus = new EventBus();
+    const handlers = new HandlerRegistry();
     const contextManager = new ContextManager(bus);
     const client = new AcpClient({ bus, contextManager, config });
     let connected = false;
     // Route frontend events to the agent — any frontend (Shell, WebSocket,
     // REST handler, test harness) can emit these without knowing about AcpClient.
-    bus.on("agent:submit", ({ query }) => {
+    bus.on("agent:submit", ({ query, modeInstruction, modeLabel }) => {
         (async () => {
             // Wait briefly for agent connection if start() is still in progress
             if (!connected) {
@@ -42,7 +46,7 @@ export function createCore(config) {
                 bus.emit("ui:error", { message: "Agent not connected. Please wait a moment and try again." });
                 return;
             }
-            await client.sendPrompt(query);
+            await client.sendPrompt(query, { modeInstruction, modeLabel });
         })().catch((err) => {
             bus.emit("agent:error", {
                 message: err instanceof Error ? err.message : String(err),
@@ -67,6 +71,12 @@ export function createCore(config) {
                 getAcpClient: () => client,
                 quit: opts.quit,
                 setPalette,
+                createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
+                createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
+                getExtensionSettings: settingsMod.getExtensionSettings,
+                define: (name, fn) => handlers.define(name, fn),
+                advise: (name, wrapper) => handlers.advise(name, wrapper),
+                call: (name, ...args) => handlers.call(name, ...args),
             };
         },
         kill() {

package/dist/event-bus.d.ts

@@ -22,16 +22,21 @@ export interface ShellEvents {
     "shell:agent-exec-done": Record<string, never>;
     "agent:submit": {
         query: string;
+        modeInstruction?: string;
+        modeLabel?: string;
     };
     "agent:cancel-request": Record<string, never>;
+    "input-mode:register": import("./types.js").InputModeConfig;
     "agent:query": {
         query: string;
+        modeLabel?: string;
     };
     "agent:thinking-chunk": {
         text: string;
     };
     "agent:response-chunk": {
         text: string;
+        blocks?: ContentBlock[];
     };
     "agent:response-done": {
         response: string;
@@ -126,6 +131,20 @@ export interface ShellEvents {
         }[];
     };
 }
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "code-block";
+    language: string;
+    code: string;
+} | {
+    type: "image";
+    data: Buffer;
+} | {
+    type: "raw";
+    escape: string;
+};
 type Listener<T> = (payload: T) => void;
 type PipeListener<T> = (payload: T) => T;
 type AsyncPipeListener<T> = (payload: T) => T | Promise<T>;
@@ -145,6 +164,13 @@ export declare class EventBus {
     off<K extends keyof ShellEvents>(event: K, fn: Listener<ShellEvents[K]>): void;
     /** Emit a fire-and-forget event. */
     emit<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): void;
+    /**
+     * Transform-then-notify: run the payload through any registered pipe
+     * listeners (transforms), then emit the final result to regular `on`
+     * listeners (renderers). This enables content pipelines where extensions
+     * modify data (e.g. render LaTeX → terminal image) before renderers see it.
+     */
+    emitTransform<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): void;
     /** Register a transform listener for a pipeline event. */
     onPipe<K extends keyof ShellEvents>(event: K, fn: PipeListener<ShellEvents[K]>): void;
     /**

package/dist/event-bus.js

@@ -21,6 +21,16 @@ export class EventBus {
     emit(event, payload) {
         this.emitter.emit(event, payload);
     }
+    /**
+     * Transform-then-notify: run the payload through any registered pipe
+     * listeners (transforms), then emit the final result to regular `on`
+     * listeners (renderers). This enables content pipelines where extensions
+     * modify data (e.g. render LaTeX → terminal image) before renderers see it.
+     */
+    emitTransform(event, payload) {
+        const transformed = this.emitPipe(event, payload);
+        this.emitter.emit(event, transformed);
+    }
     /** Register a transform listener for a pipeline event. */
     onPipe(event, fn) {
         let listeners = this.pipeListeners.get(event);

package/dist/extensions/tui-renderer.d.ts

@@ -1,2 +1,2 @@
 import type { ExtensionContext } from "../types.js";
-export default function activate({ bus, getAcpClient }: ExtensionContext): void;
+export default function activate(ctx: ExtensionContext): void;