agent-sh 0.14.11 → 0.15.0

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

@@ -43,6 +43,10 @@ function defaultReasoningBuilder(level) {
         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;
@@ -91,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: {
@@ -280,33 +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;
             if (!usableProvider(p))
                 continue;
-            const shapeId = p.reasoningShape ?? id;
             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);
@@ -329,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)
@@ -342,13 +357,15 @@ 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 }) => {
@@ -388,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", {
@@ -413,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,
                 });
@@ -505,8 +521,8 @@ export default function agentBackend(ctx) {
             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) => {
@@ -526,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/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/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/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". */

package/dist/cli/install.js

@@ -190,6 +190,32 @@ function rewriteFileDeps(target, sourcePath) {
     if (changed)
         fs.writeFileSync(pkgJson, `${JSON.stringify(pkg, null, 2)}\n`);
 }
+/** --dev: repoint the extension's agent-sh dep at the running host's package
+ *  root, so the install builds and runs against the local (possibly unreleased)
+ *  core instead of the published registry version. npm links the file: path, so
+ *  later core rebuilds flow through without reinstalling. */
+function pinHostCore(target) {
+    const pkgJson = path.join(target, "package.json");
+    if (!fs.existsSync(pkgJson))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+    const sections = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+    let changed = false;
+    for (const section of sections) {
+        const deps = pkg[section];
+        if (!deps || typeof deps !== "object")
+            continue;
+        const d = deps;
+        if (typeof d["agent-sh"] !== "string")
+            continue;
+        d["agent-sh"] = `file:${PACKAGE_ROOT}`;
+        changed = true;
+    }
+    if (!changed)
+        return;
+    fs.writeFileSync(pkgJson, `${JSON.stringify(pkg, null, 2)}\n`);
+    console.log(`agent-sh: --dev — linking ${path.basename(target)} against host core at ${PACKAGE_ROOT}`);
+}
 function maybeNpmInstall(target, pkg) {
     const deps = { ...(pkg.dependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
     if (Object.keys(deps).length === 0)
@@ -252,7 +278,7 @@ function linkBins(target, pkg) {
 }
 export async function runInstall(spec, opts = {}) {
     if (!spec) {
-        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force] [--sync-deps]\n\n" +
+        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force] [--sync-deps] [--dev]\n\n" +
             "Bundled extensions:\n" +
             listBundled()
                 .map((n) => `  ${n}`)
@@ -286,6 +312,8 @@ export async function runInstall(spec, opts = {}) {
         });
         try {
             rewriteFileDeps(target, resolved.sourcePath);
+            if (opts.dev)
+                pinHostCore(target);
             syncAgentShVersion(target, opts.syncDeps ?? false);
             const pkg = readPackageJson(target);
             if (pkg) {

package/dist/cli/subcommands.js

@@ -6,6 +6,7 @@ const SUBCOMMANDS = {
     install: (args) => runInstall(args[0] ?? "", {
         force: args.includes("--force"),
         syncDeps: args.includes("--sync-deps"),
+        dev: args.includes("--dev"),
     }),
     uninstall: (args) => runUninstall(args[0] ?? ""),
     list: () => runList(),

package/dist/core/event-bus.js

@@ -159,9 +159,7 @@ export class EventBus {
      * returns the original payload unchanged (with safe defaults).
      */
     async emitPipeAsync(event, payload) {
-        // Phase 1: notify (lets renderers prepare for interactive I/O)
         this.dispatch(event, payload);
-        // Phase 2: transform (extensions provide decisions)
         const listeners = this.asyncPipeListeners.get(event);
         if (!listeners)
             return payload;

package/dist/core/extension-loader.js

@@ -119,7 +119,9 @@ function createScopedContext(ctx, extensionName) {
         onDispose: (fn) => { cleanups.push(fn); },
     };
     const dispose = () => {
-        for (const fn of cleanups) {
+        // Snapshot: a re-registering cleanup appends a new cleanup, and iterating
+        // the live array would run it and undo the restore in the same pass.
+        for (const fn of cleanups.slice()) {
             try {
                 fn();
             }

package/dist/core/index.d.ts

@@ -13,7 +13,7 @@ import { HandlerRegistry } from "../utils/handler-registry.js";
 export { EventBus } from "./event-bus.js";
 export type { BusEvents, ContentBlock, BackendRegistration } from "./event-bus.js";
 export type { CoreContext, CoreConfig } from "./types.js";
-export type { AgentContext, AgentConfig, AgentSurface, AgentConfigSurface, AgentMode, LlmInterface, LlmMessage, LlmSession } from "../agent/host-types.js";
+export type { AgentContext, AgentConfig, AgentSurface, AgentConfigSurface, Model, LlmInterface, LlmMessage, LlmSession } from "../agent/host-types.js";
 export type { ShellContext, ShellConfig, ShellSurface, ShellConfigSurface, ExtensionContext, RemoteSession, RemoteSessionOptions, RenderSurface, InputModeConfig, TerminalSession, BlockTransformOptions, FencedBlockTransformOptions, AppConfig } from "../shell/host-types.js";
 export { palette, setPalette, resetPalette } from "../utils/palette.js";
 export type { ColorPalette } from "../utils/palette.js";

package/dist/core/index.js

@@ -29,10 +29,11 @@ export function createCore(config) {
     bus.setSource(instanceId);
     handlers.define("config:get-app-config", () => config);
     handlers.define("cwd", () => process.cwd());
-    // Empty defaults so registerContextProducer can advise regardless of
-    // backend. Each backend chooses how to consume the strings.
+    // Empty defaults so advisors can wrap these regardless of load order;
+    // system-prompt:frontend is where the active frontend describes its surface.
     handlers.define("dynamic-context:build", () => "");
     handlers.define("query-context:build", () => "");
+    handlers.define("system-prompt:frontend", () => "");
     const backends = new Map();
     let activeBackendName = null;
     bus.on("agent:register-backend", (backend) => {

package/dist/extensions/slash-commands/index.js

@@ -41,16 +41,21 @@ export default function activate(ctx) {
         description: "Cycle to next model, or switch to a specific one",
         handler: (args) => {
             const name = args.trim();
+            const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
             if (!name) {
-                const { active } = bus.emitPipe("config:get-models", { models: [], active: null });
-                const label = active
-                    ? `${active.model}${active.provider ? ` [${active.provider}]` : ""}`
-                    : "none";
+                const label = active ? `${active.id} [${active.provider}]` : "none";
                 bus.emit("ui:info", { message: `Model: ${label}` });
+                return;
             }
-            else {
-                bus.emit("config:switch-model", { model: name });
+            const atIdx = name.lastIndexOf("@");
+            const id = atIdx > 0 ? name.slice(0, atIdx) : name;
+            const providerHint = atIdx > 0 ? name.slice(atIdx + 1) : undefined;
+            const found = models.find((m) => m.id === id && (!providerHint || m.provider === providerHint));
+            if (!found) {
+                bus.emit("ui:error", { message: `Unknown model: ${name}` });
+                return;
             }
+            bus.emit("config:switch-model", { id: found.id, provider: found.provider });
         },
     });
     register({
@@ -163,16 +168,16 @@ export default function activate(ctx) {
         const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
         const counts = new Map();
         for (const m of models)
-            counts.set(m.model, (counts.get(m.model) ?? 0) + 1);
+            counts.set(m.id, (counts.get(m.id) ?? 0) + 1);
         const items = models
-            .filter((m) => m.model.toLowerCase().includes(partial))
+            .filter((m) => m.id.toLowerCase().includes(partial))
             .slice(0, 15)
             .map((m) => {
-            const ambiguous = (counts.get(m.model) ?? 0) > 1 && m.provider;
-            const qualified = ambiguous ? `${m.model}@${m.provider}` : m.model;
+            const ambiguous = (counts.get(m.id) ?? 0) > 1;
+            const qualified = ambiguous ? `${m.id}@${m.provider}` : m.id;
             return {
                 name: `/model ${qualified}`,
-                description: `${m.provider ? `[${m.provider}]` : ""}${active && m.model === active.model && m.provider === active.provider ? " (active)" : ""}`,
+                description: `[${m.provider}]${active && m.id === active.id && m.provider === active.provider ? " (active)" : ""}`,
             };
         });
         if (items.length === 0)

package/dist/shell/index.js

@@ -7,11 +7,13 @@ import "./events.js"; // augments BusEvents with shell-owned events
 import { Shell } from "./shell.js";
 import { DefaultCompositor } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";
+import { FloatingPanel } from "../utils/floating-panel.js";
 import { setPalette } from "../utils/palette.js";
 import * as streamTransform from "../utils/stream-transform.js";
 import activateShellContext from "./shell-context.js";
 import activateTuiRenderer from "./tui-renderer.js";
 import { processTerminal, surfaceFromTerminal } from "./terminal.js";
+const SHELL_SURFACE = `You're attached through a terminal shell. It shares the user's working directory, environment, and command history, and you can act on their live session — everything they run at the prompt is visible to you.`;
 /**
  * Register shell-owned handlers extensions can `ctx.call`, and attach
  * the shell surface to ctx. Must run before `loadExtensions` so user
@@ -20,6 +22,10 @@ import { processTerminal, surfaceFromTerminal } from "./terminal.js";
 export function registerShellHandlers(ctx) {
     const { bus } = ctx;
     const compositor = new DefaultCompositor(bus);
+    ctx.advise("system-prompt:frontend", (next) => {
+        const base = next() ?? "";
+        return base ? `${base}\n\n${SHELL_SURFACE}` : SHELL_SURFACE;
+    });
     const shellSurface = {
         compositor,
         setPalette,
@@ -69,6 +75,9 @@ export function registerShellHandlers(ctx) {
         terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
         return terminalBufferSingleton;
     });
+    // bus override lets callers pass their scoped bus, so the panel's
+    // listeners unwire when the extension reloads.
+    ctx.define("floating-panel:create", (config, bus) => new FloatingPanel(bus ?? ctx.bus, config));
     activateShellContext(ctx);
     activateTuiRenderer(ctx);
 }

package/dist/shell/shell-context.d.ts

@@ -1,5 +1,5 @@
 /** Tracks PTY commands and cwd, spills long outputs, contributes per-query
- *  `<cwd>` (always) and `<shell_events>` (fresh user exchanges). Frontends
- *  without a PTY skip this and fall back to core's process.cwd() default. */
+ *  `<shell_events>` (fresh user exchanges) and — under the shell frontend —
+ *  `<cwd>`. Frontends without a PTY skip this. */
 import type { ExtensionContext } from "./host-types.js";
 export default function activate(ctx: ExtensionContext): void;