agent-sh 0.3.1 → 0.5.0

package/README.md

@@ -5,145 +5,115 @@
 
 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.
+I live in a terminal. I don't want an agent that can run shell commands when it needs to — I want my shell, with an agent I can reach for when *I* need to. Most AI tools get this backwards: the LLM drives the experience and the shell is bolted on as an afterthought. No real PTY, no job control, no vim, fragile `cd` tracking. The agent is the main character and your terminal is a prop.
 
-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.
+agent-sh flips this. It's your shell first — full PTY, your rc config, your aliases, everything just works. But type `?` or `>` at the start of a line, and you're talking to an agent that has full context of what you've been doing.
 
 ```
 ⚡ 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          # execute mode → agent investigates using its own tools
+⚡ src $ ? deploy to staging              # help 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.
+## Key Features
 
-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.
+**Real terminal, zero compromise.** Full PTY with your shell config, aliases, and environment. Shell starts instantly — the agent connects asynchronously in the background.
 
-### Why ACP?
+**Context-aware agent.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `? fix this`, and the agent knows exactly what happened. It has built-in tools for file read/write/edit, bash, grep, glob — no external setup needed.
 
-The [Agent Client Protocol](https://agentclientprotocol.com/) decouples the shell from any specific agent:
+**Two input modes.** `>` for questions and tasks — the agent investigates using its own isolated tools. `?` for commands that run directly in your live shell, affecting your real environment. The agent knows which mode it's in and behaves accordingly.
 
-- **Pluggable agents** — swap between pi-acp, claude-code, codex with a CLI flag
-- **Standard protocol** — JSON-RPC 2.0 over stdio, well-specified capability negotiation
-- **Agent handles LLM details** — no API keys, tool definitions, or context windows to manage
-- **Terminal delegation** — ACP defines `terminal/create`, `terminal/output`, `terminal/wait_for_exit` — exactly what an agent needs to run commands in your shell
+**Any LLM, any backend.** Works with any OpenAI-compatible API out of the box. Define multiple providers in settings and cycle between models at runtime with Shift+Tab. Or swap in a completely different agent — [Claude Code](examples/extensions/claude-code-bridge/) and [pi](examples/extensions/pi-bridge/) run as drop-in backend extensions.
 
-## Key Features
+**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 — nothing is special.
 
-- **Instant Start** — Shell starts immediately, no waiting for agent connection
-- **Smart Connection** — Agent connects asynchronously in the background
-- **Auto-Wait** — Queries automatically wait for agent to finish connecting
-- **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
-- **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
-- **Themeable** — Semantic color palette, swappable via [extensions](docs/extensions.md)
+**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.
 
 ## Quick Start
 
 ```bash
