agent-sh 0.15.0 → 0.15.2

package/src/core/index.ts

@@ -0,0 +1,152 @@
+/**
+ * Core kernel — EventBus + HandlerRegistry + backend registry. Knows
+ * nothing about LLMs, tools, or specific backends; backends (ash,
+ * claude-code-bridge, ...) register through `agent:register-backend`
+ * and core dispatches to whichever is configured as default.
+ */
+import { EventBus, type BackendRegistration } from "./event-bus.js";
+// Side-effect imports so downstream tsc sees module-augmented BusEvents.
+import "../shell/events.js";
+import "../agent/events.js";
+import "../extensions/slash-commands/events.js";
+import type { AppConfig, ExtensionContext } from "../shell/host-types.js";
+import * as settingsMod from "./settings.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 { CONFIG_DIR } from "./settings.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, 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";
+export type { AgentBackend, ToolDefinition, ImageContent } from "../agent/types.js";
+export { runSubagent, type SubagentOptions } from "../agent/subagent.js";
+export { LlmClient } from "../agent/llm-client.js";
+export type { NuclearEntry } from "../agent/nuclear-form.js";
+export { compileSearchRegex, matchEntry, formatNuclearLine } from "../agent/nuclear-form.js";
+
+export interface AgentShellCore {
+  bus: EventBus;
+  handlers: HandlerRegistry;
+  /** Unique id for this agent process; used for shell-marker tagging and lineage tracking. */
+  instanceId: string;
+  /** Activates a registered backend by name (or persisted default / first registered). */
+  activateBackend(override?: string): Promise<void>;
+  extensionContext(opts: { quit: () => void }): ExtensionContext;
+  kill(): void;
+}
+
+export function createCore(config: AppConfig): AgentShellCore {
+  const bus = new EventBus();
+  const handlers = new HandlerRegistry();
+  // 3 bytes = 6 hex chars; legacy content may have 16-char iids so parsers
+  // should accept ≥6 hex chars.
+  const instanceId = crypto.randomBytes(3).toString("hex");
+  bus.setSource(instanceId);
+  handlers.define("config:get-app-config", () => config);
+  handlers.define("cwd", () => process.cwd());
+
+  // 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<string, BackendRegistration>();
+  let activeBackendName: string | null = null;
+
+  bus.on("agent:register-backend", (backend) => {
+    backends.set(backend.name, backend);
+  });
+
+  bus.onPipe("config:get-backends", () => ({
+    names: [...backends.keys()],
+    active: activeBackendName,
+  }));
+
+  const activateByName = async (name: string): Promise<boolean> => {
+    const backend = backends.get(name);
+    if (!backend) {
+      bus.emit("ui:error", { message: `Unknown backend: ${name}` });
+      return false;
+    }
+    if (activeBackendName && activeBackendName !== name) {
+      backends.get(activeBackendName)?.kill();
+    }
+    activeBackendName = name;
+    await backend.start?.();
+    return true;
+  };
+
+  bus.on("config:switch-backend", ({ name }) => {
+    activateByName(name).then((ok) => {
+      if (!ok) return;
+      settingsMod.updateSettings({ defaultBackend: name });
+      bus.emit("ui:info", { message: `Backend: ${name} (saved as default)` });
+      bus.emit("config:changed", {});
+    });
+  });
+
+  bus.on("config:list-backends", () => {
+    const list = [...backends.keys()]
+      .map((n) => n === activeBackendName ? `${n} (active)` : n)
+      .join(", ");
+    bus.emit("ui:info", { message: `Backends: ${list || "(none registered)"}` });
+  });
+
+  return {
+    bus,
+    handlers,
+    instanceId,
+
+    async activateBackend(override?: string) {
+      if (backends.size === 0) {
+        bus.emit("ui:info", { message: "No agent backend registered." });
+        return;
+      }
+      const preferred = override ?? settingsMod.getSettings().defaultBackend;
+      const name = preferred && backends.has(preferred)
+        ? preferred
+        : backends.keys().next().value!;
+      await activateByName(name);
+    },
+
+    extensionContext(opts) {
+      const ctx = {
+        bus,
+        instanceId,
+        quit: opts.quit,
+        define: (name: string, fn: (...args: any[]) => any) => handlers.define(name, fn),
+        advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => handlers.advise(name, wrapper),
+        call: (name: string, ...args: any[]) => handlers.call(name, ...args),
+        list: () => handlers.list(),
+        onDispose: () => {},
+        getExtensionSettings: settingsMod.getExtensionSettings,
+        getStoragePath: (namespace: string) => {
+          const dir = path.join(CONFIG_DIR, namespace);
+          fs.mkdirSync(dir, { recursive: true });
+          return dir;
+        },
+        registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) =>
+          bus.emit("command:register", { name, description, handler }),
+        adviseCommand: (name: string, advisor: (next: (args: string) => Promise<void> | void, args: string) => Promise<void> | void) => {
+          const key = name.startsWith("/") ? name : `/${name}`;
+          return handlers.advise(`command:${key}`, advisor as Parameters<typeof handlers.advise>[1]);
+        },
+      } as unknown as ExtensionContext;
+      return ctx;
+    },
+
+    kill() {
+      if (activeBackendName) {
+        backends.get(activeBackendName)?.kill();
+        activeBackendName = null;
+      }
+    },
+  };
+}

