@interf/compiler 0.5.1 → 0.6.3

package/dist/lib/agent-shells.js

@@ -1,847 +1 @@
-import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
-import { basename, dirname, join, relative } from "node:path";
-import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { WORKFLOW_PACKAGE_DIR } from "./interf-detect.js";
-import { ensureCompiledZoneTargets, readCompiledSchemaFile, compiledZoneAbsolutePath, } from "./compiled-schema.js";
-import { stageExecutionShellsRoot, workflowImprovementLoopRoot, workflowPackagePathForCompiled, compiledInterfConfigPath, compiledRuntimeRoot, } from "./compiled-paths.js";
-import { resolveWorkflowImprovementReviewSourcePaths } from "./workflow-review-paths.js";
-const LOCAL_SKILL_ROOTS = [
-    ".claude/skills",
-    ".codex/skills",
-    ".agents/skills",
-    ".cursor/skills",
-];
-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;
-}
-function compiledQuerySkillSourcePath(compiledPath) {
-    return join(workflowPackagePathForCompiled(compiledPath), "use", "query", "SKILL.md");
-}
-function compiledZoneSummaryLines(compiledPath) {
-    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
-    if (!schema)
-        return ["- No compiled schema is available yet."];
-    return schema.zones
-        .filter((zone) => zone.id !== "raw" && zone.kind !== "runtime")
-        .map((zone) => `- \`${zone.id}\` -> \`${zone.path}\` (${zone.kind})`);
-}
-export function renderCompiledAgents(compiledPath, name, workflowId, about, options = {}) {
-    const workflowOriginSelected = options.workflowOriginSelected ?? workflowId;
-    const workflowLocalDraft = options.workflowLocalDraft === true;
-    const zoneLines = compiledZoneSummaryLines(compiledPath);
-    return [
-        `# ${name}`,
-        "",
-        "This is a compiled dataset built by Interf Compiler.",
-        "It is a file-based layer on top of the raw files, built for agents to navigate, retrieve evidence, and answer more accurately.",
-        "",
-        ...(about
-            ? [
-                `About: ${about}`,
-                "",
-            ]
-            : []),
-        "## How to use this compiled dataset",
-        "",
-        "1. Use the local native `interf-query` skill that Interf Compiler generated for this compiled dataset.",
-        "2. Let the workflow docs and compiled output zones guide retrieval instead of assuming a fixed note layout.",
-        "3. Use `raw/` when you need direct quotes, exact chart values, table lookups, or verification.",
-        "",
-        "## How this compiled dataset works",
-        "",
-        "- `.interf/interf.json` points to the local `raw/` snapshot via `source.path` and back to the dataset control plane via `source.control_path`.",
-        `- Workflow seed: \`${workflowOriginSelected}\`.`,
-        ...(workflowLocalDraft
-            ? ["- This compiled dataset now carries a local workflow draft improved from that seed. Recompiling this compiled dataset reuses the local `.interf/workflow/` package."]
-            : []),
-        `- Active local workflow id: \`${workflowId}\`.`,
-        "- `.interf/workflow/` is the local editable method package for this compiled dataset.",
-        "- `.interf/workflow/compiled.schema.json` is the deterministic output shape for this compiled dataset.",
-        "- `.interf/workflow/improve/` is the editable source for workflow-improvement loops.",
-        "- `.interf/workflow/use/query/` is the editable source for the generated native query shell.",
-        "- `.interf/workflow/compile/stages/` defines stage-specific docs that Interf Compiler projects into native execution shells for automated runs.",
-        "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
-        "- `raw/` contains the local raw snapshot used for evidence and verification.",
-        "- Compiled output zones are declared in `.interf/workflow/compiled.schema.json`.",
-        ...zoneLines,
-        "- `.interf/runtime/` holds CLI-owned runtime artifacts.",
-        "- `.interf/tests/` mirrors the latest dataset-level comparison and keeps detailed target runs plus preserved sandboxes.",
-        "- `.interf/tests/targets/` holds detailed raw and compiled target runs plus preserved test sandboxes.",
-        "",
-        "## Manual query rules",
-        "",
-        "- Prefer the workflow-declared compiled outputs before `raw/`.",
-        "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/workflow/use/query/SKILL.md`.",
-        "- Treat `.interf/` as method/runtime metadata, not answer evidence, unless explicitly asked to inspect workflow or test history.",
-        "- Use `raw/` for quotes, verification, ambiguity, or evidence the compiled layer does not expose well.",
-        "- If exact chart, table, or image-derived evidence matters, inspect the raw source and say whether the answer was text-derived, table-derived, or chart-derived.",
-        "",
-        "## Commands",
-        "",
-        "```",
-        "interf compile            build this compiled dataset",
-        "interf test               run saved truth checks against this compiled dataset",
-        "interf verify stage <id>  verify one workflow stage",
-        "interf verify compiled    verify the full workflow output",
-        "interf status             show deterministic health",
-        "```",
-        "",
-        "## Rules",
-        "",
-        "- Do not modify files under `raw/`.",
-        "- Treat compiled notes as working retrieval artifacts, not final truth.",
-        "- When confidence is low, verify against `raw/` before answering strongly.",
-        "",
-    ].join("\n");
-}
-export function renderCompiledQuerySkill() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note.toLowerCase()}`);
-    return [
-        "# Manual Query Loop",
-        "",
-        "This file is the editable authoring source for the generated native local `interf-query` skill.",
-        "",
-        "Default loop:",
-        "1. Read `workflow/README.md` and this file first.",
-        "2. Use the compiled output zones declared in `workflow/compiled.schema.json` before falling back to `raw/`.",
-        "3. Use `raw/` for direct quotes, verification, exact table lookups, and cases where the compiled layer is missing or ambiguous.",
-        "",
-        "Answering rule:",
-        "- do not modify files under `raw/`",
-        "- treat the workflow package as the method layer and the compiled zones as the working retrieval surface",
-        "- when a number is chart-derived, say that explicitly",
-        "- use `raw/` to confirm source page, metric family, or provenance when the compiled layer is missing or ambiguous",
-        ...chartNotes,
-        "- when the compiled layer is insufficient, verify in `raw/` and then answer",
-        "",
-        "You can edit this file to bias manual question-answering behavior for this compiled dataset.",
-        "",
-    ].join("\n");
-}
-function renderRawTestAgents() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
-    return [
-        "# Raw Test Shell",
-        "",
-        "This is an isolated raw-files test shell generated by Interf Compiler.",
-        "There is no compiled dataset in this shell.",
-        "",
-        "## How to use this shell",
-        "",
-        "1. Read this file first.",
-        "2. Use the local native `interf-query` skill available in this shell.",
-        "3. Read only from `raw/`.",
-        "",
-        "## Rules",
-        "",
-        "- Answer only from the files under `raw/`.",
-        "- There is no compiled dataset here, so do not assume any compiled output zones exist.",
-        "- Do not treat hidden runtime files or test artifacts as evidence.",
-        ...chartNotes,
-        "- Write the requested answer and trace files, then stop.",
-        "",
-    ].join("\n");
-}
-function renderRawTestQuerySkill() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
-    return [
-        "---",
-        "name: interf-query",
-        "description: >",
-        "  Native local query skill for an Interf raw test shell. Use it only",
-        "  to answer baseline questions directly from `raw/`.",
-        "---",
-        "",
-        "# Interf Raw Test Query",
-        "",
-        "This is the native local query skill for an isolated raw-files test shell.",
-        "",
-        "Loop:",
-        "1. Read `raw/` directly.",
-        "2. Verify exact claims against the raw files before answering strongly.",
-        ...chartNotes,
-        "8. Do not rely on compiled dataset artifacts because they do not exist in this shell.",
-        "",
-    ].join("\n");
-}
-function readCompiledQuerySkillSource(compiledPath) {
-    const filePath = compiledQuerySkillSourcePath(compiledPath);
-    if (!existsSync(filePath)) {
-        throw new Error(`Missing compiled query skill source at ${filePath}. Interf compile runs the local workflow package directly, so reseed or repair this compiled dataset instead of auto-healing query docs.`);
-    }
-    return readFileSync(filePath, "utf8").trim();
-}
-function stageShellWorkflowRoot(shellRoot) {
-    return join(shellRoot, WORKFLOW_PACKAGE_DIR);
-}
-function shellInputZonePath(shellRoot, zoneId) {
-    return join(shellRoot, "inputs", zoneId);
-}
-function shellOutputZonePath(shellRoot, zoneId) {
-    return join(shellRoot, "outputs", zoneId);
-}
-function shellZoneAliasMountPath(shellRoot, zone, mountKind) {
-    const mountRoot = mountKind === "inputs"
-        ? shellInputZonePath(shellRoot, zone.id)
-        : shellOutputZonePath(shellRoot, zone.id);
-    return zone.kind === "file"
-        ? join(mountRoot, basename(zone.path))
-        : mountRoot;
-}
-function describeShellZoneAliasMountPath(zone, mountKind) {
-    return zone.kind === "file"
-        ? `${mountKind}/${zone.id}/${basename(zone.path)}`
-        : `${mountKind}/${zone.id}`;
-}
-function shellRuntimePath(shellRoot, relativePath) {
-    return join(shellRoot, "runtime", relativePath);
-}
-function writeIfChanged(path, content) {
-    if (existsSync(path) && readFileSync(path, "utf8") === content) {
-        return false;
-    }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content);
-    return true;
-}
-function writeNativeSkillCopies(rootPath, skillName, content) {
-    let changed = false;
-    for (const skillsRoot of LOCAL_SKILL_ROOTS) {
-        const skillPath = join(rootPath, skillsRoot, skillName, "SKILL.md");
-        changed = writeIfChanged(skillPath, content) || changed;
-    }
-    return changed;
-}
-function linkPath(targetPath, linkPathname) {
-    mkdirSync(dirname(linkPathname), { recursive: true });
-    symlinkSync(targetPath, linkPathname);
-}
-function linkRelativePath(targetPath, linkPathname) {
-    mkdirSync(dirname(linkPathname), { recursive: true });
-    symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
-}
-function loadCompiledSchema(compiledPath) {
-    const workflowRoot = workflowPackagePathForCompiled(compiledPath);
-    const schema = readCompiledSchemaFile(workflowRoot);
-    if (!schema) {
-        throw new Error(`Missing workflow compiled schema at ${join(workflowRoot, "compiled.schema.json")}`);
-    }
-    return schema;
-}
-function zoneMap(schema) {
-    return new Map(schema.zones.map((zone) => [zone.id, zone]));
-}
-function zoneOrThrow(zones, zoneId) {
-    const zone = zones.get(zoneId);
-    if (!zone) {
-        throw new Error(`Missing compiled schema zone "${zoneId}" for stage shell projection.`);
-    }
-    return zone;
-}
-function normalizeArtifactRelativePath(path) {
-    return path
-        .replaceAll("\\", "/")
-        .replace(/^\.?\//, "")
-        .replace(/\/+$/g, "");
-}
-function relativePathEqualsOrWithin(basePath, candidatePath) {
-    const base = normalizeArtifactRelativePath(basePath);
-    const candidate = normalizeArtifactRelativePath(candidatePath);
-    if (base.length === 0 || candidate.length === 0)
-        return false;
-    return candidate === base || candidate.startsWith(`${base}/`);
-}
-function stageWriteZoneSet(schema, stage) {
-    return new Set(stage.writes.filter((zoneId) => schema.zones.some((zone) => zone.id === zoneId)));
-}
-function stageMaterializedZoneSet(schema, stage, writeArtifacts = []) {
-    const materialized = stageWriteZoneSet(schema, stage);
-    for (const zone of schema.zones) {
-        if (zone.kind === "runtime" && stage.reads.includes(zone.id)) {
-            materialized.add(zone.id);
-        }
-    }
-    for (const artifactPath of writeArtifacts) {
-        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
-        if (normalizedArtifactPath.length === 0)
-            continue;
-        const owner = schema.zones.find((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath));
-        if (owner) {
-            materialized.add(owner.id);
-        }
-    }
-    return materialized;
-}
-function ensureShellLocalProjection(sourcePath, targetPath, zone) {
-    if (existsSync(sourcePath)) {
-        copyResolvedTree({
-            sourcePath,
-            targetPath,
-            shellType: "stage-execution",
-        });
-        return;
-    }
-    if (zone.kind === "file") {
-        mkdirSync(dirname(targetPath), { recursive: true });
-        return;
-    }
-    mkdirSync(targetPath, { recursive: true });
-}
-function ensureCompiledExecutionSurface(compiledPath) {
-    mkdirSync(compiledRuntimeRoot(compiledPath), { recursive: true });
-    mkdirSync(workflowPackagePathForCompiled(compiledPath), { recursive: true });
-    const schema = loadCompiledSchema(compiledPath);
-    ensureCompiledZoneTargets(compiledPath, schema);
-    return schema;
-}
-function readStageMethodDoc(compiledPath, stage) {
-    const path = join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir, "SKILL.md");
-    if (!existsSync(path))
-        return null;
-    return readFileSync(path, "utf8").trim();
-}
-function stageWorkflowDocsPath(compiledPath, stage) {
-    return join(workflowPackagePathForCompiled(compiledPath), "compile", "stages", stage.skillDir);
-}
-function renderStageExecutionAgents(compiledName, workflowId, stage) {
-    return [
-        `# ${compiledName} — ${stage.label} Execution Shell`,
-        "",
-        "This is an ephemeral stage-execution shell generated by Interf Compiler.",
-        "It is for automated pipeline execution only, not for manual querying.",
-        "",
-        "## Start Here",
-        "",
-        "1. Read `runtime/stage-contract.json` now.",
-        "2. Read `runtime/paths.json` now.",
-        "3. Use the local native `interf-stage` skill now.",
-        `4. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
-        "",
-        "## Shell ABI",
-        "",
-        "- `inputs/<zone-id>/` = read mounts for the current stage.",
-        "- `outputs/<zone-id>/` = write mounts for the current stage.",
-        "- For file zones, `runtime/paths.json` points to the exact file path inside those mount roots.",
-        "- declared compiled zone paths are also projected at the shell root so workflow-relative contract paths stay valid.",
-        "- `runtime/` = stage contract and machine-readable path map for this shell.",
-        "- `workflow/` = workflow metadata, compiled schema, and docs for the current stage only.",
-        "",
-        "## Boundaries",
-        "",
-        `- Workflow: \`${workflowId}\`.`,
-        `- Contract type: \`${stage.contractType}\`.`,
-        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the compiled-dataset query shell.",
-        "- The compiled dataset root itself is not linked into this shell.",
-        "- Do not switch into query mode or act like a user-facing assistant.",
-        "- Do not modify files under `inputs/` unless the same zone is also mounted under `outputs/`.",
-        "",
-        "## Current Stage Zones",
-        "",
-        `- reads: ${stage.reads.join(", ")}`,
-        `- writes: ${stage.writes.join(", ")}`,
-        "",
-        "## Goal",
-        "",
-        "- complete the current stage",
-        "- honor the deterministic contract",
-        "- write outputs through the declared zone mounts",
-        "- stop when the stage is complete",
-        "",
-    ].join("\n");
-}
-function renderStageExecutionSkill(stage, stageMethodDoc) {
-    return [
-        "---",
-        "name: interf-stage",
-        "description: >",
-        `  Native local execution skill for the ${stage.label} stage in this`,
-        "  Interf Compiler run. Use it only inside an automated stage execution shell.",
-        "---",
-        "",
-        `# Interf Compiler Stage Execution — ${stage.label}`,
-        "",
-        "This local native skill exists for automated Interf Compiler stage execution.",
-        "Read `runtime/stage-contract.json` first.",
-        "Then read `runtime/paths.json` and use the mounted `inputs/` and `outputs/` zones for this stage.",
-        "Do not switch into manual query mode.",
-        "",
-        "## Current Stage",
-        "",
-        `- id: \`${stage.id}\``,
-        `- label: ${stage.label}`,
-        `- contract type: \`${stage.contractType}\``,
-        `- reads: ${stage.reads.join(", ")}`,
-        `- writes: ${stage.writes.join(", ")}`,
-        `- editable source: \`workflow/compile/stages/${stage.skillDir}/SKILL.md\``,
-        "",
-        ...(stageMethodDoc
-            ? [
-                "## Stage Method",
-                "",
-                stageMethodDoc,
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-function renderCompiledQueryNativeSkill(querySkillContent) {
-    return [
-        "---",
-        "name: interf-query",
-        "description: >",
-        "  Native local query skill for this compiled dataset built by Interf",
-        "  Compiler. Use it for manual questions against the compiled dataset and",
-        "  its raw fallback.",
-        "---",
-        "",
-        "# Interf Compiler Query",
-        "",
-        "This is the native local query skill for a compiled dataset built by Interf Compiler.",
-        "Use it when reading this compiled dataset manually.",
-        "Editable source: `.interf/workflow/use/query/SKILL.md`.",
-        "",
-        querySkillContent.trim(),
-        "",
-    ].join("\n");
-}
-function projectWorkflowMetadata(compiledPath, shellRoot, stage) {
-    const shellWorkflowRoot = stageShellWorkflowRoot(shellRoot);
-    mkdirSync(join(shellWorkflowRoot, "compile", "stages"), { recursive: true });
-    const compiledWorkflowRoot = workflowPackagePathForCompiled(compiledPath);
-    const workflowJsonPath = join(compiledWorkflowRoot, "workflow.json");
-    if (existsSync(workflowJsonPath)) {
-        linkPath(workflowJsonPath, join(shellWorkflowRoot, "workflow.json"));
-    }
-    const compiledSchemaPath = join(compiledWorkflowRoot, "compiled.schema.json");
-    if (existsSync(compiledSchemaPath)) {
-        linkPath(compiledSchemaPath, join(shellWorkflowRoot, "compiled.schema.json"));
-    }
-    const readmePath = join(compiledWorkflowRoot, "README.md");
-    if (existsSync(readmePath)) {
-        linkPath(readmePath, join(shellWorkflowRoot, "README.md"));
-    }
-    const stageDocsPath = stageWorkflowDocsPath(compiledPath, stage);
-    if (existsSync(stageDocsPath)) {
-        linkPath(stageDocsPath, join(shellWorkflowRoot, "compile", "stages", stage.skillDir));
-    }
-}
-function projectCompiledSchemaZones(compiledPath, shellRoot, schema, zoneIds, materializedZoneIds) {
-    const allowedZoneIds = zoneIds ? new Set(zoneIds) : null;
-    for (const zone of schema.zones) {
-        if (allowedZoneIds && !allowedZoneIds.has(zone.id))
-            continue;
-        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
-        const targetPath = join(shellRoot, zone.path);
-        if (materializedZoneIds?.has(zone.id)) {
-            ensureShellLocalProjection(sourcePath, targetPath, zone);
-            continue;
-        }
-        linkPath(sourcePath, targetPath);
-    }
-}
-function buildStageZoneMounts(compiledPath, shellRoot, stage, schema) {
-    const zones = zoneMap(schema);
-    const mountFor = (zoneId) => {
-        const zone = zoneOrThrow(zones, zoneId);
-        return {
-            zone_id: zone.id,
-            compiled_path: zone.path,
-            shell_root_path: zone.path,
-            input_mount_path: stage.reads.includes(zoneId)
-                ? describeShellZoneAliasMountPath(zone, "inputs")
-                : null,
-            output_mount_path: stage.writes.includes(zoneId)
-                ? describeShellZoneAliasMountPath(zone, "outputs")
-                : null,
-        };
-    };
-    return {
-        reads: stage.reads.map(mountFor),
-        writes: stage.writes.map(mountFor),
-    };
-}
-function projectStageZoneMountAliases(shellRoot, stage, schema) {
-    const zones = zoneMap(schema);
-    for (const zoneId of new Set([...stage.reads, ...stage.writes])) {
-        const zone = zoneOrThrow(zones, zoneId);
-        const targetPath = join(shellRoot, zone.path);
-        if (stage.reads.includes(zoneId)) {
-            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "inputs"));
-        }
-        if (stage.writes.includes(zoneId)) {
-            linkRelativePath(targetPath, shellZoneAliasMountPath(shellRoot, zone, "outputs"));
-        }
-    }
-}
-function writeExecutionShellPathsFile(shellRoot, workflowId, stage, mounts) {
-    const paths = {
-        kind: "interf-execution-shell",
-        version: 1,
-        workflow: workflowId,
-        stage: stage.id,
-        reads: mounts.reads,
-        writes: mounts.writes,
-    };
-    writeFileSync(shellRuntimePath(shellRoot, "paths.json"), `${JSON.stringify(paths, null, 2)}\n`);
-}
-export function syncStageExecutionShellWrites(compiledPath, shellRoot, stage, writeArtifacts = []) {
-    const schema = ensureCompiledExecutionSurface(compiledPath);
-    const zones = zoneMap(schema);
-    const stageWriteZones = Array.from(stageWriteZoneSet(schema, stage))
-        .map((zoneId) => zoneOrThrow(zones, zoneId));
-    for (const zone of stageWriteZones) {
-        const canonicalShellZonePath = join(shellRoot, zone.path);
-        const outputAliasPath = shellZoneAliasMountPath(shellRoot, zone, "outputs");
-        const shellZonePath = zone.kind === "file" &&
-            existsSync(outputAliasPath) &&
-            !lstatSync(outputAliasPath).isSymbolicLink()
-            ? outputAliasPath
-            : canonicalShellZonePath;
-        if (!existsSync(shellZonePath))
-            continue;
-        const shellZoneStat = lstatSync(shellZonePath);
-        if (shellZoneStat.isSymbolicLink())
-            continue;
-        const compiledZonePath = compiledZoneAbsolutePath(compiledPath, zone);
-        if (shellZoneStat.isDirectory()) {
-            rmSync(compiledZonePath, { recursive: true, force: true });
-            mkdirSync(dirname(compiledZonePath), { recursive: true });
-            cpSync(shellZonePath, compiledZonePath, {
-                recursive: true,
-                force: true,
-            });
-            continue;
-        }
-        mkdirSync(dirname(compiledZonePath), { recursive: true });
-        copyFileSync(shellZonePath, compiledZonePath);
-    }
-    for (const artifactPath of writeArtifacts) {
-        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
-        if (normalizedArtifactPath.length === 0 ||
-            stageWriteZones.some((zone) => relativePathEqualsOrWithin(zone.path, normalizedArtifactPath))) {
-            continue;
-        }
-        const shellArtifactPath = join(shellRoot, normalizedArtifactPath);
-        if (!existsSync(shellArtifactPath))
-            continue;
-        const compiledArtifactPath = join(compiledPath, normalizedArtifactPath);
-        const shellArtifactStat = lstatSync(shellArtifactPath);
-        if (shellArtifactStat.isSymbolicLink())
-            continue;
-        if (shellArtifactStat.isDirectory()) {
-            rmSync(compiledArtifactPath, { recursive: true, force: true });
-            mkdirSync(dirname(compiledArtifactPath), { recursive: true });
-            cpSync(shellArtifactPath, compiledArtifactPath, {
-                recursive: true,
-                force: true,
-            });
-            continue;
-        }
-        mkdirSync(dirname(compiledArtifactPath), { recursive: true });
-        copyFileSync(shellArtifactPath, compiledArtifactPath);
-    }
-}
-function preservedShellManifestPath(rootPath) {
-    return shellRuntimePath(rootPath, "preserved-shell.json");
-}
-function shouldSkipFrozenStageShellRelativePath(relativePath) {
-    const normalized = relativePath.replaceAll("\\", "/");
-    return normalized === "execution-shells" ||
-        normalized.endsWith("/execution-shells") ||
-        normalized.includes("/execution-shells/") ||
-        normalized === "improvement-loops" ||
-        normalized.endsWith("/improvement-loops") ||
-        normalized.includes("/improvement-loops/");
-}
-function copyResolvedTree(options) {
-    const relativePath = options.relativePath ?? "";
-    if (options.shellType === "stage-execution" && shouldSkipFrozenStageShellRelativePath(relativePath)) {
-        return { materializedSymlinks: 0 };
-    }
-    const stat = lstatSync(options.sourcePath);
-    if (stat.isSymbolicLink()) {
-        const realTarget = realpathSync(options.sourcePath);
-        const realStat = statSync(realTarget);
-        if (realStat.isDirectory()) {
-            const mappedTarget = options.materializedRealPaths?.get(realTarget);
-            if (mappedTarget) {
-                linkRelativePath(mappedTarget, options.targetPath);
-                return { materializedSymlinks: 1 };
-            }
-            return {
-                materializedSymlinks: 1 + copyResolvedTree({
-                    sourcePath: realTarget,
-                    targetPath: options.targetPath,
-                    shellType: options.shellType,
-                    relativePath,
-                    activeRealPaths: options.activeRealPaths,
-                    materializedRealPaths: options.materializedRealPaths,
-                }).materializedSymlinks,
-            };
-        }
-        mkdirSync(dirname(options.targetPath), { recursive: true });
-        copyFileSync(realTarget, options.targetPath);
-        return { materializedSymlinks: 1 };
-    }
-    if (stat.isDirectory()) {
-        const realSource = realpathSync(options.sourcePath);
-        const mappedTarget = options.materializedRealPaths?.get(realSource);
-        if (mappedTarget && mappedTarget !== options.targetPath) {
-            linkRelativePath(mappedTarget, options.targetPath);
-            return { materializedSymlinks: 0 };
-        }
-        const nextRealPaths = new Set([...(options.activeRealPaths ?? []), realSource]);
-        const nextMaterializedRealPaths = new Map(options.materializedRealPaths ?? []);
-        nextMaterializedRealPaths.set(realSource, options.targetPath);
-        mkdirSync(options.targetPath, { recursive: true });
-        let materializedSymlinks = 0;
-        for (const entry of readdirSync(options.sourcePath)) {
-            const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry}` : entry;
-            const copied = copyResolvedTree({
-                sourcePath: join(options.sourcePath, entry),
-                targetPath: join(options.targetPath, entry),
-                shellType: options.shellType,
-                relativePath: childRelativePath,
-                activeRealPaths: nextRealPaths,
-                materializedRealPaths: nextMaterializedRealPaths,
-            });
-            materializedSymlinks += copied.materializedSymlinks;
-        }
-        return { materializedSymlinks };
-    }
-    mkdirSync(dirname(options.targetPath), { recursive: true });
-    copyFileSync(options.sourcePath, options.targetPath);
-    return { materializedSymlinks: 0 };
-}
-function freezePreservedShell(rootPath, shellType) {
-    if (!existsSync(rootPath))
-        return null;
-    const manifestPath = preservedShellManifestPath(rootPath);
-    if (existsSync(manifestPath))
-        return manifestPath;
-    const tempRoot = `${rootPath}.frozen-${Date.now().toString(36)}`;
-    const copied = copyResolvedTree({
-        sourcePath: rootPath,
-        targetPath: tempRoot,
-        shellType,
-    });
-    const manifest = {
-        kind: "interf-preserved-shell",
-        version: 1,
-        shell_type: shellType,
-        generated_at: new Date().toISOString(),
-        root_path: rootPath,
-        materialized_symlinks: copied.materializedSymlinks,
-    };
-    writeFileSync(preservedShellManifestPath(tempRoot), `${JSON.stringify(manifest, null, 2)}\n`);
-    rmSync(rootPath, { recursive: true, force: true });
-    renameSync(tempRoot, rootPath);
-    return manifestPath;
-}
-export function renderClaudeBootstrap(content) {
-    return [
-        "<!-- Generated compatibility mirror of AGENTS.md. Interf Compiler may rewrite this file. -->",
-        "",
-        content.trimEnd(),
-        "",
-    ].join("\n");
-}
-function improvementWorkflowDocsPath(compiledPath) {
-    return join(workflowPackagePathForCompiled(compiledPath), "improve");
-}
-function renderWorkflowImprovementAgents(compiledName, workflowId, loopIndex) {
-    return [
-        `# ${compiledName} — Workflow Improvement Shell`,
-        "",
-        "This is an automated workflow-improvement shell generated by Interf Compiler.",
-        "It exists to review failed compile/test runs and edit the workflow package for the next variation.",
-        "",
-        "## Start Here",
-        "",
-        "1. Read `runtime/loop-context.json` now.",
-        "2. Read `workflow/README.md`, `workflow/workflow.json`, and `workflow/compiled.schema.json` now.",
-        "3. Read `workflow/improve/SKILL.md` now.",
-        "4. Use the local native `interf-workflow-improver` skill now.",
-        "",
-        "## Boundaries",
-        "",
-        `- Workflow: \`${workflowId}\`.`,
-        `- Improvement loop: ${loopIndex}.`,
-        "- Edit only files under `workflow/`.",
-        "- Do not edit truth checks, test specs, raw dataset files, or generated compiled outputs.",
-        "- Review compiled outputs under `artifacts/compiled-view/` and test/runtime evidence under `artifacts/`.",
-        "- Keep the workflow valid for the current compiler API and compiled schema.",
-        "",
-        "## Goal",
-        "",
-        "- create a better workflow variation for this dataset",
-        "- preserve deterministic compiled structure",
-        "- stop after the workflow edits are complete",
-        "",
-    ].join("\n");
-}
-function readWorkflowImprovementDoc(compiledPath) {
-    const path = join(improvementWorkflowDocsPath(compiledPath), "SKILL.md");
-    if (!existsSync(path))
-        return null;
-    return readFileSync(path, "utf8").trim();
-}
-function renderWorkflowImprovementSkill(workflowId, loopIndex, improvementDoc) {
-    return [
-        "---",
-        "name: interf-workflow-improver",
-        "description: >",
-        "  Native local workflow-improvement skill for this Interf Compiler run.",
-        "  Use it only inside an automated workflow-improvement shell.",
-        "---",
-        "",
-        `# Interf Compiler Workflow Improvement — ${workflowId}`,
-        "",
-        "This local native skill exists for automated workflow-improvement loops.",
-        "Read `runtime/loop-context.json` first.",
-        "Then review the linked workflow package, `artifacts/compiled-view/`, preserved stage shells, runtime logs, and saved test outputs before editing `workflow/`.",
-        "",
-        "## Current Loop",
-        "",
-        `- workflow: \`${workflowId}\``,
-        `- loop index: ${loopIndex}`,
-        "- editable source: `workflow/improve/SKILL.md`",
-        "",
-        ...(improvementDoc
-            ? [
-                "## Improvement Method",
-                "",
-                improvementDoc,
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-function projectCompiledReviewArtifactsSnapshot(compiledPath, shellRoot, schema) {
-    const compiledViewRoot = join(shellRoot, "artifacts", "compiled-view");
-    mkdirSync(compiledViewRoot, { recursive: true });
-    for (const zone of schema.zones) {
-        if (zone.kind === "runtime" || zone.path === "raw")
-            continue;
-        const sourcePath = compiledZoneAbsolutePath(compiledPath, zone);
-        if (!existsSync(sourcePath))
-            continue;
-        copyResolvedTree({
-            sourcePath,
-            targetPath: join(compiledViewRoot, zone.path),
-            shellType: "workflow-improvement",
-        });
-    }
-}
-function linkIfExists(targetPath, linkPathname) {
-    if (!existsSync(targetPath))
-        return;
-    linkPath(targetPath, linkPathname);
-}
-function copyIfExists(sourcePath, targetPath, shellType) {
-    if (!existsSync(sourcePath))
-        return;
-    copyResolvedTree({
-        sourcePath,
-        targetPath,
-        shellType,
-    });
-}
-function projectCompiledRuntimeArtifacts(compiledPath, shellRoot) {
-    const runtimeTarget = join(shellRoot, "artifacts", "compiled-runtime");
-    mkdirSync(runtimeTarget, { recursive: true });
-    const runtimeRoot = compiledRuntimeRoot(compiledPath);
-    const artifactNames = [
-        "run.json",
-        "run-history.jsonl",
-        "state.json",
-        "health.json",
-        "view-spec.json",
-        "raw-snapshot.json",
-        "logs",
-    ];
-    for (const artifactName of artifactNames) {
-        copyIfExists(join(runtimeRoot, artifactName), join(runtimeTarget, artifactName), "workflow-improvement");
-    }
-}
-export function pruneStageExecutionShells(compiledPath) {
-    rmSync(stageExecutionShellsRoot(compiledPath), { recursive: true, force: true });
-}
-export function projectCompiledQueryShell(compiledPath, compiledName, workflowId, about, options) {
-    const agentsContent = renderCompiledAgents(compiledPath, compiledName, workflowId, about, options);
-    const querySkillContent = readCompiledQuerySkillSource(compiledPath);
-    return writeNativeAgentSurface(compiledPath, agentsContent, "interf-query", renderCompiledQueryNativeSkill(querySkillContent));
-}
-export function projectRawTestQueryShell(rootPath) {
-    return writeNativeAgentSurface(rootPath, renderRawTestAgents(), "interf-query", renderRawTestQuerySkill());
-}
-export function createStageExecutionShell(compiledPath, compiledName, workflowId, stage, writeArtifacts = []) {
-    const schema = ensureCompiledExecutionSurface(compiledPath);
-    const materializedZones = stageMaterializedZoneSet(schema, stage, writeArtifacts);
-    const shellsRoot = stageExecutionShellsRoot(compiledPath);
-    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, "inputs"), { recursive: true });
-    mkdirSync(join(shellRoot, "outputs"), { recursive: true });
-    linkPath(compiledInterfConfigPath(compiledPath), join(shellRoot, "interf.json"));
-    linkPath(join(compiledRuntimeRoot(compiledPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
-    projectCompiledSchemaZones(compiledPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedZones);
-    projectWorkflowMetadata(compiledPath, shellRoot, stage);
-    projectStageZoneMountAliases(shellRoot, stage, schema);
-    writeExecutionShellPathsFile(shellRoot, workflowId, stage, buildStageZoneMounts(compiledPath, shellRoot, stage, schema));
-    const agentsContent = renderStageExecutionAgents(compiledName, workflowId, stage);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageMethodDoc(compiledPath, stage)));
-    return {
-        rootPath: shellRoot,
-    };
-}
-export function freezeStageExecutionShell(rootPath) {
-    return freezePreservedShell(rootPath, "stage-execution");
-}
-export function createWorkflowImprovementShell(options) {
-    const schema = ensureCompiledExecutionSurface(options.compiledPath);
-    const loopRootPath = workflowImprovementLoopRoot(options.compiledPath, 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`);
-    projectCompiledReviewArtifactsSnapshot(options.compiledPath, shellRoot, schema);
-    linkPath(workflowPackagePathForCompiled(options.compiledPath), join(shellRoot, "workflow"));
-    copyIfExists(compiledInterfConfigPath(options.compiledPath), join(shellRoot, "interf.json"), "workflow-improvement");
-    projectCompiledRuntimeArtifacts(options.compiledPath, shellRoot);
-    const reviewSources = resolveWorkflowImprovementReviewSourcePaths(options.compiledPath);
-    if (reviewSources.executionShells) {
-        copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "workflow-improvement");
-    }
-    if (reviewSources.testComparisons) {
-        copyIfExists(reviewSources.testComparisons, join(shellRoot, "artifacts", "test-comparisons"), "workflow-improvement");
-    }
-    if (reviewSources.targetTestRuns) {
-        copyIfExists(reviewSources.targetTestRuns, join(shellRoot, "artifacts", "test-runs"), "workflow-improvement");
-    }
-    if (reviewSources.targetTestSandboxes) {
-        copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "workflow-improvement");
-    }
-    const agentsContent = renderWorkflowImprovementAgents(options.compiledName, options.workflowId, options.loopIndex);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-workflow-improver", renderWorkflowImprovementSkill(options.workflowId, options.loopIndex, readWorkflowImprovementDoc(options.compiledPath)));
-    return {
-        rootPath: shellRoot,
-        loopRootPath,
-        workflowBeforePath: join(loopRootPath, "workflow-before"),
-        workflowAfterPath: join(loopRootPath, "workflow-after"),
-        promptLogPath: join(loopRootPath, "logs", "workflow-improver.prompt.txt"),
-        eventLogPath: join(loopRootPath, "logs", "workflow-improver.events.ndjson"),
-        statusLogPath: join(loopRootPath, "logs", "workflow-improver.status.log"),
-    };
-}
-export function freezeWorkflowImprovementShell(rootPath) {
-    return freezePreservedShell(rootPath, "workflow-improvement");
-}
+export * from "../packages/agents/lib/shells.js";