agent-sh 0.14.10 → 0.15.0

package/dist/agent/events.d.ts

@@ -1,5 +1,5 @@
-import type { ProviderRegistration } from "./host-types.js";
-import type { ToolDefinition, ToolResultDisplay } from "./types.js";
+import type { Model, ProviderRegistration } from "./host-types.js";
+import type { ImageContent, ToolDefinition, ToolResultDisplay } from "./types.js";
 export interface AgentIdentity {
     name: string;
     version: string;
@@ -20,8 +20,9 @@ declare module "../core/event-bus.js" {
         "provider:configure": {
             id: string;
             reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
+            cacheTokens?: (usage: Record<string, unknown>) => number | undefined;
         };
-        "agent:modes-changed": Record<string, never>;
+        "agent:models-changed": Record<string, never>;
         "config:switch-provider": {
             provider: string;
         };
@@ -44,6 +45,7 @@ declare module "../core/event-bus.js" {
         };
         "agent:submit": {
             query: string;
+            images?: ImageContent[];
         };
         "agent:cancel-request": {
             silent?: boolean;
@@ -69,6 +71,7 @@ declare module "../core/event-bus.js" {
             prompt_tokens: number;
             completion_tokens: number;
             total_tokens: number;
+            cached_prompt_tokens?: number;
         };
         "agent:processing-start": Record<string, never>;
         "agent:processing-done": Record<string, never>;
@@ -189,17 +192,12 @@ declare module "../core/event-bus.js" {
             };
         };
         "config:switch-model": {
-            model: string;
+            id: string;
+            provider: string;
         };
         "config:get-models": {
-            models: {
-                model: string;
-                provider: string;
-            }[];
-            active: {
-                model: string;
-                provider: string;
-            } | null;
+            models: Model[];
+            active: Model | null;
         };
         "config:set-thinking": {
             level: string;

package/dist/agent/host-types.d.ts

@@ -56,19 +56,16 @@ export interface ProviderRegistration {
     /** Local daemons etc. — `auth list/login` shows "no auth required". */
     noAuth?: boolean;
 }
-/** A model entry in the cycling list, optionally tied to a provider. */
-export interface AgentMode {
-    model: string;
-    /** Provider id — when cycling changes provider, LlmClient is reconfigured. */
-    provider?: string;
-    /** Provider-specific config for reconfiguring LlmClient on switch. */
-    providerConfig?: {
-        apiKey: string;
-        baseURL?: string;
-    };
+/** A selectable (provider, model) target the frontend lists and switches.
+ *  Serializable — identity + capabilities only; the secret + closures needed to
+ *  invoke it live in ModelEndpoint, so this can safely cross to frontends and
+ *  out-of-process bridges. */
+export interface Model {
+    id: string;
+    provider: string;
     /** Context window size in tokens (for usage display). */
     contextWindow?: number;
-    /** Max output tokens for this mode. */
+    /** Max output tokens. */
     maxTokens?: number;
     /** Model supports reasoning/thinking tokens. */
     reasoning?: boolean;
@@ -79,7 +76,15 @@ export interface AgentMode {
     echoReasoning?: boolean;
     /** Input modalities the model supports. Defaults to ["text"]. */
     modalities?: ("text" | "image")[];
+}
+/** Credentials + provider-shape transforms for invoking a Model, resolved by
+ *  (provider, id). Internal: holds a secret (apiKey) and non-serializable
+ *  closures, so it must never ride a bus event. */
+export interface ModelEndpoint {
+    apiKey: string;
+    baseURL?: string;
     buildReasoningParams?: (level: string) => Record<string, unknown>;
+    extractCachedTokens?: (usage: Record<string, unknown>) => number | undefined;
 }
 /**
  * Capabilities the agent host adds on top of CoreContext. Only available
@@ -94,6 +99,7 @@ export interface AgentSurface {
         unregister: (id: string) => void;
         configure: (id: string, opts: {
             reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
+            cacheTokens?: (usage: Record<string, unknown>) => number | undefined;
         }) => void;
     };
     registerTool: (tool: ToolDefinition) => void;

package/dist/agent/index.d.ts

@@ -11,5 +11,5 @@ export { AgentLoop } from "./agent-loop.js";
 export { ToolRegistry } from "./tool-registry.js";
 export { runSubagent, type SubagentOptions } from "./subagent.js";
 /** Built-in providers register unconditionally so `auth list` can
- *  enumerate them; buildModes() skips entries without an apiKey. */
+ *  enumerate them; buildModels() skips entries without an apiKey. */
 export declare function activateAgent(ctx: ExtensionContext): void;

package/dist/agent/index.js

@@ -32,11 +32,21 @@ function persistedModelFor(providerName) {
         return undefined;
     return getSettings().providers?.[providerName]?.defaultModel;
 }
+/** The OpenAI SDK silently defaults an empty baseURL to api.openai.com, so a
+ *  provider with a key but no endpoint would misroute its key there. `openai`
+ *  is exempt: that default is its endpoint. */
+function usableProvider(p) {
+    return !!p?.apiKey && (!!p.baseURL || p.id === "openai");
+}
 function defaultReasoningBuilder(level) {
     if (level === "off")
         return {};
     return { reasoning_effort: level === "xhigh" ? "high" : level };
 }
+function defaultCacheTokens(usage) {
+    const details = usage.prompt_tokens_details;
+    return typeof details?.cached_tokens === "number" ? details.cached_tokens : undefined;
+}
 function mergeCaps(settingsCaps, payloadCaps, modelIds) {
     if (!settingsCaps)
         return payloadCaps.size > 0 ? payloadCaps : undefined;
@@ -85,11 +95,12 @@ export default function agentBackend(ctx) {
             settingsProviders.set(name, p);
     }
     const providerHooks = new Map();
-    // Bakes model id so AgentMode.buildReasoningParams keeps its (level) signature.
+    // Bakes model id so ModelEndpoint.buildReasoningParams keeps its (level) signature.
     const bindReasoning = (shapeId, model) => {
         const hook = providerHooks.get(shapeId)?.reasoningParams;
         return hook ? (level) => hook(level, model) : defaultReasoningBuilder;
     };
+    const bindCacheTokens = (shapeId) => providerHooks.get(shapeId)?.cacheTokens ?? defaultCacheTokens;
     const agentSurface = {
         llm: createLlmFacade({ list: ctx.list, call: ctx.call }),
         providers: {
@@ -274,31 +285,43 @@ export default function agentBackend(ctx) {
         }
         return out;
     };
-    const buildModes = () => {
+    const buildModels = () => {
         const out = [];
         for (const [id, p] of resolvedProviders) {
             if (!p.apiKey)
                 continue;
-            const shapeId = p.reasoningShape ?? id;
+            if (!usableProvider(p))
+                continue;
             for (const model of p.models) {
                 const mc = p.modelCapabilities?.get(model);
                 out.push({
-                    model,
+                    id: model,
                     provider: id,
-                    providerConfig: { apiKey: p.apiKey, baseURL: p.baseURL },
                     contextWindow: mc?.contextWindow ?? p.contextWindow,
                     maxTokens: mc?.maxTokens ?? (mc?.contextWindow ? Math.min(Math.floor(mc.contextWindow * 0.4), 65536) : undefined),
                     reasoning: mc?.reasoning,
                     supportsReasoningEffort: p.supportsReasoningEffort,
                     echoReasoning: mc?.echoReasoning,
                     modalities: mc?.modalities,
-                    buildReasoningParams: bindReasoning(shapeId, model),
                 });
             }
         }
         return out;
     };
-    ctx.define("agent:get-modes", () => buildModes());
+    const resolveEndpoint = (providerId, modelId) => {
+        const p = resolvedProviders.get(providerId);
+        if (!p?.apiKey)
+            return undefined;
+        const shapeId = p.reasoningShape ?? providerId;
+        return {
+            apiKey: p.apiKey,
+            baseURL: p.baseURL,
+            buildReasoningParams: bindReasoning(shapeId, modelId),
+            extractCachedTokens: bindCacheTokens(shapeId),
+        };
+    };
+    ctx.define("agent:get-models", () => buildModels());
+    ctx.define("agent:resolve-endpoint", ({ provider, id }) => resolveEndpoint(provider, id));
     // Reconfigured at core:extensions-loaded; start() gates on `resolved`.
     const llmClient = new LlmClient({ apiKey: "not-configured", model: "not-configured" });
     ctx.define("llm:get-client", () => llmClient);
@@ -321,10 +344,10 @@ export default function agentBackend(ctx) {
         resolvedProviders = computeResolvedProviders();
         if (!resolved)
             return;
-        bus.emit("agent:modes-changed", {});
+        bus.emit("agent:models-changed", {});
         if (!ashActive)
             return;
-        if (buildModes().some((m) => m.model === llmClient.model))
+        if (buildModels().some((m) => m.id === llmClient.model))
             return;
         const pendingProvider = getSettings().defaultProvider;
         if (!pendingProvider)
@@ -334,26 +357,47 @@ export default function agentBackend(ctx) {
             return;
         const pendingModel = persistedModelFor(pendingProvider);
         if (pendingModel && p.models.includes(pendingModel) && llmClient.model !== pendingModel) {
-            bus.emit("config:switch-model", { model: pendingModel });
+            bus.emit("config:switch-model", { id: pendingModel, provider: pendingProvider });
         }
     });
-    bus.on("provider:configure", ({ id, reasoningParams }) => {
+    bus.on("provider:configure", ({ id, reasoningParams, cacheTokens }) => {
         const prev = providerHooks.get(id) ?? {};
         if (reasoningParams !== undefined)
             prev.reasoningParams = reasoningParams;
+        if (cacheTokens !== undefined)
+            prev.cacheTokens = cacheTokens;
         providerHooks.set(id, prev);
     });
     bus.on("core:extensions-loaded", ({ names }) => {
         loadedExtensionNames = names;
         resolvedProviders = computeResolvedProviders();
         const settings = getSettings();
-        // Built-ins register unconditionally so `auth list` can enumerate them;
-        // the fallback must skip keyless entries or it lands on openrouter and
-        // bails at the `!effectiveApiKey` guard below.
-        const providerName = config.provider
-            ?? settings.defaultProvider
-            ?? [...resolvedProviders].find(([, p]) => p.apiKey)?.[0];
-        const activeProvider = providerName ? resolvedProviders.get(providerName) ?? null : null;
+        let providerName = config.provider ?? settings.defaultProvider;
+        let activeProvider = providerName ? resolvedProviders.get(providerName) ?? null : null;
+        // Inline CLI credentials carry their own endpoint, so they skip the
+        // usable-provider fallback that registry-driven selection needs.
+        if (!config.apiKey) {
+            if (!providerName) {
+                const first = [...resolvedProviders].find(([, p]) => usableProvider(p));
+                providerName = first?.[0];
+                activeProvider = first?.[1] ?? null;
+            }
+            else if (!usableProvider(activeProvider)) {
+                const reason = !activeProvider ? "is not registered"
+                    : !activeProvider.apiKey ? "has no API key configured"
+                        : "has no endpoint configured";
+                const next = [...resolvedProviders].find(([, p]) => usableProvider(p));
+                if (next) {
+                    bus.emit("ui:error", { message: `Provider "${providerName}" ${reason}; falling back to "${next[0]}".` });
+                    providerName = next[0];
+                    activeProvider = next[1];
+                }
+                else {
+                    bus.emit("ui:error", { message: `Provider "${providerName}" ${reason}, and no other configured provider has both an API key and an endpoint. Run \`agent-sh auth\` to configure one.` });
+                    return;
+                }
+            }
+        }
         // Persisted defaultModel wins over openrouter's hardcoded DEFAULT_MODELS[0].
         const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
         const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
@@ -361,15 +405,14 @@ export default function agentBackend(ctx) {
         // No provider → don't register ash; let another backend own activation.
         if (!effectiveApiKey || !effectiveModel)
             return;
-        const foundInModes = buildModes().find((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id));
+        const foundModel = buildModels().find((m) => m.id === effectiveModel && (!activeProvider || m.provider === activeProvider.id));
         // Stub when openrouter's async catalog hasn't returned yet; reconciled
         // later via agent:providers:changed → config:switch-model.
-        const initialMode = foundInModes ?? (activeProvider ? {
-            model: effectiveModel,
-            provider: activeProvider.id,
-            providerConfig: { apiKey: effectiveApiKey, baseURL: effectiveBaseURL },
-            supportsReasoningEffort: activeProvider.supportsReasoningEffort,
-        } : { model: effectiveModel });
+        const initialModel = foundModel ?? {
+            id: effectiveModel,
+            provider: activeProvider?.id ?? providerName ?? "custom",
+            supportsReasoningEffort: activeProvider?.supportsReasoningEffort,
+        };
         llmClient.reconfigure({ apiKey: effectiveApiKey, baseURL: effectiveBaseURL, model: effectiveModel });
         resolved = true;
         bus.emit("agent:register-backend", {
@@ -386,7 +429,7 @@ export default function agentBackend(ctx) {
                     bus,
                     llmClient,
                     handlers: { define: ctx.define, advise: ctx.advise, call: ctx.call, list: ctx.list },
-                    initialMode,
+                    initialModel,
                     compositor: ctx.shell?.compositor,
                     instanceId: ctx.instanceId,
                 });
@@ -468,14 +511,18 @@ export default function agentBackend(ctx) {
             bus.emit("ui:error", { message: `Provider "${name}" has no API key configured` });
             return;
         }
+        if (!p.baseURL && p.id !== "openai") {
+            bus.emit("ui:error", { message: `Provider "${name}" has no endpoint configured` });
+            return;
+        }
         const switchModel = p.defaultModel ?? p.models[0];
         if (!switchModel) {
             bus.emit("ui:error", { message: `Provider "${name}" has no models configured` });
             return;
         }
         llmClient.reconfigure({ apiKey: p.apiKey, baseURL: p.baseURL, model: switchModel });
-        bus.emit("agent:modes-changed", {});
-        bus.emit("config:switch-model", { model: switchModel });
+        bus.emit("agent:models-changed", {});
+        bus.emit("config:switch-model", { id: switchModel, provider: name });
         bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
     });
     bus.onPipe("banner:collect", (e) => {
@@ -495,7 +542,7 @@ export { AgentLoop } from "./agent-loop.js";
 export { ToolRegistry } from "./tool-registry.js";
 export { runSubagent } from "./subagent.js";
 /** Built-in providers register unconditionally so `auth list` can
- *  enumerate them; buildModes() skips entries without an apiKey. */
+ *  enumerate them; buildModels() skips entries without an apiKey. */
 export function activateAgent(ctx) {
     agentBackend(ctx);
     const agentCtx = ctx;

package/dist/agent/live-view.d.ts

@@ -19,7 +19,7 @@ export declare class LiveView {
     constructor(handlers?: HandlerFunctions, instanceId?: string);
     private getMessagesJson;
     private invalidateMessagesCache;
-    addUserMessage(text: string): void;
+    addUserMessage(text: string, images?: ImageContent[]): void;
     addAssistantMessage(content: string | null, toolCalls?: {
         id: string;
         function: {
@@ -34,9 +34,9 @@ export declare class LiveView {
     appendUserMessage(text: string): void;
     private hasOpenToolCalls;
     private flushPendingMessages;
-    getMessages(): ChatCompletionMessageParam[];
-    get(): AgentShMessage[];
+    /** Send-shaped; may be longer than get() (dangling calls stubbed) — never link()/replace() by these indices. */
     forLLM(): ChatCompletionMessageParam[];
+    get(): AgentShMessage[];
     replace(msgs: AgentShMessage[]): void;
     link(index: number, entryId: string): void;
     /** DeepSeek 400s on tool messages without a matching tool_call;

package/dist/agent/live-view.js

@@ -1,4 +1,3 @@
-import { stripMeta } from "./llm-client.js";
 export class LiveView {
     messages = [];
     messagesDirty = true;
@@ -26,8 +25,19 @@ export class LiveView {
         this.messagesDirty = true;
         this.cachedMessagesJson = null;
     }
-    addUserMessage(text) {
-        this.messages.push({ role: "user", content: text });
+    addUserMessage(text, images) {
+        if (images?.length) {
+            const parts = [];
+            if (text)
+                parts.push({ type: "text", text });
+            for (const img of images) {
+                parts.push({ type: "image_url", image_url: { url: `data:${img.mimeType};base64,${img.data}` } });
+            }
+            this.messages.push({ role: "user", content: parts });
+        }
+        else {
+            this.messages.push({ role: "user", content: text });
+        }
         this.invalidateMessagesCache();
     }
     addAssistantMessage(content, toolCalls, extras) {
@@ -131,15 +141,13 @@ export class LiveView {
         }
         this.invalidateMessagesCache();
     }
-    getMessages() {
+    /** Send-shaped; may be longer than get() (dangling calls stubbed) — never link()/replace() by these indices. */
+    forLLM() {
         return this.normalizeReasoningConsistency(this.stubDanglingToolCalls(this.dropOrphanToolMessages(this.messages)));
     }
     get() {
         return this.messages;
     }
-    forLLM() {
-        return this.getMessages().map(stripMeta);
-    }
     replace(msgs) {
         this.replaceMessages(msgs);
     }

package/dist/agent/providers/deepseek.js

@@ -10,7 +10,15 @@ function buildReasoningParams(level, _model) {
         : { thinking: { type: "enabled" }, reasoning_effort: level };
 }
 export default function activate(ctx) {
-    ctx.agent.providers.configure("deepseek", { reasoningParams: buildReasoningParams });
+    ctx.agent.providers.configure("deepseek", {
+        reasoningParams: buildReasoningParams,
+        // Native DeepSeek reports caching as flat hit/miss counts, not the
+        // OpenAI-standard prompt_tokens_details.cached_tokens the default reads.
+        cacheTokens: (u) => {
+            const hit = u.prompt_cache_hit_tokens;
+            return typeof hit === "number" ? hit : undefined;
+        },
+    });
     ctx.agent.providers.register({
         id: "deepseek",
         apiKey: resolveApiKey("deepseek").key ?? undefined,

package/dist/agent/providers/openrouter.js

@@ -14,6 +14,14 @@ function buildReasoningParams(level, _model) {
         ? { reasoning: { effort: "none" } }
         : { reasoning: { effort: level } };
 }
+/** OpenRouter's input_modalities → the text/image subset; undefined when absent
+ *  so the fail-closed image guard treats the model as text-only. */
+function toModalities(input) {
+    if (!Array.isArray(input))
+        return undefined;
+    const out = input.filter((v) => v === "text" || v === "image");
+    return out.length ? out : undefined;
+}
 export default function activate(ctx) {
     const apiKey = resolveApiKey("openrouter").key;
     ctx.agent.providers.configure("openrouter", { reasoningParams: buildReasoningParams });
@@ -42,6 +50,7 @@ export default function activate(ctx) {
                 reasoning: m.supported_parameters?.includes("reasoning") ?? false,
                 contextWindow: m.context_length,
                 echoReasoning: userOverrides.get(m.id) ?? patterns.some((re) => re.test(m.id)),
+                modalities: toModalities(m.architecture?.input_modalities),
             })),
         });
     }).catch(() => { });

package/dist/agent/session-store.js

@@ -237,7 +237,7 @@ export class SessionStore {
         for (const e of this.entries.values()) {
             if (e.type === "message" && e.message.role === "user") {
                 const raw = typeof e.message.content === "string" ? e.message.content : "";
-                const txt = stripContextWrappers(raw);
+                const txt = stripContextWrappers(raw).replace(/\s+/g, " ").trim();
                 if (txt)
                     return txt.slice(0, 80);
             }

package/dist/agent/subagent.js

@@ -109,7 +109,7 @@ async function streamOnce(llmClient, systemPrompt, conversation, apiTools, model
     const stream = await llmClient.stream({
         messages: [
             { role: "system", content: systemPrompt },
-            ...wrapTrailingWithDynamicContext(conversation.getMessages(), dynamicContext ?? ""),
+            ...wrapTrailingWithDynamicContext(conversation.forLLM(), dynamicContext ?? ""),
         ],
         tools: apiTools.length > 0 ? apiTools : undefined,
         model,

package/dist/agent/system-prompt.d.ts

@@ -7,10 +7,14 @@ import { type Skill } from "./skills.js";
 export declare function formatSkillsBlock(skills: Skill[]): string;
 export declare function loadGlobalAgentsMd(): string | null;
 /**
- * Static system prompt — identical across all queries, cacheable.
- * Contains only identity and behavioral instructions.
+ * Identity — paragraph one of the system prompt. Surface-agnostic, cacheable.
  */
-export declare const STATIC_SYSTEM_PROMPT: string;
+export declare const STATIC_IDENTITY = "You are ash, an AI coding assistant running inside agent-sh \u2014 a composable agent runtime with a small core and everything else, including the frontend you're attached to, layered on as extensions.";
+/**
+ * The rest of the static prompt — code map, tool guidance, envelope contract.
+ * Follows the frontend surface description in the assembled prompt.
+ */
+export declare const STATIC_GUIDE: string;
 /**
  * CWD-scoped static context: project conventions (CLAUDE.md / AGENT.md)
  * and discovered skills. Stable for a given cwd — callers should cache

package/dist/agent/system-prompt.js

@@ -85,14 +85,14 @@ function loadConventionFiles(dir) {
     return result;
 }
 /**
- * Static system prompt — identical across all queries, cacheable.
- * Contains only identity and behavioral instructions.
+ * Identity — paragraph one of the system prompt. Surface-agnostic, cacheable.
  */
-export const STATIC_SYSTEM_PROMPT = `You are ash, an AI coding assistant running inside agent-sh — a composable agent runtime with a small core and everything else, including the shell integration, layered on as extensions.
-
-You may be paired with a terminal shell that shares the user's CWD, environment, and history — in that mode you can read shell events and act on the user's session. Otherwise you may be embedded as a library, exposed over a bridge protocol, or running headless, with no shell available; in those modes you operate purely through your registered tools.
-
-agent-sh source and documentation live at ${CODE_DIR}. Read them when you need to understand how the runtime works, or when the user asks how to modify or extend it:
+export const STATIC_IDENTITY = `You are ash, an AI coding assistant running inside agent-sh — a composable agent runtime with a small core and everything else, including the frontend you're attached to, layered on as extensions.`;
+/**
+ * The rest of the static prompt — code map, tool guidance, envelope contract.
+ * Follows the frontend surface description in the assembled prompt.
+ */
+export const STATIC_GUIDE = `agent-sh source and documentation live at ${CODE_DIR}. Read them when you need to understand how the runtime works, or when the user asks how to modify or extend it:
 - ${path.join(CODE_DIR, "docs")} — start with README.md; architecture.md and extensions.md cover the kernel boundary and extension API
 - ${path.join(CODE_DIR, "src")} — kernel in src/core, default backend in src/agent, shell host in src/shell, built-in extensions in src/extensions
 - ${path.join(CODE_DIR, "examples/extensions")} — reference extensions to study or copy when adding functionality
@@ -105,15 +105,12 @@ guidance rather than assuming a particular tool exists. Tool output is
 returned to you for reasoning — the user doesn't see it directly.
 
 # Context Envelopes
-- \`<query_context>\` (contains \`<cwd>\` always, and \`<shell_events>\` when there were user shell commands since the last turn): the user's situation when they sent this turn — \`<cwd>\` anchors where they are right now, \`<shell_events>\` grounds "fix this" / "what just happened" requests. Trust the most recent \`<cwd>\` over any cwd referenced in earlier history.
-- \`<dynamic_context>\`: current system state — in-flight work, mode markers, warnings.
-\`<dynamic_context>\` may be absent on any turn.
 
-# Preference Learning
+A turn may be preceded by either of two wrappers:
+- \`<query_context>\`: the user's situation when they sent this turn — the frontend and extensions inject what grounds the request here. Trust the most recent values over anything referenced earlier in history.
+- \`<dynamic_context>\`: current system state — in-flight work, mode markers, warnings.
 
-Treat the user's past commands as standing preferences. Before acting, check shell history
-and conversation context for recurring patterns — apply them proactively and do not wait to
-be reminded.`;
+Either may be absent on any turn.`;
 /**
  * CWD-scoped static context: project conventions (CLAUDE.md / AGENT.md)
  * and discovered skills. Stable for a given cwd — callers should cache

package/dist/agent/tool-protocol.js

@@ -84,7 +84,6 @@ export class InlineToolProtocol {
                 const name = obj.tool;
                 if (typeof name !== "string")
                     continue;
-                // Separate tool name from args
                 const { tool: _, ...args } = obj;
                 calls.push({
                     id: `inline_${++this.callCounter}`,
@@ -128,7 +127,6 @@ class CodeBlockFilter {
         let raw = "";
         while (this.buf.length > 0) {
             if (this.inFence) {
-                // Look for closing ```
                 const closeIdx = this.buf.indexOf("```");
                 if (closeIdx !== -1) {
                     // Skip past closing ``` and any trailing whitespace on that line
@@ -142,7 +140,6 @@ class CodeBlockFilter {
                 // No closing yet — keep buffering
                 break;
             }
-            // Look for opening ```tool
             const openIdx = this.buf.indexOf("```tool");
             if (openIdx !== -1) {
                 // Emit everything before the fence, trimming trailing newline
@@ -184,7 +181,6 @@ class CodeBlockFilter {
             raw += this.buf;
             this.buf = "";
         }
-        // Collapse runs of 3+ newlines into 2 (one blank line max)
         return this.collapseNewlines(raw);
     }
     flush() {
@@ -209,7 +205,6 @@ class CodeBlockFilter {
             prefix = "\n".repeat(Math.min(leading, allowed));
             text = text.slice(leading);
         }
-        // Collapse internal runs
         text = text.replace(/\n{3,}/g, "\n\n");
         // Track trailing newlines for next call
         let trailing = 0;
@@ -322,9 +317,7 @@ export class DeferredToolProtocol {
             if (schemaProps) {
                 const validParams = new Set(Object.keys(schemaProps));
                 const providedParams = Object.keys(targetArgs);
-                // Check for unknown params (likely wrong names)
                 const unknown = providedParams.filter((p) => !validParams.has(p));
-                // Check for missing required params
                 const missing = [...requiredParams].filter((p) => !targetArgs[p]);
                 if (unknown.length > 0 || missing.length > 0) {
                     const expected = [...validParams]

package/dist/cli/args.js

@@ -3,9 +3,10 @@ const HELP_TEXT = `agent-sh — a shell-first terminal where AI is one keystroke
 
 Usage: agent-sh [options]
        agent-sh init [--force]            Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
-       agent-sh install <spec> [--force] [--sync-deps]
+       agent-sh install <spec> [--force] [--sync-deps] [--dev]
                                           Install an extension (bundled name, file:, npm:, github:)
                                           --sync-deps rewrites a stale agent-sh pin to the host version
+                                          --dev links the extension against the running host's core (local development)
        agent-sh uninstall <name>          Remove an installed extension
        agent-sh list                      List installed extensions
        agent-sh auth login [provider]     Store an API key for a built-in provider

package/dist/cli/install.d.ts

@@ -1,6 +1,7 @@
 interface InstallOpts {
     force?: boolean;
     syncDeps?: boolean;
+    dev?: boolean;
 }
 export declare function listBundled(): string[];
 /** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */