agent-sh 0.15.0 → 0.15.1

package/docs/usage.md

@@ -0,0 +1,306 @@
+# Usage Guide
+
+## Running agent-sh
+
+The simplest way to run agent-sh — just provide an API key and model:
+
+```bash
+# Using environment variables
+OPENAI_API_KEY="your-key" agent-sh --model gpt-4o
+
+# Using CLI flags
+agent-sh --api-key "your-key" --base-url http://localhost:11434/v1 --model llama3
+
+# Using npx
+npx agent-sh --api-key "$KEY" --model gpt-4o
+```
+
+Environment variables `OPENAI_API_KEY` and `OPENAI_BASE_URL` are supported as alternatives to CLI flags.
+
+### Other Options
+
+```bash
+# Use a different shell
+agent-sh --shell /bin/zsh
+
+# Launch a non-default agent backend (per-session override; doesn't touch settings)
+agent-sh --backend pi
+
+# Development mode (no build step)
+npm run dev
+
+# Debug mode
+DEBUG=1 agent-sh --api-key "$KEY" --model gpt-4o
+```
+
+### Subcommands
+
+```bash
+agent-sh init                   # scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+agent-sh install <name>         # install a bundled extension (e.g. agent-sh install pi-bridge)
+agent-sh install ./path/to/ext  # install from a local path
+agent-sh uninstall <name>       # remove an installed extension
+agent-sh list                   # show extensions discovered from ~/.agent-sh/extensions/ and settings.json
+agent-sh auth login [provider]  # store an API key; provider list is discovered from built-ins, settings.json, and any extension that calls ctx.agent.providers.register
+agent-sh auth logout <provider> # remove a stored key
+agent-sh auth list              # show configured providers and their key source ("(no auth required)" for local-daemon providers registered with noAuth: true)
+```
+
+Keys stored via `auth` live in `~/.agent-sh/keys.json` (chmod 0600). Resolution order when launching is `settings.json` → `keys.json` → env var, so explicit configuration always wins over the auth store.
+
+Any provider you declare under `providers` in `settings.json` is also accepted by `auth login <id>`. This lets you keep custom endpoints in version control (id, baseURL, model list) while the key stays in `keys.json` out of the committable file:
+
+```json
+{
+  "providers": {
+    "my-llama": {
+      "baseURL": "http://localhost:8000/v1",
+      "defaultModel": "llama-3.1-70b",
+      "models": ["llama-3.1-70b"]
+    }
+  }
+}
+```
+
+```bash
+agent-sh auth login my-llama   # prompts for the key, saves to keys.json
+```
+
+`auth login <id>` also accepts ids it doesn't recognize (with a warning). This lets extensions that register their own provider at runtime tell users to run `agent-sh auth login <their-id>` — the key sits in `keys.json` until the extension loads and claims it. Such entries appear in `auth list` tagged `unattached`.
+
+`install` accepts a bundled-extension name (see `agent-sh install` with no argument for the list), a `file:`/`./`/absolute path, or — once implemented — `npm:<pkg>` and `github:<user>/<repo>` specs.
+
+## Updating
+
+To pick up the latest changes, re-run the install command — npm replaces the global install in place. No uninstall step needed.
+
+```bash
+npm install -g agent-sh@latest             # latest npm release (recommended)
+```
+
+For unreleased changes on `main`, use the clone-and-link flow from the [Quick Start](../README.md#quick-start) — `npm install -g github:...` builds on your machine and can fail if the TypeScript toolchain doesn't extract cleanly.
+
+## Provider Examples
+
+agent-sh works with any OpenAI-compatible API. Here are common configurations:
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="sk-..."
+agent-sh --model gpt-4o
+# or: agent-sh --model gpt-4o-mini
+```
+
+### DeepSeek
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+agent-sh
+```
+
+### Ollama (Local)
+
+```bash
+# No API key needed — Ollama doesn't require authentication
+agent-sh --api-key dummy --base-url http://localhost:11434/v1 --model llama3
+```
+
+### OpenRouter
+
+```bash
+agent-sh --api-key "$OPENROUTER_KEY" \
+  --base-url https://openrouter.ai/api/v1 \
+  --model anthropic/claude-sonnet-4-20250514
+```
+
+### Together AI
+
+```bash
+agent-sh --api-key "$TOGETHER_KEY" \
+  --base-url https://api.together.xyz/v1 \
+  --model meta-llama/Llama-3-70b-chat-hf
+```
+
+### Groq
+
+```bash
+agent-sh --api-key "$GROQ_KEY" \
+  --base-url https://api.groq.com/openai/v1 \
+  --model llama-3.3-70b-versatile
+```
+
+### LM Studio
+
+```bash
+agent-sh --api-key dummy \
+  --base-url http://localhost:1234/v1 \
+  --model local-model
+```
+
+### vLLM
+
+```bash
+agent-sh --api-key dummy \
+  --base-url http://localhost:8000/v1 \
+  --model your-model
+```
+
+## Using agent-sh as Your Default Shell
+
+Add to the end of your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+if [[ -z "$AGENT_SH" && $- == *i* && -t 0 ]]; then
+  exec agent-sh --api-key "$OPENAI_API_KEY" --model gpt-4o
+fi
+```
+
+The `AGENT_SH` guard prevents infinite recursion. The checks ensure it only launches for interactive terminal sessions.
+
+## Configuration
+
+agent-sh stores settings and query history in `~/.agent-sh/`. Configure via `~/.agent-sh/settings.json` — all fields are optional with sensible defaults.
+
+### Provider Profiles
+
+Instead of passing `--api-key` and `--base-url` every time, define named providers in settings.json:
+
+```json
+{
+  "defaultProvider": "openai",
+  "providers": {
+    "openai": {
+      "apiKey": "$OPENAI_API_KEY",
+      "defaultModel": "gpt-4o",
+      "models": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+      "contextWindow": 128000
+    },
+    "ollama": {
+      "apiKey": "not-needed",
+      "baseURL": "http://localhost:11434/v1",
+      "defaultModel": "llama3",
+      "models": ["llama3", "mistral", "codellama"]
+    },
+    "openrouter": {
+      "apiKey": "$OPENROUTER_KEY",
+      "baseURL": "https://openrouter.ai/api/v1",
+      "defaultModel": "anthropic/claude-sonnet-4.5",
+      "models": [
+        { "id": "anthropic/claude-sonnet-4.5", "contextWindow": 200000, "reasoning": true },
+        { "id": "google/gemini-2.5-pro",       "contextWindow": 1000000 }
+      ]
+    }
+  }
+}
+```
+
+Then just run:
+
+```bash
+agent-sh                          # uses defaultProvider
+agent-sh --provider ollama        # use a specific provider
+agent-sh --provider openai --model gpt-4-turbo  # override the default model
+```
+
+The `apiKey` field supports `$ENV_VAR` and `${ENV_VAR}` syntax — variables are expanded at runtime, so you don't store secrets in the file.
+
+### Declaring the context window
+
+agent-sh adapts its auto-compaction trigger to the model's context window. There are two places to declare it:
+
+- **Provider-level `contextWindow`** — applies to every model in that provider unless a more specific value is set.
+- **Per-model `contextWindow`** (inside an entry of `models`) — overrides the provider-level value for a specific model, and also lets you tag reasoning-capable models via `reasoning: true`.
+
+If neither is set, agent-sh falls back to a conservative 60k-token default.
+
+Entries in `models` can be plain strings (just the model id, uses the provider-level `contextWindow`) or objects:
+
+```json
+"models": [
+  "gpt-4o-mini",
+  { "id": "gpt-4o",    "contextWindow": 128000 },
+  { "id": "o1-preview", "contextWindow": 128000, "reasoning": true }
+]
+```
+
+### Switching models at runtime
+
+- **`/model`** — show the current model
+- **`/model <name>`** — switch to a specific model (may cross providers; API key and base URL are reconfigured automatically)
+
+Switching mid-conversation preserves your conversation state — only the LLM endpoint changes.
+
+### CLI Flags
+
+| Flag | Environment Variable | Description |
+|---|---|---|
+| `--provider <name>` | — | Use a named provider from settings.json |
+| `--model <name>` | — | Model name (overrides provider default) |
+| `--api-key <key>` | `OPENAI_API_KEY` | API key for OpenAI-compatible API |
+| `--base-url <url>` | `OPENAI_BASE_URL` | Base URL for API endpoint |
+| `--shell <path>` | `SHELL` | Shell to use (default: `/bin/bash`) |
+| `--backend <name>` | — | Agent backend to launch (e.g. `ash`, `pi`); per-session override of `settings.defaultBackend`, does not persist. Errors out if the named backend isn't registered. |
+| `-e, --extensions` | — | Extensions to load (comma-separated, repeatable) |
+
+**Precedence** (highest to lowest): CLI flags → environment variables → provider profile in settings.json → defaults.
+
+### General Settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `defaultProvider` | — | Which provider to use when no `--provider` flag is given |
+| `defaultBackend` | `"ash"` | Which agent backend to activate. Set to an extension backend name (e.g. `"claude-code"`, `"pi"`) to use it by default |
+| `extensions` | `[]` | Extensions to load (npm packages or file paths) |
+| `historySize` | `500` | Max agent query history entries (persisted across sessions) |
+| `shellTruncateThreshold` | `20` | Shell output lines before spill-to-tempfile |
+| `shellHeadLines` / `shellTailLines` | `10` / `10` | Lines kept from start/end when output is spilled |
+| `autoCompactThreshold` | `0.5` | Fraction of the model's context window at which conversation auto-compacts |
+| `historyMaxBytes` | `104857600` | Max size of `~/.agent-sh/history` before front-truncation (100MB) |
+| `historyStartupEntries` | `100` | Prior history entries injected as `[Prior session history]` preamble on launch |
+| `maxCommandOutputLines` | `3` | Max tool output lines shown inline in TUI |
+| `readOutputMaxLines` | `10` | Max read tool output lines shown inline (0 = hidden) |
+| `diffMaxLines` | `Infinity` | Max diff lines rendered in the TUI. Defaults to no limit |
+| `skillPaths` | `[]` | Extra directories to scan for skills (supports `~` expansion) |
+| `diagnose` | `false` | Enable the `diagnose` tool — lets the agent evaluate JS expressions against its own runtime state (introspection; agent already has bash, so this is convenience, not new capability) |
+| `startupBanner` | `true` | Show the startup banner (backend / model / extensions / skills) on launch |
+| `promptIndicator` | `true` | Show a subtle agent-sh indicator in the shell prompt |
+| `toolMode` | `"api"` | How tools are presented to the LLM. `"api"` sends all tool schemas. `"deferred"` bundles extension tools behind a `use_extension(name, args)` meta-tool (saves prompt tokens, loses schema fidelity). `"deferred-lookup"` keeps extension schemas dormant until the model calls `load_tool(names[])` — loaded tools then become first-class on the next turn with full schemas. `"inline"` describes tools as text. |
+| `disabledExtensions` | `[]` | Names of user extensions in `~/.agent-sh/extensions/` to skip when auto-discovering. Match by basename without extension for files (`"peer-mesh"` matches `peer-mesh.ts`) or by directory name for dir-style extensions (`"superash"` matches `superash/index.ts`). Avoids having to rename files to `.disabled`. |
+| `disabledBuiltins` | `[]` | Names of built-in extensions to disable. |
+
+## Startup Banner
+
+On launch, agent-sh displays a structured startup banner showing:
+
+- **Backend** — which agent backend is active (`ash`, `claude-code`, `pi`, etc.)
+- **Model** — current model with provider in brackets (e.g. `gpt-4o [openai]`)
+- **Extensions** — loaded extensions (from CLI `-e`, settings, or `~/.agent-sh/extensions/`)
+- **Skills** — discovered skills (global + project)
+
+Set `startupBanner: false` in settings to disable.
+
+## Shell Context
+
+The agent automatically receives structured context about your shell session with each query:
+
+- **Current working directory** — tracked via OSC 7 escape sequences
+- **Recent commands and output** — new shell activity since the last turn is wrapped as `<shell_events>` inside `<query_context>` and prepended to your query
+- **Long outputs are spilled to tempfiles** — outputs over `shellTruncateThreshold` lines are written to `<tmpdir>/agent-sh-<pid>/<id>.out` at capture; the agent sees head+tail plus the path and recovers the full text via the built-in `read_file` tool
+
+This means you can run a failing command, then type `> fix this` and the agent knows exactly what happened — including a pointer to the full output if it got truncated. See [Context Management](context-management.md) for the full design.
+
+## Slash Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/model [name]` | Show current model; with a name, switch to that model |
+| `/backend [name]` | List backends, or switch to a named backend |
+| `/thinking [level]` | Set reasoning effort (off, low, medium, high) |
+| `/compact` | Compact conversation (free up context space) |
+| `/context` | Show context budget usage (active tokens vs. budget) |
+| `/history [on\|off\|status]` | Pause/resume cross-session history writes for this session (no cache invalidation) |
+| `/reload` | Reload user extensions from `~/.agent-sh/extensions/` |
+
+See [Context Management](context-management.md) for how `/compact` and `/context` work, and [Extensions: Custom Agent Backends](extensions.md#custom-agent-backends) for `/backend`.

package/examples/extensions/ash-scheme/package.json

@@ -6,6 +6,6 @@
   "main": "index.ts",
   "dependencies": {
     "@jcubic/lips": "1.0.0-beta.20",
-    "agent-sh": "^0.14.0"
+    "agent-sh": "^0.15.0"
   }
 }

package/examples/extensions/ashi/EXTENDING.md

@@ -58,7 +58,7 @@ const myModel: RenderModel<...> = {
 ## Renderers
 
 The whole TUI is swappable. ashi (the substrate) depends only on the `Renderer`
-contract from [`@guanyilun/ashi/renderer`](src/renderer.ts) — the schema, theme,
+contract from [`@guanyilun/ashi/renderer`](https://github.com/guanyilun/agent-sh/blob/main/examples/extensions/ashi/src/renderer.ts) — the schema, theme,
 chat controllers, and frontend never import a concrete TUI library. The built-in
 renderer is pi-tui (`src/renderers/pi-tui`).
 
@@ -113,6 +113,6 @@ agent-sh's shell clears OPOST on boot (pi-tui emits its own `\r`); ashi reads
 gets the conventional terminal for free; only a raw driver like pi-tui sets
 `rawOutput: true`.
 
-See [`examples/extensions/ashi-ink`](../ashi-ink) for a worked example — a **working**
+See [`examples/extensions/ashi-ink`](https://github.com/guanyilun/agent-sh/tree/main/examples/extensions/ashi-ink) for a worked example — a **working**
 Ink (React) renderer (`ASHI_RENDERER=ink ashi -e ashi-ink`), verified with
 `ink-testing-library`.

package/examples/extensions/ashi/README.md

@@ -13,7 +13,7 @@ Rendering is **decoupled** — even *how* ashi draws tool calls and results is a
 |---|---|
 | ![ashi rendering tool calls pi-style](https://raw.githubusercontent.com/guanyilun/agent-sh/main/assets/ashi-pi-style.png) | ![ashi rendering tool calls claude-code-style](https://raw.githubusercontent.com/guanyilun/agent-sh/main/assets/ashi-claude-code-style.png) |
 
-The claude-code-style renderer is [ashi-ink](../ashi-ink), a working Ink (React) renderer; see [Extending ashi](#extending-ashi) for the contract.
+The claude-code-style renderer is [ashi-ink](https://github.com/guanyilun/agent-sh/tree/main/examples/extensions/ashi-ink), a working Ink (React) renderer; see [Extending ashi](#extending-ashi) for the contract.
 
 ## Install
 
@@ -159,7 +159,7 @@ Each tool inherits from `default` and is overridden by its own block. Unknown to
 ## Extending ashi
 
 Other extensions can customize chat and tool-result rendering — and even swap the whole
-TUI renderer (pi-tui, [Ink](../ashi-ink), …) — without forking ashi. See **[EXTENDING.md](EXTENDING.md)**
+TUI renderer (pi-tui, [Ink](https://github.com/guanyilun/agent-sh/tree/main/examples/extensions/ashi-ink), …) — without forking ashi. See **[EXTENDING.md](EXTENDING.md)**
 for the chat/tool render hooks, the declarative tool render schema, and the renderer
 contract. For non-render concerns (commands, settings, tools, providers), use the
 standard [agent-sh extension API](https://github.com/guanyilun/agent-sh/blob/main/docs/extensions.md).

package/examples/extensions/ashi/docs/ui-surface-protocol.md

@@ -152,7 +152,7 @@ contract has no free-placement layer yet. Use the dock, dialogs, and notices abo
 
 ## Working example
 
-[`ashi-ui-demo.ts`](../../ashi-ui-demo.ts) exercises every surface through the typed helper. Load
+[`ashi-ui-demo.ts`](https://github.com/guanyilun/agent-sh/blob/main/examples/extensions/ashi-ui-demo.ts) exercises every surface through the typed helper. Load
 it and try the commands:
 
 ```

package/examples/extensions/ashi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanyilun/ashi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Ash in an interactive TUI — agent-sh's built-in agent without the shell underneath",
   "type": "module",
   "main": "dist/cli.js",
@@ -28,7 +28,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "EXTENDING.md",
+    "docs"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",
@@ -68,7 +70,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.74.0",
-    "agent-sh": "^0.14.11",
+    "agent-sh": "^0.15.0",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11"
   },

package/examples/extensions/ashi/src/cli.ts

@@ -180,7 +180,7 @@ async function main(): Promise<void> {
 
   activateAgent(ctx);
   activateShellContext(ctx);
-  const builtinExtensions = await loadBuiltinExtensions(ctx);
+  await loadBuiltinExtensions(ctx);
 
   const shell = new Shell({
     bus: core.bus,
@@ -263,10 +263,11 @@ async function main(): Promise<void> {
     await handle.rebuildChat();
     ctx.bus.emit("ui:info", { message: `continued session ${resumeId.slice(0, 12)}…` });
   } else {
-    // New-session only: skip on resume so a restored transcript isn't prefixed with this.
-    const loadedExtensions = [...new Set([...builtinExtensions, ...loaded])];
-    if (loadedExtensions.length > 0) {
-      ctx.bus.emit("ui:info", { message: `extensions: ${loadedExtensions.join(" · ")}` });
+    // New-session only: skip on resume so a restored transcript isn't prefixed
+    // with this. List user/installed extensions only — built-ins are always present.
+    const userExtensions = [...new Set(loaded)];
+    if (userExtensions.length > 0) {
+      ctx.bus.emit("ui:info", { message: `extensions: ${userExtensions.join(" · ")}` });
     }
   }
 

package/examples/extensions/ashi/src/renderer.ts

@@ -167,7 +167,17 @@ export interface ToolGroupView {
 }
 
 /** Default tool-group rendering (`├`/`└` tree): one styled line per row, no indent. */
-export function renderToolGroupLines(model: ToolGroupModel): string[] {
+/** Tail-biased middle truncation — keeps the end (e.g. a filename) visible. */
+function truncateMiddle(s: string, max: number): string {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  if (max === 1) return "…";
+  const keep = max - 1;
+  const tail = Math.ceil(keep * 0.65);
+  return (keep - tail > 0 ? s.slice(0, keep - tail) : "") + "…" + s.slice(s.length - tail);
+}
+
+export function renderToolGroupLines(model: ToolGroupModel, width?: number): string[] {
   const lines: string[] = [
     segmentsToString([
       { text: model.icon, style: { color: "warning" } },
@@ -187,7 +197,17 @@ export function renderToolGroupLines(model: ToolGroupModel): string[] {
   model.children.forEach((child, idx) => {
     const segs: Segment[] = [{ text: idx === model.children.length - 1 ? "└" : "├", style: { color: "muted" } }, " "];
     if (child.name !== model.kind) segs.push({ text: child.name, style: { bold: true, color: "toolTitle" } }, " ");
-    segs.push({ text: child.detail, style: { color: "muted" } }, " ");
+    let detail = child.detail;
+    if (width && width > 0) {
+      // Everything else on the row is fixed-width; truncate the detail (path/
+      // command) so the row stays one line instead of wrapping.
+      let overhead = 3; // tree char + space, and the space after detail
+      if (child.name !== model.kind) overhead += child.name.length + 1;
+      if (!child.status) overhead += 2;
+      else overhead += 2 + (child.status.summary ? 1 + child.status.summary.length : 0);
+      detail = truncateMiddle(detail, Math.max(8, width - overhead));
+    }
+    segs.push({ text: detail, style: { color: "muted" } }, " ");
     if (!child.status) {
       segs.push(" ", { text: "…", style: { color: "muted" } });
     } else {

package/examples/extensions/ashi/src/renderers/pi-tui/tool-group.ts

@@ -3,18 +3,15 @@ import { createNodes } from "./nodes.js";
 
 export function createPiTuiToolGroup(): ToolGroupView {
   const nodes = createNodes();
-  const rows = nodes.container();
   const container = nodes.container();
   container.addChild(nodes.spacer(1));
-  container.addChild(rows.node);
+  const text = nodes.text({ paddingX: 1 });
+  container.addChild(text.node);
 
   const update = (model: ToolGroupModel): void => {
-    rows.clear();
-    for (const line of renderToolGroupLines(model)) {
-      const t = nodes.text({ paddingX: 1 });
-      t.setText(line);
-      rows.addChild(t.node);
-    }
+    // paddingX:1 on both sides → content area is width-2; render width-aware so
+    // long paths truncate to fit rather than wrap.
+    text.setRenderFn((width) => renderToolGroupLines(model, Math.max(1, width - 2)));
   };
 
   return { node: container.node, update };

package/examples/extensions/ashi-ink/package.json

@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.74.0",
-    "@guanyilun/ashi": "^0.2.0",
-    "agent-sh": "^0.14.0",
+    "@guanyilun/ashi": "^0.3.0",
+    "agent-sh": "^0.15.0",
     "cli-table3": "^0.6.0",
     "ink": "^5.0.0",
     "ink-spinner": "^5.0.0",

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

@@ -6,7 +6,7 @@
   "main": "index.ts",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.0",
-    "agent-sh": "^0.14.0",
+    "agent-sh": "^0.15.0",
     "zod": "^4.0.0"
   }
 }

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

@@ -6,6 +6,6 @@
   "main": "index.ts",
   "dependencies": {
     "@opencode-ai/sdk": "^1.14.41",
-    "agent-sh": "^0.14.0"
+    "agent-sh": "^0.15.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "A composable agent runtime — pair any frontend with any agent backend over one shared extension layer",
   "type": "module",
   "workspaces": [
@@ -140,6 +140,8 @@
   },
   "files": [
     "dist",
+    "src",
+    "docs",
     "examples/extensions"
   ],
   "scripts": {