agent-sh 0.9.0 → 0.10.0

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,7 +40,7 @@ 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).
 
@@ -42,21 +50,6 @@ Requires Node.js 18+.
 
 **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

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

@@ -27,6 +27,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;
@@ -41,6 +43,18 @@ export declare class AgentLoop implements AgentBackend {
     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 +63,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,13 +76,30 @@ 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. */
@@ -74,6 +107,12 @@ export declare class AgentLoop implements AgentBackend {
     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 +133,7 @@ export declare class AgentLoop implements AgentBackend {
      */
     private executeLoop;
     private readonly maxRetries;
+    private filePathFromArgs;
     /**
      * Stream with retry logic. Handles:
      *   - Context overflow → compact and retry