-# 1. Install agent-sh and an ACP-compatible agent
-npm install -g agent-sh pi-acp
-
-# 2. Set API keys
-export ANTHROPIC_API_KEY="your-key"
-
-# 3. Start
-agent-sh                           # default agent (pi-acp)
-agent-sh --agent claude-agent-acp  # use a different agent
+npm install -g agent-sh
+agent-sh
 ```
 
-Requires Node.js 18+. Other ACP agents: `npm install -g @agentclientprotocol/claude-agent-acp`
-
-> **Note**: The `claude` CLI tool (Claude Code) does **not** support ACP. Use `claude-agent-acp` or `pi-acp` with Anthropic models.
+Set `OPENAI_API_KEY` in your environment (or configure providers in `~/.agent-sh/settings.json`). Works with any OpenAI-compatible API — see the [Usage Guide](docs/usage.md) for provider examples (OpenAI, Ollama, OpenRouter, Together, Groq, LM Studio, vLLM).
 
-See the [Usage Guide](docs/usage.md) for all options, model configuration, and environment variables.
+Requires Node.js 18+.
 
 ## Input Modes
 
-| 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 |
-| `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 `>`) |
-
-### Agent Input Keybindings
-
-When typing after `>`, full readline-style keybindings are available:
-
-| Key | Action |
-|---|---|
-| `↑` / `↓` | Browse query history (persisted across sessions) |
-| `Shift-Enter` | Insert newline (multiline input) |
-| `Shift-Tab` | Cycle thinking level |
-| `Ctrl-D` | Exit agent input mode (on empty line) |
-| `Ctrl-A` / `Home` | Move to start of line |
-| `Ctrl-E` / `End` | Move to end of line |
-| `Ctrl-B` / `←` | Move back one character |
-| `Ctrl-F` / `→` | Move forward one character |
-| `Option-B` / `Option-←` | Move back one word |
-| `Option-F` / `Option-→` | Move forward one word |
-| `Ctrl-U` | Delete to start of line |
-| `Ctrl-K` | Delete to end of line |
-| `Ctrl-W` / `Option-Backspace` | Delete word backward |
-| `Option-D` | Delete word forward |
-
-### Thinking Level
-
-The agent prompt shows the current thinking level next to the model name:
+- **`>` Execute mode** — Agent uses its own tools (bash, file read/write, search) to investigate and answer. Stays in execute mode for follow-ups.
+- **`?` Help mode** — Agent runs a command in your live shell. Your aliases, env vars, and cwd apply. Returns to shell after.
 
