agent-sh 0.14.10 → 0.15.0

package/README.md

@@ -1,15 +1,15 @@
 # agent-sh
 
-A real shell with an AI agent one keystroke away.
-
 [![npm version](https://img.shields.io/npm/v/agent-sh.svg)](https://www.npmjs.com/package/agent-sh)
 [![license](https://img.shields.io/npm/l/agent-sh.svg)](https://github.com/guanyilun/agent-sh/blob/main/LICENSE)
 
-![demo](assets/demo.gif)
+A composable agent runtime — pair any frontend with any agent backend, over one shared extension layer.
 
-I live in my terminal. A lot of the time I'm not coding — I'm deploying something, poking at a failing `rsync`, figuring out why `docker build` won't start, fixing a one-liner. And very often I need an AI agent to help. Spinning up a full coding agent for this stuff is overkill, and I got tired of copy-pasting errors into a chat window every time.
+## A shell with the agent one keystroke away
 
-So I built agent-sh. Under the hood it's a normal shell on top of node-pty — your rc config, your aliases, vim and tmux all just work. But at the start of any line, type `>` and you're talking to a small agent that already sees your cwd, your last command, and its output. Nothing to set up, no project to explain.
+The frontend bundled with agent-sh: a normal shell on top of node-pty — your rc config, your aliases, vim and tmux all just work. But at the start of any line, type `>` and you're talking to an agent that already sees your cwd, your last command, and its output. Nothing to set up, no project to explain.
+
+![demo](assets/demo.gif)
 
 ```
 ~ $ ls -la                       # real shell command
@@ -19,10 +19,12 @@ So I built agent-sh. Under the hood it's a normal shell on top of node-pty — y
 ~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
-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.
+**The agent behind `>` is swappable — the terminal stays the same.** Out of the box it's **`ash`**, agent-sh's own lightweight agent: it works with any OpenAI-compatible API and shares its tool surface with every extension you install. Already invested in another coding agent? The same `>` and the same shell-context wiring can host **pi**, **claude-code**, or **opencode** instead through in-the-box bridges — bring your own backend, keep the workflow. The Quick Start below walks through both.
 
 ## Quick Start
 
+**This sets up the agent-sh shell** — the frontend bundled in the `agent-sh` package. (For the other frontends, install [ashi](examples/extensions/ashi/) or [asHub](https://github.com/firslov/asHub) instead.)
+
 ### Installation
 
 Install from npm:
@@ -139,19 +141,40 @@ All three bridges receive agent-sh's per-query shell context (`<shell_events>`)
 
 **Caveat:** pi, claude-code, and opencode each manage their own tool surfaces, so agent-sh extensions that register tools (or skills, instructions, etc.) for the built-in `ash` agent generally won't be visible to a hosted backend. Frontend extensions (themes, content transforms, slash commands, the TUI renderer) keep working — only the agent-side capabilities differ. Use the bridges when you want that agent's toolset; stay on `ash` when you want agent-sh's extension ecosystem.
 
-## Key Features
+## Same runtime, other frontends
+
+The shell is just one frontend. Because the frontend is itself an extension on the bus, the same runtime — same agent backends, tools, providers, and `~/.agent-sh/settings.json` — drives completely different apps.
+
+### ashi — a standalone coding agent
+
+[**`@guanyilun/ashi`**](examples/extensions/ashi/) is the same `ash` agent in a chat-style TUI, with no shell underneath — just the agent. Installed separately, it reuses agent-sh's backend, tools, slash commands, providers, and skills, and adds session history, in-session branching, and LLM-driven compaction.
+
+```bash
+npm install -g @guanyilun/ashi
+ashi
+```
+
+ashi makes the runtime's **decoupled rendering** concrete: the frontend is itself an extension, and even *how* it draws tool calls and results is a swappable render extension. Same agent backend, same conversation — load a different render extension and the whole TUI restyles, no code changes:
+
+| pi-style rendering | claude-code-style rendering |
+|---|---|
+| ![ashi rendering tool calls pi-style](assets/ashi-pi-style.png) | ![ashi rendering tool calls claude-code-style](assets/ashi-claude-code-style.png) |
+
+### asHub — a GUI coding agent
+
+[**firslov/asHub**](https://github.com/firslov/asHub) is a third-party cross-platform desktop app (Electron) built on the agent-sh runtime: a multi-session sidebar, persistence across restarts, and a live-streaming interface with Markdown, syntax-highlighted code, diffs, and tool-call rendering. macOS / Windows / Linux.
 
-**Real terminal, zero compromise.** Full PTY with your shell config, aliases, and environment. Shell starts instantly — the agent connects asynchronously in the background.
+It pushes the same decoupling one step further — the frontend isn't a terminal at all, but a full desktop GUI on the same runtime, backends, and tools:
 
-**One entry point, smart tool selection.** Type `>` and agent-sh figures out how to help. Scratchpad tools (`bash`, `read_file`, `grep`, `glob`) for investigation. Extensions add capabilities like running commands in your live shell. No modes to pick — the agent reasons about which tools to use based on your intent.
+![asHub desktop GUI](assets/ashub.png)
 
-**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).
+## How it works
 
-**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — bundled bridges run [pi](examples/extensions/pi-bridge/), [claude-code](examples/extensions/claude-code-bridge/), or [opencode](examples/extensions/opencode-bridge/) as a drop-in backend (see [Bring your own agent](#bring-your-own-agent)).
+At agent-sh's center is a pure kernel — a typed event bus, a named-handler registry, and an extension loader — that knows nothing about terminals, LLMs, shells, or rendering. Everything else plugs into it: the agent backend, its tools, provider management, and the frontend that drives it.
 
-**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.
+The frontend and the agent backend are both just components on the bus, so you **mix and match** them freely — wire several frontends to one backend, or keep one frontend and swap the backend underneath — all sharing the **same extension layer** of tools, content transforms, slash commands, and themes. The shell swapping `ash` for a bridged agent, and ashi/asHub putting a different UI on the same backend, are the same idea seen from two directions. `import { createCore } from "agent-sh"` gives you the headless kernel; load the pieces you want and wire your own I/O.
 
-**Embeddable as a library.** The core is a headless kernel — `import { createCore } from "agent-sh"` to build WebSocket servers, REST APIs, Electron apps, or test harnesses. No terminal required.
+For the kernel design in full — the bus, handlers, the compositor, and the shell ↔ agent boundary — see [Architecture](docs/architecture.md). To embed the runtime in your own frontend, see the [Library Guide](docs/library.md).
 
 ## Documentation
 

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

@@ -1,18 +1,10 @@
 /**
- * Internal agent backend — bus-driven, self-wiring.
- *
- * Subscribes to bus events in constructor:
- *   - agent:submit → run query through LLM tool loop
- *   - agent:cancel-request → abort current loop
- *
- * Emits bus events during execution:
- *   - agent:query, agent:processing-start/done, agent:response-chunk/done
- *   - agent:tool-started, agent:tool-call, agent:tool-output-chunk,
- *     agent:tool-completed, agent:tool-output
- *   - agent:thinking-chunk, agent:cancelled, agent:error
+ * Internal agent backend — bus-driven and self-wiring. wire() subscribes to
+ * agent:submit (run the LLM tool loop) and agent:cancel-request (abort it),
+ * and the loop emits the agent:* progress/response/tool event stream.
  */
 import type { EventBus } from "../core/event-bus.js";
-import type { AgentMode } from "./host-types.js";
+import type { Model } from "./host-types.js";
 import type { LlmClient } from "./llm-client.js";
 import type { HandlerFunctions } from "../utils/handler-registry.js";
 import { type AgentBackend, type ToolDefinition } from "./types.js";
@@ -21,7 +13,7 @@ export interface AgentLoopConfig {
     bus: EventBus;
     llmClient: LlmClient;
     handlers: HandlerFunctions;
-    initialMode?: AgentMode;
+    initialModel?: Model;
     compositor?: Compositor;
     /** Instance ID from core — ensures history entries match the ID in prompts. */
     instanceId?: string;
@@ -31,7 +23,8 @@ export declare class AgentLoop implements AgentBackend {
     private toolRegistry;
     private conversation;
     private fileReadCache;
-    private activeMode;
+    private activeModel;
+    private activeEndpoint;
     private boundListeners;
     private boundPipeListeners;
     private lastProjectSkillNames;
@@ -91,10 +84,9 @@ export declare class AgentLoop implements AgentBackend {
     kill(): void;
     private cancel;
     private reasoningParams;
-    private get currentMode();
-    private pullModes;
+    private resolveEndpoint;
+    private pullModels;
     private emitIdentity;
-    private get currentModel();
     /**
      * Run compaction via the `conversation:compact` handler. After any
      * compaction, emit `conversation:after-compact` so listeners