indusagi-coding-agent 0.2.5 → 0.2.9

package/src/boot/contract.ts

@@ -0,0 +1,238 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Boot-layer contract — the FROZEN type surface of Phase 1.
+ *
+ * This module is the single typed seam between the operating-system entry point
+ * (`entry.ts`) and everything that turns a command line into a running coding
+ * agent. It declares *only* shapes — no behavior, no I/O, no literals beyond the
+ * narrow string unions that pin the public modes. Every later boot module
+ * (workspace locator, upgrade registry, stage pipeline, runner registry) is
+ * written against the names declared here, so this file is intentionally small,
+ * append-mostly, and stable.
+ *
+ * Design stance:
+ *   - One immutable {@link BootContext} is threaded through an ordered list of
+ *     {@link Stage} transforms; a stage returns the next context (or the same
+ *     one) and never mutates in place.
+ *   - All branding lives in a single {@link Brand} record and all on-disk paths
+ *     in a single {@link Workspace} object — there are no scattered free getters
+ *     and no string literals duplicated across the codebase.
+ *   - Where the rebuilt framework already owns a concept (the model catalog, the
+ *     user-settings shape), the resolved-resource graph is typed against the
+ *     framework's published types rather than re-declaring them here.
+ *
+ * Framework anchors (all from the `indusagi` package):
+ *   - `ModelRegistry`  ← `indusagi/ai`     — the resolved model catalog.
+ *   - `Settings`       ← `indusagi/shell-app` — the user-tunable config shape.
+ *   - `ThinkingLevel`  ← `indusagi/agent`  — reasoning-effort vocabulary (re-exported
+ *                                            for convenience by boot consumers).
+ */
+import type { ModelRegistry } from "indusagi/ai";
+import type { Settings } from "indusagi/shell-app";
+import type { ThinkingLevel } from "indusagi/agent";
+/** Re-exported framework reasoning vocabulary, surfaced through the boot contract. */
+export type { ThinkingLevel };
+/**
+ * The single source of truth for every branding / identity literal.
+ *
+ * Nothing else in the app hard-codes the product name, the profile directory
+ * name, the bin names, the environment-variable namespace, or the share-viewer
+ * origin. Resolving these once into a frozen record means a rebrand touches one
+ * value, never a grep across the tree.
+ */
+export interface Brand {
+    /** Product name used in banners and `process.title` (e.g. `"indusagi"`). */
+    readonly name: string;
+    /** Display label for human-facing surfaces; defaults to {@link name}. */
+    readonly label: string;
+    /** Profile directory leaf under the user's home (e.g. `".indusagi"`). */
+    readonly profileDirName: string;
+    /** Sub-directory of the profile holding the agent's own state (e.g. `"agent"`). */
+    readonly stateDirName: string;
+    /** The executable names this app installs as (both point at one entry). */
+    readonly binNames: readonly [primary: string, alias: string];
+    /** Environment-variable name prefix shared by all app-scoped vars (e.g. `"INDUSAGI"`). */
+    readonly envPrefix: string;
+    /** Env var overriding the resolved profile directory (e.g. `"INDUSAGI_CODING_AGENT_DIR"`). */
+    readonly envProfileDir: string;
+    /** Env var that, when set, disables transport-noise log filtering (e.g. `"INDUSAGI_DEBUG"`). */
+    readonly envDebug: string;
+    /** Env var overriding the share-viewer origin (e.g. `"INDUSAGI_SHARE_VIEWER_URL"`). */
+    readonly envShareViewer: string;
+    /** Default origin a published transcript links to. */
+    readonly shareViewerUrl: string;
+}
+/**
+ * Every resolved on-disk location the app reads or writes, as one immutable
+ * record rather than a family of free `get*Path()` getters.
+ *
+ * All members are absolute paths already expanded against the user's home and
+ * the active {@link Brand}; consumers join nothing further. A single object also
+ * makes the layout trivially inspectable and swappable in tests.
+ */
+export interface Workspace {
+    /** Root profile directory, e.g. `~/.indusagi/agent`. */
+    readonly profileDir: string;
+    /** Merged-settings file (`settings.json`). */
+    readonly settingsPath: string;
+    /** Consolidated credential store (`auth.json`). */
+    readonly authPath: string;
+    /** Per-cwd transcript directory root (`sessions/`). */
+    readonly sessionsDir: string;
+    /** Custom model-catalog overrides (`models.json`). */
+    readonly modelsPath: string;
+    /** Provisioned native helper binaries (`bin/`, holds fd / rg). */
+    readonly toolsDir: string;
+    /** Alias for the managed-binary directory; equals {@link toolsDir}. */
+    readonly binDir: string;
+    /** User-authored prompt/command templates (`prompts/`). */
+    readonly promptsDir: string;
+    /** User-installed color themes (`themes/`). */
+    readonly themesDir: string;
+    /** Bundled HTML transcript-export template directory. */
+    readonly exportTemplateDir: string;
+    /** Verbose diagnostic log file path. */
+    readonly debugLogPath: string;
+    /** External MCP server configuration (`mcp-servers.json`). */
+    readonly mcpConfigPath: string;
+    /** Memory-feature configuration (`memory.json`). */
+    readonly memoryConfigPath: string;
+    /** Composio-integration configuration (`composio.json`). */
+    readonly composioConfigPath: string;
+    /** On-disk memory database (`memory.db`). */
+    readonly memoryDbPath: string;
+}
+/**
+ * The three top-level execution modes the boot layer can dispatch to.
+ *
+ *   - `repl`    — interactive terminal session.
+ *   - `oneshot` — single non-interactive request to stdout (text or JSON).
+ *   - `link`    — headless JSON-RPC link for a driving parent process.
+ */
+export type RunnerId = "repl" | "oneshot" | "link";
+/**
+ * The parsed command line, reduced to what the boot layer needs to choose and
+ * configure a {@link Runner}. This is the minimal Phase-1 shape; Phase 10 enriches
+ * it with the full declarative flag surface. Raw, un-consumed tokens survive in
+ * {@link rest} and loosely-typed switches in {@link flags} so nothing is lost
+ * before the richer parser lands.
+ */
+export interface Invocation {
+    /** Resolved execution mode. */
+    readonly mode: RunnerId;
+    /** First user message / request text, when supplied positionally or via stdin. */
+    readonly prompt?: string;
+    /** Explicit model selector from the command line, if any (`--model` / `-m`). */
+    readonly modelId?: string;
+    /** Model to fall back to when the bound model is overloaded mid-turn (`--fallback-model`). */
+    readonly fallbackModelId?: string;
+    /** Working directory the run is scoped to; absent means the process cwd (`--cwd`). */
+    readonly cwd?: string;
+    /** Named credential account to authenticate with (`--account`). */
+    readonly account?: string;
+    /** Reasoning effort (`--thinking`): off / minimal / low / medium / high / xhigh. */
+    readonly thinking?: string;
+    /** Replacement system prompt (`--system`); a path is read as a file, else literal text. */
+    readonly system?: string;
+    /** Extra text appended after the system prompt (`--append-system`); path-or-literal. */
+    readonly appendSystem?: string;
+    /** Allow-list of built-in tool names (`--tools`); absent means the full deck. */
+    readonly tools?: readonly string[];
+    /** Disable every built-in tool (`--no-tools`). */
+    readonly noTools?: boolean;
+    /** External MCP endpoint config paths to attach (`--mcp`). */
+    readonly mcp?: readonly string[];
+    /** Open the resume picker before the session starts (`--resume` / `-r`). */
+    readonly resume?: boolean;
+    /** Auto-resume the most recent session in the cwd (`--continue` / `-c`). */
+    readonly continueLatest?: boolean;
+    /** Print the model catalog and exit (`--list-models`). */
+    readonly listModels?: boolean;
+    /** Optional substring filter for `--list-models`. */
+    readonly listModelsFilter?: string;
+    /** Parsed switches, keyed by canonical flag name (values intentionally loose). */
+    readonly flags: Record<string, unknown>;
+    /** Positional / pass-through tokens not consumed as flags. */
+    readonly rest: string[];
+}
+/**
+ * Placeholder for the resolved per-account credential graph.
+ *
+ * The rebuilt framework publishes no credential type, so the boot contract owns
+ * an opaque, forward-declared shape here; Phase 2 replaces it with the concrete
+ * multi-account credential vault. Kept deliberately structural (an indexable
+ * bag) so a stage may attach it without the vault module existing yet.
+ */
+export interface CredentialGraph {
+    readonly [account: string]: unknown;
+}
+/**
+ * The resolved settings / auth / model-registry graph assembled during startup.
+ *
+ * This is a Phase-1 placeholder: the fields are typed against the framework's
+ * own published types where one exists ({@link Settings}, {@link ModelRegistry}),
+ * and against an app-local placeholder ({@link CredentialGraph}) where the
+ * framework does not yet own the concept. Later phases attach the loaded
+ * extension/MCP graph onto the same object without changing these anchors.
+ */
+export interface StartupResources {
+    /** Merged user settings (framework-owned shape). */
+    readonly settings: Settings;
+    /** Resolved credentials per account (app-owned placeholder until Phase 2). */
+    readonly auth: CredentialGraph;
+    /** The resolved model catalog (framework-owned registry). */
+    readonly models: ModelRegistry;
+}
+/**
+ * The immutable value threaded through the {@link Stage} pipeline.
+ *
+ * Each stage receives a context and returns the next one; treat every field as
+ * read-only and produce successors by spreading rather than mutating. The
+ * resolved-resource graph is optional because early stages run before it exists.
+ * {@link closables} accumulates teardown callbacks (open files, servers, MCP
+ * clients) that the entry point drains in reverse on exit.
+ */
+export interface BootContext {
+    /** The process arguments the launch was invoked with (already sliced). */
+    readonly argv: string[];
+    /** Resolved on-disk layout. */
+    readonly workspace: Workspace;
+    /** Resolved identity literals. */
+    readonly brand: Brand;
+    /** Parsed command line. */
+    readonly invocation: Invocation;
+    /** Resolved settings/auth/model graph; absent until the resource stage runs. */
+    readonly resources?: StartupResources;
+    /** Teardown callbacks to drain on shutdown (latest-registered first). */
+    readonly closables: Array<() => Promise<void>>;
+}
+/**
+ * One step of the launch pipeline: a named, pure-ish transform over a context
+ * value of type `C` (defaulting to {@link BootContext}).
+ *
+ * A stage may return its result synchronously or asynchronously. It must not
+ * mutate its input; it returns the next context. The `name` is used for tracing
+ * and error attribution when a stage throws.
+ */
+export interface Stage<C = BootContext> {
+    /** Stable identifier for tracing and error messages. */
+    readonly name: string;
+    /** Transform the context, yielding its successor. */
+    apply(ctx: C): Promise<C> | C;
+}
+/**
+ * A terminal execution strategy for one {@link RunnerId} mode.
+ *
+ * The runner registry asks each runner whether it {@link accepts} a parsed
+ * {@link Invocation}; the first match runs. {@link run} drives the selected mode
+ * to completion and resolves to the process exit code.
+ */
+export interface Runner {
+    /** The mode this runner serves. */
+    readonly id: RunnerId;
+    /** Whether this runner handles the given invocation. */
+    accepts(inv: Invocation): boolean;
+    /** Execute the mode; resolves to the process exit code. */
+    run(ctx: BootContext): Promise<number>;
+}

