@interf/compiler 0.9.5 → 0.16.0

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 };
+        },
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Role router — picks which connected agent runs a given stage role.
+ *
+ * The compile pipeline calls `resolveAgentForRole` for each agent-typed
+ * stage, passing the stage's declared role and the current registry +
+ * active agent. The verify pipeline always passes role `"verifier"`.
+ *
+ * Resolution priority (lean / explicit):
+ *   1. Explicit role-map entry for the requested role.
+ *   2. Role-map's `general` row (when the requested role isn't mapped).
+ *   3. The active agent (when `general` isn't mapped either).
+ *
+ * If the role-map points at an agent name that no longer exists in the
+ * merged agents list (e.g. user uninstalled it), we fall through to
+ * `general` then `activeAgent`. Only when ALL three are missing does the
+ * router return an error.
+ */
+import type { AgentRecord, RoleMap } from "../../contracts/lib/schema.js";
+export type RoleResolutionSource = "explicit" | "fallback-general" | "fallback-active";
+export interface ResolvedAgent {
+    agent: AgentRecord;
+    /** The role the caller asked for (kept for audit / logging). */
+    role: string;
+    /** Which fallback rung the agent came from. */
+    source: RoleResolutionSource;
+}
+export interface RoleResolutionContext {
+    roleMap: RoleMap;
+    agents: AgentRecord[];
+    /**
+     * The agent the role-map's `general` row points at — or, when no
+     * role-map exists yet, the first detected agent. Pass `null` when
+     * there is no agent available; the router then returns an error.
+     */
+    activeAgent: AgentRecord | null;
+}
+export type RoleResolutionError = {
+    error: "no-agents";
+    detail: string;
+} | {
+    error: "mapped-agent-missing";
+    detail: string;
+};
+/**
+ * Resolve a stage role to an agent + provenance trail. Returns
+ * `{ agent, role, source }` on success or `{ error, detail }` on
+ * failure.
+ */
+export declare function resolveAgentForRole(role: string, context: RoleResolutionContext): ResolvedAgent | RoleResolutionError;
+/**
+ * Resolve every role declared by a Method's stages. Useful for
+ * pre-flight: returns either `{ resolutions }` (one entry per stage)
+ * or `{ error, role }` if any stage cannot resolve.
+ */
+export declare function resolveAgentsForStages(stages: ReadonlyArray<{
+    id: string;
+    role: string;
+}>, context: RoleResolutionContext): {
+    resolutions: Array<{
+        stageId: string;
+        resolved: ResolvedAgent;
+    }>;
+} | (RoleResolutionError & {
+    stageId: string;
+    role: string;
+});

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

@@ -0,0 +1,73 @@
+/**
+ * Resolve a stage role to an agent + provenance trail. Returns
+ * `{ agent, role, source }` on success or `{ error, detail }` on
+ * failure.
+ */
+export function resolveAgentForRole(role, context) {
+    if (context.agents.length === 0) {
+        return {
+            error: "no-agents",
+            detail: "No agents are available. Install Claude Code, Codex, or another agent CLI, " +
+                "or register a custom CLI with `interf agents register`.",
+        };
+    }
+    const trimmedRole = role && role.trim().length > 0 ? role.trim() : "general";
+    // 1. Explicit role-map entry for the requested role.
+    const explicitName = context.roleMap[trimmedRole];
+    if (explicitName) {
+        const found = context.agents.find((agent) => agent.name === explicitName);
+        if (found) {
+            return { agent: found, role: trimmedRole, source: "explicit" };
+        }
+        // Map exists but points at a missing agent. Fall through to
+        // `general` and ultimately `activeAgent`. We do NOT return
+        // `mapped-agent-missing` here because the resolution priority
+        // explicitly allows fallback through `general` and active —
+        // returning an error would block a usable agent.
+    }
+    // 2. Role-map's `general` row, if the requested role isn't `general`.
+    if (trimmedRole !== "general") {
+        const generalName = context.roleMap["general"];
+        if (generalName) {
+            const found = context.agents.find((agent) => agent.name === generalName);
+            if (found) {
+                return { agent: found, role: trimmedRole, source: "fallback-general" };
+            }
+        }
+    }
+    // 3. Active agent.
+    if (context.activeAgent) {
+        return {
+            agent: context.activeAgent,
+            role: trimmedRole,
+            source: "fallback-active",
+        };
+    }
+    // Map points at an agent we cannot find AND there is no active fallback.
+    if (explicitName) {
+        return {
+            error: "mapped-agent-missing",
+            detail: `Role "${trimmedRole}" maps to agent "${explicitName}", which is not detected or registered.`,
+        };
+    }
+    return {
+        error: "no-agents",
+        detail: `No agent is mapped to role "${trimmedRole}" and no active agent fallback is available.`,
+    };
+}
+/**
+ * Resolve every role declared by a Method's stages. Useful for
+ * pre-flight: returns either `{ resolutions }` (one entry per stage)
+ * or `{ error, role }` if any stage cannot resolve.
+ */
+export function resolveAgentsForStages(stages, context) {
+    const resolutions = [];
+    for (const stage of stages) {
+        const result = resolveAgentForRole(stage.role, context);
+        if ("error" in result) {
+            return { ...result, stageId: stage.id, role: stage.role };
+        }
+        resolutions.push({ stageId: stage.id, resolved: result });
+    }
+    return { resolutions };
+}