@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/runtime/runtime-caches.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Runtime read-side caches.
+ *
+ * The local service runtime fronts a filesystem-backed model: every
+ * "list" or "get" call walks `.interf/runtime/...`, parses each JSON
+ * record through Zod, and returns the typed shape. Polling clients
+ * (Interf Desktop renderer, CLI status loops) hit those endpoints multiple times
+ * per second; on instances with hundreds of Build / benchmark runs this
+ * shows up as the dominant CPU cost.
+ *
+ * The caches here memoize the parsed-and-validated results. Each cache
+ * is keyed by Project data directory so independent Projects do
+ * not cross-pollinate, and each cache exposes both a read path (`get(...)`) and an explicit
+ * invalidation hook (`invalidate(...)`). The runtime calls
+ * `invalidate*` whenever it writes, so the next read repopulates from
+ * disk. Invalidation is intentionally broad (per-Project, not
+ * per-record) — staleness is the only correctness bug worth avoiding,
+ * and per-record invalidation introduces fan-out without measurably
+ * lowering recompute cost.
+ */
+/**
+ * Per-(Project data directory, project) cache for Build records, plus a
+ * runId -> project index so `getBuildRun(runId)` can resolve to
+ * the owning Project without scanning every Project's runs.
+ */
+export declare class RunListingCache<TRecord> {
+    /** projectDataDir -> project id -> records (newest-first sorted). */
+    private byProjectRoot;
+    /** projectDataDir -> runId -> project. */
+    private runIndex;
+    get(projectDataDir: string, project: string, fill: () => TRecord[], runIdOf: (record: TRecord) => string): TRecord[];
+    /** Look up which project owns this runId, if known. */
+    projectFor(projectDataDir: string, runId: string): string | null;
+    /** Invalidate a single project's cached records and id index. */
+    invalidateProject(projectDataDir: string, project: string): void;
+    /** Drop everything for a Project data directory (e.g. after a reset). */
+    invalidateProjectRoot(projectDataDir: string): void;
+}
+/**
+ * Per-(Project data directory, project) readiness cache. Readiness joins build
+ * runs, benchmark runs, and the Project config; it
+ * is computed on every poll. The cache invalidates when the runtime
+ * writes any of those underlying objects for a given project.
+ */
+export declare class ReadinessCache<TReadiness> {
+    private byProjectRoot;
+    get(projectDataDir: string, project: string, compute: () => TReadiness): TReadiness;
+    invalidateProject(projectDataDir: string, project: string): void;
+    invalidateProjectRoot(projectDataDir: string): void;
+}
+/**
+ * Source-folder listing cache keyed by `(cacheKey, folderRootMtime)`.
+ * `cacheKey` is the slot identifier; `folderPath` is the directory the
+ * cache stats for an mtime probe. UI polling is the hot path; CLI
+ * commands rarely hit the same path twice in <2s, hence the short TTL
+ * fallback.
+ */
+export declare class MtimeListingCache<TList> {
+    private static readonly TTL_MS;
+    private cache;
+    get(cacheKey: string, folderPath: string, fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}
+/**
+ * Build Plan listing cache keyed by the joined mtimes of the
+ * bundled / user-library / Project-local Build Plan package roots. If
+ * any of those ticks (a new local Build Plan package, an edit to the user library, etc.) the cache
+ * misses and we re-resolve.
+ */
+export declare class BuildPlanListingCache<TList> {
+    private cache;
+    get(cacheKey: string, rootPaths: string[], fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}
+/**
+ * Per-Project source-state cache.
+ *
+ * Computing the file index hash requires reading every source file's first
+ * 64KB; on Projects with thousands of files this is the dominant cost of a
+ * drift check. The cache keys by Project id and invalidates on Build
+ * completion (which produces a new Context Graph the drift verdict compares to).
+ */
+export declare class ProjectSourceStateCache<TState> {
+    private byProjectId;
+    get(projectId: string, compute: () => TState): TState;
+    set(projectId: string, value: TState): void;
+    invalidateProject(projectId: string): void;
+    invalidateAll(): void;
+}

package/dist/packages/{engine → runtime}/runtime-caches.js

@@ -4,16 +4,16 @@
  * The local service runtime fronts a filesystem-backed model: every
  * "list" or "get" call walks `.interf/runtime/...`, parses each JSON
  * record through Zod, and returns the typed shape. Polling clients
- * (Interf UI, CLI status loops) hit those endpoints multiple times
- * per second; on instances with hundreds of build / test runs this
+ * (Interf Desktop renderer, CLI status loops) hit those endpoints multiple times
+ * per second; on instances with hundreds of Build / benchmark runs this
  * shows up as the dominant CPU cost.
  *
  * The caches here memoize the parsed-and-validated results. Each cache
- * is keyed by Preparation data directory so independent Preparations do
+ * is keyed by Project data directory so independent Projects do
  * not cross-pollinate, and each cache exposes both a read path (`get(...)`) and an explicit
  * invalidation hook (`invalidate(...)`). The runtime calls
  * `invalidate*` whenever it writes, so the next read repopulates from
- * disk. Invalidation is intentionally broad (per-preparation, not
+ * disk. Invalidation is intentionally broad (per-Project, not
  * per-record) — staleness is the only correctness bug worth avoiding,
  * and per-record invalidation introduces fan-out without measurably
  * lowering recompute cost.
@@ -21,101 +21,101 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 /**
- * Per-(Preparation data directory, preparation) cache for Build run records, plus a
- * runId -> preparation index so `getBuildRun(runId)` can resolve to
- * the owning preparation without scanning every preparation's runs.
+ * Per-(Project data directory, project) cache for Build records, plus a
+ * runId -> project index so `getBuildRun(runId)` can resolve to
+ * the owning Project without scanning every Project's runs.
  */
 export class RunListingCache {
-    /** prepDataDir -> preparation -> records (newest-first sorted). */
-    byPreparationRoot = new Map();
-    /** prepDataDir -> runId -> preparation. */
+    /** projectDataDir -> project id -> records (newest-first sorted). */
+    byProjectRoot = new Map();
+    /** projectDataDir -> runId -> project. */
     runIndex = new Map();
-    get(prepDataDir, preparation, fill, runIdOf) {
-        const wsKey = resolve(prepDataDir);
-        let bucket = this.byPreparationRoot.get(wsKey);
+    get(projectDataDir, project, fill, runIdOf) {
+        const wsKey = resolve(projectDataDir);
+        let bucket = this.byProjectRoot.get(wsKey);
         if (!bucket) {
             bucket = new Map();
-            this.byPreparationRoot.set(wsKey, bucket);
+            this.byProjectRoot.set(wsKey, bucket);
         }
-        const cached = bucket.get(preparation);
+        const cached = bucket.get(project);
         if (cached)
             return cached;
         const fresh = fill();
-        bucket.set(preparation, fresh);
+        bucket.set(project, fresh);
         let index = this.runIndex.get(wsKey);
         if (!index) {
             index = new Map();
             this.runIndex.set(wsKey, index);
         }
         for (const record of fresh) {
-            index.set(runIdOf(record), preparation);
+            index.set(runIdOf(record), project);
         }
         return fresh;
     }
-    /** Look up which preparation owns this runId, if known. */
-    preparationFor(prepDataDir, runId) {
-        const wsKey = resolve(prepDataDir);
+    /** Look up which project owns this runId, if known. */
+    projectFor(projectDataDir, runId) {
+        const wsKey = resolve(projectDataDir);
         return this.runIndex.get(wsKey)?.get(runId) ?? null;
     }
-    /** Invalidate a single preparation's cached records and id index. */
-    invalidatePreparation(prepDataDir, preparation) {
-        const wsKey = resolve(prepDataDir);
-        const bucket = this.byPreparationRoot.get(wsKey);
+    /** Invalidate a single project's cached records and id index. */
+    invalidateProject(projectDataDir, project) {
+        const wsKey = resolve(projectDataDir);
+        const bucket = this.byProjectRoot.get(wsKey);
         if (bucket) {
-            bucket.delete(preparation);
+            bucket.delete(project);
             if (bucket.size === 0)
-                this.byPreparationRoot.delete(wsKey);
+                this.byProjectRoot.delete(wsKey);
         }
         const index = this.runIndex.get(wsKey);
         if (index) {
             for (const [runId, owner] of index) {
-                if (owner === preparation)
+                if (owner === project)
                     index.delete(runId);
             }
             if (index.size === 0)
                 this.runIndex.delete(wsKey);
         }
     }
-    /** Drop everything for a Preparation data directory (e.g. after a reset). */
-    invalidatePreparationRoot(prepDataDir) {
-        const wsKey = resolve(prepDataDir);
-        this.byPreparationRoot.delete(wsKey);
+    /** Drop everything for a Project data directory (e.g. after a reset). */
+    invalidateProjectRoot(projectDataDir) {
+        const wsKey = resolve(projectDataDir);
+        this.byProjectRoot.delete(wsKey);
         this.runIndex.delete(wsKey);
     }
 }
 /**
- * Per-(Preparation data directory, preparation) readiness cache. Readiness joins build
- * runs, test runs, readiness-check runs, and the preparation config; it
+ * Per-(Project data directory, project) readiness cache. Readiness joins build
+ * runs, benchmark runs, and the Project config; it
  * is computed on every poll. The cache invalidates when the runtime
- * writes any of those underlying objects for a given preparation.
+ * writes any of those underlying objects for a given project.
  */
 export class ReadinessCache {
-    byPreparationRoot = new Map();
-    get(prepDataDir, preparation, compute) {
-        const wsKey = resolve(prepDataDir);
-        let bucket = this.byPreparationRoot.get(wsKey);
+    byProjectRoot = new Map();
+    get(projectDataDir, project, compute) {
+        const wsKey = resolve(projectDataDir);
+        let bucket = this.byProjectRoot.get(wsKey);
         if (!bucket) {
             bucket = new Map();
-            this.byPreparationRoot.set(wsKey, bucket);
+            this.byProjectRoot.set(wsKey, bucket);
         }
-        const cached = bucket.get(preparation);
+        const cached = bucket.get(project);
         if (cached !== undefined)
             return cached;
         const fresh = compute();
-        bucket.set(preparation, fresh);
+        bucket.set(project, fresh);
         return fresh;
     }
-    invalidatePreparation(prepDataDir, preparation) {
-        const wsKey = resolve(prepDataDir);
-        const bucket = this.byPreparationRoot.get(wsKey);
+    invalidateProject(projectDataDir, project) {
+        const wsKey = resolve(projectDataDir);
+        const bucket = this.byProjectRoot.get(wsKey);
         if (bucket) {
-            bucket.delete(preparation);
+            bucket.delete(project);
             if (bucket.size === 0)
-                this.byPreparationRoot.delete(wsKey);
+                this.byProjectRoot.delete(wsKey);
         }
     }
-    invalidatePreparationRoot(prepDataDir) {
-        this.byPreparationRoot.delete(resolve(prepDataDir));
+    invalidateProjectRoot(projectDataDir) {
+        this.byProjectRoot.delete(resolve(projectDataDir));
     }
 }
 /**
@@ -155,7 +155,7 @@ export class MtimeListingCache {
 }
 /**
  * Build Plan listing cache keyed by the joined mtimes of the
- * bundled / user-library / Preparation-local Build Plan package roots. If
+ * bundled / user-library / Project-local Build Plan package roots. If
  * any of those ticks (a new local Build Plan package, an edit to the user library, etc.) the cache
  * misses and we re-resolve.
  */
@@ -189,3 +189,31 @@ function safeStat(path) {
         return null;
     }
 }
+/**
+ * Per-Project source-state cache.
+ *
+ * Computing the file index hash requires reading every source file's first
+ * 64KB; on Projects with thousands of files this is the dominant cost of a
+ * drift check. The cache keys by Project id and invalidates on Build
+ * completion (which produces a new Context Graph the drift verdict compares to).
+ */
+export class ProjectSourceStateCache {
+    byProjectId = new Map();
+    get(projectId, compute) {
+        const cached = this.byProjectId.get(projectId);
+        if (cached !== undefined)
+            return cached;
+        const fresh = compute();
+        this.byProjectId.set(projectId, fresh);
+        return fresh;
+    }
+    set(projectId, value) {
+        this.byProjectId.set(projectId, value);
+    }
+    invalidateProject(projectId) {
+        this.byProjectId.delete(projectId);
+    }
+    invalidateAll() {
+        this.byProjectId.clear();
+    }
+}

package/dist/packages/{engine → runtime}/runtime-event-applier.d.ts

@@ -7,6 +7,8 @@
  * compose these without learning the resource shape.
  */
 import { type BuildRun, type InterfRunEvent } from "./execution/lib/schema.js";
-import { type LocalJobEvent, type LocalJobRunResource } from "./lib/schema.js";
+import { type LocalJobEvent, type LocalJobRunResource } from "./schemas/index.js";
+export declare const INTERRUPTED_BUILD_RUN_REASON = "Build interrupted because the local service stopped before the run reached a terminal state.";
+export declare function reconcileBuildRunTerminalStatus(run: BuildRun): BuildRun;
 export declare function applyEventToBuildRun(run: BuildRun, event: InterfRunEvent): BuildRun;
 export declare function applyEventToLocalJob(run: LocalJobRunResource, event: LocalJobEvent): LocalJobRunResource;

package/dist/packages/{engine → runtime}/runtime-event-applier.js

@@ -1,4 +1,47 @@
 import { uniqueArtifacts } from "./run-observability.js";
+export const INTERRUPTED_BUILD_RUN_REASON = "Build interrupted because the local service stopped before the run reached a terminal state.";
+function isRecoverableCancellation(event) {
+    return event.type === "run.cancelled" && event.reason === INTERRUPTED_BUILD_RUN_REASON;
+}
+export function reconcileBuildRunTerminalStatus(run) {
+    let status = run.status;
+    let finishedAt = run.finished_at;
+    let stickyCancellationAt = null;
+    for (const event of run.events) {
+        if (event.type === "run.cancelled") {
+            status = "cancelled";
+            finishedAt = event.timestamp;
+            stickyCancellationAt = isRecoverableCancellation(event) ? null : event.timestamp;
+            continue;
+        }
+        if (event.type === "run.completed") {
+            if (stickyCancellationAt) {
+                status = "cancelled";
+                finishedAt = stickyCancellationAt;
+            }
+            else {
+                status = "succeeded";
+                finishedAt = event.timestamp;
+            }
+            continue;
+        }
+        if (event.type === "run.failed") {
+            if (stickyCancellationAt) {
+                status = "cancelled";
+                finishedAt = stickyCancellationAt;
+            }
+            else {
+                status = "failed";
+                finishedAt = event.timestamp;
+            }
+        }
+    }
+    return {
+        ...run,
+        status,
+        ...(finishedAt ? { finished_at: finishedAt } : {}),
+    };
+}
 export function applyEventToBuildRun(run, event) {
     const now = event.timestamp;
     const stageFor = (stageId) => {
@@ -32,6 +75,7 @@ export function applyEventToBuildRun(run, event) {
                 started_at: now,
                 stage_index: event.stage_index,
                 stage_total: event.stage_total,
+                ...(event.logs ? { logs: event.logs } : {}),
             });
             break;
         case "artifact.written": {
@@ -41,15 +85,15 @@ export function applyEventToBuildRun(run, event) {
             });
             break;
         }
-        case "proof.updated":
+        case "evidence.updated":
             if (event.stage_id) {
                 updateStage(event.stage_id, {
-                    latest_proof: event.proof,
+                    latest_evidence: event.evidence,
                 });
             }
             return {
                 ...run,
-                latest_proof: event.proof,
+                latest_evidence: event.evidence,
                 events: [...run.events, event],
             };
         case "log.appended":
@@ -71,28 +115,20 @@ export function applyEventToBuildRun(run, event) {
             });
             break;
         case "run.completed":
-            return {
+            return reconcileBuildRunTerminalStatus({
                 ...run,
-                // Once cancelled, the cancelled status is sticky; the handler may
-                // still emit a completion event after the cancel signal has landed.
-                status: run.status === "cancelled" ? "cancelled" : "succeeded",
-                finished_at: run.finished_at ?? now,
                 events: [...run.events, event],
-            };
+            });
         case "run.failed":
-            return {
+            return reconcileBuildRunTerminalStatus({
                 ...run,
-                status: run.status === "cancelled" ? "cancelled" : "failed",
-                finished_at: run.finished_at ?? now,
                 events: [...run.events, event],
-            };
+            });
         case "run.cancelled":
-            return {
+            return reconcileBuildRunTerminalStatus({
                 ...run,
-                status: "cancelled",
-                finished_at: run.finished_at ?? now,
                 events: [...run.events, event],
-            };
+            });
         case "readiness.updated":
             return {
                 ...run,

package/dist/packages/runtime/runtime-executor.d.ts

@@ -0,0 +1,22 @@
+import { type LocalExecutorStatus } from "./schemas/index.js";
+import type { AgentPrefs, AgentRecord, RoleMap } from "../contracts/lib/schema.js";
+export interface AgentsRegistryState {
+    agents: AgentRecord[];
+    role_map: RoleMap;
+    active_agent: AgentRecord | null;
+}
+export interface AgentsRegistryRoleState {
+    role_map: RoleMap;
+    active_agent: AgentRecord | null;
+}
+export declare function getExecutorStatus(): LocalExecutorStatus;
+export declare function selectExecutor(requestValue: unknown): LocalExecutorStatus;
+export declare function getAgentsRegistry(): AgentsRegistryState;
+export declare function registerCustomAgent(input: {
+    name: string;
+    display_name: string;
+    command: string;
+}): AgentsRegistryState;
+export declare function unregisterCustomAgent(name: string): AgentsRegistryState;
+export declare function patchAgentsRoleMap(patch: Record<string, string>): AgentsRegistryRoleState;
+export declare function setAgentPrefs(name: string, prefs: AgentPrefs): AgentsRegistryState;

package/dist/packages/runtime/runtime-executor.js

@@ -0,0 +1,131 @@
+import { detectAgents, resolveAgent, supportsAutomatedRuns, } from "./agents/lib/detection.js";
+import { loadUserConfig, saveUserConfig, } from "./agents/lib/user-config.js";
+import { AGENTS } from "./agents/lib/constants.js";
+import { loadAgentsRegistry, patchRoleMap, registerCustomAgent as registerCustomAgentRecord, setActiveAgent, setAgentPrefs as setAgentPrefsRecord, unregisterCustomAgent as unregisterCustomAgentRecord, } from "./agents/registry.js";
+import { LocalExecutorSelectRequestSchema, LocalExecutorStatusSchema, } from "./schemas/index.js";
+function configuredAgentName() {
+    const config = loadUserConfig();
+    if (!config)
+        return null;
+    const configured = AGENTS.find((agent) => agent.command === config.agentCommand) ??
+        AGENTS.find((agent) => agent.name === config.agent) ??
+        AGENTS.find((agent) => agent.displayName === config.agent);
+    return configured?.name ?? null;
+}
+function detectedExecutorOptions(currentAgentName) {
+    return detectAgents()
+        .filter(supportsAutomatedRuns)
+        .map((agent) => ({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        current: agent.name === currentAgentName,
+    }));
+}
+export function getExecutorStatus() {
+    const checkedAt = new Date().toISOString();
+    try {
+        const resolved = resolveAgent();
+        const currentName = resolved.agent?.name ?? configuredAgentName();
+        const availableExecutors = detectedExecutorOptions(currentName);
+        if (!resolved.agent) {
+            return LocalExecutorStatusSchema.parse({
+                kind: "interf-local-executor-status",
+                version: 1,
+                status: "unavailable",
+                checked_at: checkedAt,
+                executor: null,
+                available_executors: availableExecutors,
+                message: resolved.error ?? "No supported local coding agent is configured.",
+            });
+        }
+        return LocalExecutorStatusSchema.parse({
+            kind: "interf-local-executor-status",
+            version: 1,
+            status: "connected",
+            checked_at: checkedAt,
+            executor: {
+                name: resolved.agent.name,
+                display_name: resolved.agent.displayName,
+                command: resolved.agent.command,
+            },
+            available_executors: availableExecutors.length > 0
+                ? availableExecutors
+                : [{
+                        name: resolved.agent.name,
+                        display_name: resolved.agent.displayName,
+                        command: resolved.agent.command,
+                        current: true,
+                    }],
+            message: `${resolved.agent.displayName} is configured for local Interf actions.`,
+        });
+    }
+    catch (error) {
+        const currentName = configuredAgentName();
+        return LocalExecutorStatusSchema.parse({
+            kind: "interf-local-executor-status",
+            version: 1,
+            status: "unavailable",
+            checked_at: checkedAt,
+            executor: null,
+            available_executors: detectedExecutorOptions(currentName),
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export function selectExecutor(requestValue) {
+    const request = LocalExecutorSelectRequestSchema.parse(requestValue);
+    const selected = detectAgents()
+        .filter(supportsAutomatedRuns)
+        .find((agent) => agent.name === request.agent);
+    if (!selected) {
+        throw new Error(`Local agent "${request.agent}" is not detected or cannot run Interf runs.`);
+    }
+    const current = loadUserConfig();
+    saveUserConfig({
+        agent: selected.name,
+        agentCommand: selected.command,
+        skillsInstalled: current?.skillsInstalled ?? false,
+        initialized: current?.initialized ?? new Date().toISOString(),
+    });
+    // Mirror the selection into the role-map. `setActiveAgent` also sweeps
+    // any role still pointing at the previous active so single-active-agent
+    // setups stay coherent across CLIs.
+    try {
+        setActiveAgent(selected.name);
+    }
+    catch {
+        // Best effort — the registry update is convenience for the new
+        // role-aware path. The user_config.json write above is the source of
+        // truth for the previous `getExecutorStatus()`.
+    }
+    return getExecutorStatus();
+}
+export function getAgentsRegistry() {
+    const registry = loadAgentsRegistry();
+    return {
+        agents: registry.agents,
+        role_map: registry.roleMap,
+        active_agent: registry.activeAgent,
+    };
+}
+export function registerCustomAgent(input) {
+    registerCustomAgentRecord(input);
+    return getAgentsRegistry();
+}
+export function unregisterCustomAgent(name) {
+    unregisterCustomAgentRecord(name);
+    return getAgentsRegistry();
+}
+export function patchAgentsRoleMap(patch) {
+    patchRoleMap(patch);
+    const registry = loadAgentsRegistry();
+    return {
+        role_map: registry.roleMap,
+        active_agent: registry.activeAgent,
+    };
+}
+export function setAgentPrefs(name, prefs) {
+    setAgentPrefsRecord(name, prefs);
+    return getAgentsRegistry();
+}

package/dist/packages/runtime/runtime-jobs.d.ts

@@ -0,0 +1,13 @@
+import { type LocalJobEvent, type LocalJobRunResource } from "./schemas/index.js";
+import type { LocalServiceJobRunContext, LocalServiceRuntime } from "./runtime.js";
+export declare function listJobs(projectDataDir: string): LocalJobRunResource[];
+export declare function getJob(projectDataDir: string, runId: string): LocalJobRunResource | null;
+export declare function getJobEvents(projectDataDir: string, runId: string): LocalJobEvent[] | null;
+export declare function createJobRun(runtime: LocalServiceRuntime, projectDataDir: string, requestValue: unknown): LocalJobRunResource;
+export declare function appendJobRunEvent(runtime: LocalServiceRuntime, projectDataDir: string, runId: string, requestValue: unknown): LocalJobRunResource | null;
+export declare function createBenchmarkQuestionDraftRun(runtime: LocalServiceRuntime, projectDataDir: string, requestValue: unknown): Promise<LocalJobRunResource>;
+export declare function createBuildPlanAuthoringRun(runtime: LocalServiceRuntime, projectDataDir: string, requestValue: unknown, jobType?: "build-plan-draft" | "build-plan-improvement"): Promise<LocalJobRunResource>;
+export declare function jobRunContext(runtime: LocalServiceRuntime, projectDataDir: string, runId: string): LocalServiceJobRunContext;
+export declare function writeJobRun(runtime: LocalServiceRuntime, projectDataDir: string, run: LocalJobRunResource): void;
+export declare function setJobRunResult(runtime: LocalServiceRuntime, projectDataDir: string, runId: string, result: unknown): void;
+export declare function finalizeInterruptedJobRuns(runtime: LocalServiceRuntime, projectDataDir: string): void;