package/src/boot/heap.ts

@@ -0,0 +1,59 @@
+/**
+ * Heap headroom guard.
+ *
+ * Node's default old-space cap (~2 GB on 64-bit builds) is too small for heavy
+ * runs — most acutely a burst of parallel sub-agents whose combined transcripts
+ * push the resident heap past the default and abort the whole process with a V8
+ * "JavaScript heap out of memory" fatal (the exact crash this guards against).
+ *
+ * `--max-old-space-size` can only be set at process launch, so before any real
+ * work begins we re-exec the *same* program once with a raised cap, inherit its
+ * stdio (so the interactive TUI runs unchanged in the child), and adopt its exit
+ * code. The re-exec is one level deep: the child carries `INDUS_HEAP_BOOSTED=1`
+ * so it skips the guard and runs the agent directly.
+ *
+ * Controlled by env:
+ *   INDUS_MAX_HEAP_MB   target old-space size in MB (default 4096; 0 disables
+ *                       the guard entirely and runs in-process).
+ *   INDUS_HEAP_BOOSTED  set internally on the child; never set this yourself.
+ *
+ * If the re-exec cannot spawn (a locked-down sandbox, a missing argv[1]) the
+ * guard silently falls back to running in the current, un-boosted process rather
+ * than failing to start.
+ */
+import { spawnSync } from "node:child_process";
+import { argv, env, execArgv, execPath, exit } from "node:process";
+
+function targetHeapMb(): number {
+  const raw = parseInt(env.INDUS_MAX_HEAP_MB ?? "", 10);
+  if (Number.isFinite(raw)) return Math.max(0, raw);
+  return 4096;
+}
+
+function alreadyRaised(): boolean {
+  return env.INDUS_HEAP_BOOSTED === "1" || (env.NODE_OPTIONS ?? "").includes("--max-old-space-size") || execArgv.some(
+    (a) => a.startsWith("--max-old-space-size") || a.startsWith("--max_old_space_size"),
+  );
+}
+
+/**
+ * Ensure the process has heap headroom, re-execing once if it does not.
+ *
+ * Returns normally in three cases: the guard is disabled, the cap is already
+ * raised, or the re-exec could not be spawned. Otherwise it does NOT return —
+ * it runs the boosted child to completion and exits with the child's status.
+ */
+export function ensureHeapHeadroom(): void {
+  const mb = targetHeapMb();
+  if (mb === 0 || alreadyRaised()) return;
+  const entry = argv[1];
+  if (!entry) return;
+  const result = spawnSync(
+    execPath,
+    [`--max-old-space-size=${mb}`, ...execArgv, entry, ...argv.slice(2)],
+    { stdio: "inherit", env: { ...env, INDUS_HEAP_BOOSTED: "1" } },
+  );
+  if (result.error) return;
+  if (typeof result.status === "number") exit(result.status);
+  exit(result.signal ? 1 : 0);
+}