package/src/core/settings.ts

@@ -0,0 +1,398 @@
+/**
+ * User settings loaded from ~/.agent-sh/settings.json.
+ *
+ * Settings are loaded once at startup and available synchronously
+ * throughout the app. Unknown keys are preserved on write.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+/** Root config directory. Override via AGENT_SH_HOME for isolated instances
+ *  (testing, multi-agent setups). Path is resolved at module load. */
+export const CONFIG_DIR = process.env.AGENT_SH_HOME
+  ? path.resolve(process.env.AGENT_SH_HOME)
+  : path.join(os.homedir(), ".agent-sh");
+const SETTINGS_PATH = path.join(CONFIG_DIR, "settings.json");
+
+/** Per-model capability overrides. */
+export interface ModelCapabilityConfig {
+  /** Model identifier. */
+  id: string;
+  /** Whether the model supports reasoning/thinking tokens. */
+  reasoning?: boolean;
+  /** Context window size in tokens for this specific model. */
+  contextWindow?: number;
+  /** Max output tokens for this model. */
+  maxTokens?: number;
+  /** Echo reasoning_content back on assistant turns. Required by DeepSeek. */
+  echoReasoning?: boolean;
+  /** Content modalities the model supports (e.g. ["text", "image"]). */
+  modalities?: ("text" | "image")[];
+}
+
+/** Provider profile — a named LLM configuration. */
+export interface ProviderConfig {
+  /** API key (supports $ENV_VAR syntax for runtime expansion). */
+  apiKey?: string;
+  /** Base URL for OpenAI-compatible API. */
+  baseURL?: string;
+  /** Default model to use. Falls back to first entry in models list. */
+  defaultModel?: string;
+  /** Models available for cycling. Plain strings or objects with capabilities. */
+  models?: (string | ModelCapabilityConfig)[];
+  /** Context window size in tokens (e.g. 128000). Used for usage display. */
+  contextWindow?: number;
+  /** Case-insensitive regex sources matched against model id; matches default
+   *  to echoReasoning=true. Per-model echoReasoning still wins. */
+  echoReasoningPatterns?: string[];
+  /** Borrow another registered provider's reasoning request shape by id
+   *  (e.g. "openrouter"). Defaults to OpenAI-compat. */
+  reasoningShape?: string;
+}
+
+export interface Settings {
+  /** Extensions to load (npm packages or file paths). */
+  extensions?: string[];
+  /** Max agent query history entries to keep. */
+  historySize?: number;
+
+  // ── Provider profiles ─────────────────────────────────────
+  /** Named provider configurations. */
+  providers?: Record<string, ProviderConfig>;
+  /** Which provider to use by default. */
+  defaultProvider?: string;
+  /** Preferred agent backend (extension name, e.g. "pi", "claude-code"). */
+  defaultBackend?: string;
+  /** Default thinking/reasoning effort level for new sessions ("off"|"low"|"medium"|"high"). */
+  thinkingLevel?: string;
+
+  // ── Shell output spill ────────────────────────────────────
+  /** Shell output lines before spill-to-tempfile kicks in. */
+  shellTruncateThreshold?: number;
+  /** Lines kept from start of spilled shell output. */
+  shellHeadLines?: number;
+  /** Lines kept from end of spilled shell output. */
+  shellTailLines?: number;
+
+  // ── History ──────────────────────────────────────────────
+  /** Max history file size in bytes (default: 102400 = 100KB). */
+  historyMaxBytes?: number;
+  /** Number of prior history entries to load on startup (default: 50). */
+  historyStartupEntries?: number;
+  /**
+   * Override the history file path. Defaults to `~/.agent-sh/history`.
+   * The `AGENT_SH_HISTORY_FILE` env var takes precedence over this setting.
+   * Use a per-project path to keep sessions isolated (e.g. embedding apps
+   * that boot agent-sh as a library against a specific working tree).
+   */
+  historyFilePath?: string;
+  autoCompact?: boolean;
+  autoCompactThreshold?: number;
+
+  // ── Display ───────────────────────────────────────────────
+  /** Max command output lines shown inline in TUI. */
+  maxCommandOutputLines?: number;
+  /** Max read tool output lines shown inline in TUI (0 = hide). */
+  readOutputMaxLines?: number;
+  /** Max diff lines rendered in the TUI (Infinity = no limit). */
+  diffMaxLines?: number;
+  /** Lines of head content shown when a brand-new file is created. */
+  newFilePreviewLines?: number;
+
+  // ── Agent integration ─────────────────────────────────────
+  /** Tool protocol:
+   *   "api" — all tools sent with full schema.
+   *   "deferred" — extensions dispatched through `use_extension(name, args)` meta-tool.
+   *   "deferred-lookup" — extensions loaded on demand via `load_tool(names[])`; once loaded, callable as first-class tools.
+   *   "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[];
+  /**
+   * Enable the "diagnose" tool — lets the agent evaluate JavaScript
+   * expressions against its own runtime state. Powerful for introspection
+   * (e.g. this.conversation.turns.length) but grants arbitrary code
+   * execution within the agent process. Off by default because the
+   * agent already has unrestricted bash access — this is a convenience,
+   * not a new capability.
+   */
+  diagnose?: boolean;
+
+  // ── Identity & startup ───────────────────────────────────
+  /** Show a startup banner when agent-sh launches. */
+  startupBanner?: boolean;
+  /** Show a subtle agent-sh indicator in the shell prompt. */
+  promptIndicator?: boolean;
+
+  // ── Built-in extensions ──────────────────────────────────
+  /** Names of built-in extensions to disable (e.g. ["command-suggest"]). */
+  disabledBuiltins?: string[];
+
+  /**
+   * Names of user extensions in ~/.agent-sh/extensions/ to skip when
+   * auto-discovering. Match by basename without extension for files
+   * (e.g. "peer-mesh" matches peer-mesh.ts), or by directory name for
+   * directory-style extensions (e.g. "superash" matches superash/index.ts).
+   * Beats having to rename files to .disabled every time.
+   */
+  disabledExtensions?: string[];
+}
+
+const DEFAULTS: Required<Settings> = {
+  extensions: [],
+  historySize: 500,
+  providers: {},
+  defaultProvider: undefined as unknown as string,
+  defaultBackend: "ash",
+  thinkingLevel: undefined as unknown as string,
+  toolMode: "api" as "api" | "deferred" | "deferred-lookup" | "inline",
+  coreTools: [],
+  shellTruncateThreshold: 20,
+  shellHeadLines: 10,
+  shellTailLines: 10,
+  historyMaxBytes: 104857600, // 100MB — history is only accessed via search/expand, never loaded wholesale
+  historyStartupEntries: 100,
+  historyFilePath: undefined as unknown as string,
+  autoCompact: true,
+  autoCompactThreshold: 0.5,
+  maxCommandOutputLines: 3,
+  readOutputMaxLines: 10,
+  diffMaxLines: Infinity,
+  newFilePreviewLines: 5,
+  skillPaths: [],
+  diagnose: false,
+  startupBanner: true,
+  promptIndicator: true,
+  disabledBuiltins: [],
+  disabledExtensions: [],
+};
+
+let cached: Settings | null = null;
+let envOverrides: Partial<Settings> | null = null;
+let sessionOverlay: Partial<Settings> = {};
+
+export type SettingSource = "session" | "env" | "file" | "default";
+
+function parseBoolEnv(raw: string | undefined, key: string): boolean | undefined {
+  if (raw === undefined) return undefined;
+  const v = raw.trim().toLowerCase();
+  if (v === "on" || v === "true" || v === "1") return true;
+  if (v === "off" || v === "false" || v === "0") return false;
+  console.error(`[agent-sh] Warning: ${key}="${raw}" is not a boolean (off|on|true|false|0|1); ignoring.`);
+  return undefined;
+}
+
+function parseUnitFloatEnv(raw: string | undefined, key: string): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    console.error(`[agent-sh] Warning: ${key}="${raw}" is not a number in [0, 1]; ignoring.`);
+    return undefined;
+  }
+  return n;
+}
+
+function loadEnvOverrides(): Partial<Settings> {
+  if (envOverrides) return envOverrides;
+  const out: Partial<Settings> = {};
+  const ac = parseBoolEnv(process.env.AGENT_SH_AUTO_COMPACT, "AGENT_SH_AUTO_COMPACT");
+  if (ac !== undefined) out.autoCompact = ac;
+  const th = parseUnitFloatEnv(process.env.AGENT_SH_AUTO_COMPACT_THRESHOLD, "AGENT_SH_AUTO_COMPACT_THRESHOLD");
+  if (th !== undefined) out.autoCompactThreshold = th;
+  envOverrides = out;
+  return envOverrides;
+}
+
+/** Load settings from disk (cached after first call). */
+export function getSettings(): Settings & typeof DEFAULTS {
+  if (!cached) {
+    try {
+      const raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+      cached = JSON.parse(raw) as Settings;
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        console.error(`[agent-sh] Warning: invalid JSON in ${SETTINGS_PATH}: ${err.message}`);
+      }
+      cached = {};
+    }
+  }
+  return { ...DEFAULTS, ...cached, ...loadEnvOverrides(), ...sessionOverlay };
+}
+
+export function setSessionOverlay(patch: Partial<Settings>): void {
+  sessionOverlay = { ...sessionOverlay, ...patch };
+}
+
+export function clearSessionOverlay(...keys: (keyof Settings)[]): void {
+  if (keys.length === 0) {
+    sessionOverlay = {};
+    return;
+  }
+  const next = { ...sessionOverlay };
+  for (const k of keys) delete next[k];
+  sessionOverlay = next;
+}
+
+export function getSettingSource(key: keyof Settings): SettingSource {
+  if (key in sessionOverlay) return "session";
+  if (key in loadEnvOverrides()) return "env";
+  if (cached && key in cached) return "file";
+  return "default";
+}
+
+/**
+ * Get settings for an extension, namespaced under its key in settings.json.
+ *
+ * Example settings.json:
+ *   { "latex-images": { "dpi": 600, "fgColor": "ffffff" } }
+ *
+ * Usage in extension:
+ *   const config = getExtensionSettings("latex-images", { dpi: 300, fgColor: "d4d4d4" });
+ *   // config.dpi === 600 (overridden), config.fgColor === "ffffff" (overridden)
+ */
+export function getExtensionSettings<T extends Record<string, unknown>>(
+  namespace: string,
+  defaults: T,
+): T {
+  const all = getSettings() as unknown as Record<string, unknown>;
+  const ext = all[namespace];
+  if (ext && typeof ext === "object" && !Array.isArray(ext)) {
+    return { ...defaults, ...(ext as Partial<T>) };
+  }
+  return defaults;
+}
+
+/** Reset cached settings (for testing or after external edit). */
+export function reloadSettings(): void {
+  cached = null;
+  envOverrides = null;
+  sessionOverlay = {};
+}
+
+/**
+ * Deep-merge a patch into ~/.agent-sh/settings.json on disk.
+ *
+ * Reads the raw file (preserving unknown keys), merges the patch, writes back
+ * with 2-space indentation, and clears the cache so subsequent getSettings()
+ * calls see the new values.
+ *
+ * Used by runtime controls (`/model`, `/backend`) that want their selection
+ * to persist as the default across restarts.
+ */
+export function updateSettings(patch: Record<string, unknown>): void {
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+    existing = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    // file missing or unreadable — start fresh
+  }
+
+  const merged = deepMerge(existing, patch);
+
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(SETTINGS_PATH, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+    cached = null;
+  } catch (err) {
+    console.error(`[agent-sh] Warning: failed to update ${SETTINGS_PATH}: ${(err as Error).message}`);
+  }
+}
+
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...target };
+  for (const [key, val] of Object.entries(source)) {
+    const existing = out[key];
+    if (
+      val !== null && typeof val === "object" && !Array.isArray(val) &&
+      existing !== null && typeof existing === "object" && !Array.isArray(existing)
+    ) {
+      out[key] = deepMerge(existing as Record<string, unknown>, val as Record<string, unknown>);
+    } else {
+      out[key] = val;
+    }
+  }
+  return out;
+}
+
+/**
+ * Expand $ENV_VAR references in a string.
+ * Supports $VAR and ${VAR} syntax.
+ */
+export function expandEnvVars(value: string): string {
+  return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, braced, plain) => {
+    const name = braced || plain;
+    return process.env[name] ?? "";
+  });
+}
+
+/** Resolved provider ready for use (env vars expanded, defaults applied). */
+export interface ResolvedProvider {
+  id: string;
+  apiKey?: string;
+  baseURL?: string;
+  defaultModel?: string;
+  models: string[];
+  /** User explicitly listed `models` (locks the catalog to that list). */
+  modelsExplicit: boolean;
+  contextWindow?: number;
+  /** Provider supports the reasoning_effort parameter. Default: true. */
+  supportsReasoningEffort?: boolean;
+  /** Per-model capabilities, keyed by model id. */
+  modelCapabilities?: Map<string, { reasoning?: boolean; contextWindow?: number; maxTokens?: number; echoReasoning?: boolean; modalities?: ("text" | "image")[] }>;
+  /** Borrow another registered provider's reasoning request shape by id. */
+  reasoningShape?: string;
+}
+
+/**
+ * Resolve a provider config by name from settings.
+ * Returns null if provider not found.
+ */
+export function resolveProvider(name: string): ResolvedProvider | null {
+  const settings = getSettings();
+  const provider = settings.providers?.[name];
+  if (!provider) return null;
+
+  const rawModels = provider.models ?? (provider.defaultModel ? [provider.defaultModel] : []);
+  const modelIds: string[] = [];
+  const caps = new Map<string, { reasoning?: boolean; contextWindow?: number; maxTokens?: number; echoReasoning?: boolean; modalities?: ("text" | "image")[] }>();
+  for (const m of rawModels) {
+    if (typeof m === "string") {
+      modelIds.push(m);
+    } else {
+      modelIds.push(m.id);
+      if (m.reasoning !== undefined || m.contextWindow !== undefined || m.maxTokens !== undefined || m.echoReasoning !== undefined || m.modalities !== undefined) {
+        caps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow, maxTokens: m.maxTokens, echoReasoning: m.echoReasoning, modalities: m.modalities });
+      }
+    }
+  }
+
+  const defaultModel = provider.defaultModel ?? modelIds[0];
+
+  return {
+    id: name,
+    apiKey: provider.apiKey ? expandEnvVars(provider.apiKey) : undefined,
+    baseURL: provider.baseURL,
+    defaultModel,
+    models: modelIds.length ? modelIds : (defaultModel ? [defaultModel] : []),
+    modelsExplicit: Array.isArray(provider.models),
+    contextWindow: provider.contextWindow,
+    modelCapabilities: caps.size > 0 ? caps : undefined,
+    reasoningShape: provider.reasoningShape,
+  };
+}
+
+/** Get all configured provider names. */
+export function getProviderNames(): string[] {
+  const settings = getSettings();
+  return Object.keys(settings.providers ?? {});
+}