-```
-pi (claude-3.5-sonnet) [medium] ● ❯
-```
+Everything else works as a normal shell — commands go straight to the PTY. Modes are extensible — see [Extensions: Custom Input Modes](docs/extensions.md#custom-input-modes).
 
-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.
+> **Why `>` for the main mode?** `>` is easy to type and the most common interaction — asking the agent to do things. `?` is reserved for when you need the agent to run something directly in your live shell.
 
 ### Slash Commands
 
 | Command | Description |
 |---|---|
 | `/help` | Show available commands |
-| `/clear` | Start a new agent session |
-| `/copy` | Copy last agent response to clipboard |
-| `/compact` | Ask agent to summarize the conversation |
-| `/quit` | Exit agent-sh |
+| `/model [name]` | Cycle to the next model, or switch to a specific one |
+| `/backend [name]` | List backends, or switch to a named backend |
 
 ## Configuration
 
-agent-sh stores settings and history in `~/.agent-sh/`. Behavior is configurable via `~/.agent-sh/settings.json` — context window size, truncation thresholds, display limits, and more. All fields are optional with sensible defaults.
+Configure via `~/.agent-sh/settings.json`. Define named providers with multiple models:
+
+```json
+{
+  "defaultProvider": "openai",
+  "providers": {
+    "openai": {
+      "apiKey": "$OPENAI_API_KEY",
+      "defaultModel": "gpt-4o",
+      "models": ["gpt-4o", "gpt-4o-mini"]
+    },
+    "ollama": {
+      "apiKey": "not-needed",
+      "baseURL": "http://localhost:11434/v1",
+      "defaultModel": "llama3",
+      "models": ["llama3", "mistral"]
+    }
+  }
+}
+```
 
-See the [Usage Guide](docs/usage.md#configuration) for the full settings reference.
+Cycle models with **Shift+Tab**, switch providers with `/provider <name>`, switch backends with `/backend <name>`. API keys support `$ENV_VAR` syntax.
 
-## Development
+Additional options:
 
-```bash
-npm run dev                        # development mode (no build step)
-npm run build                      # build
-npm start                          # run built version
-DEBUG=1 npm start                  # debug mode (logs ACP protocol details)
-```
+| Key | Default | Description |
+|---|---|---|
+| `startupBanner` | `true` | Show startup banner with model info and usage hints |
+| `promptIndicator` | `true` | Show `⚡ agent-sh` in terminal tab/window title |
+
+Set either to `false` to disable.
+
+See the [Usage Guide](docs/usage.md#configuration) for the full settings reference.
 
 ## Documentation
 
-- [Usage Guide](docs/usage.md) — models, providers, API keys, environment config
-- [Architecture](docs/architecture.md) — design philosophy, protocol details, project structure
-- [Extensions](docs/extensions.md) — writing extensions, theming, yolo mode
-- [Library Usage](docs/library.md) — using agent-sh as a Node.js library
+- [Usage Guide](docs/usage.md) — providers, models, configuration, provider profiles
+- [Internal Agent](docs/agent.md) — how the agent loop works: tools, context, streaming
+- [Architecture](docs/architecture.md) — design philosophy, component overview, project structure
+- [Extensions](docs/extensions.md) — event bus, content transforms, custom backends, theming
+- [Library Usage](docs/library.md) — embedding agent-sh in your own apps
 - [Troubleshooting](docs/troubleshooting.md) — common errors and debug mode
 
+## Development
+
+```bash
+git clone https://github.com/guanyilun/agent-sh.git
+cd agent-sh
+npm install
+npm run build
+npm start
+```
+
 ## License
 
 MIT

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

@@ -0,0 +1,85 @@
+/**
+ * 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
+ *   - config:cycle → cycle through modes
+ *
+ * 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
+ */
+import type { EventBus } from "../event-bus.js";
+import type { AgentMode } from "../types.js";
+import type { ContextManager } from "../context-manager.js";
+import type { LlmClient } from "../utils/llm-client.js";
+import type { HandlerRegistry } from "../utils/handler-registry.js";
+import type { AgentBackend, ToolDefinition } from "./types.js";
+export declare class AgentLoop implements AgentBackend {
+    private bus;
+    private contextManager;
+    private llmClient;
+    private handlers;
+    private abortController;
+    private toolRegistry;
+    private conversation;
+    private modes;
+    private currentModeIndex;
+    private boundListeners;
+    private lastProjectSkillNames;
+    private static readonly THINKING_LEVELS;
+    private thinkingLevel;
+    constructor(bus: EventBus, contextManager: ContextManager, llmClient: LlmClient, handlers: HandlerRegistry, modeConfig?: AgentMode[], initialModeIndex?: number);
+    /** Subscribe to bus events — activates this backend. */
+    wire(): void;
+    /** Unsubscribe from bus events — deactivates this backend. */
+    unwire(): void;
+    /** Register a tool (used by extensions via ctx.registerTool). */
+    registerTool(tool: ToolDefinition): void;
+    /** Get all registered tools. */
+    getTools(): ToolDefinition[];
+    kill(): void;
+    private cancel;
+    /** Check if reasoning_effort should be sent for the current model/provider. */
+    private shouldSendReasoningEffort;
+    private cycleMode;
+    private get currentMode();
+    private get currentModel();
+    private isContextOverflow;
+    /** Check if an error is retryable (transient). */
+    private isRetryable;
+    /** Extract retry delay from error headers or use exponential backoff. */
+    private getRetryDelay;
+    /** Format an error with provider context for user-facing display. */
+    private formatError;
+    private registerCoreTools;
+    /**
+     * Register named handlers that extensions can advise.
+     * Only high-power use cases where multiple extensions compose.
+     */
+    private registerHandlers;
+    private handleQuery;
+    /** Max tokens before auto-compaction (conservative default). */
+    private maxContextTokens;
+    /**
+     * Core agent loop: stream LLM response → execute tools → repeat.
+     * Returns the final accumulated response text.
+     */
+    private executeLoop;
+    private readonly maxRetries;
+    /**
+     * Stream with retry logic. Handles:
+     *   - Context overflow → compact and retry
+     *   - Rate limits (429) → backoff with Retry-After
+     *   - Transient errors (500/502/503, network) → exponential backoff
+     */
+    private streamWithRetry;
+    /**
+     * Stream a single LLM response. Returns accumulated text, parsed tool calls,
+     * and the raw assistant message data for conversation recording.
+     */
+    private streamResponse;
+}