package/src/boot/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Boot subsystem — public barrel.
+ *
+ * Re-exports the frozen Phase-1 contract type surface plus the assembled boot
+ * layer: the orchestrator ({@link boot}), the stage pipeline
+ * ({@link runStages} / {@link STAGES}), the invocation parser
+ * ({@link tokenizeInvocation}), the runner registry ({@link selectRunner} /
+ * {@link RUNNERS}), and the upgrade driver ({@link applyUpgrades}). Consumers
+ * import the boot type surface and behavior from `src/boot` rather than reaching
+ * into individual modules.
+ */
+export type { Brand, Workspace, Invocation, RunnerId, BootContext, Stage, Runner, StartupResources, CredentialGraph, ThinkingLevel, } from "./contract.js";
+export { boot } from "./boot.js";
+export { runStages, STAGES, locateWorkspace, upgrade, buildInvocation, resolveResources, selectRunnerStage, } from "./stages.js";
+export { tokenizeInvocation, wantsHelp, wantsVersion, } from "./invocation.js";
+export { replRunner, oneshotRunner, linkRunner, RUNNERS, selectRunner } from "./runners/registry.js";
+export { createAuthVault } from "./auth-vault.js";
+export { ensureHeapHeadroom } from "./heap.js";
+export { serverMode } from "./runners/server-mode.js";
+export { delegateRunner } from "./runners/delegate-runner.js";
+export { buildOverlayServices, applyResume } from "./runners/repl-runner.js";
+export { buildAddonHost, wrapToolsWithAddons, concatAddonTools } from "./runners/addon-wiring.js";
+export { memoryDirFor, DiskMemoryStore } from "./runners/memdir.js";
+export type { Upgrade, UpgradeReport } from "./upgrade/index.js";
+export { applyUpgrades, UPGRADES } from "./upgrade/index.js";
+export { BRAND, VERSION } from "../workspace/brand.js";
+export { createWorkspace, ensureDirs } from "../workspace/locator.js";
+export type { WorkspaceOverrides } from "../workspace/locator.js";