package/src/core/types.ts

@@ -0,0 +1,61 @@
+import type { EventBus } from "./event-bus.js";
+
+export type { ContentBlock } from "./event-bus.js";
+
+// ── Core extension context ────────────────────────────────────────
+
+/**
+ * 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;
+
+  // ── Named handler registry (Emacs-style advice) ───────────
+  /** 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;
+}
+
+// ── Core config ───────────────────────────────────────────────────
+
+/**
+ * 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/src/extensions/file-autocomplete.ts

@@ -0,0 +1,71 @@
+/**
+ * File autocomplete extension.
+ *
+ * Provides @-triggered file path completion in agent input mode.
+ * Responds to "autocomplete:request" pipe events by listing files
+ * matching the path after the @ trigger.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "../shell/host-types.js";
+
+export default function activate(ctx: ExtensionContext): void {
+  ctx.bus.onPipe("autocomplete:request", (payload) => {
+    const atPos = payload.buffer.lastIndexOf("@");
+    if (atPos < 0 || (atPos > 0 && payload.buffer[atPos - 1] !== " ")) {
+      return payload;
+    }
+    const afterAt = payload.buffer.slice(atPos + 1);
+    if (afterAt.includes(" ") || !/^[a-zA-Z0-9_.\/-]*$/.test(afterAt)) {
+      return payload;
+    }
+
+    const files = listFiles(afterAt, ctx.call("cwd") as string);
+    if (files.length === 0) return payload;
+    return { ...payload, items: [...payload.items, ...files] };
+  });
+}
+
+function listFiles(
+  query: string,
+  cwd: string,
+): { name: string; description: string }[] {
+  const lastSlash = query.lastIndexOf("/");
+  let searchDir: string;
+  let prefix: string;
+  let basePath: string;
+
+  if (lastSlash >= 0) {
+    basePath = query.slice(0, lastSlash + 1);
+    searchDir = path.resolve(cwd, query.slice(0, lastSlash) || ".");
+    prefix = query.slice(lastSlash + 1);
+  } else {
+    basePath = "";
+    searchDir = cwd;
+    prefix = query;
+  }
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(searchDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter(
+      (e) =>
+        !e.name.startsWith(".") &&
+        e.name.toLowerCase().startsWith(prefix.toLowerCase()),
+    )
+    .sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    })
+    .slice(0, 15)
+    .map((e) => ({
+      name: basePath + e.name + (e.isDirectory() ? "/" : ""),
+      description: e.isDirectory() ? "dir" : "",
+    }));
+}