@interf/compiler 0.13.0 → 0.16.0

package/dist/packages/engine/agents/lib/detection.d.ts

@@ -0,0 +1,13 @@
+import type { Agent } from "./types.js";
+export declare function detectAgents(): Agent[];
+/**
+ * Whether the executable named in an agent's `command` field resolves on
+ * PATH. Custom agents may register commands like `"opencode --prompt"`,
+ * so we only check the first whitespace-separated token.
+ */
+export declare function agentCommandAvailable(command: string): boolean;
+export declare function supportsAutomatedRuns(agent: Agent): boolean;
+export declare function resolveAgent(): {
+    agent: Agent | null;
+    error?: string;
+};

package/dist/packages/{agents → engine/agents}/lib/detection.js

@@ -19,6 +19,17 @@ function commandExists(command) {
         return false;
     }
 }
+/**
+ * Whether the executable named in an agent's `command` field resolves on
+ * PATH. Custom agents may register commands like `"opencode --prompt"`,
+ * so we only check the first whitespace-separated token.
+ */
+export function agentCommandAvailable(command) {
+    const firstToken = command.trim().split(/\s+/)[0];
+    if (!firstToken)
+        return false;
+    return commandExists(firstToken);
+}
 export function supportsAutomatedRuns(agent) {
     return agent.name === "claude-code" || agent.name === "codex";
 }

