agent-sh 0.12.20 → 0.12.22

package/README.md

@@ -19,7 +19,7 @@ So I built agent-sh. Under the hood it's a normal shell on top of node-pty — y
 ~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
-I still use Claude Code and pi for serious coding work — this doesn't replace them. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, bridge extensions let you plug [Claude Code](examples/extensions/claude-code-bridge/) or [pi](examples/extensions/pi-bridge/) in as the backend.
+I still use a proper coding harness for serious work — this doesn't replace that. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, you can swap in [pi](examples/extensions/pi-bridge/) as the backend via a bridge extension.
 
 ## Quick Start
 
@@ -57,14 +57,22 @@ export OPENAI_API_KEY=sk-...
 agent-sh
 ```
 
+**DeepSeek:**
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+agent-sh
+```
+
 **Local models** (Ollama, llama.cpp server, LM Studio, vLLM — anything OpenAI-compatible):
 
 ```bash
-export OPENAI_API_KEY=ollama                        # any value; dummy is fine
 export OPENAI_BASE_URL=http://localhost:11434/v1    # point at your server
 agent-sh
 ```
 
+Set `OPENAI_API_KEY` too if your server requires auth.
+
 Once running, switch models at any time with `/model <name>` (tab-completes; selection persists across sessions).
 
 For richer configuration (multiple providers, extensions), run `agent-sh init` to scaffold `~/.agent-sh/settings.json` with copy-pasteable examples. See the [Usage Guide](docs/usage.md) for the full list of supported providers.
@@ -87,7 +95,7 @@ Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fis
 
 **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 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.
+**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 — [pi](examples/extensions/pi-bridge/) runs as a drop-in backend extension.
 
 **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.
 

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

