agent-sh 0.15.0 → 0.15.1

package/docs/library.md

@@ -0,0 +1,84 @@
+# Using agent-sh as a Library
+
+## Library vs Extension
+
+agent-sh has two integration points. The difference: **extensions customize the existing TUI**, while **library mode lets you build your own frontend**.
+
+| | Extension | Library |
+|---|---|---|
+| **Use when** | You want to add features to the interactive terminal — themes, custom renderers, input modes, content transforms | You're building something else entirely — a REST API, Electron app, test harness, CI pipeline |
+| **You get** | An `ExtensionContext` — substrate (bus, handlers, lifecycle, compositor) + slash-command registration + optional host surfaces. `ctx.agent` (LLM, tools, instructions) and `ctx.shell` (palette, transforms, remote sessions) are attached by their hosts during activation; under headless backends, the missing surface is `undefined`. Narrower types (`AgentContext`, `ShellContext`, or their intersection) let extensions declare which hosts they require. | `AgentShellCore` — bus, handler registry, lifecycle control (`activateBackend`, `kill`) |
+| **Who controls the frontend?** | The built-in TUI does; you decorate it | You do; there is no TUI |
+| **How to use** | Export an `activate` function, load with `-e` | Import `createCore()`, load extensions, wire your own I/O |
+
+If you're adding a Mermaid renderer or a custom slash command, write an extension. If you're building a web server that talks to an LLM, use the library.
+
+Two real frontends are built this way: [**ashi**](../examples/extensions/ashi/) (published as `@guanyilun/ashi`) drives `createCore()` into a standalone chat-style TUI with no shell underneath, and [**asHub**](https://github.com/firslov/asHub) wraps the same kernel in an Electron desktop app. Both reuse the ash backend, tools, and providers — only the frontend differs.
+
+## Quick Start
+
+```typescript
+import { createCore } from "agent-sh";
+import { activateAgent } from "agent-sh/agent";
+import { loadBuiltinExtensions } from "agent-sh/extensions";
+
+const core = createCore({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: "gpt-4o",
+});
+
+const ctx = core.extensionContext({ quit: () => process.exit(0) });
+
+activateAgent(ctx);
+const loaded = await loadBuiltinExtensions(ctx);
+core.bus.emit("core:extensions-loaded", { names: loaded });
+
+core.bus.on("agent:response-chunk", ({ blocks }) => {
+  for (const b of blocks) if (b.type === "text") process.stdout.write(b.text);
+});
+core.bus.on("agent:processing-done", () => console.log("\n[done]"));
+
+await core.activateBackend();
+core.bus.emit("agent:submit", { query: "explain this codebase" });
+```
+
+`createCore()` returns a headless kernel — the event bus and handler registry, with no terminal, shell, LLM, or agent attached. `activateAgent(ctx)` attaches the agent surface (tools, LLM client, providers) and registers the built-in `ash` backend; `loadBuiltinExtensions(ctx)` adds the abstract backend registry, slash commands, and file autocomplete. `core:extensions-loaded` triggers provider resolution; `activateBackend()` then starts ash (or whichever backend is configured). Send queries by emitting `agent:submit` and consume responses by listening to bus events.
+
+Tools run without confirmation by default; to gate them, register tool advisors via `ctx.agent.adviseTool` (see examples/extensions/interactive-prompts.ts).
+
+## AgentShellCore API
+
+| Method | Description |
+|---|---|
+| `bus` | The event bus — same one extensions use. See [Extensions: Event Bus](extensions.md#event-bus) |
+| `handlers` | Named handler registry for `define`/`advise`/`call`. Core defines `cwd` (returns `process.cwd()`); shell-context advises it with the PTY-tracked value when loaded |
+| `activateBackend(name?)` | Activates the named (or persisted-default) agent backend. Call after loading extensions and emitting `core:extensions-loaded` |
+| `extensionContext(opts)` | Creates an `ExtensionContext` — use this to load extensions in library mode |
+| `kill()` | Clean shutdown |
+
+Send queries with `bus.emit("agent:submit", { query })`; cancel with `bus.emit("agent:cancel-request", { silent: false })`.
+
+## Loading Extensions in Library Mode
+
+Extensions aren't loaded automatically in library mode — you get a bare kernel with no agent. You must call `activateAgent` (for the ash agent surface) and load built-ins (for the backend registry):
+
+```typescript
+import { createCore } from "agent-sh";
+import { activateAgent } from "agent-sh/agent";
+import { loadBuiltinExtensions } from "agent-sh/extensions";
+import myTheme from "./my-theme";
+
+const core = createCore({ apiKey: "...", model: "gpt-4o" });
+const ctx = core.extensionContext({ quit: () => process.exit(0) });
+
+activateAgent(ctx);
+const builtin = await loadBuiltinExtensions(ctx, ["slash-commands"]); // optionally disable
+myTheme(ctx);
+core.bus.emit("core:extensions-loaded", { names: builtin });
+
+await core.activateBackend();
+```
+
+This is exactly what the CLI does internally: `createCore()` → `activateAgent()` → `loadBuiltinExtensions()` → user extensions → emit `core:extensions-loaded` → `activateBackend()`. The interactive terminal is just another layer on top of the same kernel.
+
+See [Architecture](architecture.md) for details on the core design and EventBus.

package/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+# Troubleshooting
+
+## Common Issues
+
+**Problem**: No response from agent (thinking appears but no text)
+
+**Solutions**:
+1. Check API key: `echo $OPENAI_API_KEY`
+2. Test the API endpoint directly:
+   ```bash
+   curl -s "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY" | head
+   ```
+3. Verify the model name is correct for your provider
+
+**Problem**: "context overflow" or response cut off
+
+**Solution**: The conversation is too long. Use `/compact` to manually free up space, or the agent will auto-compact after the error.
+
+**Problem**: Tool calls not working (agent responds but doesn't use tools)
+
+**Solution**: Some models have limited or no tool/function calling support. Try a more capable model (e.g., gpt-4o, claude-sonnet-4-6 via OpenRouter).
+
+**Problem**: Garbled output, startup banner overwritten, or messy prompt rendering
+
+**Cause**: Powerlevel10k's **instant prompt** feature races with agent-sh's TUI. Instant prompt caches the previous prompt, displays it immediately, redirects stdout/stderr during shell init, then redraws the prompt using cursor-movement sequences — all of which can overwrite agent-sh's output.
+
+**Solution**: Guard the instant prompt block in your `~/.zshrc` so it's skipped inside agent-sh:
+
+```zsh
+# Disable p10k instant prompt inside agent-sh (it races with TUI rendering)
+if [[ -z "$AGENT_SH" && -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
+  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
+fi
+```
+
+Your normal p10k prompt still works — only the "flash cached prompt then redraw" behavior is disabled.
+
+## Common Errors
+
+**Error**: "API key not found" or "401 Unauthorized"
+- **Cause**: Missing or invalid API key
+- **Solution**: Set the appropriate key: `export OPENAI_API_KEY="your-key"`
+
+**Error**: "Invalid model name" or "404 Not Found"
+- **Cause**: Model not available at the configured endpoint
+- **Solution**: Check available models for your provider. Local providers (Ollama, LM Studio) need the model downloaded first.
+
+**Error**: Stream errors or disconnections
+- **Cause**: Network issues or provider rate limits
+- **Solution**: The agent will show the error. Try again, or check provider status.
+
+## Debug Mode
+
+Enable debug mode for detailed protocol logging:
+
+```bash
+DEBUG=1 agent-sh --api-key "$KEY" --model gpt-4o
+```
+
+## Getting Help
+
+If you encounter issues:
+1. Check the [Usage Guide](usage.md) for provider configuration
+2. Try a different model or provider to isolate the problem
+3. Check [GitHub issues](https://github.com/guanyilun/agent-sh/issues) for known problems

package/docs/tui-composition.md

@@ -0,0 +1,294 @@
+# TUI Composition
+
+How agent-sh routes rendered output to different surfaces (stdout, floating panels, test buffers) and how extensions intercept or redirect that output.
+
+## Overview
+
+The TUI rendering pipeline has three layers:
+
+1. **Components** — know *what* to render. Pure functions that turn state into `string[]`. Examples: `renderBoxFrame()`, `renderDiff()`, `renderToolCall()`.
+
+2. **Surfaces** — know *where* output goes. A surface accepts lines and raw writes. Stdout is a surface. A floating panel's content area is a surface.
+
+3. **Compositor** — knows *how to route*. Maps named streams to surfaces. Extensions override routing with `redirect()` to capture output.
+
+```
+                    ┌─────────────────┐
+ EventBus events    │  tui-renderer   │  (subscribes to agent:* events,
+  agent:query  ───► │                 │   manages state, calls components)
+  agent:chunk  ───► │  RenderState    │
+  agent:tool-* ───► │  MarkdownRender │
+                    └───────┬─────────┘
+                            │ writes to named streams
+                            ▼
+                    ┌─────────────────┐
+                    │   Compositor    │  routes streams → surfaces
+                    │                 │
+                    │ "agent"  ──► ?  │
+                    │ "query"  ──► ?  │
+                    │ "status" ──► ?  │
+                    └───────┬─────────┘
+                            │ resolves to active surface
+                    ┌───────┴─────────────────────┐
+                    ▼                             ▼
+             ┌─────────────┐              ┌──────────────┐
+             │ StdoutSurface│              │ PanelSurface │
+             │ (default)    │              │ (override)   │
+             └─────────────┘              └──────────────┘
+```
+
+## Surfaces
+
+A `RenderSurface` is anything that can accept rendered output:
+
+```typescript
+interface RenderSurface {
+  write(text: string): void;    // raw — supports \r, escape codes
+  writeLine(line: string): void; // line + newline
+  readonly columns: number;      // available width
+}
+```
+
+Built-in surfaces:
+
+| Surface | Description |
+|---|---|
+| `StdoutSurface` | Default. Writes to `process.stdout`. |
+| `nullSurface` | Drops all output silently. Used when no route exists. |
+
+Extensions create their own surfaces. For example, a floating panel surface:
+
+```typescript
+const panelSurface: RenderSurface = {
+  write(text) {
+    if (text.startsWith("\r")) {
+      // Handle spinner \r overwrites
+      const cleaned = text.replace(/^\r/, "").replace(/\x1b\[\d*K/g, "");
+      if (cleaned.trim()) panel.updateLastLine(() => cleaned);
+      return;
+    }
+    panel.appendText(text);
+  },
+  writeLine(line) { panel.appendLine(line); },
+  get columns() { return panel.computeGeometry().contentW; },
+};
+```
+
+## Compositor
+
+The compositor maps named streams to surfaces. Components write to streams — they never know (or care) which surface they end up on.
+
+```typescript
+interface Compositor {
+  surface(stream: string): RenderSurface;
+  redirect(stream: string, target: RenderSurface): () => void;
+  setDefault(stream: string, target: RenderSurface): void;
+}
+```
+
+### Default streams
+
+| Stream | Content |
+|---|---|
+| `"agent"` | Agent response: markdown, tool calls, spinner, diffs, code blocks |
+| `"query"` | User query display (the bordered input box) |
+| `"status"` | Info messages, errors, suggestions |
+
+The shell frontend (`src/shell/`) sets all three to `StdoutSurface` during `activateShell`. A library or web consumer that doesn't load the shell frontend has no defaults — it must call `compositor.setDefault(...)` itself.
+
+### Redirecting a stream
+
+`redirect()` returns a restore function. Redirects are stack-based — multiple redirects on the same stream nest correctly:
+
+```typescript
+const restore = compositor.redirect("agent", panelSurface);
+// ... agent output now goes to the panel ...
+restore(); // back to previous surface
+```
+
+### Hierarchical streams
+
+Stream names are hierarchical, separated by `:`. When resolving a surface, the compositor walks up the hierarchy until it finds an override or default:
+
+```
+"agent:sub:abc123"  →  "agent:sub"  →  "agent"  →  nullSurface
+```
+
+This enables fine-grained interception without registering defaults for every sub-stream:
+
+```typescript
+// All agent output goes to stdout (the "agent" default)
+compositor.setDefault("agent", stdoutSurface);
+
+// Redirect just diffs to a viewer panel — everything else unaffected
+compositor.redirect("agent:diff", diffPanelSurface);
+
+// Redirect a specific subagent to its own panel
+compositor.redirect("agent:sub:abc123", subagentPanelSurface);
+```
+
+The tui-renderer writes to the appropriate sub-stream. If no override exists for that sub-stream, output falls through to the parent — which is typically stdout.
+
+## Writing an extension that uses the compositor
+
+### Example: overlay agent (full redirect)
+
+The overlay agent redirects *all* render streams to a floating panel when active. This is the simplest pattern — whole-sale capture:
+
+```typescript
+import { FloatingPanel } from "agent-sh/utils/floating-panel";
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, compositor } = ctx;
+  const terminalBuffer = ctx.call("terminal-buffer");
+
+  const panel = new FloatingPanel(bus, { trigger: "\x1c", terminalBuffer: terminalBuffer ?? undefined });
+  const panelSurface = createPanelSurface(panel);
+
+  let restoreAgent: (() => void) | null = null;
+  let restoreQuery: (() => void) | null = null;
+
+  panel.handlers.advise("panel:submit", (_next, query: string) => {
+    restoreAgent = compositor.redirect("agent", panelSurface);
+    restoreQuery = compositor.redirect("query", panelSurface);
+    panel.setActive();
+    bus.emit("agent:submit", { query });
+  });
+
+  panel.handlers.advise("panel:dismiss", (next) => {
+    next();
+    restoreAgent?.(); restoreAgent = null;
+    restoreQuery?.(); restoreQuery = null;
+  });
+}
+```
+
+Because the full tui-renderer pipeline still runs — it just writes to the panel surface instead of stdout — the overlay gets markdown rendering, tool grouping, diffs, and syntax highlighting for free.
+
+### Example: diff viewer (sub-stream redirect)
+
+An extension that captures just diff output into a separate panel:
+
+```typescript
+import { FloatingPanel } from "agent-sh/utils/floating-panel";
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus, compositor } = ctx;
+  const terminalBuffer = ctx.call("terminal-buffer");
+
+  const panel = new FloatingPanel(bus, { trigger: "\x04", terminalBuffer: terminalBuffer ?? undefined });
+  const surface = createPanelSurface(panel);
+
+  panel.handlers.advise("panel:show", (_next) => {
+    // Redirect just the diff sub-stream
+    compositor.redirect("agent:diff", surface);
+  });
+}
+```
+
+Main agent output (text, tools, spinner) continues on stdout. Only diffs route to the panel.
+
+### Example: subagent panel
+
+A panel that shows a subagent's work separately from the main agent:
+
+```typescript
+function onSubagentSpawn(id: string, ctx: ExtensionContext): void {
+  const panel = new FloatingPanel(ctx.bus, { dimBackground: false });
+  const surface = createPanelSurface(panel);
+
+  // This subagent's output goes to its own panel
+  const restore = ctx.shell.compositor.redirect(`agent:sub:${id}`, surface);
+
+  panel.open();
+  // When done, restore routing
+  ctx.bus.on("agent:processing-done", () => {
+    restore();
+    panel.setDone();
+  });
+}
+```
+
+## How tui-renderer uses the compositor
+
+The tui-renderer gets the compositor from `ExtensionContext` and writes to named streams instead of stdout directly:
+
+```typescript
+export default function activate(ctx: ExtensionContext): void {
+  const { compositor } = ctx;
+
+  // Shorthand — get the current agent surface
+  function out(): RenderSurface {
+    return compositor.surface("agent");
+  }
+
+  // Drain markdown renderer lines to the active surface
+  function drain(): void {
+    const surface = out();
+    for (const line of renderer.drainLines()) {
+      surface.writeLine(line);
+    }
+  }
+
+  // Spinner writes directly to the surface
+  setInterval(() => {
+    out().write(`\r  ${spinnerLine}\x1b[K`);
+  }, 80);
+}
+```
+
+The renderer doesn't know whether it's writing to stdout or a panel. The compositor resolves the target on each `surface()` call, so redirects take effect immediately — even mid-response.
+
+## Remote sessions
+
+For most extensions that route output to a different surface, use `createRemoteSession()` instead of manual compositor redirects. It bundles compositor routing, shell lifecycle advisors, and chrome suppression into one call:
+
+```typescript
+const session = ctx.shell.createRemoteSession({
+  surface: panelSurface,
+  suppressQueryBox: true,   // session has own input
+});
+
+session.submit("what's on screen?");
+session.close();  // restores everything
+```
+
+See [Extensions: Remote Sessions](extensions.md#remote-sessions) for the full API.
+
+Use the compositor directly only when you need fine-grained control — e.g. redirecting a single sub-stream like `"agent:diff"` without affecting the rest.
+
+## Observing writes (`compositor:write`)
+
+When the core creates the compositor with an `EventBus` attached, every surface write emits a `compositor:write` event:
+
+```typescript
+bus.on("compositor:write", ({ stream, text }) => {
+  // `stream` is the named stream (e.g. "agent", "agent:diff"), `text` is the raw write
+});
+```
+
+This lets an extension mirror or inspect rendered output without intercepting stdout. Used by e.g. a compositor-mirror extension that buffers recent agent output and exposes a `compositor_read` tool.
+
+## Relationship to other systems
+
+| System | Role | Compositor interaction |
+|---|---|---|
+| **EventBus** | Delivers agent events to tui-renderer | None — events flow regardless of where output goes |
+| **Handler registry** | Advisable render functions (`render:code-block`, etc.) | Handlers produce lines; compositor routes them to surfaces |
+| **FloatingPanel** | Screen compositing, input routing, alt-screen management | Panel provides the surface; compositor routes to it |
+| **MarkdownRenderer** | Streaming markdown → lines | Produces lines; tui-renderer drains them to compositor surface |
+| **RemoteSession** | High-level "route output elsewhere" primitive | Creates compositor redirects + lifecycle advisors in one call |
+
+The compositor sits between "produce lines" and "display lines". It doesn't affect *what* gets rendered — only *where*.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `src/utils/compositor.ts` | `RenderSurface`, `Compositor`, `DefaultCompositor`, `StdoutSurface` |
+| `src/shell/tui-renderer.ts` | Main renderer — writes to compositor streams |
+| `examples/extensions/overlay-agent.ts` | Uses `ctx.shell.createRemoteSession` to route to floating panel |
+| `src/utils/floating-panel.ts` | Panel screen management and content API |
+| `src/shell/index.ts` | Allocates the compositor, registers default surfaces, implements `createRemoteSession` |
+| `src/shell/host-types.ts` | `ShellSurface.compositor`, `RemoteSession`, `RemoteSessionOptions` |
+| `examples/extensions/tmux-pane.ts` | Tmux side pane — `/split` and `/rsplit` using `ctx.shell.createRemoteSession` |