@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,266 @@
+/**
+ * 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.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * 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 {
+    /** projectDataDir -> project id -> records (newest-first sorted). */
+    byProjectRoot = new Map();
+    /** projectDataDir -> runId -> project. */
+    runIndex = new Map();
+    get(projectDataDir, project, fill, runIdOf) {
+        const wsKey = resolve(projectDataDir);
+        let bucket = this.byProjectRoot.get(wsKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.byProjectRoot.set(wsKey, bucket);
+        }
+        const cached = bucket.get(project);
+        if (cached)
+            return cached;
+        const fresh = fill();
+        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), project);
+        }
+        return fresh;
+    }
+    /** 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 project's cached records and id index. */
+    invalidateProject(projectDataDir, project) {
+        const wsKey = resolve(projectDataDir);
+        const bucket = this.byProjectRoot.get(wsKey);
+        if (bucket) {
+            bucket.delete(project);
+            if (bucket.size === 0)
+                this.byProjectRoot.delete(wsKey);
+        }
+        const index = this.runIndex.get(wsKey);
+        if (index) {
+            for (const [runId, owner] of index) {
+                if (owner === project)
+                    index.delete(runId);
+            }
+            if (index.size === 0)
+                this.runIndex.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-(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 class ReadinessCache {
+    byProjectRoot = new Map();
+    get(projectDataDir, project, compute) {
+        const wsKey = resolve(projectDataDir);
+        let bucket = this.byProjectRoot.get(wsKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.byProjectRoot.set(wsKey, bucket);
+        }
+        const cached = bucket.get(project);
+        if (cached !== undefined)
+            return cached;
+        const fresh = compute();
+        bucket.set(project, fresh);
+        return fresh;
+    }
+    invalidateProject(projectDataDir, project) {
+        const wsKey = resolve(projectDataDir);
+        const bucket = this.byProjectRoot.get(wsKey);
+        if (bucket) {
+            bucket.delete(project);
+            if (bucket.size === 0)
+                this.byProjectRoot.delete(wsKey);
+        }
+    }
+    invalidateProjectRoot(projectDataDir) {
+        this.byProjectRoot.delete(resolve(projectDataDir));
+    }
+}
+/**
+ * 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 class MtimeListingCache {
+    static TTL_MS = 2000;
+    cache = new Map();
+    get(cacheKey, folderPath, fill) {
+        const now = Date.now();
+        const stat = safeStat(folderPath);
+        const currentMtime = stat?.mtimeMs ?? 0;
+        const entry = this.cache.get(cacheKey);
+        if (entry
+            && entry.mtimeMs === currentMtime
+            && entry.expiresAt > now) {
+            return entry.value;
+        }
+        const value = fill();
+        this.cache.set(cacheKey, {
+            mtimeMs: currentMtime,
+            expiresAt: now + MtimeListingCache.TTL_MS,
+            value,
+        });
+        return value;
+    }
+    invalidate(cacheKey) {
+        this.cache.delete(cacheKey);
+    }
+    invalidateAll() {
+        this.cache.clear();
+    }
+}
+/**
+ * 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 class BuildPlanListingCache {
+    cache = new Map();
+    get(cacheKey, rootPaths, fill) {
+        const fingerprint = rootPaths
+            .map((path) => `${path}:${safeStat(path)?.mtimeMs ?? 0}`)
+            .join("|");
+        const entry = this.cache.get(cacheKey);
+        if (entry && entry.key === fingerprint)
+            return entry.value;
+        const value = fill();
+        this.cache.set(cacheKey, { key: fingerprint, value });
+        return value;
+    }
+    invalidate(cacheKey) {
+        this.cache.delete(cacheKey);
+    }
+    invalidateAll() {
+        this.cache.clear();
+    }
+}
+function safeStat(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return statSync(path);
+    }
+    catch {
+        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();
+    }
+}
+/**
+ * Per-Build-run Context Graph resource cache.
+ *
+ * A succeeded Build's Context Graph is immutable: its on-disk folder
+ * (`graph-manifest.json`, source manifest, stage sessions, semantic graph) is
+ * frozen once the run reaches `succeeded`. Rebuilding the full
+ * `ContextGraphResource` — readiness join, semantic graph, build evidence,
+ * validation — on every read is the dominant cost of opening a built Project.
+ *
+ * The cache keys by `(projectDataDir, runId, manifestMtimeMs)`:
+ *  - `runId` scopes a single Build's output.
+ *  - `manifestMtimeMs` is the mtime of the Build's
+ *    `.interf/runtime/graph-manifest.json`. It busts the entry if the graph is
+ *    rebuilt or edited in place; a fresh Build produces a fresh `runId`, so
+ *    those never collide either.
+ *
+ * Entries without a readable manifest mtime (mtime 0) are not cached — that
+ * only happens for an in-flight or malformed Build, where the resource is
+ * still changing and must be recomputed.
+ */
+export class ContextGraphResourceCache {
+    byKey = new Map();
+    get(projectDataDir, runId, manifestPath, compute) {
+        const mtimeMs = safeStat(manifestPath)?.mtimeMs ?? 0;
+        // mtime 0 means the manifest is missing/unreadable — the graph is not yet
+        // a frozen, succeeded output, so recompute every time without caching.
+        if (mtimeMs === 0)
+            return compute();
+        const cacheKey = `${resolve(projectDataDir)}${runId}`;
+        const entry = this.byKey.get(cacheKey);
+        if (entry && entry.mtimeMs === mtimeMs)
+            return entry.value;
+        const value = compute();
+        this.byKey.set(cacheKey, { mtimeMs, value });
+        return value;
+    }
+    invalidateProject(projectDataDir) {
+        const prefix = `${resolve(projectDataDir)}`;
+        for (const key of this.byKey.keys()) {
+            if (key.startsWith(prefix))
+                this.byKey.delete(key);
+        }
+    }
+    invalidateAll() {
+        this.byKey.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;