package/src/boot/invocation.ts

@@ -0,0 +1,93 @@
+/**
+ * Invocation reader for the boot layer — the adapter that drives the full
+ * Phase-10 declarative flag grammar and projects its rich result down onto the
+ * thin boot {@link Invocation} the runner pipeline routes on.
+ *
+ * The parsing itself is no longer owned here. {@link readInvocation} (from the
+ * `launch/` subsystem) walks the single declarative flag table and produces the
+ * full {@link LaunchInvocation}; this module's job is purely the *projection*:
+ * map the launch {@link OutputMode} onto the boot {@link RunnerId}, rename the
+ * resolved fields the boot layer reads (`model` → `modelId`, `positionals` →
+ * `rest`), and widen the typed flag bag back to the loose
+ * `Record<string, unknown>` the boot {@link Invocation} carries. The result is
+ * type-compatible with the rest of the boot pipeline, so the runner registry and
+ * the session helpers consume it unchanged.
+ *
+ *   - mode: `text` → `repl`, `json` → `oneshot`, `rpc` → `link`.
+ *   - the full flag bag survives on {@link Invocation.flags} so the meta checks
+ *     (`--help` / `--version`) and the oneshot output-shape probe (`json`) keep
+ *     reading the same canonical keys they always did.
+ *
+ * The parse is total and never throws: the launch reader tolerates unknown
+ * `--flags` as boolean switches in the flag bag rather than rejecting them, so
+ * nothing is silently dropped before a later phase can reinterpret it.
+ */
+import { readInvocation } from "../launch/index.js";
+import type { Invocation } from "./contract.js";
+
+function toRunnerId(mode: string): Invocation["mode"] {
+  switch (mode) {
+    case "rpc":
+      return "link";
+    case "json":
+      return "oneshot";
+    case "text":
+    default:
+      return "repl";
+  }
+}
+
+function projectInvocation(launch: ReturnType<typeof readInvocation>): Invocation {
+  const listModelsRaw = launch.flags["list-models"];
+  const listModels = listModelsRaw !== undefined && listModelsRaw !== false;
+  const listModelsFilter = typeof listModelsRaw === "string" && listModelsRaw.length > 0 ? listModelsRaw : undefined;
+  return {
+    mode: toRunnerId(launch.mode),
+    ...launch.prompt !== undefined ? { prompt: launch.prompt } : {},
+    ...launch.model !== undefined ? { modelId: launch.model } : {},
+    ...launch.fallbackModel !== undefined ? { fallbackModelId: launch.fallbackModel } : {},
+    ...launch.cwd !== undefined ? { cwd: launch.cwd } : {},
+    ...launch.account !== undefined ? { account: launch.account } : {},
+    ...launch.thinking !== undefined ? { thinking: launch.thinking } : {},
+    ...launch.system !== undefined ? { system: launch.system } : {},
+    ...launch.appendSystem !== undefined ? { appendSystem: launch.appendSystem } : {},
+    ...launch.tools !== undefined ? { tools: launch.tools } : {},
+    ...launch.noTools ? { noTools: true } : {},
+    ...launch.mcp.length > 0 ? { mcp: launch.mcp } : {},
+    ...launch.zohoUrl !== undefined && launch.zohoUrl !== "" ? { zohoUrl: launch.zohoUrl } : {},
+    ...launch.noZoho ? { noZoho: true } : {},
+    ...launch.sarvamKey !== undefined && launch.sarvamKey !== "" ? { sarvamKey: launch.sarvamKey } : {},
+    ...launch.noSarvam ? { noSarvam: true } : {},
+    ...launch.sarvamBasePath !== undefined && launch.sarvamBasePath !== "" ? { sarvamBasePath: launch.sarvamBasePath } : {},
+    ...launch.flags["resume"] === true ? { resume: true } : {},
+    ...launch.flags["continue"] === true ? { continueLatest: true } : {},
+    ...listModels ? { listModels: true } : {},
+    ...listModelsFilter !== undefined ? { listModelsFilter } : {},
+    flags: launch.flags,
+    rest: launch.positionals,
+  };
+}
+
+/**
+ * Read a sliced `process.argv` into the boot {@link Invocation}.
+ *
+ * Delegates the actual grammar to the launch {@link readInvocation} (the one
+ * declarative flag table), then projects its result onto the boot shape. The
+ * boot layer thus shares one parser with the launch subsystem — help, parsing,
+ * and routing can no longer drift.
+ *
+ * @param argv The already-sliced argument vector (no node/exec path).
+ */
+export function tokenizeInvocation(argv: readonly string[]): Invocation {
+  return projectInvocation(readInvocation(argv));
+}
+
+/** Whether the parsed invocation is asking for the help banner. */
+export function wantsHelp(inv: Invocation): boolean {
+  return inv.flags.help === true;
+}
+
+/** Whether the parsed invocation is asking for the version string. */
+export function wantsVersion(inv: Invocation): boolean {
+  return inv.flags.version === true;
+}