@@ -38,6 +38,7 @@ export declare class AgentLoop implements AgentBackend {
     private modes;
     private currentModeIndex;
     private boundListeners;
+    private boundPipeListeners;
     private ctorListeners;
     private ctorPipeListeners;
     private lastProjectSkillNames;

package/dist/agent/agent-loop.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { computeDiff, computeEditDiff, computeInputDiff } from "../utils/diff.js";
 import { ToolRegistry } from "./tool-registry.js";
+import { normalizeToolArgs } from "./normalize-args.js";
 import { ConversationState } from "./conversation-state.js";
 import { HistoryFile } from "./history-file.js";
 import { nucleate, formatNuclearLine, isReadOnly } from "./nuclear-form.js";
@@ -58,6 +59,7 @@ export class AgentLoop {
     modes;
     currentModeIndex = 0;
     boundListeners = [];
+    boundPipeListeners = [];
     ctorListeners = [];
     ctorPipeListeners = [];
     lastProjectSkillNames = new Set();
@@ -215,12 +217,24 @@ export class AgentLoop {
             this.bus.on(event, fn);
             this.boundListeners.push({ event, fn });
         };
+        const onPipe = (event, fn) => {
+            this.bus.onPipe(event, fn);
+            this.boundPipeListeners.push({ event, fn, async: false });
+        };
+        const onPipeAsync = (event, fn) => {
+            this.bus.onPipeAsync(event, fn);
+            this.boundPipeListeners.push({ event, fn, async: true });
+        };
         on("agent:submit", ({ query }) => {
             this.handleQuery(query).catch(() => { });
         });
         on("agent:cancel-request", (e) => {
             this.abortController?.abort(e.silent ? "silent" : undefined);
         });
+        on("agent:append-user-message", ({ text }) => {
+            this.conversation.appendUserMessage(text);
+            this.bus.emit("conversation:message-appended", { role: "user", content: text });
+        });
         on("config:switch-model", ({ model: target }) => {
             const atIdx = target.lastIndexOf("@");
             const modelId = atIdx > 0 ? target.slice(0, atIdx) : target;
@@ -256,7 +270,7 @@ export class AgentLoop {
             }
             this.bus.emit("config:changed", {});
         });
-        this.bus.onPipe("config:get-models", (payload) => {
+        onPipe("config:get-models", () => {
             const models = this.modes.map((m) => ({ model: m.model, provider: m.provider ?? "" }));
             const cur = this.modes[this.currentModeIndex];
             const active = cur ? { model: cur.model, provider: cur.provider ?? "" } : null;
@@ -280,7 +294,7 @@ export class AgentLoop {
             this.bus.emit("ui:info", { message: `Thinking: ${level}` });
             this.bus.emit("config:changed", {});
         });
-        this.bus.onPipe("config:get-thinking", () => {
+        onPipe("config:get-thinking", () => {
             const mode = this.currentMode;
             const supported = mode.reasoning !== false && mode.supportsReasoningEffort !== false;
             return { level: this.thinkingLevel, levels: AgentLoop.THINKING_LEVELS, supported };
@@ -302,20 +316,20 @@ export class AgentLoop {
                 this.bus.emit("ui:info", { message: "(nothing to compact)" });
             }
         });
-        this.bus.onPipe("context:get-stats", () => ({
+        onPipe("context:get-stats", () => ({
             activeTokens: this.conversation.estimateTokens(),
             totalTokens: this.conversation.estimatePromptTokens(),
             nuclearEntries: this.conversation.getNuclearEntryCount(),
             recallArchiveSize: this.conversation.getRecallArchiveSize(),
             budgetTokens: this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
         }));
-        this.bus.onPipe("context:snapshot", (payload) => {
+        onPipe("context:snapshot", (payload) => {
             payload.messages = this.conversation.getMessages();
             payload.contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             payload.activeTokens = this.conversation.estimateTokens();
             return payload;
         });
-        this.bus.onPipeAsync("context:compact", async (payload) => {
+        onPipeAsync("context:compact", async (payload) => {
             const stats = await this.compactWithHooks(0, undefined, false, payload.strategy);
             if (stats)
                 payload.stats = { before: stats.before, after: stats.after, evictedCount: stats.evictedCount };
@@ -365,6 +379,13 @@ export class AgentLoop {
             this.bus.off(event, fn);
         }
         this.boundListeners = [];
+        for (const { event, fn, async } of this.boundPipeListeners) {
+            if (async)
+                this.bus.offPipeAsync(event, fn);
+            else
+                this.bus.offPipe(event, fn);
+        }
+        this.boundPipeListeners = [];
     }
     /** Register a tool (used by extensions via ctx.registerTool). */
     registerTool(tool) {
@@ -1188,6 +1209,10 @@ export class AgentLoop {
                     });
                     return;
                 }
+                // Normalize against the tool's input_schema: some LLMs stringify
+                // nested object/array args despite the schema. See
+                // normalize-args.ts for the diagnostic that uncovered this.
+                args = normalizeToolArgs(args, tool.input_schema);
                 // ── Round-scoped cache for cacheable read-only tools ──
                 const cacheable = !tool.modifiesFiles && !tool.requiresPermission && tool.showOutput !== true;
                 const cacheKey = cacheable ? `${tc.name}:${JSON.stringify(args)}` : null;

package/dist/agent/conversation-state.d.ts

@@ -38,7 +38,7 @@ export declare class ConversationState {
     private nextSeq;
     private lastApiTokenCount;
     private lastApiMessageCount;
-    private pendingNotes;
+    private pendingMessages;
     constructor(handlers?: HandlerFunctions, instanceId?: string);
     /** Get JSON.stringify of messages, cached until next mutation. */
     private getMessagesJson;
@@ -56,8 +56,9 @@ export declare class ConversationState {
     addToolResultInline(content: string): void;
     /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
     addSystemNote(text: string): void;
+    appendUserMessage(text: string): void;
     private hasOpenToolCalls;
-    private flushPendingNotes;
+    private flushPendingMessages;
     getMessages(): ChatCompletionMessageParam[];
     /** Drop tool messages with no matching preceding tool_call — strict
      *  providers (DeepSeek) 400, and compaction can leave such orphans. */

package/dist/agent/conversation-state.js

@@ -56,10 +56,10 @@ export class ConversationState {
     nextSeq = 1;
     lastApiTokenCount = null;
     lastApiMessageCount = 0;
-    // Notes queued when addSystemNote fires mid-tool-pair; flushed once
-    // the trailing tool_result lands. Splicing into the gap breaks
-    // reasoning_content pairing and is rejected by strict providers.
-    pendingNotes = [];
+    // Buffered when addSystemNote/appendUserMessage fires mid-tool-pair;
+    // flushed once the trailing tool_result lands. Splicing into the gap
+    // breaks reasoning_content pairing and is rejected by strict providers.
+    pendingMessages = [];
     constructor(handlers, instanceId = "0000") {
         this.handlers = handlers ?? null;
         this.instanceId = instanceId;
@@ -114,23 +114,30 @@ export class ConversationState {
         if (isError)
             this.toolErrors.add(toolCallId);
         this.invalidateMessagesCache();
-        this.flushPendingNotes();
+        this.flushPendingMessages();
     }
     /** Add tool results as a user message (for inline tool protocol). */
     addToolResultInline(content) {
         this.messages.push({ role: "user", content });
         this.invalidateMessagesCache();
-        this.flushPendingNotes();
+        this.flushPendingMessages();
     }
     /** Safe from any context: queues if mid-tool-pair, appends otherwise. */
     addSystemNote(text) {
         if (this.hasOpenToolCalls()) {
-            this.pendingNotes.push(text);
+            this.pendingMessages.push({ kind: "system", text });
             return;
         }
         this.messages.push({ role: "user", content: text });
         this.invalidateMessagesCache();
     }
+    appendUserMessage(text) {
+        if (this.hasOpenToolCalls()) {
+            this.pendingMessages.push({ kind: "user", text });
+            return;
+        }
+        this.addUserMessage(text);
+    }
     hasOpenToolCalls() {
         for (let i = this.messages.length - 1; i >= 0; i--) {
             const msg = this.messages[i];
@@ -151,15 +158,21 @@ export class ConversationState {
         }
         return false;
     }
-    flushPendingNotes() {
-        if (this.pendingNotes.length === 0)
+    flushPendingMessages() {
+        if (this.pendingMessages.length === 0)
             return;
         if (this.hasOpenToolCalls())
             return;
-        for (const text of this.pendingNotes) {
-            this.messages.push({ role: "user", content: text });
+        const pending = this.pendingMessages;
+        this.pendingMessages = [];
+        for (const m of pending) {
+            if (m.kind === "user") {
+                this.addUserMessage(m.text);
+            }
+            else {
+                this.messages.push({ role: "user", content: m.text });
+            }
         }
-        this.pendingNotes = [];
         this.invalidateMessagesCache();
     }
     getMessages() {
@@ -244,7 +257,7 @@ export class ConversationState {
         this.invalidateMessagesCache();
         this.lastApiTokenCount = null;
         this.lastApiMessageCount = 0;
-        this.flushPendingNotes();
+        this.flushPendingMessages();
     }
     pruneToolErrors() {
         if (this.toolErrors.size === 0)
@@ -544,7 +557,7 @@ export class ConversationState {
         this.nuclearEntries = [];
         this.nuclearBySeq.clear();
         this.recallArchive.clear();
-        this.pendingNotes = [];
+        this.pendingMessages = [];
         this.invalidateMessagesCache();
         this.lastApiTokenCount = null;
         this.lastApiMessageCount = 0;

package/dist/agent/normalize-args.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Schema-aware tool-arg normalization.
+ *
+ * Some LLMs (notably Claude) occasionally emit nested object/array
+ * tool-call arguments as JSON-encoded strings instead of native
+ * objects, despite the schema declaring `type: "object"` /
+ * `type: "array"`. The discrepancy was diagnosed by the superash field
+ * test (2026-05-03 / commit `b9efd47`):
+ *
+ *     describe_demos: 'task' arrived as a string (length 1267)
+ *       last char code: 93 (']')
+ *       truncation suspected: true
+ *
+ * Tool handlers downstream had to add ad-hoc JSON.parse fallbacks. This
+ * helper centralizes the fix at the kernel boundary: after parsing the
+ * outer `argumentsJson`, walk each top-level field; for any field whose
+ * schema declares `object` or `array` but whose value is a string, run
+ * a single JSON.parse pass. On parse failure (e.g. truncated content),
+ * the string is left as-is — the tool can produce a clean error.
+ *
+ * Top-level only by design. Recursing into nested object schemas would
+ * change semantics for tools that legitimately accept stringified
+ * payloads as inner fields, and the observed wild cases all stringify
+ * at the top level.
+ */
+/** Normalize tool-call args against the tool's input_schema. Pure: does
+ *  not mutate `args`. Returns a new object with stringified-then-decoded
+ *  fields swapped in where applicable. */
+export declare function normalizeToolArgs(args: Record<string, unknown>, schema: unknown): Record<string, unknown>;

package/dist/agent/normalize-args.js

@@ -0,0 +1,56 @@
+/**
+ * Schema-aware tool-arg normalization.
+ *
+ * Some LLMs (notably Claude) occasionally emit nested object/array
+ * tool-call arguments as JSON-encoded strings instead of native
+ * objects, despite the schema declaring `type: "object"` /
+ * `type: "array"`. The discrepancy was diagnosed by the superash field
+ * test (2026-05-03 / commit `b9efd47`):
+ *
+ *     describe_demos: 'task' arrived as a string (length 1267)
+ *       last char code: 93 (']')
+ *       truncation suspected: true
+ *
+ * Tool handlers downstream had to add ad-hoc JSON.parse fallbacks. This
+ * helper centralizes the fix at the kernel boundary: after parsing the
+ * outer `argumentsJson`, walk each top-level field; for any field whose
+ * schema declares `object` or `array` but whose value is a string, run
+ * a single JSON.parse pass. On parse failure (e.g. truncated content),
+ * the string is left as-is — the tool can produce a clean error.
+ *
+ * Top-level only by design. Recursing into nested object schemas would
+ * change semantics for tools that legitimately accept stringified
+ * payloads as inner fields, and the observed wild cases all stringify
+ * at the top level.
+ */
+/** Normalize tool-call args against the tool's input_schema. Pure: does
+ *  not mutate `args`. Returns a new object with stringified-then-decoded
+ *  fields swapped in where applicable. */
+export function normalizeToolArgs(args, schema) {
+    if (!schema || typeof schema !== "object")
+        return args;
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object")
+        return args;
+    let out = null;
+    for (const [field, fieldSchema] of Object.entries(properties)) {
+        if (!fieldSchema || typeof fieldSchema !== "object")
+            continue;
+        const expectedType = fieldSchema.type;
+        if (expectedType !== "object" && expectedType !== "array")
+            continue;
+        const value = args[field];
+        if (typeof value !== "string")
+            continue;
+        try {
+            const parsed = JSON.parse(value);
+            if (out === null)
+                out = { ...args };
+            out[field] = parsed;
+        }
+        catch {
+            // Leave as string — downstream tool can produce a useful error.
+        }
+    }
+    return out ?? args;
+}

package/dist/agent/subagent.js

@@ -1,4 +1,5 @@
 import { ConversationState } from "./conversation-state.js";
+import { normalizeToolArgs } from "./normalize-args.js";
 import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
 /**
  * Run a subagent to completion.
@@ -56,6 +57,7 @@ export async function runSubagent(opts) {
                 conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`, true);
                 continue;
             }
+            args = normalizeToolArgs(args, tool.input_schema);
             // Emit tool events for TUI (if bus provided)
             if (bus) {
                 const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };

package/dist/core.d.ts

@@ -37,11 +37,13 @@ export interface AgentShellCore {
     /** Unique id for this agent process; used for shell-marker tagging and lineage tracking. */
     instanceId: string;
     /** Activate the agent backend (call after extensions load). */
-    activateBackend(): void;
+    activateBackend(): Promise<void>;
     /** Convenience: emit agent:submit and await the response. */
     query(text: string): Promise<string>;
     /** Convenience: emit agent:cancel-request. */
     cancel(): void;
+    /** Convenience: emit agent:append-user-message. */
+    appendUserMessage(text: string): void;
     /** Build an ExtensionContext for loading extensions against this core. */
     extensionContext(opts: {
         quit: () => void;

package/dist/core.js

@@ -56,33 +56,30 @@ export function createCore(config) {
     handlers.define("query-context:build", () => "");
     const backends = new Map();
     let activeBackendName = null;
-    const activateByName = async (name, silent = false) => {
+    const activateByName = async (name) => {
         const backend = backends.get(name);
         if (!backend) {
             bus.emit("ui:error", { message: `Unknown backend: ${name}` });
-            return;
+            return false;
         }
-        // Deactivate current backend
         if (activeBackendName) {
             backends.get(activeBackendName)?.kill();
         }
-        // Activate new backend
         await backend.start?.();
         activeBackendName = name;
-        if (!silent) {
-            bus.emit("ui:info", { message: `Backend: ${name}` });
-        }
-        bus.emit("config:changed", {});
+        return true;
     };
     bus.on("agent:register-backend", (backend) => {
         backends.set(backend.name, backend);
     });
     bus.on("config:switch-backend", ({ name }) => {
-        activateByName(name).then(() => {
-            if (activeBackendName === name) {
-                settingsMod.updateSettings({ defaultBackend: name });
-                bus.emit("ui:info", { message: `Saved '${name}' as default backend.` });
-            }
+        activateByName(name).then((ok) => {
+            if (!ok)
+                return;
+            settingsMod.updateSettings({ defaultBackend: name });
+            // Single ui:info; config:changed (which triggers prompt redraw) follows it.
+            bus.emit("ui:info", { message: `Backend: ${name} (saved as default)` });
+            bus.emit("config:changed", {});
         });
     });
     bus.on("config:list-backends", () => {
@@ -105,18 +102,12 @@ export function createCore(config) {
         bus,
         handlers,
         instanceId,
-        activateBackend() {
-            // Silent — backend info is shown in the startup banner.
-            // Runtime switches (config:switch-backend) still emit ui:info.
+        async activateBackend() {
             if (backends.size === 0)
                 return;
             const preferred = settings.defaultBackend;
-            if (preferred && backends.has(preferred)) {
-                activateByName(preferred, true);
-            }
-            else {
-                activateByName(backends.keys().next().value, true);
-            }
+            const name = preferred && backends.has(preferred) ? preferred : backends.keys().next().value;
+            await activateByName(name);
         },
         async query(text) {
             return new Promise((resolve, reject) => {
@@ -155,6 +146,9 @@ export function createCore(config) {
         cancel() {
             bus.emit("agent:cancel-request", {});
         },
+        appendUserMessage(text) {
+            bus.emit("agent:append-user-message", { text });
+        },
         extensionContext(opts) {
             const ctx = {
                 bus,

package/dist/event-bus.d.ts

@@ -47,6 +47,9 @@ export interface ShellEvents {
     "agent:cancel-request": {
         silent?: boolean;
     };
+    "agent:append-user-message": {
+        text: string;
+    };
     "input-mode:register": import("./types.js").InputModeConfig;
     "agent:query": {
         query: string;
@@ -307,7 +310,9 @@ export interface ShellEvents {
     "config:add-modes": {
         modes: AgentMode[];
     };
-    "core:extensions-loaded": Record<string, never>;
+    "core:extensions-loaded": {
+        names: string[];
+    };
     "provider:register": {
         id: string;
         apiKey?: string;
@@ -327,7 +332,7 @@ export interface ShellEvents {
     };
     "provider:configure": {
         id: string;
-        reasoningParams?: (level: string) => Record<string, unknown>;
+        reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
     };
     "agent:register-tool": {
         tool: import("./agent/types.js").ToolDefinition;
@@ -445,6 +450,8 @@ export declare class EventBus {
      * If no listeners are registered, returns the original payload unchanged.
      */
     emitPipe<K extends keyof ShellEvents>(event: K, payload: ShellEvents[K]): ShellEvents[K];
+    /** Remove an async transform listener from a pipeline event. */
+    offPipeAsync<K extends keyof ShellEvents>(event: K, fn: AsyncPipeListener<ShellEvents[K]>): void;
     /** Register an async transform listener for a pipeline event. */
     onPipeAsync<K extends keyof ShellEvents>(event: K, fn: AsyncPipeListener<ShellEvents[K]>): void;
     /**

package/dist/event-bus.js

@@ -131,6 +131,15 @@ export class EventBus {
         }
         return result;
     }
+    /** Remove an async transform listener from a pipeline event. */
+    offPipeAsync(event, fn) {
+        const listeners = this.asyncPipeListeners.get(event);
+        if (!listeners)
+            return;
+        const idx = listeners.indexOf(fn);
+        if (idx !== -1)
+            listeners.splice(idx, 1);
+    }
     /** Register an async transform listener for a pipeline event. */
     onPipeAsync(event, fn) {
         let listeners = this.asyncPipeListeners.get(event);