agent-sh 0.12.27 → 0.13.0

package/dist/{core.js → core/index.js}

@@ -6,9 +6,9 @@
  * subscribing to bus events. Shell-specific tracking lives in the
  * shell-context built-in extension.
  *
- * Agent backends are loaded as extensions and register themselves via
- * the agent:register-backend bus event. The built-in "ash" backend is
- * loaded from src/extensions/agent-backend.ts.
+ * Agent backends register themselves via the agent:register-backend bus
+ * event. The built-in "ash" backend lives in src/agent/ and is activated
+ * by hosts via activateAgent().
  *
  * Usage:
  *   import { createCore } from "agent-sh";
@@ -18,22 +18,18 @@
  *   const response = await core.query("hello");
  */
 import { EventBus } from "./event-bus.js";
-import { createLlmFacade } from "./utils/llm-facade.js";
-import { setPalette } from "./utils/palette.js";
-import * as streamTransform from "./utils/stream-transform.js";
 import * as settingsMod from "./settings.js";
-import { HandlerRegistry } from "./utils/handler-registry.js";
+import { HandlerRegistry } from "../utils/handler-registry.js";
 import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DefaultCompositor } from "./utils/compositor.js";
 import { CONFIG_DIR } from "./settings.js";
-// Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
-export { palette, setPalette, resetPalette } from "./utils/palette.js";
-export { runSubagent } from "./agent/subagent.js";
-export { LlmClient } from "./utils/llm-client.js";
-export { HistoryFile, InMemoryHistory, NoopHistory } from "./agent/history-file.js";
+export { palette, setPalette, resetPalette } from "../utils/palette.js";
+export { runSubagent } from "../agent/subagent.js";
+export { LlmClient } from "../utils/llm-client.js";
+export { HistoryFile, InMemoryHistory, NoopHistory } from "../agent/history-file.js";
+export { compileSearchRegex, matchEntry, formatNuclearLine } from "../agent/nuclear-form.js";
 export function createCore(config) {
     const bus = new EventBus();
     const handlers = new HandlerRegistry();
@@ -43,9 +39,7 @@ export function createCore(config) {
     const instanceId = crypto.randomBytes(3).toString("hex");
     bus.setSource(instanceId);
     const settings = settingsMod.getSettings();
-    // Expose raw CLI config so the agent backend extension can resolve
-    // providers and create the LLM client.
-    handlers.define("config:get-shell-config", () => config);
+    handlers.define("config:get-app-config", () => config);
     // Default; shell-context advises with the PTY-tracked cwd when loaded.
     handlers.define("cwd", () => process.cwd());
     // Empty defaults so registerContextProducer can advise regardless of
@@ -93,11 +87,6 @@ export function createCore(config) {
         const names = [...backends.keys()];
         return { names, active: activeBackendName };
     });
-    // ── Compositor ──────────────────────────────────────────────
-    // Generic surface-routing primitive. No defaults here — the active
-    // frontend (src/shell/, a web bridge, headless test harness, etc.)
-    // sets its own surfaces during activation.
-    const compositor = new DefaultCompositor(bus);
     return {
         bus,
         handlers,
@@ -153,14 +142,12 @@ export function createCore(config) {
             const ctx = {
                 bus,
                 instanceId,
-                llm: createLlmFacade(handlers),
-                providers: {
-                    configure: (id, opts) => bus.emit("provider:configure", { id, ...opts }),
-                },
                 quit: opts.quit,
-                setPalette,
-                createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
-                createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
+                define: (name, fn) => handlers.define(name, fn),
+                advise: (name, wrapper) => handlers.advise(name, wrapper),
+                call: (name, ...args) => handlers.call(name, ...args),
+                list: () => handlers.list(),
+                onDispose: () => { },
                 getExtensionSettings: settingsMod.getExtensionSettings,
                 getStoragePath: (namespace) => {
                     const dir = path.join(CONFIG_DIR, namespace);
@@ -168,70 +155,9 @@ export function createCore(config) {
                     return dir;
                 },
                 registerCommand: (name, description, handler) => bus.emit("command:register", { name, description, handler }),
-                registerTool: (tool) => bus.emit("agent:register-tool", { tool, extensionName: "" }),
-                unregisterTool: (name) => bus.emit("agent:unregister-tool", { name }),
-                getTools: () => bus.emitPipe("agent:get-tools", { tools: [] }).tools,
-                registerInstruction: (name, text) => bus.emit("agent:register-instruction", { name, text, extensionName: "" }),
-                removeInstruction: (name) => bus.emit("agent:remove-instruction", { name }),
-                registerSkill: (name, description, filePath) => bus.emit("agent:register-skill", { name, description, filePath, extensionName: "" }),
-                removeSkill: (name) => bus.emit("agent:remove-skill", { name }),
-                registerContextProducer: (_name, producer, opts) => {
-                    const handlerName = opts?.mode === "per-query"
-                        ? "query-context:build"
-                        : "dynamic-context:build";
-                    return handlers.advise(handlerName, (next) => {
-                        const base = next();
-                        const part = producer();
-                        if (!part)
-                            return base;
-                        const trimmed = part.trim();
-                        if (!trimmed)
-                            return base;
-                        return base ? `${base}\n\n${trimmed}` : trimmed;
-                    });
-                },
-                define: (name, fn) => handlers.define(name, fn),
-                advise: (name, wrapper) => handlers.advise(name, wrapper),
-                call: (name, ...args) => handlers.call(name, ...args),
-                list: () => handlers.list(),
-                compositor,
-                onDispose: () => { },
-                createRemoteSession: (opts) => {
-                    const { surface } = opts;
-                    const cleanups = [];
-                    let active = true;
-                    // Redirect all render streams
-                    cleanups.push(compositor.redirect("agent", surface));
-                    cleanups.push(compositor.redirect("query", surface));
-                    cleanups.push(compositor.redirect("status", surface));
-                    // Suppress the host shell's mute lifecycle and post-turn
-                    // redraw nudge. on-processing-done is intentionally not advised
-                    // — its scope cleanup must always run.
-                    cleanups.push(handlers.advise("shell:on-processing-start", (next) => active ? undefined : next()));
-                    cleanups.push(handlers.advise("shell:on-processing-redraw", (next) => active ? undefined : next()));
-                    // Suppress chrome
-                    if (opts.suppressBorders !== false) {
-                        cleanups.push(handlers.advise("tui:response-border", (next, ...a) => active ? null : next(...a)));
-                    }
-                    if (opts.suppressQueryBox) {
-                        cleanups.push(handlers.advise("tui:render-user-query", (next, ...a) => active ? [] : next(...a)));
-                    }
-                    if (opts.suppressUsage !== false) {
-                        cleanups.push(handlers.advise("tui:render-usage", (next, ...a) => active ? "" : next(...a)));
-                    }
-                    return {
-                        submit(query) { bus.emit("agent:submit", { query }); },
-                        get surface() { return surface; },
-                        get active() { return active; },
-                        close() {
-                            if (!active)
-                                return;
-                            active = false;
-                            for (const fn of cleanups.reverse())
-                                fn();
-                            cleanups.length = 0;
-                        },
-                    };
+                adviseCommand: (name, advisor) => {
+                    const key = name.startsWith("/") ? name : `/${name}`;
+                    return handlers.advise(`command:${key}`, advisor);
                 },
             };
             return ctx;

package/dist/{settings.d.ts → core/settings.d.ts}

@@ -78,6 +78,13 @@ export interface Settings {
      *   "inline" — tools described as text.
      */
     toolMode?: "api" | "deferred" | "deferred-lookup" | "inline";
+    /**
+     * Extra tool names treated as "core" in deferred / deferred-lookup mode —
+     * always sent with full schema instead of requiring an explicit load_tool
+     * call. Useful when an extension registers a substrate tool that should
+     * have first-class footing alongside the kernel built-ins.
+     */
+    coreTools?: string[];
     /** Additional directories to scan for skills (supports ~ expansion). */
     skillPaths?: string[];
     /**

package/dist/{settings.js → core/settings.js}

@@ -20,6 +20,7 @@ const DEFAULTS = {
     defaultProvider: undefined,
     defaultBackend: "ash",
     toolMode: "api",
+    coreTools: [],
     shellTruncateThreshold: 20,
     shellHeadLines: 10,
     shellTailLines: 10,

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+import type { EventBus } from "./event-bus.js";
+export type { ContentBlock } from "./event-bus.js";
+/**
+ * The substrate context — what every backend and every host always
+ * provides. Bus, handler registry, lifecycle, and per-instance storage.
+ *
+ * Hosts (agent, shell, web bridge, …) extend this with their own
+ * surfaces — see src/agent/host-types.ts and src/shell/host-types.ts.
+ * Extensions that only need the substrate should type their ctx as
+ * `CoreContext`; those that need host facilities should type as
+ * `AgentContext` or `ShellContext` to make their host dependency
+ * explicit (and catch misuse under bridge backends at the type level).
+ */
+export interface CoreContext {
+    bus: EventBus;
+    /** Stable per-instance identifier (4-char hex). */
+    readonly instanceId: string;
+    quit: () => 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 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[];
+    /** Teardown callback fired on /reload. For resources the scoped context
+     *  can't track: process listeners, timers, watchers, sockets. */
+    onDispose: (fn: () => void) => void;
+}
+/**
+ * The substrate config — kernel-level options. Hosts extend with their
+ * own surfaces (see AgentConfig in src/agent/host-types.ts and
+ * ShellConfig in src/shell/host-types.ts).
+ */
+export interface CoreConfig {
+    /** Extension specifiers (paths or package names) to load on startup. */
+    extensions?: string[];
+    /** Override settings.defaultBackend for this session only (does not persist). */
+    backend?: string;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/extensions/file-autocomplete.d.ts

@@ -1,2 +1,2 @@
-import type { ExtensionContext } from "../types.js";
+import type { ExtensionContext } from "../shell/host-types.js";
 export default function activate(ctx: ExtensionContext): void;

package/dist/extensions/index.d.ts

@@ -1,25 +1,18 @@
 /**
- * Built-in extension manifest.
- *
- * These extensions ship with agent-sh and load before user extensions.
- * They receive unscoped contexts (not reloadable) and can be individually
- * disabled via the `disabledBuiltins` setting in ~/.agent-sh/settings.json.
- *
- * For order-critical frontend bootstrap (the PTY shell), see `src/shell/`.
- * That module exposes its own `activate(ctx, opts)` entry point, loaded
- * specially from `src/index.ts` rather than through this manifest.
+ * Cross-cutting built-ins, toggleable via `disabledBuiltins`.
+ * Module-owned built-ins activate inline:
+ *   shell-context, tui-renderer → registerShellHandlers (src/shell/)
+ *   agent-backend, providers    → activateAgent         (src/agent/)
  */
-import type { ExtensionContext } from "../types.js";
+import type { ExtensionContext } from "../shell/host-types.js";
 type ActivateFn = (ctx: ExtensionContext) => void;
 export declare const BUILTIN_EXTENSIONS: Array<{
     name: string;
-    when?: () => boolean;
     load: () => Promise<ActivateFn>;
 }>;
 /**
- * Load built-in extensions sequentially, skipping any in the disabled list
- * or whose `when` predicate returns false. Returns the names of extensions
- * that were loaded.
+ * Load built-in extensions sequentially, skipping any in the disabled list.
+ * Returns the names of extensions that were loaded.
  */
 export declare function loadBuiltinExtensions(ctx: ExtensionContext, disabled?: string[]): Promise<string[]>;
 export {};

package/dist/extensions/index.js

@@ -1,25 +1,10 @@
 export const BUILTIN_EXTENSIONS = [
-    { name: "shell-context", load: () => import("./shell-context.js").then(m => m.default) },
-    { name: "agent-backend", load: () => import("./agent-backend.js").then(m => m.default) },
-    { name: "openrouter",
-        when: () => !!process.env.OPENROUTER_API_KEY,
-        load: () => import("./providers/openrouter.js").then(m => m.default) },
-    { name: "openai",
-        when: () => !!process.env.OPENAI_API_KEY && !process.env.OPENAI_BASE_URL,
-        load: () => import("./providers/openai.js").then(m => m.default) },
-    { name: "openai-compatible",
-        when: () => !!process.env.OPENAI_BASE_URL,
-        load: () => import("./providers/openai-compatible.js").then(m => m.default) },
-    { name: "deepseek",
-        load: () => import("./providers/deepseek.js").then(m => m.default) },
-    { name: "tui-renderer", load: () => import("./tui-renderer.js").then(m => m.default) },
     { name: "slash-commands", load: () => import("./slash-commands.js").then(m => m.default) },
     { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
 ];
 /**
- * Load built-in extensions sequentially, skipping any in the disabled list
- * or whose `when` predicate returns false. Returns the names of extensions
- * that were loaded.
+ * Load built-in extensions sequentially, skipping any in the disabled list.
+ * Returns the names of extensions that were loaded.
  */
 export async function loadBuiltinExtensions(ctx, disabled = []) {
     const disabledSet = new Set(disabled);
@@ -27,8 +12,6 @@ export async function loadBuiltinExtensions(ctx, disabled = []) {
     for (const ext of BUILTIN_EXTENSIONS) {
         if (disabledSet.has(ext.name))
             continue;
-        if (ext.when && !ext.when())
-            continue;
         const activate = await ext.load();
         activate(ctx);
         loaded.push(ext.name);

package/dist/extensions/slash-commands.d.ts

@@ -1,2 +1,2 @@
-import type { ExtensionContext } from "../types.js";
+import type { ExtensionContext } from "../shell/host-types.js";
 export default function activate(ctx: ExtensionContext): void;

package/dist/extensions/slash-commands.js

@@ -12,13 +12,17 @@
  */
 import { palette as p } from "../utils/palette.js";
 import { discoverSkills, loadSkillContent } from "../agent/skills.js";
-import { reloadExtensions } from "../extension-loader.js";
+import { reloadExtensions } from "../core/extension-loader.js";
 export default function activate(ctx) {
     const { bus } = ctx;
     const commands = new Map();
     const register = (cmd) => {
         const name = cmd.name.startsWith("/") ? cmd.name : `/${cmd.name}`;
+        if (commands.has(name)) {
+            throw new Error(`Command "${name}" already registered. Use ctx.adviseCommand() to wrap it.`);
+        }
         commands.set(name, { ...cmd, name });
+        ctx.define(`command:${name}`, cmd.handler);
     };
     // ── Built-in commands ─────────────────────────────────────────
     register({
@@ -101,6 +105,7 @@ export default function activate(ctx) {
     bus.on("command:unregister", ({ name }) => {
         const key = name.startsWith("/") ? name : `/${name}`;
         commands.delete(key);
+        // Handler entry retained so external advisors survive a reload of the owner.
     });
     // ── Skill commands (/skill:<name>) ────────────────────────────
     const getSkills = () => {
@@ -214,7 +219,7 @@ export default function activate(ctx) {
         }
         const cmd = commands.get(e.name);
         if (cmd) {
-            const result = cmd.handler(e.args);
+            const result = ctx.call(`command:${e.name}`, e.args);
             if (result instanceof Promise) {
                 result.catch((err) => {
                     bus.emit("ui:error", {

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

@@ -0,0 +1,114 @@
+import type { EventBus } from "../core/event-bus.js";
+import type { CoreConfig, CoreContext } from "../core/types.js";
+import type { AgentSurface } from "../agent/host-types.js";
+import type { ColorPalette } from "../utils/palette.js";
+import type { Compositor, RenderSurface } from "../utils/compositor.js";
+import type { BlockTransformOptions, FencedBlockTransformOptions } from "../utils/stream-transform.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: 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: RenderSurface;
+    /** Whether this session is currently active. */
+    readonly active: boolean;
+    /** Tear down — restores all routing and advisors. */
+    close(): void;
+}
+/**
+ * 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;
+}
+/**
+ * Capabilities the shell host adds to the extension context, exposed
+ * on the nested `ctx.shell` field. Available only when the TUI shell
+ * frontend is loaded; under headless backends these methods are silent
+ * no-ops (bus emits with no listeners).
+ */
+export interface ShellSurface {
+    /** Routes named render streams ("agent", "query", "status", or any
+     *  extension-defined name) to terminal surfaces. Frontends register
+     *  default surfaces during activation; extensions can `redirect()`
+     *  to capture output. Shell-scoped because today only the TUI uses
+     *  it — bus events are the wire for other frontends. */
+    compositor: Compositor;
+    /** 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;
+    /** Wrap an input mode's `onSubmit`. Lets extensions transform queries
+     *  on the way to the agent (logging, redaction, vetoing). The mode
+     *  must already be registered via the `input-mode:register` bus event. */
+    adviseInputMode: (id: string, advisor: (next: (query: string, bus: EventBus) => void, query: string, bus: EventBus) => void) => () => void;
+    /** Create a remote session that routes agent output to a surface and
+     *  optionally accepts queries. Handles compositor routing, shell
+     *  lifecycle advisors, and chrome suppression. */
+    createRemoteSession: (opts: RemoteSessionOptions) => RemoteSession;
+}
+/** Substrate + shell surface. Use this when an extension only touches
+ *  shell features (themes, palette, transforms) and doesn't need the
+ *  agent surface. */
+export type ShellContext = CoreContext & {
+    shell: ShellSurface;
+};
+/**
+ * What extension `activate()` functions receive. Substrate (`CoreContext`)
+ * + slash-command registration + host surfaces, which are **optional**
+ * because hosts attach them on activation: under headless backends
+ * `ctx.shell` is undefined; under bridge backends `ctx.agent` may be
+ * undefined too. Extensions guard with `ctx.shell?.foo()` /
+ * `if (!ctx.agent) return;`, or type their parameter as the narrower
+ * `AgentContext` / `ShellContext` to declare host requirements (those
+ * variants make the surface non-optional). When both hosts are required,
+ * intersect them at the use site: `ctx: AgentContext & ShellContext`.
+ */
+export type ExtensionContext = CoreContext & {
+    registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) => void;
+    /** Wrap an already-registered command's handler. Name is normalized
+     *  (leading `/` optional). */
+    adviseCommand: (name: string, advisor: (next: (args: string) => Promise<void> | void, args: string) => Promise<void> | void) => () => void;
+    agent?: AgentSurface;
+    shell?: ShellSurface;
+};
+export interface ShellConfigSurface {
+    /** Shell binary (e.g. /bin/zsh) launched by the PTY frontend. */
+    shell?: string;
+}
+export type ShellConfig = CoreConfig & ShellConfigSurface;
+/** The full application config — substrate + agent + shell startup options.
+ *  Prefer this in CLI/embedder code; layered names (`CoreConfig`,
+ *  `AgentConfig`, `ShellConfig`) are for code that cares about which
+ *  host owns which fields. */
+export type AppConfig = CoreConfig & import("../agent/host-types.js").AgentConfigSurface & ShellConfigSurface;

package/dist/shell/host-types.js

@@ -0,0 +1 @@
+export {};

package/dist/shell/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * Frontend bootstrap. Loaded directly from src/index.ts (not the built-in
- * extensions manifest) because PTY + stdin raw mode ownership is order-
- * critical. For pluggable capability extensions see `src/extensions/`.
+ * Frontend bootstrap. Loaded directly from src/cli/index.ts (not the
+ * built-in extensions manifest) because PTY + stdin raw mode ownership is
+ * order-critical.
  */
-import type { ExtensionContext } from "../types.js";
+import type { ExtensionContext } from "./host-types.js";
 export interface ShellActivateOptions {
     cols: number;
     rows: number;
@@ -28,13 +28,14 @@ export interface ShellHandle {
     resize(cols: number, rows: number): void;
 }
 /**
- * Register shell-owned handlers extensions can `ctx.call`. Must run before
- * `loadExtensions`; the handlers only need the bus, not the PTY.
+ * Register shell-owned handlers extensions can `ctx.call`, and attach
+ * the shell surface to ctx. Must run before `loadExtensions` so user
+ * extensions see `ctx.shell` populated.
  */
 export declare function registerShellHandlers(ctx: ExtensionContext): void;
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically
- * `src/index.ts`) uses to drive lifecycle from process-level events.
+ * `src/cli/index.ts`) uses to drive lifecycle from process-level events.
  */
 export declare function activateShell(ctx: ExtensionContext, opts: ShellActivateOptions): ShellHandle;

package/dist/shell/index.js

@@ -1,11 +1,60 @@
 import { Shell } from "./shell.js";
-import { StdoutSurface } from "../utils/compositor.js";
+import { DefaultCompositor, StdoutSurface } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.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";
 /**
- * Register shell-owned handlers extensions can `ctx.call`. Must run before
- * `loadExtensions`; the handlers only need the bus, not the PTY.
+ * Register shell-owned handlers extensions can `ctx.call`, and attach
+ * the shell surface to ctx. Must run before `loadExtensions` so user
+ * extensions see `ctx.shell` populated.
  */
 export function registerShellHandlers(ctx) {
+    const { bus } = ctx;
+    const compositor = new DefaultCompositor(bus);
+    const shellSurface = {
+        compositor,
+        setPalette,
+        createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
+        createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
+        adviseInputMode: (id, advisor) => ctx.advise(`input-mode:${id}:submit`, advisor),
+        createRemoteSession: (sessOpts) => {
+            const { surface } = sessOpts;
+            const cleanups = [];
+            let active = true;
+            cleanups.push(compositor.redirect("agent", surface));
+            cleanups.push(compositor.redirect("query", surface));
+            cleanups.push(compositor.redirect("status", surface));
+            // on-processing-done is intentionally not advised — its scope
+            // cleanup must always run.
+            cleanups.push(ctx.advise("shell:on-processing-start", (next) => active ? undefined : next()));
+            cleanups.push(ctx.advise("shell:on-processing-redraw", (next) => active ? undefined : next()));
+            if (sessOpts.suppressBorders !== false) {
+                cleanups.push(ctx.advise("tui:response-border", (next, ...a) => active ? null : next(...a)));
+            }
+            if (sessOpts.suppressQueryBox) {
+                cleanups.push(ctx.advise("tui:render-user-query", (next, ...a) => active ? [] : next(...a)));
+            }
+            if (sessOpts.suppressUsage !== false) {
+                cleanups.push(ctx.advise("tui:render-usage", (next, ...a) => active ? "" : next(...a)));
+            }
+            return {
+                submit(query) { bus.emit("agent:submit", { query }); },
+                get surface() { return surface; },
+                get active() { return active; },
+                close() {
+                    if (!active)
+                        return;
+                    active = false;
+                    for (const fn of cleanups.reverse())
+                        fn();
+                    cleanups.length = 0;
+                },
+            };
+        },
+    };
+    ctx.shell = shellSurface;
     let terminalBufferSingleton;
     ctx.define("terminal-buffer", () => {
         if (terminalBufferSingleton !== undefined)
@@ -13,19 +62,19 @@ export function registerShellHandlers(ctx) {
         terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
         return terminalBufferSingleton;
     });
+    activateShellContext(ctx);
+    activateTuiRenderer(ctx);
 }
 /**
  * Construct the Shell, wire resize forwarding, and register cleanup with the
  * provided ExtensionContext. Returns a handle the caller (typically
- * `src/index.ts`) uses to drive lifecycle from process-level events.
+ * `src/cli/index.ts`) uses to drive lifecycle from process-level events.
  */
 export function activateShell(ctx, opts) {
-    // Stdout-as-default is a frontend choice, not a kernel one — a hub or
-    // web bridge would point these at its own surfaces.
     const stdoutSurface = new StdoutSurface();
-    ctx.compositor.setDefault("agent", stdoutSurface);
-    ctx.compositor.setDefault("query", stdoutSurface);
-    ctx.compositor.setDefault("status", stdoutSurface);
+    ctx.shell.compositor.setDefault("agent", stdoutSurface);
+    ctx.shell.compositor.setDefault("query", stdoutSurface);
+    ctx.shell.compositor.setDefault("status", stdoutSurface);
     const shell = new Shell({
         bus: ctx.bus,
         handlers: { define: ctx.define, call: ctx.call },

package/dist/shell/input-handler.d.ts

@@ -1,4 +1,4 @@
-import type { EventBus } from "../event-bus.js";
+import type { EventBus } from "../core/event-bus.js";
 import { TuiInputView } from "./tui-input-view.js";
 /** Narrow contract between InputHandler and its host (Shell). */
 export interface InputContext {
@@ -10,6 +10,10 @@ export interface InputContext {
     redrawPrompt(): void;
     freshPrompt(): void;
 }
+export interface InputHandlers {
+    define: (name: string, fn: (...a: any[]) => any) => void;
+    call: (name: string, ...a: any[]) => any;
+}
 /** Line editor + shell-passthrough buffer. Delegates rendering to TuiInputView. */
 export declare class InputHandler {
     private ctx;
@@ -27,11 +31,13 @@ export declare class InputHandler {
     private savedBuffer;
     private escapeTimer;
     private bus;
+    private handlers;
     private onShowAgentInfo;
     private view;
     constructor(opts: {
         ctx: InputContext;
         bus: EventBus;
+        handlers: InputHandlers;
         onShowAgentInfo: () => {
             info: string;
             model?: string;