@executioncontrolprotocol/runtime 0.3.0

package/dist/extensions/registry.js

@@ -0,0 +1,126 @@
+/**
+ * Runtime extension registry for model providers, executors, and plugins.
+ *
+ * @category Extensions
+ */
+/**
+ * In-memory registry of runtime extension factories.
+ *
+ * @category Extensions
+ */
+export class ExtensionRegistry {
+    modelProviders = new Map();
+    executors = new Map();
+    plugins = new Map();
+    progressLoggers = new Map();
+    locked = false;
+    /**
+     * Prevent further registration changes.
+     */
+    lock() {
+        this.locked = true;
+    }
+    /**
+     * Register a model provider extension.
+     */
+    registerModelProvider(registration) {
+        this.assertUnlocked();
+        this.assertNotRegistered(registration.id, "model-provider");
+        this.modelProviders.set(registration.id, registration);
+    }
+    /**
+     * Register an executor extension.
+     */
+    registerExecutor(registration) {
+        this.assertUnlocked();
+        this.assertNotRegistered(registration.id, "executor");
+        this.executors.set(registration.id, registration);
+    }
+    /**
+     * Register a progress logger extension.
+     */
+    registerProgressLogger(registration) {
+        this.assertUnlocked();
+        this.assertNotRegistered(registration.id, "progress-logger");
+        this.progressLoggers.set(registration.id, registration);
+    }
+    /**
+     * Register a plugin extension.
+     */
+    registerPlugin(registration) {
+        this.assertUnlocked();
+        this.assertNotRegistered(registration.id, "plugin");
+        this.plugins.set(registration.id, registration);
+    }
+    /**
+     * Resolve and instantiate a model provider by ID.
+     */
+    createModelProvider(id, config) {
+        const registration = this.modelProviders.get(id);
+        if (!registration) {
+            throw new Error(`Model provider extension "${id}" is not registered.`);
+        }
+        return registration.create(config);
+    }
+    /**
+     * Get a model provider registration by ID.
+     */
+    getModelProviderRegistration(id) {
+        return this.modelProviders.get(id);
+    }
+    /**
+     * List registered model provider extensions.
+     */
+    listModelProviders() {
+        return [...this.modelProviders.values()];
+    }
+    /**
+     * List registered executor extensions.
+     */
+    listExecutors() {
+        return [...this.executors.values()];
+    }
+    /**
+     * List registered plugin extensions.
+     */
+    listPlugins() {
+        return [...this.plugins.values()];
+    }
+    /**
+     * Create a progress logger by ID.
+     */
+    createProgressLogger(id, config) {
+        const registration = this.progressLoggers.get(id);
+        if (!registration) {
+            throw new Error(`Progress logger extension "${id}" is not registered.`);
+        }
+        return registration.create(config);
+    }
+    /**
+     * Get a progress logger registration by ID.
+     */
+    getProgressLoggerRegistration(id) {
+        return this.progressLoggers.get(id);
+    }
+    /**
+     * List registered progress logger extensions.
+     */
+    listProgressLoggers() {
+        return [...this.progressLoggers.values()];
+    }
+    assertUnlocked() {
+        if (this.locked) {
+            throw new Error("Extension registry is locked and cannot be modified.");
+        }
+    }
+    assertNotRegistered(id, kind) {
+        const exists = this.modelProviders.has(id) ||
+            this.executors.has(id) ||
+            this.plugins.has(id) ||
+            this.progressLoggers.has(id);
+        if (exists) {
+            throw new Error(`Extension "${id}" is already registered; duplicate ${kind} registration denied.`);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/extensions/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/extensions/registry.ts"],"names":[],"mappings":"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"}

package/dist/extensions/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared extensibility interfaces for ECP runtime registration.
+ *
+ * @category Extensions
+ */
+import type { ExtensionSourceType } from "@executioncontrolprotocol/spec";
+import type { ModelProvider } from "../providers/model-provider.js";
+import type { ProgressCallback } from "../engine/types.js";
+/**
+ * Base metadata for all runtime extension registrations.
+ *
+ * @category Extensions
+ */
+export interface ExtensionRegistrationBase {
+    /** Stable extension ID (for example `"openai"`). */
+    id: string;
+    /** Extension version string. */
+    version: string;
+    /** Source type used to load this extension. */
+    sourceType: ExtensionSourceType;
+    /** Optional human-readable summary. */
+    description?: string;
+}
+/**
+ * Factory contract for model provider extensions.
+ *
+ * @category Extensions
+ */
+export interface ModelProviderRegistration extends ExtensionRegistrationBase {
+    /** Fixed kind discriminator for model provider extensions. */
+    kind: "model-provider";
+    /**
+     * Create a model provider instance from extension configuration.
+     */
+    create(config?: Record<string, unknown>): ModelProvider;
+}
+/**
+ * Factory contract for executor extensions.
+ *
+ * @category Extensions
+ */
+export interface ExecutorRegistration extends ExtensionRegistrationBase {
+    /** Fixed kind discriminator for executor extensions. */
+    kind: "executor";
+    /**
+     * Create an executor extension instance from extension configuration.
+     */
+    create(config?: Record<string, unknown>): unknown;
+}
+/**
+ * Factory contract for plugin extensions.
+ *
+ * @category Extensions
+ */
+export interface PluginRegistration extends ExtensionRegistrationBase {
+    /** Fixed kind discriminator for plugin extensions. */
+    kind: "plugin";
+    /**
+     * Create a plugin extension instance from extension configuration.
+     */
+    create(config?: Record<string, unknown>): unknown;
+}
+/**
+ * Factory contract for progress logger extensions.
+ * Progress loggers receive execution progress events (phase, steps, reasoning).
+ *
+ * @category Extensions
+ */
+export interface ProgressLoggerRegistration extends ExtensionRegistrationBase {
+    /** Fixed kind discriminator for progress logger extensions. */
+    kind: "progress-logger";
+    /**
+     * Create a progress logger callback from extension configuration.
+     * The callback will be invoked for each progress event during a run.
+     */
+    create(config?: Record<string, unknown>): ProgressCallback;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IAEX,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,UAAU,EAAE,mBAAmB,CAAC;IAEhC,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,yBAAyB;IAC1E,8DAA8D;IAC9D,IAAI,EAAE,gBAAgB,CAAC;IAEvB;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,yBAAyB;IACrE,wDAAwD;IACxD,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,yBAAyB;IACnE,sDAAsD;IACtD,IAAI,EAAE,QAAQ,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,+DAA+D;IAC/D,IAAI,EAAE,iBAAiB,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAAC;CAC5D"}

package/dist/extensions/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared extensibility interfaces for ECP runtime registration.
+ *
+ * @category Extensions
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/extensions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/extensions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./engine/index.js";
+export * from "./providers/index.js";
+export * from "./extensions/index.js";
+export * from "./protocols/index.js";
+export * from "./mounts/index.js";
+export * from "./policies/index.js";
+export * from "./testing/index.js";
+export * from "./evals/index.js";
+export * from "./tracing/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./engine/index.js";
+export * from "./providers/index.js";
+export * from "./extensions/index.js";
+export * from "./protocols/index.js";
+export * from "./mounts/index.js";
+export * from "./policies/index.js";
+export * from "./testing/index.js";
+export * from "./evals/index.js";
+export * from "./tracing/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/mounts/hydrator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Mount hydration service.
+ *
+ * Evaluates mounts by calling tool servers via the {@link ToolInvoker},
+ * respecting stage ordering, limits, and selectors.
+ *
+ * @category Mounts
+ */
+import type { Mount, MountStage } from "@executioncontrolprotocol/spec";
+import type { ToolInvoker } from "../protocols/tool-invoker.js";
+import type { MountOutput, ResolvedInputs } from "../engine/types.js";
+import type { SelectorResult } from "./types.js";
+/**
+ * Resolve the selected IDs from a plan output for focus/deep mount expansion.
+ *
+ * @param selectorPath - Dot-path into the plan output (e.g. `"plan.selectedIssueIds"`).
+ * @param planOutput - The orchestrator's plan output.
+ * @param maxSelected - Maximum items to select.
+ * @returns The resolved selector result.
+ *
+ * @category Mounts
+ */
+export declare function resolveSelector(selectorPath: string, planOutput: Record<string, unknown>, maxSelected?: number): SelectorResult;
+/**
+ * Default mount hydrator backed by a {@link ToolInvoker}.
+ *
+ * @category Mounts
+ */
+export declare class DefaultMountHydrator {
+    private readonly toolInvoker;
+    constructor(toolInvoker: ToolInvoker);
+    /**
+     * Hydrate a set of mounts for a specific stage.
+     *
+     * @param mounts - The mount definitions to hydrate.
+     * @param stage - The stage to hydrate (`"seed"`, `"focus"`, or `"deep"`).
+     * @param inputs - Resolved Context inputs for interpolation.
+     * @param planOutput - The orchestrator's plan output (for focus/deep selectors).
+     * @returns Hydrated mount outputs.
+     */
+    hydrateStage(mounts: Mount[], stage: MountStage, inputs: ResolvedInputs, planOutput?: Record<string, unknown>): Promise<MountOutput[]>;
+    private hydrateMount;
+    private hydrateFocusDeepMount;
+    private enforceLimit;
+}
+//# sourceMappingURL=hydrator.d.ts.map

package/dist/mounts/hydrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrator.d.ts","sourceRoot":"","sources":["../../src/mounts/hydrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,YAAY,CAAC;AAGvE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,CAAC,EAAE,MAAM,GACnB,cAAc,CAwBhB;AAED;;;;GAIG;AACH,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,WAAW;IAG3C;;;;;;;;OAQG;IACG,YAAY,CAChB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,cAAc,EACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,OAAO,CAAC,WAAW,EAAE,CAAC;YAYX,YAAY;YAiDZ,qBAAqB;IAmDnC,OAAO,CAAC,YAAY;CAIrB"}

package/dist/mounts/hydrator.js

@@ -0,0 +1,142 @@
+/**
+ * Mount hydration service.
+ *
+ * Evaluates mounts by calling tool servers via the {@link ToolInvoker},
+ * respecting stage ordering, limits, and selectors.
+ *
+ * @category Mounts
+ */
+import { interpolateArgs } from "./interpolation.js";
+/**
+ * Resolve the selected IDs from a plan output for focus/deep mount expansion.
+ *
+ * @param selectorPath - Dot-path into the plan output (e.g. `"plan.selectedIssueIds"`).
+ * @param planOutput - The orchestrator's plan output.
+ * @param maxSelected - Maximum items to select.
+ * @returns The resolved selector result.
+ *
+ * @category Mounts
+ */
+export function resolveSelector(selectorPath, planOutput, maxSelected) {
+    const parts = selectorPath.split(".");
+    let current = planOutput;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return { ids: [], wasCapped: false, originalCount: 0 };
+        }
+        current = current[part];
+    }
+    if (!Array.isArray(current)) {
+        return { ids: [], wasCapped: false, originalCount: 0 };
+    }
+    const allIds = current.map(String);
+    const max = maxSelected ?? allIds.length;
+    const capped = allIds.length > max;
+    return {
+        ids: allIds.slice(0, max),
+        wasCapped: capped,
+        originalCount: allIds.length,
+    };
+}
+/**
+ * Default mount hydrator backed by a {@link ToolInvoker}.
+ *
+ * @category Mounts
+ */
+export class DefaultMountHydrator {
+    toolInvoker;
+    constructor(toolInvoker) {
+        this.toolInvoker = toolInvoker;
+    }
+    /**
+     * Hydrate a set of mounts for a specific stage.
+     *
+     * @param mounts - The mount definitions to hydrate.
+     * @param stage - The stage to hydrate (`"seed"`, `"focus"`, or `"deep"`).
+     * @param inputs - Resolved Context inputs for interpolation.
+     * @param planOutput - The orchestrator's plan output (for focus/deep selectors).
+     * @returns Hydrated mount outputs.
+     */
+    async hydrateStage(mounts, stage, inputs, planOutput) {
+        const stageMounts = mounts.filter((m) => m.stage === stage);
+        const results = [];
+        for (const mount of stageMounts) {
+            const output = await this.hydrateMount(mount, inputs, planOutput);
+            results.push(output);
+        }
+        return results;
+    }
+    async hydrateMount(mount, inputs, planOutput) {
+        const { from } = mount;
+        if (mount.when?.selectorFrom && planOutput) {
+            return this.hydrateFocusDeepMount(mount, inputs, planOutput);
+        }
+        const ctx = { inputs };
+        const args = from.args ? interpolateArgs(from.args, ctx) : {};
+        try {
+            const result = await this.toolInvoker.callTool(from.server, from.tool, args);
+            if (result.isError) {
+                return {
+                    mountName: mount.name,
+                    stage: mount.stage,
+                    data: [],
+                    itemCount: 0,
+                };
+            }
+            const data = this.enforceLimit(result.content, mount.limits?.maxItems);
+            const itemCount = Array.isArray(data) ? data.length : 1;
+            return {
+                mountName: mount.name,
+                stage: mount.stage,
+                data,
+                itemCount,
+            };
+        }
+        catch {
+            return {
+                mountName: mount.name,
+                stage: mount.stage,
+                data: [],
+                itemCount: 0,
+            };
+        }
+    }
+    async hydrateFocusDeepMount(mount, inputs, planOutput) {
+        const selector = resolveSelector(mount.when.selectorFrom, planOutput, mount.when.maxSelected);
+        if (selector.ids.length === 0) {
+            return {
+                mountName: mount.name,
+                stage: mount.stage,
+                data: [],
+                itemCount: 0,
+            };
+        }
+        const allItems = [];
+        for (const id of selector.ids) {
+            const ctx = { inputs, item: id };
+            const args = mount.from.args ? interpolateArgs(mount.from.args, ctx) : {};
+            try {
+                const result = await this.toolInvoker.callTool(mount.from.server, mount.from.tool, args);
+                if (!result.isError) {
+                    allItems.push(result.content);
+                }
+            }
+            catch {
+                // skip failed items
+            }
+        }
+        const limited = this.enforceLimit(allItems, mount.limits?.maxItems);
+        return {
+            mountName: mount.name,
+            stage: mount.stage,
+            data: limited,
+            itemCount: limited.length,
+        };
+    }
+    enforceLimit(data, maxItems) {
+        if (!maxItems || !Array.isArray(data))
+            return data;
+        return data.slice(0, maxItems);
+    }
+}
+//# sourceMappingURL=hydrator.js.map

package/dist/mounts/hydrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrator.js","sourceRoot":"","sources":["../../src/mounts/hydrator.ts"],"names":[],"mappings":"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"}

package/dist/mounts/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./interpolation.js";
+export * from "./hydrator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mounts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mounts/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

package/dist/mounts/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./interpolation.js";
+export * from "./hydrator.js";
+//# sourceMappingURL=index.js.map

package/dist/mounts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mounts/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC"}

package/dist/mounts/interpolation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Template interpolation for mount arguments.
+ *
+ * Resolves `${inputs.foo}` and `${item}` expressions in mount arg values.
+ *
+ * @category Mounts
+ */
+import type { InterpolationContext } from "./types.js";
+/**
+ * Interpolate template expressions in a single string value.
+ *
+ * Supported expressions:
+ * - `${inputs.<name>}` — resolved from Context inputs
+ * - `${item}` — resolved from the current iteration item (focus/deep mounts)
+ *
+ * @param template - The string potentially containing `${...}` expressions.
+ * @param ctx - The interpolation context.
+ * @returns The interpolated string.
+ *
+ * @category Mounts
+ */
+export declare function interpolateString(template: string, ctx: InterpolationContext): string;
+/**
+ * Deep-interpolate all string values in a mount arguments object.
+ *
+ * @param args - The raw args from the mount definition.
+ * @param ctx - The interpolation context.
+ * @returns A new object with all string values interpolated.
+ *
+ * @category Mounts
+ */
+export declare function interpolateArgs(args: Record<string, unknown>, ctx: InterpolationContext): Record<string, unknown>;
+//# sourceMappingURL=interpolation.d.ts.map

package/dist/mounts/interpolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.d.ts","sourceRoot":"","sources":["../../src/mounts/interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,oBAAoB,GACxB,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,oBAAoB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB"}

package/dist/mounts/interpolation.js

@@ -0,0 +1,59 @@
+/**
+ * Template interpolation for mount arguments.
+ *
+ * Resolves `${inputs.foo}` and `${item}` expressions in mount arg values.
+ *
+ * @category Mounts
+ */
+/**
+ * Interpolate template expressions in a single string value.
+ *
+ * Supported expressions:
+ * - `${inputs.<name>}` — resolved from Context inputs
+ * - `${item}` — resolved from the current iteration item (focus/deep mounts)
+ *
+ * @param template - The string potentially containing `${...}` expressions.
+ * @param ctx - The interpolation context.
+ * @returns The interpolated string.
+ *
+ * @category Mounts
+ */
+export function interpolateString(template, ctx) {
+    return template.replace(/\$\{([^}]+)\}/g, (_match, expr) => {
+        const trimmed = expr.trim();
+        if (trimmed === "item") {
+            return ctx.item ?? "";
+        }
+        if (trimmed.startsWith("inputs.")) {
+            const inputName = trimmed.slice("inputs.".length);
+            const value = ctx.inputs[inputName];
+            return value !== undefined ? String(value) : "";
+        }
+        return "";
+    });
+}
+/**
+ * Deep-interpolate all string values in a mount arguments object.
+ *
+ * @param args - The raw args from the mount definition.
+ * @param ctx - The interpolation context.
+ * @returns A new object with all string values interpolated.
+ *
+ * @category Mounts
+ */
+export function interpolateArgs(args, ctx) {
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === "string") {
+            result[key] = interpolateString(value, ctx);
+        }
+        else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            result[key] = interpolateArgs(value, ctx);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=interpolation.js.map

package/dist/mounts/interpolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.js","sourceRoot":"","sources":["../../src/mounts/interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,GAAyB;IAEzB,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAE5B,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YACvB,OAAO,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QACxB,CAAC;QAED,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACpC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA6B,EAC7B,GAAyB;IAEzB,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChF,MAAM,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,KAAgC,EAAE,GAAG,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/mounts/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Types for the staged mount hydration system.
+ *
+ * Mounts retrieve data from external tool servers in three stages
+ * (seed → focus → deep) to avoid blowing up the context window.
+ *
+ * @category Mounts
+ */
+import type { Mount } from "@executioncontrolprotocol/spec";
+import type { MountOutput, MountRef, ResolvedInputs } from "../engine/types.js";
+/**
+ * Interpolation context available when resolving mount arguments.
+ *
+ * @category Mounts
+ */
+export interface InterpolationContext {
+    /** Resolved Context inputs. */
+    inputs: ResolvedInputs;
+    /** The current item ID (for focus/deep mounts iterating over selectors). */
+    item?: string;
+}
+/**
+ * A request to hydrate a single mount.
+ *
+ * @category Mounts
+ */
+export interface HydrationRequest {
+    /** The mount definition from the Context. */
+    mount: Mount;
+    /** Values for template interpolation in mount args. */
+    interpolation: InterpolationContext;
+    /**
+     * For focus/deep mounts: the selected item IDs to expand.
+     * Derived from the plan output via `mount.when.selectorFrom`.
+     */
+    selectedIds?: string[];
+}
+/**
+ * Result of selecting items from a plan output for focus/deep expansion.
+ *
+ * @category Mounts
+ */
+export interface SelectorResult {
+    /** The IDs extracted from the plan output. */
+    ids: string[];
+    /** Whether the selection was capped by `maxSelected`. */
+    wasCapped: boolean;
+    /** Original count before capping. */
+    originalCount: number;
+}
+/**
+ * Internal representation of mounted data within the engine.
+ *
+ * @category Mounts
+ */
+export type MountData = {
+    kind: "refs";
+    refs: MountRef[];
+} | {
+    kind: "expanded";
+    items: unknown[];
+} | {
+    kind: "error";
+    error: string;
+};
+/**
+ * Interface for the mount hydration service.
+ *
+ * @category Mounts
+ */
+export interface MountHydrator {
+    /**
+     * Hydrate all mounts for a given stage, respecting limits and selectors.
+     *
+     * @param requests - The mounts to hydrate.
+     * @returns The hydrated mount outputs.
+     */
+    hydrate(requests: HydrationRequest[]): Promise<MountOutput[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mounts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mounts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,MAAM,EAAE,cAAc,CAAC;IAEvB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,KAAK,EAAE,KAAK,CAAC;IAEb,uDAAuD;IACvD,aAAa,EAAE,oBAAoB,CAAC;IAEpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,GAAG,EAAE,MAAM,EAAE,CAAC;IAEd,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IAEnB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC/D"}