agent-sh 0.9.0 → 0.10.1

package/README.md

@@ -5,16 +5,18 @@ An agent that lives in a shell — not a shell that lives in an agent.
 [![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)
+
 Most AI terminal 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.
 
 agent-sh flips this. It's your shell first — full PTY, your rc config, your aliases, everything just works. But type `>` at the start of a line, and you're talking to an agent that has full context of what you've been doing.
 
 ```
-~ $ ls -la                          # real shell command
-~ $ cd ../tests && npm test          # real cd, env, aliases — all just work
-~ $ vim file.ts                      # opens vim in the same PTY
-~ $ > explain the last error          # agent investigates using its own tools
-~ $ > deploy to staging              # agent runs it in your live shell
+~ $ ls -la                       # real shell command
+~ $ cd ../tests && npm test      # real cd, env, aliases — all just work
+~ $ vim file.ts                  # opens vim in the same PTY
+~ $ > explain the last error     # agent investigates using its own tools
+~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
 ## Quick Start
@@ -24,6 +26,12 @@ npm install -g agent-sh
 agent-sh
 ```
 
+Tip: add an alias to your shell config for quick access:
+
+```bash
+alias ash="agent-sh"
+```
+
 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).
 
 Requires Node.js 18+.
@@ -32,41 +40,28 @@ Requires Node.js 18+.
 
 **Real terminal, zero compromise.** Full PTY with your shell config, aliases, and environment. Shell starts instantly — the agent connects asynchronously in the background.
 
-**One entry point, three tool categories.** Type `>` and agent-sh figures out how to help. Scratchpad tools (`bash`, `read_file`, `grep`, `glob`) for investigation. `display` to show you output. `user_shell` for commands with lasting effects in your live shell. No modes to pick — the agent reasons about which tools to use based on your intent.
+**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.
 
 **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).
 
-**Any LLM, any backend.** agent-sh 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.
+**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 — [Claude Code](examples/extensions/claude-code-bridge/) and [pi](examples/extensions/pi-bridge/) run as drop-in backend extensions.
 
 **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.
 
 **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.
 
-## Slash Commands
-
-| Command | Description |
-|---|---|
-| `/help` | Show available commands |
-| `/model [name]` | Cycle to the next model, or switch to a specific one |
-| `/backend [name]` | List backends, or switch to a named backend |
-| `/compact` | Compact conversation (free up context space) |
-| `/context` | Show context budget usage |
-| `/thinking [level]` | Set reasoning effort (off, low, medium, high) |
-
-## Configuration
-
-Configure via `~/.agent-sh/settings.json`. See the [Usage Guide](docs/usage.md#configuration) for the full settings reference.
-
 ## Documentation
 
-- [Usage Guide](docs/usage.md) — providers, models, configuration
-- [Internal Agent](docs/agent.md) — tools, context, streaming
-- [Context Management](docs/context-management.md) — three-tier history, token budget
-- [Architecture](docs/architecture.md) — design philosophy, component overview
-- [Extensions](docs/extensions.md) — event bus, content transforms, custom backends, theming
-- [TUI Composition](docs/tui-composition.md) — compositor, render surfaces, stream routing
-- [Library Usage](docs/library.md) — embedding agent-sh in your own apps
-- [Troubleshooting](docs/troubleshooting.md) — common errors and debug mode
+Start with **Usage** to get running, then **Architecture** for the mental model.
+
+1. [Usage Guide](docs/usage.md) — install, run, configure providers and models
+2. [Architecture](docs/architecture.md) — pure kernel + extensions, the shell ↔ agent boundary
+3. [The Built-in Agent: ash](docs/agent.md) — query flow, tools, system prompt, model switching
+4. [Context Management](docs/context-management.md) — shell-output spill, three-tier conversation compaction, recall APIs
+5. [Extensions](docs/extensions.md) — event bus, content transforms, custom agent backends, theming
+6. [TUI Composition](docs/tui-composition.md) — compositor, render surfaces, stream routing
+7. [Library Usage](docs/library.md) — embedding agent-sh in your own apps
+8. [Troubleshooting](docs/troubleshooting.md) — common errors and debug mode
 
 ## Development
 

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

@@ -4,7 +4,6 @@
  * 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
@@ -27,6 +26,8 @@ export interface AgentLoopConfig {
     modes?: AgentMode[];
     initialModeIndex?: number;
     compositor?: Compositor;
+    /** Instance ID from core — ensures history entries match the ID in prompts. */
+    instanceId?: string;
 }
 export declare class AgentLoop implements AgentBackend {
     private abortController;
@@ -34,13 +35,24 @@ export declare class AgentLoop implements AgentBackend {
     private historyFile;
     private conversation;
     private fileReadCache;
-    private tokenBudget;
     private modes;
     private currentModeIndex;
     private boundListeners;
     private ctorListeners;
     private ctorPipeListeners;
     private lastProjectSkillNames;
+    private sessionStartTime;
+    private toolCallCounts;
+    private totalToolCalls;
+    private totalToolErrors;
+    private totalResolutions;
+    private compactionCount;
+    private cumulativeCompactedTokens;
+    private peakConversationTokens;
+    private queryCount;
+    private totalLoopIterations;
+    private lastErrorByTool;
+    private lastErrorByFile;
     private static readonly THINKING_LEVELS;
     private bus;
     private contextManager;
@@ -49,6 +61,8 @@ export declare class AgentLoop implements AgentBackend {
     private thinkingLevel;
     private compositor;
     private toolProtocol;
+    private instanceId;
+    private lastShellSeq;
     constructor(config: AgentLoopConfig);
     /** Subscribe to bus events — activates this backend. */
     wire(): void;
@@ -60,20 +74,42 @@ export declare class AgentLoop implements AgentBackend {
     unregisterTool(name: string): void;
     /** Get all registered tools. */
     getTools(): ToolDefinition[];
+    /** Instructions keyed by name, with extension attribution. */
     private instructions;
+    /** Skills keyed by name, with extension attribution. */
+    private skills;
+    /** Tool → extension name attribution. */
+    private toolExtensions;
     /** Register a named instruction block for the system prompt. */
-    registerInstruction(name: string, text: string): void;
+    registerInstruction(name: string, text: string, extensionName: string): void;
     /** Remove a named instruction block. */
     removeInstruction(name: string): void;
-    /** Get instruction blocks registered by extensions. */
-    getInstructionSections(): string[];
+    /** Register a named skill (on-demand reference material). */
+    registerSkill(name: string, description: string, filePath: string, extensionName: string): void;
+    /** Remove a registered skill. */
+    removeSkill(name: string): void;
+    /**
+     * Build the system prompt grouped by extension.
+     *
+     * Each extension gets a unified block:
+     *   ## extension-name
+     *   ### Tools
+     *   ### Skills
+     *   ### Instructions
+     */
+    buildExtensionSections(): string[];
     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();
+    /**
+     * Run compaction via the `conversation:compact` handler. After any
+     * compaction, emit `conversation:after-compact` so listeners
+     * (metrics, UI, agent-awareness notes) can react.
+     */
+    private compactWithHooks;
     private isContextOverflow;
     /** Check if an error is retryable (transient). */
     private isRetryable;
@@ -94,6 +130,7 @@ export declare class AgentLoop implements AgentBackend {
      */
     private executeLoop;
     private readonly maxRetries;
+    private filePathFromArgs;
     /**
      * Stream with retry logic. Handles:
      *   - Context overflow → compact and retry