agent-sh 0.12.26 → 0.13.0

package/package.json

@@ -1,34 +1,34 @@
 {
   "name": "agent-sh",
-  "version": "0.12.26",
+  "version": "0.13.0",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
-  "main": "dist/core.js",
-  "types": "dist/core.d.ts",
+  "main": "dist/core/index.js",
+  "types": "dist/core/index.d.ts",
   "bin": {
-    "agent-sh": "dist/index.js"
+    "agent-sh": "dist/cli/index.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/core.d.ts",
-      "default": "./dist/core.js"
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./core": {
-      "types": "./dist/core.d.ts",
-      "default": "./dist/core.js"
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./utils/*": "./dist/utils/*",
     "./types": {
-      "types": "./dist/types.d.ts",
-      "default": "./dist/types.js"
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./settings": {
-      "types": "./dist/settings.d.ts",
-      "default": "./dist/settings.js"
+      "types": "./dist/core/settings.d.ts",
+      "default": "./dist/core/settings.js"
     },
     "./extension-loader": {
-      "types": "./dist/extension-loader.d.ts",
-      "default": "./dist/extension-loader.js"
+      "types": "./dist/core/extension-loader.d.ts",
+      "default": "./dist/core/extension-loader.js"
     },
     "./extensions": {
       "types": "./dist/extensions/index.d.ts",
@@ -46,6 +46,10 @@
       "types": "./dist/utils/terminal-buffer.d.ts",
       "default": "./dist/utils/terminal-buffer.js"
     },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "default": "./dist/agent/index.js"
+    },
     "./agent/types": {
       "types": "./dist/agent/types.d.ts",
       "default": "./dist/agent/types.js"
@@ -59,8 +63,8 @@
       "default": "./dist/agent/agent-loop.js"
     },
     "./event-bus": {
-      "types": "./dist/event-bus.d.ts",
-      "default": "./dist/event-bus.js"
+      "types": "./dist/core/event-bus.d.ts",
+      "default": "./dist/core/event-bus.js"
     },
     "./utils/compositor": {
       "types": "./dist/utils/compositor.d.ts",
@@ -83,8 +87,8 @@
       "default": "./dist/agent/nuclear-form.js"
     },
     "./executor": {
-      "types": "./dist/executor.d.ts",
-      "default": "./dist/executor.js"
+      "types": "./dist/utils/executor.d.ts",
+      "default": "./dist/utils/executor.js"
     }
   },
   "files": [
@@ -93,15 +97,15 @@
     "examples/extensions/*/package.json",
     "examples/extensions/*/tsconfig.json",
     "examples/extensions/*/README.md",
-    "examples/extensions/*/src",
+    "examples/extensions/*/src/**",
     "examples/extensions/*/index.ts",
     "examples/extensions/*/index.js"
   ],
   "scripts": {
-    "dev": "tsx src/index.ts",
+    "dev": "tsx src/cli/index.ts",
     "build": "tsc",
-    "start": "node dist/index.js",
-    "prepare": "npm run build"
+    "start": "node dist/cli/index.js",
+    "prepare": "test -d dist || npm run build"
   },
   "keywords": [
     "terminal",

package/dist/extensions/agent-backend.d.ts

@@ -1,14 +0,0 @@
-/**
- * Built-in agent backend extension.
- *
- * Constructs the AgentLoop synchronously with a placeholder LlmClient,
- * so core handlers (history:append, system-prompt:build, conversation:*)
- * are defined before user extensions activate. Mode resolution is
- * deferred to `core:extensions-loaded`, giving runtime-registered
- * providers (e.g. openrouter) a chance to register before we look up
- * settings.defaultProvider. Without this deferral, a persisted
- * `defaultProvider: "openrouter"` loses to a cold-start race and the
- * backend bails silently.
- */
-import type { ExtensionContext } from "../types.js";
-export default function agentBackend(ctx: ExtensionContext): void;

package/dist/extensions/agent-backend.js

@@ -1,307 +0,0 @@
-import { AgentLoop } from "../agent/agent-loop.js";
-import { LlmClient } from "../utils/llm-client.js";
-import { resolveProvider, getProviderNames, getSettings } from "../settings.js";
-import { PACKAGE_VERSION } from "../utils/package-version.js";
-import { discoverSkills } from "../agent/skills.js";
-/** Read the user's persisted defaultModel for a provider, if any. */
-function persistedModelFor(providerName) {
-    if (!providerName)
-        return undefined;
-    return getSettings().providers?.[providerName]?.defaultModel;
-}
-function defaultReasoningBuilder(level) {
-    return level === "off" ? {} : { reasoning_effort: level };
-}
-function mergeCaps(settingsCaps, payloadCaps, modelIds) {
-    if (!settingsCaps)
-        return payloadCaps.size > 0 ? payloadCaps : undefined;
-    const out = new Map();
-    for (const id of modelIds) {
-        const s = settingsCaps.get(id);
-        const p = payloadCaps.get(id);
-        if (!s && !p)
-            continue;
-        out.set(id, {
-            reasoning: s?.reasoning ?? p?.reasoning,
-            contextWindow: s?.contextWindow ?? p?.contextWindow,
-            maxTokens: s?.maxTokens ?? p?.maxTokens,
-            echoReasoning: s?.echoReasoning ?? p?.echoReasoning,
-        });
-    }
-    return out.size > 0 ? out : undefined;
-}
-export default function agentBackend(ctx) {
-    const { bus } = ctx;
-    const config = ctx.call("config:get-shell-config") ?? {};
-    // Immutable settings snapshot; provider:register payloads merge against it.
-    const providerRegistry = new Map();
-    const settingsProviders = new Map();
-    for (const name of getProviderNames()) {
-        const p = resolveProvider(name);
-        if (p) {
-            providerRegistry.set(name, p);
-            settingsProviders.set(name, p);
-        }
-    }
-    const providerHooks = new Map();
-    // Bakes model id into the hook so AgentMode.buildReasoningParams keeps
-    // its (level) signature while the hook can branch on model.
-    const bindReasoning = (shapeId, model) => {
-        const hook = providerHooks.get(shapeId)?.reasoningParams;
-        return hook ? (level) => hook(level, model) : defaultReasoningBuilder;
-    };
-    const buildModes = () => {
-        const allModes = [];
-        for (const [id, p] of providerRegistry) {
-            if (!p.apiKey)
-                continue;
-            const shapeId = p.reasoningShape ?? id;
-            for (const model of p.models) {
-                const mc = p.modelCapabilities?.get(model);
-                allModes.push({
-                    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,
-                    buildReasoningParams: bindReasoning(shapeId, model),
-                });
-            }
-        }
-        return allModes;
-    };
-    // Placeholder client — reconfigured at core:extensions-loaded. Any
-    // stream() call before then fails from the OpenAI SDK; start() won't
-    // wire the loop until we've resolved, so users never hit that path.
-    const llmClient = new LlmClient({ apiKey: "not-configured", model: "not-configured" });
-    ctx.define("llm:get-client", () => llmClient);
-    ctx.define("llm:invoke", (messages, opts) => {
-        return llmClient.complete({
-            messages: messages,
-            max_tokens: opts?.maxTokens,
-            model: opts?.model,
-            reasoning_effort: opts?.reasoningEffort,
-        });
-    });
-    let modes = [];
-    let initialModeIndex = 0;
-    let resolved = false;
-    // Gates late-registration reconcile so its config:switch-model emit doesn't misroute under a non-ash backend.
-    let ashActive = false;
-    bus.onPipe("config:get-initial-modes", () => ({ modes, initialModeIndex }));
-    // AgentLoop must be constructed *before* user extensions activate,
-    // because its ctor defines handlers (history:append, etc.) that
-    // extensions like superash call synchronously during their own
-    // activate. Advise-before-define works for advisers, but plain calls
-    // would hit a no-op stub.
-    const agentLoop = new AgentLoop({
-        bus,
-        llmClient,
-        handlers: { define: ctx.define, advise: ctx.advise, call: ctx.call, list: ctx.list },
-        modes,
-        initialModeIndex,
-        compositor: ctx.compositor,
-        instanceId: ctx.instanceId,
-        history: config.history,
-    });
-    let loadedExtensionNames = [];
-    bus.on("core:extensions-loaded", ({ names }) => {
-        loadedExtensionNames = names;
-        const settings = getSettings();
-        // If the user didn't pick a default, fall back to the first registered
-        // provider (built-in load order biases to openrouter → openai).
-        const providerName = config.provider ?? settings.defaultProvider
-            ?? (providerRegistry.size > 0 ? providerRegistry.keys().next().value : undefined);
-        const activeProvider = providerName ? providerRegistry.get(providerName) ?? null : null;
-        // User's persisted defaultModel wins over the provider's declared
-        // default. Dynamic providers (openrouter) re-register with their
-        // hardcoded DEFAULT_MODELS[0] each startup, which would otherwise
-        // clobber the user's /model selection.
-        const effectiveApiKey = config.apiKey ?? activeProvider?.apiKey;
-        const effectiveBaseURL = config.baseURL ?? activeProvider?.baseURL;
-        const effectiveModel = config.model ?? persistedModelFor(providerName) ?? activeProvider?.defaultModel;
-        // No provider → don't register ash at all, so another backend (e.g.
-        // claude-code-bridge) can own activation. index.ts hard-fails only
-        // when no backend ended up registered.
-        if (!effectiveApiKey || !effectiveModel)
-            return;
-        modes = buildModes();
-        if (modes.length === 0)
-            modes = [{ model: effectiveModel }];
-        let foundIdx = modes.findIndex((m) => m.model === effectiveModel && (!activeProvider || m.provider === activeProvider.id));
-        // Persisted default may not be in the provider's curated list yet (e.g.
-        // openrouter's async catalog fetch hasn't returned). Prepend a stub so
-        // the initial config:set-modes activeIndex points at the real model —
-        // otherwise AgentLoop reconfigures llmClient back to modes[0].
-        if (foundIdx === -1 && activeProvider) {
-            modes = [
-                {
-                    model: effectiveModel,
-                    provider: activeProvider.id,
-                    providerConfig: { apiKey: effectiveApiKey, baseURL: effectiveBaseURL },
-                    supportsReasoningEffort: activeProvider.supportsReasoningEffort,
-                },
-                ...modes,
-            ];
-            foundIdx = 0;
-        }
-        initialModeIndex = Math.max(0, foundIdx);
-        llmClient.reconfigure({ apiKey: effectiveApiKey, baseURL: effectiveBaseURL, model: effectiveModel });
-        bus.emit("config:set-modes", { modes, activeIndex: initialModeIndex });
-        resolved = true;
-        bus.emit("agent:register-backend", {
-            name: "ash",
-            kill: () => {
-                ashActive = false;
-                bus.emit("command:unregister", { name: "/compact" });
-                bus.emit("command:unregister", { name: "/context" });
-                agentLoop.kill();
-            },
-            start: async () => {
-                agentLoop.wire();
-                ashActive = true;
-                bus.emit("command:register", {
-                    name: "/compact",
-                    description: "Compact conversation via the active compaction strategy",
-                    handler: () => bus.emit("agent:compact-request", {}),
-                });
-                bus.emit("command:register", {
-                    name: "/context",
-                    description: "Show context budget usage",
-                    handler: () => {
-                        const stats = bus.emitPipe("context:get-stats", {
-                            activeTokens: 0,
-                            totalTokens: 0,
-                            budgetTokens: 0,
-                        });
-                        const pct = stats.budgetTokens > 0
-                            ? Math.round((stats.activeTokens / stats.budgetTokens) * 100)
-                            : 0;
-                        bus.emit("ui:info", {
-                            message: `Active context: ~${stats.activeTokens.toLocaleString()} tokens / ${stats.budgetTokens.toLocaleString()} budget (${pct}%)`,
-                        });
-                    },
-                });
-                bus.emit("agent:info", {
-                    name: "ash",
-                    version: PACKAGE_VERSION,
-                    model: llmClient.model,
-                    provider: modes[initialModeIndex]?.provider,
-                    contextWindow: modes[initialModeIndex]?.contextWindow,
-                });
-            },
-        });
-    });
-    bus.on("provider:configure", ({ id, reasoningParams }) => {
-        const prev = providerHooks.get(id) ?? {};
-        if (reasoningParams !== undefined)
-            prev.reasoningParams = reasoningParams;
-        providerHooks.set(id, prev);
-    });
-    bus.on("provider:register", (p) => {
-        const rawModels = p.models ?? (p.defaultModel ? [p.defaultModel] : []);
-        const payloadModelIds = [];
-        const payloadCaps = new Map();
-        for (const m of rawModels) {
-            if (typeof m === "string") {
-                payloadModelIds.push(m);
-            }
-            else {
-                payloadModelIds.push(m.id);
-                payloadCaps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow, maxTokens: m.maxTokens, echoReasoning: m.echoReasoning });
-            }
-        }
-        const settings = settingsProviders.get(p.id);
-        const modelIds = settings?.modelsExplicit && settings.models.length > 0 ? settings.models : payloadModelIds;
-        const mergedCaps = mergeCaps(settings?.modelCapabilities, payloadCaps, modelIds);
-        const merged = {
-            id: p.id,
-            apiKey: settings?.apiKey ?? p.apiKey,
-            baseURL: settings?.baseURL ?? p.baseURL,
-            defaultModel: settings?.defaultModel ?? p.defaultModel,
-            models: modelIds,
-            modelsExplicit: settings?.modelsExplicit ?? false,
-            contextWindow: settings?.contextWindow,
-            supportsReasoningEffort: settings?.supportsReasoningEffort ?? p.supportsReasoningEffort,
-            modelCapabilities: mergedCaps,
-            reasoningShape: settings?.reasoningShape,
-        };
-        providerRegistry.set(p.id, merged);
-        const addModes = modelIds.map((m) => {
-            const mc = mergedCaps?.get(m);
-            return {
-                model: m,
-                provider: p.id,
-                providerConfig: { apiKey: merged.apiKey ?? "", baseURL: merged.baseURL },
-                contextWindow: mc?.contextWindow,
-                maxTokens: mc?.maxTokens,
-                reasoning: mc?.reasoning,
-                supportsReasoningEffort: merged.supportsReasoningEffort,
-                echoReasoning: mc?.echoReasoning,
-                buildReasoningParams: bindReasoning(p.id, m),
-            };
-        });
-        bus.emit("config:add-modes", { modes: addModes });
-        // Late-registration reconcile: if this completes the user's persisted
-        // default (openrouter's async fetch delivers the full catalog after
-        // we've already fallen back to mode 0), quietly switch to it.
-        if (!resolved || !ashActive)
-            return;
-        const pendingProvider = getSettings().defaultProvider;
-        if (pendingProvider !== p.id)
-            return;
-        const pendingModel = persistedModelFor(pendingProvider);
-        if (pendingModel && modelIds.includes(pendingModel) && llmClient.model !== pendingModel) {
-            bus.emit("config:switch-model", { model: pendingModel });
-        }
-    });
-    bus.on("config:switch-provider", ({ provider: name }) => {
-        const p = providerRegistry.get(name);
-        if (!p) {
-            bus.emit("ui:error", { message: `Unknown provider: ${name}` });
-            return;
-        }
-        if (!p.apiKey) {
-            bus.emit("ui:error", { message: `Provider "${name}" has no API key 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 });
-        const newModes = p.models.map((m) => {
-            const mc = p.modelCapabilities?.get(m);
-            return {
-                model: m,
-                provider: name,
-                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,
-            };
-        });
-        bus.emit("config:set-modes", { modes: newModes });
-        bus.emit("agent:info", { name: "ash", version: PACKAGE_VERSION, model: switchModel, provider: name, contextWindow: p.contextWindow });
-        bus.emit("ui:info", { message: `Switched to ${name} (${switchModel})` });
-        bus.emit("config:changed", {});
-    });
-    bus.onPipe("banner:collect", (e) => {
-        if (e.activeBackend && e.activeBackend !== "ash")
-            return e;
-        if (loadedExtensionNames.length > 0) {
-            e.sections.push({ label: "Extensions", items: [...loadedExtensionNames] });
-        }
-        const skills = discoverSkills(ctx.call("cwd") ?? process.cwd());
-        if (skills.length > 0) {
-            e.sections.push({ label: "Skills", items: skills.map((s) => s.name) });
-        }
-        return e;
-    });
-}

package/dist/types.d.ts

@@ -1,227 +0,0 @@
-import type { EventBus } from "./event-bus.js";
-import type { ColorPalette } from "./utils/palette.js";
-import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
-import type { ToolDefinition } from "./agent/types.js";
-import type { Compositor } from "./utils/compositor.js";
-import type { HistoryAdapter } from "./agent/history-file.js";
-export type { ContentBlock } from "./event-bus.js";
-export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
-export type { RenderSurface } from "./utils/compositor.js";
-export interface RemoteSessionOptions {
-    /** The surface to render agent output to. */
-    surface: import("./utils/compositor.js").RenderSurface;
-    /** Suppress response borders (default: true). */
-    suppressBorders?: boolean;
-    /** Suppress user query box (default: false).
-     *  True for sessions with their own input (rsplit, overlay).
-     *  False for sessions where input comes from the main shell (split). */
-    suppressQueryBox?: boolean;
-    /** Suppress usage stats line (default: true). */
-    suppressUsage?: boolean;
-}
-export interface RemoteSession {
-    /** Submit a query to the agent from this session. */
-    submit(query: string): void;
-    /** The surface this session renders to. */
-    readonly surface: import("./utils/compositor.js").RenderSurface;
-    /** Whether this session is currently active. */
-    readonly active: boolean;
-    /** Tear down — restores all routing and advisors. */
-    close(): void;
-}
-/** 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;
-    };
-    /** Context window size in tokens (for usage display). */
-    contextWindow?: number;
-    /** Max output tokens for this mode. */
-    maxTokens?: number;
-    /** Model supports reasoning/thinking tokens. */
-    reasoning?: boolean;
-    /** Provider supports the reasoning_effort parameter. */
-    supportsReasoningEffort?: boolean;
-    /** Echo reasoning_content back on assistant turns. Required by DeepSeek;
-     *  default off (leaky shims may forward it to the model as OOD input). */
-    echoReasoning?: boolean;
-    buildReasoningParams?: (level: string) => Record<string, unknown>;
-}
-/**
- * Backend-agnostic LLM interface exposed via `ctx.llm`. Backends fulfill it
- * by defining an `llm:invoke` handler; those without an LLM leave
- * `available` false and calls reject.
- */
-export interface LlmMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
-}
-export interface LlmSession {
-    send(message: string): Promise<string>;
-    history(): ReadonlyArray<LlmMessage>;
-}
-export interface LlmInterface {
-    readonly available: boolean;
-    /** `model` overrides the globally-configured model for this call only.
-     *  Provider-specific identifier (e.g. "claude-haiku-4-5"). When omitted,
-     *  the active provider's configured default is used.
-     *
-     *  `reasoningEffort` controls thinking-model token allocation between
-     *  reasoning and final content (e.g. "low", "medium", "high", or
-     *  provider-specific). For non-reasoning models it is ignored. Set to
-     *  "low" for cheap structured-output calls so reasoning doesn't exhaust
-     *  the max-tokens budget and leave content empty. */
-    ask(opts: {
-        query: string;
-        system?: string;
-        maxTokens?: number;
-        model?: string;
-        reasoningEffort?: string;
-    }): Promise<string>;
-    session(opts?: {
-        system?: string;
-        maxTokens?: number;
-        model?: string;
-        reasoningEffort?: string;
-    }): LlmSession;
-}
-export interface AgentShellConfig {
-    shell?: string;
-    model?: string;
-    extensions?: string[];
-    /** API key for OpenAI-compatible provider. */
-    apiKey?: string;
-    /** Base URL for OpenAI-compatible API. */
-    baseURL?: string;
-    /** Named provider to use from settings.json. */
-    provider?: string;
-    /** Override settings.defaultBackend for this session only (does not persist). */
-    backend?: string;
-    /** Conversation history backend. Defaults to the on-disk HistoryFile. */
-    history?: HistoryAdapter;
-}
-/**
- * Context passed to user/third-party extensions.
- * Extensions interact with the system through the event bus — no direct
- * frontend (Shell/TUI) dependencies. This enables headless, web, or
- * alternative frontends without changing extensions.
- */
-export interface ExtensionContext {
-    bus: EventBus;
-    /** Stable per-instance identifier (4-char hex). */
-    readonly instanceId: string;
-    quit: () => void;
-    /** Override color palette slots for theming. */
-    setPalette: (overrides: Partial<ColorPalette>) => void;
-    /** Register a delimiter-based content transform (e.g. $$...$$ → image). */
-    createBlockTransform: (opts: BlockTransformOptions) => void;
-    /** Register a fenced block transform (e.g. ```lang...``` → code-block). */
-    createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
-    /** Read extension-namespaced settings from ~/.agent-sh/settings.json. */
-    getExtensionSettings: <T extends Record<string, unknown>>(namespace: string, defaults: T) => T;
-    /**
-     * Get (and lazily create) a per-extension storage directory under
-     * ~/.agent-sh/<namespace>/. Returns the absolute path. Lets extensions
-     * persist state without each one re-deriving the location.
-     */
-    getStoragePath: (namespace: string) => string;
-    /** Register a slash command available in any input mode. */
-    registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) => void;
-    /** Register a tool for the built-in agent. No-op when using bridge backends. */
-    registerTool: (tool: ToolDefinition) => void;
-    /** Unregister a tool by name. */
-    unregisterTool: (name: string) => void;
-    /** Get all registered tools (for subagent tool subsets). Returns [] when using bridge backends. */
-    getTools: () => ToolDefinition[];
-    /** Register a named instruction block for the agent's system prompt. */
-    registerInstruction: (name: string, text: string) => void;
-    /** Remove a named instruction block from the system prompt. */
-    removeInstruction: (name: string) => void;
-    /** Register a skill (on-demand reference material) for the agent. */
-    registerSkill: (name: string, description: string, filePath: string) => void;
-    /** Remove a registered skill by name. */
-    removeSkill: (name: string) => void;
-    /**
-     * Register a context producer — a function that contributes a string
-     * (or `null` to skip) into one of two lifecycles:
-     *
-     * - `mode: "per-request"` (default) — fires on **every LLM request**,
-     *   including each tool-loop iteration. Output is ephemerally wrapped
-     *   in `<dynamic_context>` onto the trailing message at request time;
-     *   never persisted. Use for "current state" signals (in-flight work,
-     *   active mode, threshold warnings).
-     *
-     * - `mode: "per-query"` — fires **once at user-query start** in
-     *   handleQuery. Output is wrapped in `<query_context>` and frozen into
-     *   the user message; persists in conversation history. Use for
-     *   "what happened between turns" signals (shell events, accumulated
-     *   notifications, calendar/inbox deltas).
-     *
-     * In both modes producers run in registration order, non-null outputs
-     * joined with blank lines. When nothing contributes, no envelope tag
-     * is emitted.
-     *
-     * Returns a dispose fn that unregisters the producer.
-     */
-    registerContextProducer: (name: string, producer: () => string | null, opts?: {
-        mode?: "per-request" | "per-query";
-    }) => () => void;
-    providers: {
-        configure: (id: string, opts: {
-            reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
-        }) => void;
-    };
-    llm: LlmInterface;
-    /** Register a named handler. */
-    define: (name: string, fn: (...args: any[]) => any) => void;
-    /** Wrap a named handler. Receives `next` (original) + args. Returns an unadvise function. */
-    advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => () => void;
-    /** Call a named handler. */
-    call: (name: string, ...args: any[]) => any;
-    /** Names of all registered handlers — for diagnostic / introspection use. */
-    list: () => string[];
-    /**
-     * Routes named render streams ("agent", "query", "status") to surfaces.
-     * Extensions use `compositor.redirect()` to capture output (e.g. overlay panels).
-     */
-    compositor: Compositor;
-    /** Teardown callback fired on /reload. For resources the scoped context
-     *  can't track: process listeners, timers, watchers, sockets. */
-    onDispose: (fn: () => void) => void;
-    /**
-     * Create a remote session that routes agent output to a surface and
-     * optionally accepts queries. Handles all compositor routing, shell
-     * lifecycle advisors, and chrome suppression.
-     *
-     *   const session = ctx.createRemoteSession({ surface });
-     *   session.submit("what's on screen?");
-     *   session.close();  // restores everything
-     */
-    createRemoteSession: (opts: RemoteSessionOptions) => RemoteSession;
-}
-/**
- * Configuration for a registered input mode.
- * Extensions emit "input-mode:register" with this shape to add new modes.
- */
-export interface InputModeConfig {
-    id: string;
-    trigger: string;
-    label: string;
-    promptIcon: string;
-    indicator: string;
-    onSubmit(query: string, bus: EventBus): void;
-    returnToSelf: boolean;
-}
-export interface TerminalSession {
-    id: string;
-    command: string;
-    output: string;
-    exitCode: number | null;
-    done: boolean;
-    resolve?: (value: void) => void;
-}