@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/runtime/agents/lib/shells.js

@@ -0,0 +1,383 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { buildShellSourceState, loadBuildStageInputs, loadContextGraphSourceManifest, loadContextGraphSourceState, } from "../../build/source-manifest.js";
+import { CHECK_PARAM_CONTRACTS, CHECK_KINDS, SourceManifestSchema, StageInputsSchema, } from "../../../contracts/lib/schema.js";
+import { stageExecutionShellsRoot, buildPlanImprovementLoopRoot, buildPlanPackagePathForContextGraph, contextGraphInterfConfigPath, contextGraphRuntimeSourceManifestPath, contextGraphRuntimeRoot, } from "../../build/context-graph-paths.js";
+import { writeFileAtomic, writeJsonAtomic } from "../../build/atomic-fs.js";
+import { resolveBuildPlanImprovementReviewSourcePaths } from "../../../build-plans/package/build-plan-review-paths.js";
+import { copyIfExists, copyResolvedTree, freezePreservedShell, writeIfChanged, writeNativeSkillCopies, } from "./shell-fs.js";
+import { shellLogsPath, shellRuntimePath, } from "./shell-paths.js";
+import { writeStageExecutionWorkspaceManifest, } from "./shell-workspace.js";
+import { readBuildPlanImprovementDoc, readContextGraphQuerySkillSource, renderBuildPlanAuthoringAgents, renderBuildPlanAuthoringSkill, renderBuildPlanImprovementAgents, renderBuildPlanImprovementSkill, renderClaudeBootstrap, renderSourceFilesTestAgents, renderSourceFilesTestQuerySkill, renderStageExecutionAgents, renderStageExecutionSkill, renderContextGraphAgents, renderContextGraphQueryNativeSkill, renderContextGraphQuerySkill, } from "./shell-templates.js";
+import { buildStageArtifactMounts, ensureBuildExecutionSurface, projectBuildPlanMetadata, projectStageArtifactMountAliases, projectContextGraphReviewArtifactsState, projectContextGraphRuntimeArtifacts, projectContextGraphSchemaArtifacts, readStageBuildPlanDoc, stageMaterializedArtifactSet, syncStageExecutionShellWrites, writeExecutionShellPathsFile, } from "./shell-projection.js";
+export { syncStageExecutionShellWrites };
+export { renderClaudeBootstrap, renderContextGraphQuerySkill };
+function shellRelativePathInside(shellRoot, locator) {
+    const absolutePath = resolve(shellRoot, locator);
+    const relativePath = relative(shellRoot, absolutePath);
+    if (relativePath === "" || relativePath.startsWith("..") || resolve(relativePath) === relativePath) {
+        return null;
+    }
+    return absolutePath;
+}
+export function validateStageExecutionShellInputs(options) {
+    const canonicalInputs = loadBuildStageInputs(options.contextGraphPath, options.stage.id);
+    if (!canonicalInputs) {
+        return { ok: false, summary: `Missing canonical stage inputs for ${options.stage.id}.` };
+    }
+    const canonicalManifest = loadContextGraphSourceManifest(options.contextGraphPath);
+    if (!canonicalManifest) {
+        return { ok: false, summary: "Missing canonical Source Manifest for stage execution." };
+    }
+    if (canonicalInputs.version !== 3 || canonicalInputs.source_manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Canonical stage inputs are not backed by the current Source Manifest." };
+    }
+    const shellInputsPath = shellRuntimePath(options.shellRoot, "stage-inputs.json");
+    if (!existsSync(shellInputsPath)) {
+        return { ok: false, summary: "Stage shell is missing runtime/stage-inputs.json." };
+    }
+    let shellInputs;
+    try {
+        shellInputs = StageInputsSchema.parse(JSON.parse(readFileSync(shellInputsPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Stage shell inputs are invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (shellInputs.source_state_id !== canonicalInputs.source_state_id) {
+        return { ok: false, summary: "Stage shell inputs do not match the canonical Source state id." };
+    }
+    if (shellInputs.version !== 3 || shellInputs.source_manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Stage shell inputs do not match the canonical Source Manifest id." };
+    }
+    if (shellInputs.inputs.length !== canonicalInputs.inputs.length || shellInputs.input_total !== canonicalInputs.input_total) {
+        return { ok: false, summary: "Stage shell input count does not match the canonical stage input count." };
+    }
+    const shellManifestPath = shellRuntimePath(options.shellRoot, "source-manifest.json");
+    if (!existsSync(shellManifestPath)) {
+        return { ok: false, summary: "Stage shell is missing runtime/source-manifest.json." };
+    }
+    let shellManifest;
+    try {
+        shellManifest = SourceManifestSchema.parse(JSON.parse(readFileSync(shellManifestPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Stage shell Source Manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (shellManifest.manifest_id !== canonicalManifest.manifest_id) {
+        return { ok: false, summary: "Stage shell Source Manifest does not match the canonical manifest id." };
+    }
+    const shellInputsByKey = new Map(shellInputs.inputs.map((input) => [`${input.source_file_id}\0${input.path}`, input]));
+    for (const canonicalInput of canonicalInputs.inputs) {
+        const key = `${canonicalInput.source_file_id}\0${canonicalInput.path}`;
+        const shellInput = shellInputsByKey.get(key);
+        if (!shellInput) {
+            return { ok: false, summary: `Stage shell is missing source input ${canonicalInput.path}.` };
+        }
+        if (canonicalInput.content_hash && shellInput.content_hash !== canonicalInput.content_hash) {
+            return { ok: false, summary: `Stage shell source input ${canonicalInput.path} has a changed content hash.` };
+        }
+        if (shellInput.locator !== canonicalInput.locator) {
+            return { ok: false, summary: `Stage shell source input ${canonicalInput.path} has a changed locator.` };
+        }
+    }
+    return { ok: true, summary: "Stage shell inputs match canonical source slices." };
+}
+export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
+    let changed = false;
+    changed = writeIfChanged(join(rootPath, "AGENTS.md"), `${agentsContent.trimEnd()}\n`) || changed;
+    changed =
+        writeIfChanged(join(rootPath, "CLAUDE.md"), renderClaudeBootstrap(agentsContent)) || changed;
+    changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
+    return changed;
+}
+export function pruneStageExecutionShells(contextGraphPath) {
+    rmSync(stageExecutionShellsRoot(contextGraphPath), { recursive: true, force: true });
+}
+export function projectContextGraphQueryShell(contextGraphPath, contextGraphName, buildPlanId, options) {
+    const agentsContent = renderContextGraphAgents(contextGraphPath, contextGraphName, buildPlanId, options);
+    const querySkillContent = readContextGraphQuerySkillSource(contextGraphPath);
+    return writeNativeAgentSurface(contextGraphPath, agentsContent, "interf-query", renderContextGraphQueryNativeSkill(querySkillContent));
+}
+export function projectSourceFilesTestQueryShell(rootPath) {
+    return writeNativeAgentSurface(rootPath, renderSourceFilesTestAgents(), "interf-query", renderSourceFilesTestQuerySkill());
+}
+export function createStageExecutionShell(contextGraphPath, contextGraphName, buildPlanId, stage, writeArtifacts = []) {
+    const schema = ensureBuildExecutionSurface(contextGraphPath);
+    const materializedArtifacts = stageMaterializedArtifactSet(schema, stage, writeArtifacts);
+    const cleanWriteArtifacts = new Set(stage.writes.filter((artifactId) => !stage.reads.includes(artifactId)));
+    const shellsRoot = stageExecutionShellsRoot(contextGraphPath);
+    const shellRoot = join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+    mkdirSync(shellRoot, { recursive: true });
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, ".interf", "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "inputs"), { recursive: true });
+    mkdirSync(join(shellRoot, "outputs"), { recursive: true });
+    mkdirSync(shellLogsPath(shellRoot), { recursive: true });
+    copyResolvedTree({
+        sourcePath: contextGraphInterfConfigPath(contextGraphPath),
+        targetPath: join(shellRoot, "interf.json"),
+        shellType: "stage-execution",
+    });
+    copyIfExists(join(contextGraphRuntimeRoot(contextGraphPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"), "stage-execution");
+    const sourceState = loadContextGraphSourceState(contextGraphPath);
+    const stageInputs = loadBuildStageInputs(contextGraphPath, stage.id);
+    const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (sourceManifest) {
+        writeJsonAtomic(shellRuntimePath(shellRoot, "source-manifest.json"), sourceManifest);
+        copyIfExists(contextGraphRuntimeSourceManifestPath(contextGraphPath), join(shellRoot, ".interf", "runtime", "source-manifest.json"), "stage-execution");
+    }
+    if (sourceState && stageInputs) {
+        writeJsonAtomic(shellRuntimePath(shellRoot, "stage-inputs.json"), stageInputs);
+        writeJsonAtomic(shellRuntimePath(shellRoot, "source-state.json"), buildShellSourceState(sourceState, stageInputs));
+    }
+    writeStageSelfCheckScript(shellRoot);
+    projectContextGraphSchemaArtifacts(contextGraphPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedArtifacts, cleanWriteArtifacts);
+    projectBuildPlanMetadata(contextGraphPath, shellRoot, stage);
+    projectStageArtifactMountAliases(shellRoot, stage, schema);
+    writeExecutionShellPathsFile(shellRoot, buildPlanId, stage, buildStageArtifactMounts(contextGraphPath, shellRoot, stage, schema));
+    const agentsContent = renderStageExecutionAgents(contextGraphName, buildPlanId, stage);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageBuildPlanDoc(contextGraphPath, stage)));
+    writeStageExecutionWorkspaceManifest({
+        contextGraphPath,
+        shellRoot,
+        buildPlanId,
+        stage,
+    });
+    return {
+        rootPath: shellRoot,
+    };
+}
+function writeStageSelfCheckScript(shellRoot) {
+    const checkEvaluatorModuleUrl = new URL("../../build/check-evaluator.js", import.meta.url).href;
+    const runtimeSchemaModuleUrl = new URL("../../build/lib/schema.js", import.meta.url).href;
+    const contractsSchemaModuleUrl = new URL("../../../contracts/lib/schema.js", import.meta.url).href;
+    const script = [
+        "#!/usr/bin/env node",
+        "import { existsSync, readFileSync } from \"node:fs\";",
+        "import { dirname, resolve } from \"node:path\";",
+        "import { fileURLToPath } from \"node:url\";",
+        "",
+        `const { evaluateChecks } = await import(${JSON.stringify(checkEvaluatorModuleUrl)});`,
+        `const { RuntimeStageContractSchema } = await import(${JSON.stringify(runtimeSchemaModuleUrl)});`,
+        `const { SourceManifestSchema, StageEvidenceSchema, StageInputsSchema } = await import(${JSON.stringify(contractsSchemaModuleUrl)});`,
+        "",
+        "const shellRoot = resolve(dirname(fileURLToPath(import.meta.url)), \"..\");",
+        "const contractPath = resolve(shellRoot, \"runtime\", \"stage-contract.json\");",
+        "const contract = RuntimeStageContractSchema.parse(JSON.parse(readFileSync(contractPath, \"utf8\")));",
+        "const artifactResults = [];",
+        "const evidenceFailures = [];",
+        "const inputFailures = [];",
+        "const stageInputsPath = resolve(shellRoot, \"runtime\", \"stage-inputs.json\");",
+        "",
+        "if (!existsSync(stageInputsPath)) {",
+        "  inputFailures.push(\"runtime/stage-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const stageInputs = StageInputsSchema.parse(JSON.parse(readFileSync(stageInputsPath, \"utf8\")));",
+        "    if (stageInputs.input_total !== stageInputs.inputs.length) {",
+        "      inputFailures.push(`stage-inputs input_total ${stageInputs.input_total} does not match ${stageInputs.inputs.length}.`);",
+        "    }",
+        "    const manifestPath = resolve(shellRoot, \"runtime\", \"source-manifest.json\");",
+        "    if (!existsSync(manifestPath)) {",
+        "      inputFailures.push(\"runtime/source-manifest.json was not written.\");",
+        "    } else {",
+        "      const manifest = SourceManifestSchema.parse(JSON.parse(readFileSync(manifestPath, \"utf8\")));",
+        "      if (stageInputs.version !== 3 || stageInputs.source_manifest_id !== manifest.manifest_id) {",
+        "        inputFailures.push(\"stage inputs are not backed by runtime/source-manifest.json.\");",
+        "      }",
+        "    }",
+        "  } catch (error) {",
+        "    inputFailures.push(`stage inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
+        "for (const writeContract of contract.artifacts.write_contracts) {",
+        "  const result = evaluateChecks(writeContract.checks, {",
+        "    rootPath: shellRoot,",
+        "    targetPath: writeContract.path,",
+        "    counts: contract.counts,",
+        "  });",
+        "  artifactResults.push({",
+        "    artifact_id: writeContract.artifact_id,",
+        "    path: writeContract.path,",
+        "    check_results: result.check_results,",
+        "    failures: result.failures,",
+        "  });",
+        "}",
+        "",
+        "const failures = artifactResults.flatMap((artifact) =>",
+        "  artifact.failures.map((failure) => ({ artifact, failure })),",
+        ");",
+        "const totalChecks = artifactResults.reduce((total, artifact) => total + artifact.check_results.length, 0);",
+        "const passedChecks = artifactResults.reduce(",
+        "  (total, artifact) => total + artifact.check_results.filter((check) => check.passed).length,",
+        "  0,",
+        ");",
+        "",
+        "if (contract.contract_type === \"build-file-evidence\") {",
+        "  const evidencePath = resolve(shellRoot, \"runtime\", \"stage-evidence.json\");",
+        "  if (!existsSync(evidencePath)) {",
+        "    evidenceFailures.push(\"runtime/stage-evidence.json was not written.\");",
+        "  } else {",
+        "    try {",
+        "      const evidence = StageEvidenceSchema.parse(JSON.parse(readFileSync(evidencePath, \"utf8\")));",
+        "      if (evidence.run_id !== contract.run_id) {",
+        "        evidenceFailures.push(`stage evidence run_id ${evidence.run_id} does not match ${contract.run_id}.`);",
+        "      }",
+        "      if (evidence.stage !== contract.stage) {",
+        "        evidenceFailures.push(`stage evidence stage ${evidence.stage} does not match ${contract.stage}.`);",
+        "      }",
+        "      const evidenceItemsWithRefs = evidence.items.filter((item) => item.source_refs.length > 0 || item.output_refs.length > 0);",
+        "      if (evidenceItemsWithRefs.length === 0) {",
+        "        evidenceFailures.push(\"stage evidence needs at least one source/output evidence item.\");",
+        "      }",
+        "      const writableArtifacts = new Set(contract.artifacts.writes);",
+        "      for (const item of evidence.items) {",
+        "        for (const ref of item.output_refs) {",
+        "          if (!writableArtifacts.has(ref.artifact_id)) {",
+        "            evidenceFailures.push(`stage evidence output artifact ${ref.artifact_id} is not a declared write.`);",
+        "          }",
+        "          if (!existsSync(resolve(shellRoot, ref.path))) {",
+        "            evidenceFailures.push(`stage evidence output path ${ref.path} does not exist.`);",
+        "          }",
+        "        }",
+        "      }",
+        "    } catch (error) {",
+        "      evidenceFailures.push(`stage evidence JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "    }",
+        "  }",
+        "}",
+        "",
+        "if (failures.length === 0 && evidenceFailures.length === 0 && inputFailures.length === 0) {",
+        "  console.log(`VALID: ${contract.stage} stage outputs satisfy ${passedChecks}/${totalChecks} deterministic check(s).`);",
+        "  process.exit(0);",
+        "}",
+        "",
+        "console.log(`INVALID: ${failures.length + evidenceFailures.length + inputFailures.length} required deterministic check(s) failed for stage ${contract.stage}.`);",
+        "for (const { artifact, failure } of failures) {",
+        "  console.log(`- ${artifact.artifact_id} (${artifact.path}) / ${failure.check_id}: ${failure.summary}`);",
+        "  if (failure.details) {",
+        "    console.log(`  details: ${JSON.stringify(failure.details)}`);",
+        "  }",
+        "}",
+        "for (const failure of evidenceFailures) {",
+        "  console.log(`- stage evidence: ${failure}`);",
+        "}",
+        "for (const failure of inputFailures) {",
+        "  console.log(`- stage input: ${failure}`);",
+        "}",
+        "process.exit(1);",
+        "",
+    ].join("\n");
+    writeFileAtomic(shellRuntimePath(shellRoot, "check-stage.mjs"), script);
+}
+export function freezeStageExecutionShell(rootPath) {
+    return freezePreservedShell(rootPath, "stage-execution");
+}
+export function createBuildPlanAuthoringShell(options) {
+    const shellRoot = mkdtempSync(join(tmpdir(), `interf-build-plan-author-${options.buildPlanId}-`));
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    mkdirSync(join(shellRoot, "logs"), { recursive: true });
+    const context = {
+        kind: "interf-build-plan-authoring",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        authoring_mode: "from-scratch",
+        build_plan_id: options.buildPlanId,
+        build_plan_label: options.label,
+        ...(options.referenceBuildPlanId ? { reference_build_plan_id: options.referenceBuildPlanId } : {}),
+        intent: options.intent,
+        ...(options.userPrepInstructions ? { user_prep_instructions: options.userPrepInstructions } : {}),
+        allowed_check_kinds: CHECK_KINDS,
+        check_param_contracts: CHECK_PARAM_CONTRACTS,
+        requested_artifacts: options.requestedArtifacts ?? [],
+        checks: options.checks,
+        artifact_requirements: options.artifactRequirements ?? [],
+        project: {
+            source_folder_path: options.sourceFolderPath,
+            source_context: options.sourceContext ?? null,
+        },
+    };
+    writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
+    writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
+        kind: "interf-source-locator",
+        version: 1,
+        generated_at: new Date().toISOString(),
+        source: {
+            kind: "local-folder",
+            locator: options.sourceFolderPath,
+        },
+        note: "Interf does not pre-scan Source files for Build Plan authoring. The authoring agent inspects this locator through its own Source access.",
+    }, null, 2)}\n`);
+    copyResolvedTree({
+        sourcePath: options.buildPlanPath,
+        targetPath: join(shellRoot, "build-plan"),
+        shellType: "build-plan-authoring",
+    });
+    writeNativeAgentSurface(shellRoot, renderBuildPlanAuthoringAgents({
+        buildPlanId: options.buildPlanId,
+        label: options.label,
+        referenceBuildPlanId: options.referenceBuildPlanId ?? null,
+    }), "interf-build-plan-author", renderBuildPlanAuthoringSkill());
+    return {
+        rootPath: shellRoot,
+        buildPlanBeforePath: join(shellRoot, "artifacts", "build-plan-before"),
+        buildPlanAfterPath: join(shellRoot, "artifacts", "build-plan-after"),
+        promptLogPath: join(shellRoot, "logs", "build-plan-author.prompt.txt"),
+        eventLogPath: join(shellRoot, "logs", "build-plan-author.events.ndjson"),
+        statusLogPath: join(shellRoot, "logs", "build-plan-author.status.log"),
+    };
+}
+export function createBuildPlanImprovementShell(options) {
+    const schema = ensureBuildExecutionSurface(options.contextGraphPath);
+    const loopRootPath = buildPlanImprovementLoopRoot(options.contextGraphPath, options.runId, options.loopIndex);
+    const shellRoot = join(loopRootPath, "shell");
+    mkdirSync(shellRoot, { recursive: true });
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    mkdirSync(join(loopRootPath, "logs"), { recursive: true });
+    writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
+    projectContextGraphReviewArtifactsState(options.contextGraphPath, shellRoot, schema);
+    copyResolvedTree({
+        sourcePath: buildPlanPackagePathForContextGraph(options.contextGraphPath),
+        targetPath: join(shellRoot, "build-plan"),
+        shellType: "build-plan-improvement",
+    });
+    copyIfExists(contextGraphInterfConfigPath(options.contextGraphPath), join(shellRoot, "interf.json"), "build-plan-improvement");
+    projectContextGraphRuntimeArtifacts(options.contextGraphPath, shellRoot);
+    const reviewSources = resolveBuildPlanImprovementReviewSourcePaths(options.contextGraphPath);
+    if (reviewSources.executionShells) {
+        copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "build-plan-improvement");
+    }
+    if (reviewSources.benchmarkRuns) {
+        copyIfExists(reviewSources.benchmarkRuns, join(shellRoot, "artifacts", "benchmark-runs"), "build-plan-improvement");
+    }
+    if (reviewSources.targetTestRuns) {
+        copyIfExists(reviewSources.targetTestRuns, join(shellRoot, "artifacts", "test-runs"), "build-plan-improvement");
+    }
+    if (reviewSources.targetTestSandboxes) {
+        copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "build-plan-improvement");
+    }
+    const agentsContent = renderBuildPlanImprovementAgents(options.contextGraphName, options.buildPlanId, options.loopIndex);
+    writeNativeAgentSurface(shellRoot, agentsContent, "interf-build-plan-improver", renderBuildPlanImprovementSkill(options.buildPlanId, options.loopIndex, readBuildPlanImprovementDoc(options.contextGraphPath)));
+    return {
+        rootPath: shellRoot,
+        loopRootPath,
+        buildPlanBeforePath: join(loopRootPath, "build-plan-before"),
+        buildPlanAfterPath: join(loopRootPath, "build-plan-after"),
+        promptLogPath: join(loopRootPath, "logs", "build-plan-improver.prompt.txt"),
+        eventLogPath: join(loopRootPath, "logs", "build-plan-improver.events.ndjson"),
+        statusLogPath: join(loopRootPath, "logs", "build-plan-improver.status.log"),
+    };
+}
+export function freezeBuildPlanImprovementShell(rootPath) {
+    return freezePreservedShell(rootPath, "build-plan-improvement");
+}

package/dist/packages/{engine → runtime}/agents/lib/user-config.d.ts

@@ -1,5 +1,11 @@
-import { type InterfUserConfig } from "./schema.js";
-export type { InterfUserConfig } from "./schema.js";
+import { z } from "zod";
+export declare const InterfUserConfigSchema: z.ZodObject<{
+    agent: z.ZodString;
+    agentCommand: z.ZodString;
+    skillsInstalled: z.ZodBoolean;
+    initialized: z.ZodString;
+}, z.core.$strip>;
+export type InterfUserConfig = z.infer<typeof InterfUserConfigSchema>;
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export declare function interfHome(): string;
 /** `~/.interf/config.json` — local executor preferences. */

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

@@ -1,8 +1,14 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { z } from "zod";
 import { readJsonFileWithSchema } from "../../../contracts/utils/parse.js";
-import { interfHomeRoot } from "../../../contracts/lib/preparation-paths.js";
-import { InterfUserConfigSchema } from "./schema.js";
+import { interfHomeRoot } from "../../../contracts/lib/project-paths.js";
+export const InterfUserConfigSchema = z.object({
+    agent: z.string(),
+    agentCommand: z.string(),
+    skillsInstalled: z.boolean(),
+    initialized: z.string(),
+});
 /** `~/.interf/` (overridable via `INTERF_USER_HOME`). */
 export function interfHome() {
     return interfHomeRoot();

package/dist/packages/runtime/agents/providers/claude-code.d.ts

@@ -0,0 +1,13 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Claude Code provider.
+ *
+ * Configuration follows Anthropic's third-party integration spec:
+ * https://code.claude.com/docs/en/third-party-integrations
+ *
+ * The user-facing model knob is the alias (`opus`, `sonnet`, `haiku`)
+ * which Anthropic resolves server-side to the current pinned version.
+ * Hosts that need to pin a specific version do it via the
+ * `ANTHROPIC_DEFAULT_*_MODEL` env vars supplied by the user.
+ */
+export declare const claudeCodeProvider: AgentProvider;

package/dist/packages/runtime/agents/providers/claude-code.js

@@ -0,0 +1,45 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Claude Code provider.
+ *
+ * Configuration follows Anthropic's third-party integration spec:
+ * https://code.claude.com/docs/en/third-party-integrations
+ *
+ * The user-facing model knob is the alias (`opus`, `sonnet`, `haiku`)
+ * which Anthropic resolves server-side to the current pinned version.
+ * Hosts that need to pin a specific version do it via the
+ * `ANTHROPIC_DEFAULT_*_MODEL` env vars supplied by the user.
+ */
+export const claudeCodeProvider = {
+    name: "claude-code",
+    displayName: "Claude Code",
+    command: "claude",
+    homeDir: join(homedir(), ".claude"),
+    skillsDir: join(homedir(), ".claude", "skills"),
+    supportsAutomatedRuns: true,
+    defaultModel: "claude-sonnet-4-6",
+    defaultEffort: "low",
+    noiseFilters: [],
+    buildArgs(prompt, profile) {
+        const args = [
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--allowedTools",
+            "Read,Write,Edit,Bash,Grep,Glob,Agent",
+        ];
+        if (profile.model) {
+            args.push("--model", profile.model);
+        }
+        if (profile.effort) {
+            args.push("--effort", profile.effort);
+        }
+        return args;
+    },
+    buildEnv(baseEnv) {
+        return { ...baseEnv };
+    },
+};

package/dist/packages/runtime/agents/providers/codex.d.ts

@@ -0,0 +1,17 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Codex provider.
+ *
+ * Reasoning effort is passed via the documented config override
+ * (`-c model_reasoning_effort=...`) rather than a flag.
+ *
+ * The `SHELL` env var is stripped from the spawn so Codex picks a
+ * sandbox-safe default shell instead of inheriting the host login shell.
+ *
+ * Two stderr noise lines are expected on every run and must not be
+ * treated as preflight failures.
+ *
+ * Codex preflight is retried when it reports transient session-record
+ * errors that resolve on a second attempt.
+ */
+export declare const codexProvider: AgentProvider;

package/dist/packages/runtime/agents/providers/codex.js

@@ -0,0 +1,64 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SANDBOX_MODE = `work${"space-write"}`;
+/**
+ * Codex provider.
+ *
+ * Reasoning effort is passed via the documented config override
+ * (`-c model_reasoning_effort=...`) rather than a flag.
+ *
+ * The `SHELL` env var is stripped from the spawn so Codex picks a
+ * sandbox-safe default shell instead of inheriting the host login shell.
+ *
+ * Two stderr noise lines are expected on every run and must not be
+ * treated as preflight failures.
+ *
+ * Codex preflight is retried when it reports transient session-record
+ * errors that resolve on a second attempt.
+ */
+export const codexProvider = {
+    name: "codex",
+    displayName: "Codex",
+    command: "codex",
+    homeDir: join(homedir(), ".codex"),
+    skillsDir: join(homedir(), ".codex", "skills"),
+    supportsAutomatedRuns: true,
+    defaultModel: "gpt-5.3-codex",
+    defaultEffort: "high",
+    noiseFilters: [
+        /codex_core_skills::loader: failed to stat skills entry .*\/interf-[^ ]+ \(symlink\): No such file or directory/,
+        /codex_core::codex: failed to load skill .*\/gstack\/SKILL\.md: invalid description: exceeds maximum length of 1024 characters/,
+    ],
+    buildArgs(prompt, profile) {
+        const args = [
+            "exec",
+            "--json",
+            "-s",
+            SANDBOX_MODE,
+            "--skip-git-repo-check",
+        ];
+        if (profile.model) {
+            args.push("--model", profile.model);
+        }
+        if (profile.profile) {
+            args.push("--profile", profile.profile);
+        }
+        if (profile.effort) {
+            args.push("-c", `model_reasoning_effort=${JSON.stringify(profile.effort)}`);
+        }
+        args.push(prompt);
+        return args;
+    },
+    buildEnv(baseEnv) {
+        const env = { ...baseEnv };
+        delete env.SHELL;
+        return env;
+    },
+    isTransientPreflightFailure(stderr, errorMessage) {
+        const text = `${errorMessage}\n${stderr}`;
+        if (/usage limit/i.test(text))
+            return false;
+        return /failed to record rollout items/i.test(text)
+            || /thread\s+[0-9a-f-]+\s+not found/i.test(text);
+    },
+};

package/dist/packages/runtime/agents/providers/cursor.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProvider } from "./types.js";
+/**
+ * Cursor provider.
+ *
+ * Cursor is detected for `interf init` so the listing shows it, but
+ * Interf cannot drive automated Build runs through Cursor today.
+ * `buildArgs` therefore throws.
+ */
+export declare const cursorProvider: AgentProvider;

package/dist/packages/runtime/agents/providers/cursor.js

@@ -0,0 +1,24 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Cursor provider.
+ *
+ * Cursor is detected for `interf init` so the listing shows it, but
+ * Interf cannot drive automated Build runs through Cursor today.
+ * `buildArgs` therefore throws.
+ */
+export const cursorProvider = {
+    name: "cursor",
+    displayName: "Cursor",
+    command: "cursor",
+    homeDir: join(homedir(), ".cursor"),
+    skillsDir: join(homedir(), ".cursor", "skills"),
+    supportsAutomatedRuns: false,
+    noiseFilters: [],
+    buildArgs() {
+        throw new Error('Cursor is not yet supported for automated Build runs.');
+    },
+    buildEnv(baseEnv) {
+        return { ...baseEnv };
+    },
+};

package/dist/packages/runtime/agents/providers/index.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProvider } from "./types.js";
+export type { AgentProvider } from "./types.js";
+export declare const BUILT_IN_PROVIDERS: ReadonlyArray<AgentProvider>;
+/** Look up a built-in provider by name. Returns undefined for custom agents. */
+export declare function getBuiltInProvider(name: string): AgentProvider | undefined;
+/** True when `name` matches a built-in provider. */
+export declare function isBuiltInProviderName(name: string): boolean;
+/** All providers that support automated Build runs. */
+export declare function automatableBuiltInProviders(): AgentProvider[];

package/dist/packages/runtime/agents/providers/index.js

@@ -0,0 +1,31 @@
+/**
+ * Agent provider registry.
+ *
+ * The full set of built-in agent providers Interf knows about. Engine
+ * code consumes this list as data — there are no name comparisons or
+ * `if (agent === "codex")` branches outside the provider files.
+ *
+ * User-registered custom agents (`source: "user"` in the registry) flow
+ * through a separate generic provider that builds spawn args from a
+ * stored command template; that path lives outside this list.
+ */
+import { claudeCodeProvider } from "./claude-code.js";
+import { codexProvider } from "./codex.js";
+import { cursorProvider } from "./cursor.js";
+export const BUILT_IN_PROVIDERS = [
+    claudeCodeProvider,
+    codexProvider,
+    cursorProvider,
+];
+/** Look up a built-in provider by name. Returns undefined for custom agents. */
+export function getBuiltInProvider(name) {
+    return BUILT_IN_PROVIDERS.find((provider) => provider.name === name);
+}
+/** True when `name` matches a built-in provider. */
+export function isBuiltInProviderName(name) {
+    return BUILT_IN_PROVIDERS.some((provider) => provider.name === name);
+}
+/** All providers that support automated Build runs. */
+export function automatableBuiltInProviders() {
+    return BUILT_IN_PROVIDERS.filter((provider) => provider.supportsAutomatedRuns);
+}