package/dist/packages/{agents → engine/agents}/lib/executors.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeExecutorInfo } from "../../contracts/lib/schema.js";
+import type { RuntimeExecutorInfo } from "../../../contracts/lib/schema.js";
 import type { Agent } from "./types.js";
 export type MethodExecutorKind = "local-agent" | "connected-provider" | "managed";
 export interface MethodExecutionProfile {
@@ -21,7 +21,7 @@ export interface MethodExecutor {
     executionProfile?: MethodExecutionProfile;
     execute(rootPath: string, prompt: string, options?: MethodExecuteOptions): Promise<number>;
 }
-export type { RuntimeExecutorInfo } from "../../contracts/lib/schema.js";
+export type { RuntimeExecutorInfo } from "../../../contracts/lib/schema.js";
 export declare function buildRuntimeExecutorInfo(executor: MethodExecutor): RuntimeExecutorInfo;
 export declare function createLocalAgentExecutor(agent: Agent, executionProfile?: MethodExecutionProfile): MethodExecutor;
 export declare function resolveLocalExecutor(options?: {

package/dist/packages/{agents → engine/agents}/lib/shells.d.ts

@@ -1,7 +1,7 @@
-import type { MethodImprovementContext } from "../../compiler/lib/schema.js";
-import type { RuntimeContractType } from "../../contracts/lib/schema.js";
-import type { SourceReadinessCheck } from "../../project-model/lib/schema.js";
-import { type ContextInterfaceZoneId as MethodZoneId } from "../../method-package/context-interface.js";
+import type { MethodImprovementContext } from "../../compile/lib/schema.js";
+import type { RuntimeContractType } from "../../../contracts/lib/schema.js";
+import type { SourceReadinessCheck } from "../../../project/lib/schema.js";
+import { type ContextInterfaceZoneId as MethodZoneId } from "../../../methods/package/context-interface.js";
 export interface NativeStageDefinition {
     id: string;
     label: string;

package/dist/packages/{agents → engine/agents}/lib/shells.js

@@ -2,13 +2,13 @@ import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, re
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, sep as pathSep } from "node:path";
 import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { buildCompiledSourceFiles } from "../../compiler/source-files.js";
-import { METHOD_PACKAGE_DIR } from "../../project-model/interf-detect.js";
-import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../method-package/context-interface.js";
-import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compiler/compiled-paths.js";
-import { ensureCompiledZoneTargets } from "../../compiler/compiled-schema.js";
-import { listFilesRecursive } from "../../shared/filesystem.js";
-import { resolveMethodImprovementReviewSourcePaths } from "../../method-package/method-review-paths.js";
+import { buildCompiledSourceFiles } from "../../compile/source-files.js";
+import { METHOD_PACKAGE_DIR } from "../../../project/interf-detect.js";
+import { CONTEXT_INTERFACE_FILE as METHOD_SCHEMA_FILE, contextInterfaceZoneAbsolutePath as compiledZoneAbsolutePath, readContextInterface as readCompiledSchemaFile, resolveContextInterfacePath as resolveMethodSchemaPath, } from "../../../methods/package/context-interface.js";
+import { stageExecutionShellsRoot, methodImprovementLoopRoot, methodPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, compiledRuntimeSourceSnapshotPath, compiledRuntimeStageInputsPath, } from "../../compile/compiled-paths.js";
+import { ensureCompiledZoneTargets } from "../../compile/compiled-schema.js";
+import { listFilesRecursive } from "../../../contracts/utils/filesystem.js";
+import { resolveMethodImprovementReviewSourcePaths } from "../../../methods/package/method-review-paths.js";
 const LOCAL_SKILL_ROOTS = [
     ".claude/skills",
     ".codex/skills",
@@ -90,7 +90,7 @@ export function renderCompiledAgents(compiledPath, name, methodId, about, option
         "",
         "```",
         "interf compile            build this portable context",
-        "interf test               run checks against this portable context",
+        "interf verify               run checks against this portable context",
         "interf status             show deterministic health",
         "```",
         "",

package/dist/packages/{agents → engine/agents}/lib/user-config.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { readJsonFileWithSchema } from "../../shared/parse.js";
-import { interfHomeRoot } from "../../contracts/lib/preparation-paths.js";
+import { readJsonFileWithSchema } from "../../../contracts/utils/parse.js";
+import { interfHomeRoot } from "../../../contracts/lib/preparation-paths.js";
 import { InterfUserConfigSchema } from "./schema.js";
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export function interfHome() {

package/dist/packages/engine/agents/registry.d.ts

@@ -0,0 +1,91 @@
+import { type AgentRecord, type AgentsRegistry, type RoleMap } from "../../contracts/lib/schema.js";
+export declare const AGENTS_REGISTRY_FILENAME = "agents.json";
+/** `~/.interf/agents.json` — persisted custom agents + role-map. */
+export declare function agentsRegistryPath(): string;
+/**
+ * Load just the persisted on-disk part of the registry. Built-in agents
+ * are NOT included — call `loadAgentsRegistry()` for the merged view.
+ *
+ * Returns `{ agents: [], role_map: {} }` when the file is missing or
+ * unreadable; persisted custom agents always have `source: "user"`.
+ */
+export declare function loadPersistedRegistry(): AgentsRegistry;
+/** Persist the on-disk part of the registry (custom agents + role-map). */
+export declare function savePersistedRegistry(registry: AgentsRegistry): void;
+/**
+ * Detect built-in agents present on this machine. Filtered to agents
+ * whose marker home directory exists; we do NOT require the command
+ * to be on PATH at registry read time — that's a runtime concern.
+ */
+export declare function detectBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Same as `detectBuiltinAgentRecords()` but only includes agents the
+ * current Interf build can fully drive (Claude Code, Codex). Used by
+ * the role-router and the CLI / UI listing as the "available agents"
+ * set.
+ */
+export declare function detectAutomatableBuiltinAgentRecords(): AgentRecord[];
+/**
+ * Full advertisement set — all built-in agents Interf knows about,
+ * regardless of whether they are installed locally. Used by the
+ * "install cards" zero-state surface so the UI / wizard can offer
+ * the user choices to install.
+ */
+export declare function listKnownBuiltinAgents(): AgentRecord[];
+export interface ResolvedRegistry {
+    /** All currently usable agents — built-in detected + persisted custom. */
+    agents: AgentRecord[];
+    /** Role → agent-name. Includes any persisted user edits. */
+    roleMap: RoleMap;
+    /**
+     * The "active" / default agent. This is whatever the role-map's
+     * `general` row points at, falling back to the first available
+     * agent when `general` is unset or maps to something that no longer
+     * exists in `agents`.
+     */
+    activeAgent: AgentRecord | null;
+}
+/**
+ * Public entry point — read the persisted registry, merge with detected
+ * built-ins, and seed the default role-map on first read if needed.
+ *
+ * Does NOT write back to disk. Callers that mutate the registry should
+ * call `savePersistedRegistry()` explicitly with the persisted slice.
+ */
+export declare function loadAgentsRegistry(): ResolvedRegistry;
+/** Pure helper — like `loadAgentsRegistry()` but works off in-memory data. */
+export declare function resolveRegistry(persisted: AgentsRegistry, builtinDetected: AgentRecord[]): ResolvedRegistry;
+/**
+ * Update the role-map (full replace). Returns the persisted slice that
+ * was written.
+ */
+export declare function updateRoleMap(nextRoleMap: RoleMap): AgentsRegistry;
+/**
+ * Patch the role-map with a partial update. Empty-string values clear
+ * the role (it falls back to `general` / active agent at run time).
+ */
+export declare function patchRoleMap(patch: Record<string, string>): AgentsRegistry;
+/**
+ * Register a new custom agent. Throws if `name` collides with a known
+ * built-in or with an already-persisted custom agent.
+ */
+export declare function registerCustomAgent(input: {
+    name: string;
+    display_name: string;
+    command: string;
+}): AgentsRegistry;
+/**
+ * Unregister a custom agent. Throws if `name` matches a built-in or no
+ * custom record exists. Removes any role-map entry pointing at the
+ * removed agent.
+ */
+export declare function unregisterCustomAgent(name: string): AgentsRegistry;
+/**
+ * Set the "active" agent — i.e. the agent the role-map's `general` row
+ * points at. Also updates any role still pointing at the previous
+ * active agent so existing single-active-agent setups don't need
+ * per-role edits when switching agents.
+ *
+ * Throws if `name` is not in the merged agents list.
+ */
+export declare function setActiveAgent(name: string): AgentsRegistry;

package/dist/packages/engine/agents/registry.js

@@ -0,0 +1,321 @@
+/**
+ * Agents registry — `~/.interf/agents.json`.
+ *
+ * Reads / writes the persisted user-registered agents and the role-map.
+ * Built-in agents (Claude Code, Codex, Cursor) are NOT persisted; they
+ * are detected dynamically at read time and merged with the persisted
+ * custom agents. The role-map IS persisted.
+ *
+ * 0.15 contract:
+ *   {
+ *     "agents": [
+ *       { "name": "opencode", "display_name": "OpenCode", "command": "opencode --prompt", "source": "user" }
+ *     ],
+ *     "role_map": {
+ *       "extractor": "claude-code",
+ *       "summarizer": "claude-code",
+ *       "structurer": "claude-code",
+ *       "verifier": "claude-code",
+ *       "general": "claude-code"
+ *     }
+ *   }
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AgentRecordSchema, AgentsRegistrySchema, CANONICAL_ROLES, } from "../../contracts/lib/schema.js";
+import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
+import { interfHomeRoot } from "../instance-paths.js";
+import { agentCommandAvailable, detectAgents, supportsAutomatedRuns } from "./lib/detection.js";
+import { AGENTS } from "./lib/constants.js";
+export const AGENTS_REGISTRY_FILENAME = "agents.json";
+/** `~/.interf/agents.json` — persisted custom agents + role-map. */
+export function agentsRegistryPath() {
+    return join(interfHomeRoot(), AGENTS_REGISTRY_FILENAME);
+}
+/**
+ * Load just the persisted on-disk part of the registry. Built-in agents
+ * are NOT included — call `loadAgentsRegistry()` for the merged view.
+ *
+ * Returns `{ agents: [], role_map: {} }` when the file is missing or
+ * unreadable; persisted custom agents always have `source: "user"`.
+ */
+export function loadPersistedRegistry() {
+    const path = agentsRegistryPath();
+    if (!existsSync(path)) {
+        return AgentsRegistrySchema.parse({});
+    }
+    const value = readJsonFileWithSchema(path, "agents registry", AgentsRegistrySchema);
+    return value ?? AgentsRegistrySchema.parse({});
+}
+/** Persist the on-disk part of the registry (custom agents + role-map). */
+export function savePersistedRegistry(registry) {
+    const home = interfHomeRoot();
+    mkdirSync(home, { recursive: true });
+    const sanitized = {
+        agents: registry.agents.map(({ available: _available, ...agent }) => AgentRecordSchema.parse({ ...agent, source: "user" })),
+        role_map: { ...registry.role_map },
+    };
+    writeFileSync(agentsRegistryPath(), `${JSON.stringify(sanitized, null, 2)}\n`);
+}
+/**
+ * Detect built-in agents present on this machine. Filtered to agents
+ * whose marker home directory exists; we do NOT require the command
+ * to be on PATH at registry read time — that's a runtime concern.
+ */
+export function detectBuiltinAgentRecords() {
+    return detectAgents().map((agent) => AgentRecordSchema.parse({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        source: "builtin",
+    }));
+}
+/**
+ * Same as `detectBuiltinAgentRecords()` but only includes agents the
+ * current Interf build can fully drive (Claude Code, Codex). Used by
+ * the role-router and the CLI / UI listing as the "available agents"
+ * set.
+ */
+export function detectAutomatableBuiltinAgentRecords() {
+    return detectAgents()
+        .filter(supportsAutomatedRuns)
+        .map((agent) => AgentRecordSchema.parse({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        source: "builtin",
+    }));
+}
+/**
+ * Full advertisement set — all built-in agents Interf knows about,
+ * regardless of whether they are installed locally. Used by the
+ * "install cards" zero-state surface so the UI / wizard can offer
+ * the user choices to install.
+ */
+export function listKnownBuiltinAgents() {
+    return AGENTS.map((agent) => AgentRecordSchema.parse({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        source: "builtin",
+    }));
+}
+/**
+ * Merge persisted custom agents with the built-in agents currently
+ * detected on this machine. Detected built-ins are listed first; any
+ * persisted custom entry whose name collides with a built-in is
+ * dropped (built-ins are immutable / cannot be overridden).
+ *
+ * Each merged record carries an `available` flag — true when the
+ * agent's command resolves on PATH. Built-ins are detected by their
+ * marker directory and assumed available; custom agents are checked
+ * against `which` so a stale `~/.interf/agents.json` entry does not
+ * appear as a usable choice.
+ */
+function mergeAgents(builtin, persisted) {
+    const seen = new Set(builtin.map((agent) => agent.name));
+    const merged = builtin.map((agent) => ({ ...agent, available: true }));
+    for (const agent of persisted) {
+        if (seen.has(agent.name))
+            continue;
+        seen.add(agent.name);
+        merged.push({
+            ...agent,
+            source: "user",
+            available: agentCommandAvailable(agent.command),
+        });
+    }
+    return merged;
+}
+function pickActiveAgent(agents, roleMap) {
+    const generalName = roleMap["general"];
+    const generalAgent = generalName
+        ? agents.find((agent) => agent.name === generalName)
+        : null;
+    if (generalAgent && generalAgent.available !== false)
+        return generalAgent;
+    return agents.find((agent) => agent.available !== false) ?? null;
+}
+/**
+ * Default role-map for a fresh install: every canonical role maps to
+ * the first available agent. If nothing is detected, returns an empty
+ * object (callers must handle "no agents available" upstream).
+ */
+function buildDefaultRoleMap(agents) {
+    const first = agents.find((agent) => agent.available !== false) ?? agents[0];
+    if (!first)
+        return {};
+    const map = {};
+    for (const role of CANONICAL_ROLES) {
+        map[role] = first.name;
+    }
+    return map;
+}
+/**
+ * Public entry point — read the persisted registry, merge with detected
+ * built-ins, and seed the default role-map on first read if needed.
+ *
+ * Does NOT write back to disk. Callers that mutate the registry should
+ * call `savePersistedRegistry()` explicitly with the persisted slice.
+ */
+export function loadAgentsRegistry() {
+    const persisted = loadPersistedRegistry();
+    const builtinDetected = detectAutomatableBuiltinAgentRecords();
+    const agents = mergeAgents(builtinDetected, persisted.agents);
+    // Seed the default role-map on first read when the persisted file
+    // has no role-map entries AND we have at least one detectable agent.
+    // (We do not write to disk yet; the seeded map is computed on the
+    // fly for each reader so a fresh install behaves identically before
+    // and after the first user edit.)
+    const persistedRoleMap = persisted.role_map;
+    const hasPersistedEntries = Object.keys(persistedRoleMap).length > 0;
+    const roleMap = hasPersistedEntries
+        ? { ...persistedRoleMap }
+        : buildDefaultRoleMap(agents);
+    // Derive the "active" agent: role-map's `general` entry, falling
+    // back to the first available agent. Skips the general entry if it
+    // points at an agent whose command is no longer on PATH.
+    const activeAgent = pickActiveAgent(agents, roleMap);
+    return { agents, roleMap, activeAgent };
+}
+/** Pure helper — like `loadAgentsRegistry()` but works off in-memory data. */
+export function resolveRegistry(persisted, builtinDetected) {
+    const agents = mergeAgents(builtinDetected, persisted.agents);
+    const hasPersistedEntries = Object.keys(persisted.role_map).length > 0;
+    const roleMap = hasPersistedEntries
+        ? { ...persisted.role_map }
+        : buildDefaultRoleMap(agents);
+    const activeAgent = pickActiveAgent(agents, roleMap);
+    return { agents, roleMap, activeAgent };
+}
+/**
+ * Update the role-map (full replace). Returns the persisted slice that
+ * was written.
+ */
+export function updateRoleMap(nextRoleMap) {
+    const current = loadPersistedRegistry();
+    const next = {
+        agents: current.agents,
+        role_map: { ...nextRoleMap },
+    };
+    savePersistedRegistry(next);
+    return next;
+}
+/**
+ * Patch the role-map with a partial update. Empty-string values clear
+ * the role (it falls back to `general` / active agent at run time).
+ */
+export function patchRoleMap(patch) {
+    const current = loadPersistedRegistry();
+    const next = { ...current.role_map };
+    for (const [role, agentName] of Object.entries(patch)) {
+        if (typeof agentName !== "string" || agentName.trim().length === 0) {
+            delete next[role];
+            continue;
+        }
+        next[role] = agentName.trim();
+    }
+    const updated = {
+        agents: current.agents,
+        role_map: next,
+    };
+    savePersistedRegistry(updated);
+    return updated;
+}
+/**
+ * Register a new custom agent. Throws if `name` collides with a known
+ * built-in or with an already-persisted custom agent.
+ */
+export function registerCustomAgent(input) {
+    const trimmedName = input.name.trim();
+    const trimmedDisplayName = input.display_name.trim();
+    const trimmedCommand = input.command.trim();
+    if (!trimmedName)
+        throw new Error("Agent name is required.");
+    if (!trimmedDisplayName)
+        throw new Error("Agent display name is required.");
+    if (!trimmedCommand)
+        throw new Error("Agent command is required.");
+    if (AGENTS.some((agent) => agent.name === trimmedName)) {
+        throw new Error(`Cannot register custom agent "${trimmedName}": that name is reserved for a built-in agent.`);
+    }
+    const current = loadPersistedRegistry();
+    if (current.agents.some((agent) => agent.name === trimmedName)) {
+        throw new Error(`Custom agent "${trimmedName}" is already registered.`);
+    }
+    const record = AgentRecordSchema.parse({
+        name: trimmedName,
+        display_name: trimmedDisplayName,
+        command: trimmedCommand,
+        source: "user",
+    });
+    const next = {
+        agents: [...current.agents, record],
+        role_map: { ...current.role_map },
+    };
+    savePersistedRegistry(next);
+    return next;
+}
+/**
+ * Unregister a custom agent. Throws if `name` matches a built-in or no
+ * custom record exists. Removes any role-map entry pointing at the
+ * removed agent.
+ */
+export function unregisterCustomAgent(name) {
+    const trimmedName = name.trim();
+    if (AGENTS.some((agent) => agent.name === trimmedName)) {
+        throw new Error(`Cannot unregister built-in agent "${trimmedName}". Built-in agents are detected dynamically.`);
+    }
+    const current = loadPersistedRegistry();
+    const remaining = current.agents.filter((agent) => agent.name !== trimmedName);
+    if (remaining.length === current.agents.length) {
+        throw new Error(`Custom agent "${trimmedName}" is not registered.`);
+    }
+    const trimmedRoleMap = {};
+    for (const [role, agentName] of Object.entries(current.role_map)) {
+        if (agentName === trimmedName)
+            continue;
+        trimmedRoleMap[role] = agentName;
+    }
+    const next = {
+        agents: remaining,
+        role_map: trimmedRoleMap,
+    };
+    savePersistedRegistry(next);
+    return next;
+}
+/**
+ * Set the "active" agent — i.e. the agent the role-map's `general` row
+ * points at. Also updates any role still pointing at the previous
+ * active agent so existing single-active-agent setups don't need
+ * per-role edits when switching agents.
+ *
+ * Throws if `name` is not in the merged agents list.
+ */
+export function setActiveAgent(name) {
+    const trimmedName = name.trim();
+    if (!trimmedName)
+        throw new Error("Agent name is required.");
+    const persisted = loadPersistedRegistry();
+    const builtinDetected = detectAutomatableBuiltinAgentRecords();
+    const agents = mergeAgents(builtinDetected, persisted.agents);
+    if (!agents.some((agent) => agent.name === trimmedName)) {
+        throw new Error(`Agent "${trimmedName}" is not detected or registered. Install or register it before making it active.`);
+    }
+    // The previous active is whatever `general` currently maps to (or the
+    // first agent in the merged list when `general` is unset).
+    const previousActive = persisted.role_map["general"] ?? agents[0]?.name ?? null;
+    const nextRoleMap = { ...persisted.role_map };
+    for (const [role, currentName] of Object.entries(nextRoleMap)) {
+        if (currentName === previousActive) {
+            nextRoleMap[role] = trimmedName;
+        }
+    }
+    nextRoleMap["general"] = trimmedName;
+    const next = {
+        agents: persisted.agents,
+        role_map: nextRoleMap,
+    };
+    savePersistedRegistry(next);
+    return next;
+}

package/dist/packages/engine/agents/role-executors.d.ts

@@ -0,0 +1,35 @@
+import type { AgentRecord, RoleMap } from "../../contracts/lib/schema.js";
+import type { MethodExecutionProfile, MethodExecutor } from "./lib/executors.js";
+import { type ResolvedAgent, type RoleResolutionContext } from "./role-router.js";
+export interface RoleExecutorBundle {
+    /** Map agent name → method executor. */
+    executors: Map<string, MethodExecutor>;
+    /** Default fallback executor — usually the active agent. */
+    defaultExecutor: MethodExecutor;
+    /** The registry context we built this bundle from. */
+    context: RoleResolutionContext;
+    /**
+     * Resolve a stage's role to an executor + provenance. Falls back
+     * through `general` and the default executor before raising.
+     */
+    resolveExecutorForRole(role: string): {
+        executor: MethodExecutor;
+        resolved: ResolvedAgent;
+    };
+}
+export interface BuildRoleExecutorBundleInput {
+    agents: AgentRecord[];
+    roleMap: RoleMap;
+    /** The agent the role-map's `general` row points at, or fallback. */
+    activeAgent: AgentRecord | null;
+    /** The fallback executor — used when role resolution yields the active. */
+    defaultExecutor: MethodExecutor;
+    executionProfile?: MethodExecutionProfile;
+}
+/**
+ * Build a per-role executor bundle from a registry snapshot. The
+ * `defaultExecutor` is what the pipeline already passes for the
+ * single-active-agent case (so role lookups that fall through to
+ * `fallback-active` resolve to the same executor).
+ */
+export declare function buildRoleExecutorBundle(input: BuildRoleExecutorBundleInput): RoleExecutorBundle;

package/dist/packages/engine/agents/role-executors.js

@@ -0,0 +1,88 @@
+/**
+ * Role-aware executor factory.
+ *
+ * Bridges the registry layer (`AgentRecord` / `RoleMap`) to the runtime
+ * layer (`MethodExecutor`). Builds a per-agent-name `MethodExecutor`
+ * map up front and exposes a `resolveExecutorForRole(role)` helper that
+ * the compile / verify pipelines can call per-stage.
+ *
+ * Falls back gracefully: when a role isn't mapped, or the mapped agent
+ * is missing, we fall through to `general` and ultimately to the
+ * default executor (the active agent at job start).
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createLocalAgentExecutor } from "./lib/executors.js";
+import { AGENTS } from "./lib/constants.js";
+import { resolveAgentForRole, } from "./role-router.js";
+/**
+ * Hydrate an `AgentRecord` (registry shape) into an `Agent` (runtime
+ * shape with `skillsDir`). For built-in agents we copy the canonical
+ * `skillsDir`; for custom user agents we synthesize a path under
+ * `~/.<name>` so any future skill loader has somewhere to look.
+ */
+function agentRecordToAgent(record) {
+    const builtin = AGENTS.find((agent) => agent.name === record.name);
+    if (builtin)
+        return { ...builtin };
+    return {
+        name: record.name,
+        displayName: record.display_name,
+        skillsDir: join(homedir(), `.${record.name}`),
+        command: record.command,
+    };
+}
+/**
+ * Build a per-role executor bundle from a registry snapshot. The
+ * `defaultExecutor` is what the pipeline already passes for the
+ * single-active-agent case (so role lookups that fall through to
+ * `fallback-active` resolve to the same executor).
+ */
+export function buildRoleExecutorBundle(input) {
+    const executors = new Map();
+    for (const record of input.agents) {
+        const agent = agentRecordToAgent(record);
+        executors.set(record.name, createLocalAgentExecutor(agent, input.executionProfile));
+    }
+    // Make sure the active / default executor is reachable by name
+    // even when the active agent isn't formally in the registry yet
+    // (e.g. legacy single-active setups during the 0.14 → 0.15 transition).
+    if (input.activeAgent && !executors.has(input.activeAgent.name)) {
+        executors.set(input.activeAgent.name, input.defaultExecutor);
+    }
+    const context = {
+        roleMap: input.roleMap,
+        agents: input.agents,
+        activeAgent: input.activeAgent,
+    };
+    return {
+        executors,
+        defaultExecutor: input.defaultExecutor,
+        context,
+        resolveExecutorForRole(role) {
+            const result = resolveAgentForRole(role, context);
+            if ("error" in result) {
+                // Role-router refused — fall back to the default executor and
+                // synthesize a `fallback-active` resolution. This keeps prepare
+                // runs alive when the registry is empty / mid-edit.
+                const synthetic = {
+                    agent: input.activeAgent
+                        ?? {
+                            name: input.defaultExecutor.name,
+                            display_name: input.defaultExecutor.displayName,
+                            command: input.defaultExecutor.command ?? input.defaultExecutor.name,
+                            source: "user",
+                        },
+                    role,
+                    source: "fallback-active",
+                };
+                return {
+                    executor: input.defaultExecutor,
+                    resolved: synthetic,
+                };
+            }
+            const executor = executors.get(result.agent.name) ?? input.defaultExecutor;
+            return { executor, resolved: result };
+        },
+    };
+}