package/src/boot/runners/addon-wiring.ts

@@ -0,0 +1,153 @@
+/**
+ * Boot helper: activate the addon host for a session and fold its tool
+ * interceptors around the deck.
+ *
+ * The {@link createAddonHost addon host} is the product's extension mechanism —
+ * locally-authored modules under `<cwd>/.indus/addons` that graft tools, slash
+ * commands, lifecycle observers, and tool-boundary interceptors onto a running
+ * session. The host itself is fully built and tested, but until this module it
+ * was never *instantiated* outside its own unit tests: nothing in the boot path
+ * discovered, loaded, or wired addons.
+ *
+ * This module closes that gap with two narrow seams the runners call once at
+ * session-assembly time:
+ *
+ *   1. {@link buildAddonHost} — construct a host, swallow its fault stream (a
+ *      broken addon must never sink the session), and {@link AddonHost.loadAll
+ *      load} every addon discovered under the run's `.indus/addons` directory.
+ *      With no such directory the returned {@link AddonSurfaceBundle} is empty —
+ *      no interceptors, no contributed tools — so wiring it is a perfect no-op.
+ *   2. {@link wrapToolsWithAddons} — fold the bundle's
+ *      {@link InterceptorChain} around every tool whose name a stage matches,
+ *      leaving the rest identity-equal. A wrapped tool runs the chain's
+ *      `enter` → real `execute` → `exit` reduce; an `enter` block short-circuits
+ *      to an `isError` result without ever invoking the real tool.
+ *
+ * Scope (v1): only the per-tool interceptor boundary is wired. The richer
+ * lifecycle-event fan-out (`session:start`, `turn:end`, …) needs a conductor
+ * seam that does not exist yet and is deferred. The tool interceptor boundary is
+ * the load-bearing one — it is where the Wave 4 permission gate later registers
+ * as a built-in interceptor rather than a parallel mechanism.
+ */
+import {
+  type AddonSurfaceBundle,
+  type AgentTool,
+  type InterceptorChain,
+  createAddonHost,
+} from "../../addons/index.js";
+import type { BootContext } from "../contract.js";
+
+/**
+ * Build and populate the addon host for a run, returning its wired
+ * {@link AddonSurfaceBundle}.
+ *
+ * Constructs a host with an empty {@link FrameworkHandles} bag (v1 supplies no
+ * `exec` handle — the runner has no shell-exec callback to hand an addon — and
+ * the rest are interactive-only), installs a swallow-everything fault sink so a
+ * broken addon degrades silently instead of crashing the boot, then discovers
+ * and loads every addon under `<cwd>/.indus/addons` (the contract's default
+ * {@link ADDONS_DIR}). With no addons directory the bundle is empty and wiring it
+ * downstream is a no-op.
+ *
+ * @param ctx the boot context whose invocation carries the run cwd
+ * @returns the wired bundle (dispatch, interceptors, contributed commands/tools)
+ */
+export async function buildAddonHost(ctx: BootContext): Promise<AddonSurfaceBundle> {
+  const host = createAddonHost({ handles: {} });
+  host.onFault(() => {
+    // swallow addon load faults so a broken addon cannot sink the session
+  });
+  return host.loadAll({ workspace: ctx.invocation.cwd ?? process.cwd() });
+}
+
+/**
+ * Fold a bundle's {@link InterceptorChain} around every tool a stage matches.
+ *
+ * Each tool whose `name` the chain matches is replaced with a wrapper that runs
+ * the chain around its real `execute`; every other tool is returned *identical*
+ * (same object reference) so an empty bundle leaves the deck untouched. The
+ * contributed `bundle.tools` are NOT appended here — the caller concatenates
+ * them (de-duped against the existing deck) before wrapping, so addon tools are
+ * themselves subject to interception.
+ *
+ * @param tools  the run's tool deck (deck + MCP + already-concatenated addon tools)
+ * @param bundle the loaded addon bundle whose interceptor chain wraps the deck
+ * @returns a new array: matched tools wrapped, unmatched tools identity-equal
+ */
+export function wrapToolsWithAddons(tools: AgentTool[], bundle: AddonSurfaceBundle): AgentTool[] {
+  const chain = bundle.interceptors;
+  return tools.map(
+    (tool) => chain.matches(tool.name) ? wrapOne(tool, chain) : tool,
+  );
+}
+
+/**
+ * Wrap one tool so its `execute` runs through the interceptor chain.
+ *
+ * The wrapper spreads the original tool (preserving `name` / `description` /
+ * `parameters` / `label` and any extra fields) and overrides only `execute`. The
+ * override:
+ *
+ *   - closes over the live `toolCallId`, `signal`, and `onUpdate` so streaming
+ *     updates and cancellation still reach the real tool (the chain only threads
+ *     the decoded `args`, so these must be captured here);
+ *   - hands the chain a `(args) => realExecute(args)` closure as the inner
+ *     execution and runs `chain.run({ tool, callId, args }, …)`;
+ *   - maps the resulting {@link InterceptResult} back to an
+ *     {@link AgentToolResult}: a `blocked` enter short-circuits to an `isError`
+ *     result carrying the gate's `reason` (the real tool never ran); otherwise
+ *     the chain's (possibly exit-rewritten) `result` is returned.
+ *
+ * The chain — not this wrapper — owns fault isolation and the throw-on-no-recover
+ * semantics, so a tool error that no exit stage recovers propagates exactly as it
+ * would unwrapped.
+ *
+ * @param tool  the real tool to fold the chain around
+ * @param chain the interceptor chain matching this tool's name
+ */
+export function wrapOne(tool: AgentTool, chain: InterceptorChain): AgentTool {
+  const realExecute = tool.execute.bind(tool);
+  return {
+    ...tool,
+    async execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: unknown) {
+      const args = params ?? {};
+      const outcome = await chain.run(
+        { tool: tool.name, callId: toolCallId, args: args as Record<string, unknown> },
+        (next) => realExecute(toolCallId, next, signal as never, onUpdate as never),
+      );
+      if (outcome.blocked !== undefined) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: outcome.blocked.reason ?? "Blocked by an addon.",
+            },
+          ],
+          details: undefined,
+          isError: true,
+        };
+      }
+      return outcome.result ?? { content: [], details: undefined };
+    },
+  };
+}
+
+/**
+ * Concatenate an addon bundle's contributed tools onto an existing deck, dropping
+ * any whose name a deck tool already claims.
+ *
+ * The host de-dupes its OWN tools against each other, but not against the product
+ * deck or MCP tools — so an addon tool named `read` would otherwise shadow (or
+ * be appended alongside) the core read tool. This filter keeps the first
+ * claimant (the existing deck) and admits only addon tools with a fresh name.
+ *
+ * @param deck   the existing tool deck (deck + MCP)
+ * @param bundle the loaded addon bundle whose `tools` are appended
+ * @returns the deck followed by the non-conflicting addon tools
+ */
+export function concatAddonTools(deck: AgentTool[], bundle: AddonSurfaceBundle): AgentTool[] {
+  if (bundle.tools.length === 0) return deck;
+  const claimed = new Set(deck.map((t) => t.name));
+  const fresh = bundle.tools.filter((t) => !claimed.has(t.name));
+  return fresh.length === 0 ? deck : [...deck, ...fresh];
+}