@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/runtime.js

@@ -0,0 +1,431 @@
+import { resolve } from "node:path";
+import { RunListingCache, ReadinessCache, MtimeListingCache, BuildPlanListingCache, ContextGraphResourceCache, } from "./runtime-caches.js";
+import { LocalServiceHealthSchema, } from "./schemas/index.js";
+import { buildLocalServiceUrl, } from "./service/routes.js";
+import { resolveConfiguredSourceFolderPath } from "../projects/source-config.js";
+import { getExecutorStatus, getAgentsRegistry, patchAgentsRoleMap, registerCustomAgent, selectExecutor, setAgentPrefs, unregisterCustomAgent, } from "./runtime-executor.js";
+import { applyBuildPlanChange, getBuildPlanResource, listBuildPlans, } from "./runtime-build-plans.js";
+import { computeProjectReadiness, getProject, getProjectReadiness, getReadiness, getContextGraph, getContextGraphHandoff, listProjectReadiness, listProjects, listReadiness, listSourceFiles, listContextGraphs, getLatestContextGraph, listLatestContextGraphStageSessions, } from "./runtime-project-reads.js";
+import { applyReset, defaultProjectId, ensureContextGraphForRun, resolveProjectConfig, } from "./runtime-project-mutations.js";
+import { createBuildPlanAuthoringRun, createBenchmarkQuestionDraftRun, finalizeInterruptedJobRuns, getJob, getJobEvents, listJobs, } from "./runtime-jobs.js";
+import { cancelBuildRun, createBuildRun, expireIdempotencyKeyForTesting, finalizeInterruptedBuildRuns, findIdempotentBuildRun, getBuildRun, getBuildRunArtifacts, getBuildRunEvents, getBuildRunEvidence, listBuildRuns, listBuildRunsForProject, recordIdempotentBuildRun, } from "./runtime-build-runs.js";
+import { createVerifyRun, getVerifyRun, listVerifyRuns, listVerifyRunsForProject, } from "./runtime-verify-runs.js";
+import { createActionProposal, decideActionProposal, getActionProposal, listActionProposals, } from "./runtime-action-proposals.js";
+import { getRunObservability, listBuildPlanRuns, listRunObservability, } from "./runtime-observability.js";
+export class LocalServiceRuntime {
+    host;
+    port;
+    startedAt;
+    packageVersion;
+    ownerKind;
+    ownerPid;
+    handlers;
+    /**
+     * The seed root path the runtime was constructed with. Used as a
+     * non-Project fallback when a Project-independent route
+     * (Build Plans, action proposals, runs listings) needs an anchor to load
+     * shared state (user-library Build Plans, bundled Build Plans, etc).
+     */
+    rootPath;
+    /**
+     * Per-instance bearer token. Protected routes require this on the
+     * Authorization header. `null` means tokenless-dev mode (test harness).
+     */
+    authToken;
+    /**
+     * Auth dispatch mode. See {@link LocalServiceRuntimeOptions.authMode}.
+     * Default is `"hex"` so loopback engines and existing tests are unaffected.
+     */
+    authMode;
+    /**
+     * Active account / signed-in user for this engine instance. Populated at
+     * boot from `~/.interf/auth/session.json`. `null` for pre-auth /
+     * anonymous sessions; entitlement guards treat null as Free tier.
+     */
+    currentAccount = null;
+    /** Map of projectDataDir -> ProjectContext. */
+    projectContexts = new Map();
+    /** Hook called whenever a Project is registered or deregistered. */
+    onRegistryChanged = null;
+    /** In-flight runs across all projects. Used for `idle_for_seconds`. */
+    activeRunCount = 0;
+    // The fields below are package-internal but intentionally `public` so
+    // the sibling `runtime-*.ts` modules that hold the extracted method
+    // bodies can mutate them. They were `private` while every code path
+    // lived in this file; they are not part of the public engine API.
+    /**
+     * Active Build run cancellation handles, keyed by run id. Populated
+     * when a Build run is launched and cleared once the run reaches a
+     * terminal state. Each entry remembers where the persisted record lives
+     * so cancel can mark it without re-resolving the Project.
+     */
+    activeBuildRuns = new Map();
+    /**
+     * Active local job runs, keyed by run id. Build Plan drafting,
+     * Build Plan improvement, and benchmark-question drafting all persist
+     * through the local-job store; recovery must not mark these as
+     * interrupted while this runtime is still executing them.
+     */
+    activeJobRuns = new Set();
+    /**
+     * Idempotency-key cache for `POST .../build-runs`. Outer key is the
+     * resolved project root; inner key is the client-supplied idempotency
+     * value. Namespacing per project prevents key collisions across
+     * tenants on the same engine (CSO finding: a malicious project could
+     * otherwise hijack another project's run id by reusing its key).
+     * Entries expire after the idempotency TTL defined in `runtime-build-runs.ts`.
+     */
+    idempotencyKeyCache = new Map();
+    /**
+     * Read-side caches. Polling clients (Interf Desktop renderer, CLI status loops)
+     * hit list/get endpoints multiple times per second; without these,
+     * every request re-walks the filesystem and re-parses every JSON
+     * record through Zod. The runtime invalidates each cache on the
+     * matching write path. See {@link runtime-caches} for design notes.
+     */
+    buildRunCache = new RunListingCache();
+    verifyRunCache = new RunListingCache();
+    readinessCache = new ReadinessCache();
+    sourceFilesCache = new MtimeListingCache();
+    buildPlanListingCache = new BuildPlanListingCache();
+    /**
+     * Per-Build-run Context Graph resource cache. A succeeded Build's graph is
+     * immutable, so the full `ContextGraphResource` (readiness join, semantic
+     * graph, evidence, validation) is memoized keyed by run id + graph-manifest
+     * mtime. Busted on Build completion and Build Plan change via
+     * `invalidateProject` on the matching write paths.
+     */
+    contextGraphResourceCache = new ContextGraphResourceCache();
+    constructor(options) {
+        this.host = options.host;
+        this.port = options.port;
+        this.startedAt = options.startedAt ?? new Date().toISOString();
+        this.packageVersion = options.packageVersion;
+        this.ownerKind = options.ownerKind ?? "headless";
+        this.ownerPid = options.ownerPid;
+        this.handlers = options.handlers ?? {};
+        this.authToken = options.authToken ?? null;
+        this.authMode = options.authMode ?? "hex";
+        this.currentAccount = options.currentAccount ?? null;
+        this.rootPath = resolve(options.rootPath);
+    }
+    setBoundPort(port) {
+        this.port = port;
+    }
+    /** Set a hook that fires whenever the registered Projects change. */
+    setOnRegistryChanged(handler) {
+        this.onRegistryChanged = handler;
+    }
+    /**
+     * Register a Project with this runtime. Returns the ProjectContext.
+     * Idempotent: re-registering an existing Project updates `lastActivity`.
+     */
+    registerProject(projectDataDir) {
+        const resolved = resolve(projectDataDir);
+        const now = new Date().toISOString();
+        const existing = this.projectContexts.get(resolved);
+        if (existing) {
+            existing.lastActivity = now;
+            this.onRegistryChanged?.();
+            return existing;
+        }
+        const context = {
+            rootPath: resolved,
+            startedAt: now,
+            lastActivity: now,
+        };
+        this.projectContexts.set(resolved, context);
+        finalizeInterruptedBuildRuns(this, resolved);
+        finalizeInterruptedJobRuns(this, resolved);
+        this.onRegistryChanged?.();
+        return context;
+    }
+    /**
+     * Remove a project from the runtime. Returns true if a project was
+     * removed.
+     */
+    deregisterProject(projectDataDir) {
+        const resolved = resolve(projectDataDir);
+        const removed = this.projectContexts.delete(resolved);
+        if (removed) {
+            this.onRegistryChanged?.();
+        }
+        return removed;
+    }
+    /**
+     * Most recently active project, or the first registered if none has
+     * activity yet. Server code uses this as the fallback when a request
+     * does not specify a project. Throws if none are registered.
+     */
+    defaultProjectDataDir() {
+        if (this.projectContexts.size === 0) {
+            throw new Error("Local service has no registered Projects.");
+        }
+        let best = null;
+        let bestKey = -Infinity;
+        for (const context of this.projectContexts.values()) {
+            const key = Date.parse(context.lastActivity);
+            if (Number.isFinite(key) && key > bestKey) {
+                best = context;
+                bestKey = key;
+            }
+        }
+        return (best ?? this.projectContexts.values().next().value).rootPath;
+    }
+    /** Look up a Project context by rootPath. */
+    getProjectContext(projectDataDir) {
+        return this.projectContexts.get(resolve(projectDataDir)) ?? null;
+    }
+    /** All registered Projects, ordered by registration time. */
+    listRegisteredProjects() {
+        return Array.from(this.projectContexts.values()).sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
+    }
+    /** True when no projects are registered. */
+    hasNoProjects() {
+        return this.projectContexts.size === 0;
+    }
+    /** Number of registered Projects. */
+    registeredProjectCount() {
+        return this.projectContexts.size;
+    }
+    /** Increment in-flight run counter. Call when a long-running run starts. */
+    beginActiveRun() {
+        this.activeRunCount += 1;
+    }
+    /** Decrement in-flight run counter. Pair with `beginActiveRun`. */
+    endActiveRun() {
+        if (this.activeRunCount > 0)
+            this.activeRunCount -= 1;
+    }
+    /** Sum of in-flight runs across all projects. */
+    activeRuns() {
+        return this.activeRunCount;
+    }
+    beginActiveJobRun(runId) {
+        this.activeJobRuns.add(runId);
+    }
+    endActiveJobRun(runId) {
+        this.activeJobRuns.delete(runId);
+    }
+    /**
+     * Mark the project as recently active. Routes call this on entry so
+     * `idleForSeconds` and the registry graphs stay in sync with the
+     * actual request cadence.
+     */
+    touchProject(projectDataDir) {
+        const context = this.projectContexts.get(resolve(projectDataDir));
+        if (context) {
+            context.lastActivity = new Date().toISOString();
+        }
+    }
+    /** Seconds since the most recent Project activity (0 if active). */
+    idleForSeconds() {
+        const all = this.listRegisteredProjects();
+        if (all.length === 0)
+            return 0;
+        if (this.activeRunCount > 0)
+            return 0;
+        let mostRecent = 0;
+        for (const context of all) {
+            const ts = Date.parse(context.lastActivity);
+            if (Number.isFinite(ts) && ts > mostRecent)
+                mostRecent = ts;
+        }
+        if (mostRecent <= 0)
+            return 0;
+        const elapsed = Math.max(0, Date.now() - mostRecent);
+        return Math.floor(elapsed / 1000);
+    }
+    health(projectDataDir) {
+        const sourceFolderPath = projectDataDir ? resolveConfiguredSourceFolderPath(projectDataDir) : null;
+        return LocalServiceHealthSchema.parse({
+            kind: "interf-local-service-health",
+            version: 1,
+            status: "ok",
+            host: this.host,
+            port: this.port,
+            service_url: buildLocalServiceUrl({ host: this.host, port: this.port }),
+            ...(projectDataDir ? { control_path: projectDataDir } : {}),
+            source_folder_path: sourceFolderPath,
+            started_at: this.startedAt,
+            ...(this.packageVersion ? { package_version: this.packageVersion } : {}),
+            instance_started_at: this.startedAt,
+            active_runs: this.activeRunCount,
+            idle_for_seconds: this.idleForSeconds(),
+        });
+    }
+    // ─── Project reads ─────────────────────────────────────────────────
+    listProjects(projectDataDir) {
+        return listProjects(this, projectDataDir);
+    }
+    getProject(projectDataDir, projectName) {
+        return getProject(this, projectDataDir, projectName);
+    }
+    listProjectReadiness(projectDataDir) {
+        return listProjectReadiness(this, projectDataDir);
+    }
+    getProjectReadiness(projectDataDir, projectName) {
+        return getProjectReadiness(this, projectDataDir, projectName);
+    }
+    listReadiness(projectDataDir) {
+        return listReadiness(this, projectDataDir);
+    }
+    getReadiness(projectDataDir, projectName) {
+        return getReadiness(this, projectDataDir, projectName);
+    }
+    computeProjectReadiness(projectDataDir, project) {
+        return computeProjectReadiness(this, projectDataDir, project);
+    }
+    listSourceFiles(projectDataDir, projectName) {
+        return listSourceFiles(this, projectDataDir, projectName);
+    }
+    listContextGraphs(projectDataDir, projectName) {
+        return listContextGraphs(this, projectDataDir, projectName);
+    }
+    getContextGraph(projectDataDir, graphId) {
+        return getContextGraph(this, projectDataDir, graphId);
+    }
+    getLatestContextGraph(projectDataDir, projectName) {
+        return getLatestContextGraph(this, projectDataDir, projectName);
+    }
+    listLatestContextGraphStageSessions(projectDataDir, projectName) {
+        return listLatestContextGraphStageSessions(this, projectDataDir, projectName);
+    }
+    getContextGraphHandoff(projectDataDir, projectName) {
+        return getContextGraphHandoff(this, projectDataDir, projectName);
+    }
+    // ─── Build Plans ───────────────────────────────────────────────────
+    listBuildPlans(projectDataDir) {
+        return listBuildPlans(this, projectDataDir);
+    }
+    getBuildPlanResource(projectDataDir, buildPlanId) {
+        return getBuildPlanResource(this, projectDataDir, buildPlanId);
+    }
+    applyBuildPlanChange(projectDataDir, requestValue) {
+        return applyBuildPlanChange(this, projectDataDir, requestValue);
+    }
+    // ─── Project mutations ─────────────────────────────────────────────
+    applyReset(projectDataDir, requestValue) {
+        return applyReset(this, projectDataDir, requestValue);
+    }
+    resolveProjectConfig(projectDataDir, projectName, overrides = {}) {
+        return resolveProjectConfig(projectDataDir, projectName, overrides);
+    }
+    ensureContextGraphForRun(projectDataDir, projectConfig, runId) {
+        return ensureContextGraphForRun(projectDataDir, projectConfig, runId);
+    }
+    defaultProjectId(projectDataDir) {
+        return defaultProjectId(projectDataDir);
+    }
+    // ─── Executor + Agents ─────────────────────────────────────────────
+    getExecutorStatus() {
+        return getExecutorStatus();
+    }
+    selectExecutor(requestValue) {
+        return selectExecutor(requestValue);
+    }
+    getAgentsRegistry() {
+        return getAgentsRegistry();
+    }
+    registerCustomAgent(input) {
+        return registerCustomAgent(input);
+    }
+    unregisterCustomAgent(name) {
+        return unregisterCustomAgent(name);
+    }
+    patchAgentsRoleMap(patch) {
+        return patchAgentsRoleMap(patch);
+    }
+    setAgentPrefs(name, prefs) {
+        return setAgentPrefs(name, prefs);
+    }
+    // ─── Action proposals ──────────────────────────────────────────────
+    listActionProposals(projectDataDir) {
+        return listActionProposals(projectDataDir);
+    }
+    getActionProposal(projectDataDir, proposalId) {
+        return getActionProposal(projectDataDir, proposalId);
+    }
+    async createActionProposal(projectDataDir, requestValue) {
+        return createActionProposal(this, projectDataDir, requestValue);
+    }
+    async decideActionProposal(projectDataDir, proposalId, requestValue) {
+        return decideActionProposal(this, projectDataDir, proposalId, requestValue);
+    }
+    // ─── Run observability ─────────────────────────────────────────────
+    listRunObservability(projectDataDir) {
+        return listRunObservability(this, projectDataDir);
+    }
+    getRunObservability(projectDataDir, runId) {
+        return getRunObservability(this, projectDataDir, runId);
+    }
+    listBuildPlanRuns(projectDataDir, buildPlanId) {
+        return listBuildPlanRuns(this, projectDataDir, buildPlanId);
+    }
+    // ─── Build runs ────────────────────────────────────────────────────
+    listBuildRuns(projectDataDir) {
+        return listBuildRuns(this, projectDataDir);
+    }
+    listBuildRunsForProject(projectDataDir, projectName) {
+        return listBuildRunsForProject(this, projectDataDir, projectName);
+    }
+    getBuildRun(projectDataDir, runId) {
+        return getBuildRun(this, projectDataDir, runId);
+    }
+    getBuildRunEvents(projectDataDir, runId) {
+        return getBuildRunEvents(this, projectDataDir, runId);
+    }
+    getBuildRunEvidence(projectDataDir, runId) {
+        return getBuildRunEvidence(this, projectDataDir, runId);
+    }
+    getBuildRunArtifacts(projectDataDir, runId) {
+        return getBuildRunArtifacts(this, projectDataDir, runId);
+    }
+    async createBuildRun(projectDataDir, requestValue) {
+        return createBuildRun(this, projectDataDir, requestValue);
+    }
+    cancelBuildRun(runId) {
+        return cancelBuildRun(this, runId);
+    }
+    findIdempotentBuildRun(projectDataDir, key) {
+        return findIdempotentBuildRun(this, projectDataDir, key);
+    }
+    recordIdempotentBuildRun(projectDataDir, key, runId) {
+        return recordIdempotentBuildRun(this, projectDataDir, key, runId);
+    }
+    expireIdempotencyKeyForTesting(projectDataDir, key) {
+        return expireIdempotencyKeyForTesting(this, projectDataDir, key);
+    }
+    // ─── Verify runs ───────────────────────────────────────────────────
+    listVerifyRuns(projectDataDir) {
+        return listVerifyRuns(this, projectDataDir);
+    }
+    listVerifyRunsForProject(projectDataDir, projectName) {
+        return listVerifyRunsForProject(this, projectDataDir, projectName);
+    }
+    getVerifyRun(projectDataDir, runId) {
+        return getVerifyRun(this, projectDataDir, runId);
+    }
+    async createVerifyRun(projectDataDir, requestValue) {
+        return createVerifyRun(this, projectDataDir, requestValue);
+    }
+    // ─── Jobs ──────────────────────────────────────────────────────────
+    listJobs(projectDataDir) {
+        return listJobs(projectDataDir);
+    }
+    getJob(projectDataDir, runId) {
+        return getJob(projectDataDir, runId);
+    }
+    getJobEvents(projectDataDir, runId) {
+        return getJobEvents(projectDataDir, runId);
+    }
+    async createBenchmarkQuestionDraftRun(projectDataDir, requestValue) {
+        return createBenchmarkQuestionDraftRun(this, projectDataDir, requestValue);
+    }
+    async createBuildPlanAuthoringRun(projectDataDir, requestValue, jobType = "build-plan-draft") {
+        return createBuildPlanAuthoringRun(this, projectDataDir, requestValue, jobType);
+    }
+}
+export function createLocalServiceRuntime(options) {
+    return new LocalServiceRuntime(options);
+}