@aitne/daemon 0.1.8 → 0.1.10

package/dist/core/skills-compiler.js

@@ -1,19 +1,26 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { APP_NAME, BACKEND_IDS, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, applyIntegrationModeFilter, collectSessionDeniedTools, filterDeniedToolsForBackend, selectSkillVariantFile, selectTaskFlowVariantSuffix, substituteBrandTokens, } from "@aitne/shared";
-import { getProfileForEvent, getProfileForProcess, resolveSkillManifest, resolveSkillManifestForProcess, } from "./skills-manifest.js";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { APP_NAME, INTEGRATION_KEYS, applyIntegrationModeFilter, selectSkillVariantFile, substituteBrandTokens, } from "@aitne/shared";
+import { composeSkillSet, getProfileForEvent, getProfileForProcess, resolveSkillManifest, resolveSkillManifestForProcess, } from "./skills-manifest.js";
 import { applyCharacterBlockRewrite, buildCharacterBlock } from "./character-block.js";
-import { applyOutputLanguagePointerRewrite, renderOutputLanguagePolicyPointer, } from "./output-language-policy.js";
+import { applyOutputLanguagePointerRewrite } from "./output-language-policy.js";
 import { createLogger } from "../logging.js";
 import { loadFetchWindowSystemPrompt } from "./fetch-window-prompt-loader.js";
 import { substituteIntegrationRoutingTables } from "./management-md.js";
 import { loadCurationDeclaration, } from "./skill-curation/declarations.js";
-import { listBuiltinSlugs, resolveBuiltinSkillDir, } from "./skill-source-paths.js";
+import { resolveBuiltinSkillDir } from "./skill-source-paths.js";
 import { OverlayStore } from "./skill-curation/overlay-store.js";
 import { hasCurationAnchors, spliceCurationAnchors, } from "./skill-curation/splicer.js";
-// Exported so tests can spy on `logger.warn` (e.g. the missing-reference
-// branch of `renderReferenceIncludes`). Production callers do not import it.
-export const logger = createLogger("skills-compiler");
+import { isValidSkillSlug, missingDelegatedVariants, } from "./skills-compiler-variants.js";
+import { EMPTY_MAIL_ACCOUNTS_MD, pruneStaleBuiltinSkillDirs, readTreeFiles, renderMailAccountsMd, substituteBrandTokensInDir, substituteWikiWorkspaceTokens, substituteWikiWorkspaceTokensInDir, } from "./skills-compiler-tree.js";
+import { loadSkillIndexPreamble, renderPartialIncludes, renderReferenceIncludes, renderSkillIndexBlock, stripUnconfiguredServices, } from "./skills-compiler-skill-index.js";
+import { applyAllDeniedToolsForSkill, buildSameBackendDenyBlock } from "./skills-compiler-denied-tools.js";
+import { cliInstructionFileName, cliSkillsDirName, prependCodexReadSensitiveBanner, renderCliInstructionFile, renderDaemonApiUsageSection, } from "./skills-compiler-cli-renderer.js";
+// Module logger for the class's own warn callsites (invalid-slug warning
+// in writeSkillsDir, skill-curation declaration / anchor warnings in
+// spliceCurationAnchorsInSkill). Not exported — sibling modules carry
+// their own peer loggers; the test suite spies on those.
+const logger = createLogger("skills-compiler");
 // docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — single shared constant
 // for the pre-pass process key. Typed as `ProcessKey` (not the inferred
 // string literal) so a rename in `@aitne/shared/process-key.ts` lights up
@@ -26,199 +33,6 @@ const FETCH_WINDOW_PROCESS_KEY = "routine.fetch_window";
 // `external-services`, `attach`) are already restated by the integration
 // partial the runner inlines into the user prompt.
 const FETCH_WINDOW_SLIM_SKILL = "observations";
-/**
- * Check whether the skill AND task-flow variants a given integration would
- * require when delegated to `delegatedBackend` are all present on disk.
- * Returns missing file paths split by kind.
- *
- * DELEGATED-MODE-V2-DESIGN.md §4.1.1 — variant filenames are keyed on
- * **session backend**, not the delegated backend. Three resolutions:
- *  - sessionBackend === delegatedBackend → `null` (no skill body, native MCP)
- *  - sessionBackend !== delegatedBackend → `SKILL.delegated.<sessionBackend>.md`
- *    (cross-backend; the daemon proxy spawns delegatedBackend)
- *  - non-delegated touch → `SKILL.md` (no delegated variant required)
- *
- * Task flow variants always fire as `delegated.<sessionBackend>` whenever
- * any touched integration is delegated, regardless of same- vs cross-backend
- * (`selectTaskFlowVariantSuffix`).
- *
- * The gate enumerates every potential session backend (`BACKEND_IDS`) and
- * defers to the resolvers; that keeps the gate automatically aligned with
- * `selectSkillVariantFile` / `selectTaskFlowVariantSuffix` if those grow new
- * cases. We pin the integration's mode locally as `delegated` with the
- * supplied `delegatedBackend` so the resolvers see the post-PATCH state.
- *
- * Consumed by:
- *  - `SkillsCompiler.validateDelegatedVariants()` — startup aggregate
- *  - `PATCH /api/integrations/:key` — pre-commit hard reject (§4.7)
- *  - `buildIntegrationHealthMap` — surfaces the list in
- *    `/health.integrationModes.<key>.variantsMissing`
- */
-/**
- * Walk a materialized session subdirectory and rewrite every `.md` file with
- * `{APP_NAME}` tokens resolved. Called immediately after `cpSync(src, dest, …)`
- * so the verbatim copy from `agent-assets/` becomes brand-substituted before
- * any downstream transform (renderReferenceIncludes, applyIntegrationModeFilter,
- * tool-deny filter) reads it. Idempotent — running it twice is a no-op.
- */
-function substituteBrandTokensInDir(dir) {
-    if (!existsSync(dir))
-        return;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            substituteBrandTokensInDir(full);
-        }
-        else if (entry.isFile() && entry.name.endsWith(".md")) {
-            const original = readFileSync(full, "utf-8");
-            const substituted = substituteBrandTokens(original);
-            if (substituted !== original) {
-                writeFileSync(full, substituted, "utf-8");
-            }
-        }
-    }
-}
-let wikiWorkspaceTokenResolver = null;
-export function setWikiWorkspaceTokenResolver(resolver) {
-    wikiWorkspaceTokenResolver = resolver;
-}
-function wikiTokensFor(processKey, workspaceName) {
-    if (!processKey?.startsWith("wiki."))
-        return null;
-    return wikiWorkspaceTokenResolver?.(processKey, workspaceName) ?? null;
-}
-function substituteWikiWorkspaceTokens(content, processKey, workspaceName) {
-    const tokens = wikiTokensFor(processKey, workspaceName);
-    if (!tokens)
-        return content;
-    return content
-        .replaceAll("{{vault_path}}", tokens.vault_path)
-        .replaceAll("{{language}}", tokens.language)
-        .replaceAll("{{workspace_name}}", tokens.workspace_name)
-        .replaceAll("{{schema_version}}", tokens.schema_version);
-}
-function substituteWikiWorkspaceTokensInDir(dir, processKey, workspaceName) {
-    if (!existsSync(dir))
-        return;
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            substituteWikiWorkspaceTokensInDir(full, processKey, workspaceName);
-        }
-        else if (entry.isFile() && entry.name.endsWith(".md")) {
-            const original = readFileSync(full, "utf-8");
-            const substituted = substituteWikiWorkspaceTokens(original, processKey, workspaceName);
-            if (substituted !== original) {
-                writeFileSync(full, substituted, "utf-8");
-            }
-        }
-    }
-}
-export function missingDelegatedVariants(workspaceDir, integrationKey, delegatedBackend) {
-    return missingVariantsForMode(workspaceDir, integrationKey, {
-        mode: "delegated",
-        delegatedBackend,
-    });
-}
-/**
- * INTEGRATION_NATIVE_MODE_DESIGN.md §7.4 / §8.5 — symmetric to
- * {@link missingDelegatedVariants} for the new `native` mode. Used by
- * the PATCH route's pre-commit hard reject and (Phase B2 onwards) by
- * `skills-manifest.test.ts` to assert variant existence on every
- * supported `(integration, native backend)` pair before a release.
- */
-export function missingNativeVariants(workspaceDir, integrationKey, nativeBackend) {
-    return missingVariantsForMode(workspaceDir, integrationKey, {
-        mode: "native",
-        nativeBackend,
-    });
-}
-function missingVariantsForMode(workspaceDir, integrationKey, pinnedState) {
-    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
-    const skillsRoot = join(workspaceDir, "agent-assets", "skills");
-    const taskFlowsRoot = join(workspaceDir, "agent-assets", "task-flows");
-    // Synthetic post-PATCH state. The resolvers consume only `mode` and
-    // the backend binding; `lastChangedAt` is required by the type but not
-    // read here.
-    const synthetic = pinnedState.mode === "delegated"
-        ? {
-            mode: "delegated",
-            delegatedBackend: pinnedState.delegatedBackend,
-            deniedTools: [],
-            lastChangedAt: "1970-01-01T00:00:00.000Z",
-        }
-        : {
-            mode: "native",
-            nativeBackend: pinnedState.nativeBackend,
-            deniedTools: [],
-            lastChangedAt: "1970-01-01T00:00:00.000Z",
-        };
-    const integrationsState = {
-        [integrationKey]: synthetic,
-    };
-    // For `native` mode the variant is only required when the session
-    // backend is the bound native backend (other session backends would
-    // resolve to `disabled` per §5.4.1's safety degrade, so they don't need
-    // a SKILL.native.<other>.md file). For `delegated` we keep the original
-    // walk over every session backend since cross-backend variants ARE
-    // required.
-    const sessionBackendsToCheck = pinnedState.mode === "native"
-        ? [pinnedState.nativeBackend]
-        : BACKEND_IDS.filter((backend) => backend !== "opencode");
-    // De-dup with sets — the same file path can come up under multiple
-    // session backends when descriptors share a slug.
-    const skills = new Set();
-    for (const slug of descriptor.skillsTouched) {
-        for (const sessionBackend of sessionBackendsToCheck) {
-            const variantFile = selectSkillVariantFile(slug, sessionBackend, integrationsState);
-            // null  → same-backend delegated drops body; no file required.
-            // SKILL.md → resolver fell back to direct/disabled; no variant file.
-            if (variantFile === null || variantFile === "SKILL.md")
-                continue;
-            const variantPath = join(resolveBuiltinSkillDir(skillsRoot, slug), variantFile);
-            if (!existsSync(variantPath))
-                skills.add(variantPath);
-        }
-    }
-    const taskFlows = new Set();
-    for (const flowKey of descriptor.taskFlowsTouched) {
-        for (const sessionBackend of sessionBackendsToCheck) {
-            const suffix = selectTaskFlowVariantSuffix(flowKey, sessionBackend, integrationsState);
-            if (suffix === "direct")
-                continue;
-            const variantPath = join(taskFlowsRoot, `${flowKey}.${suffix}.md`);
-            if (existsSync(variantPath))
-                continue;
-            // INTEGRATION_NATIVE_MODE_DESIGN.md §8.1 — when a task-flow lists a
-            // mode-aware integration in `taskFlowsTouched` but doesn't ship a
-            // per-mode variant file, the loader (`prompts.ts:loadFlowVariant`)
-            // gracefully falls back to the canonical base file. Treat that as
-            // a valid coverage path so the `missingDelegatedVariants` /
-            // `missingNativeVariants` PATCH-time check doesn't reject a flip
-            // for which the loader's base-file fallback is the designed answer.
-            //
-            // Concrete example: `message.received.dm` is listed in gmail /
-            // google_calendar / notion `taskFlowsTouched` so the native DM
-            // variant resolves; the matching delegated variant
-            // (`message.received.dm.delegated.<backend>.md`) is intentionally
-            // absent. The base `message.received.dm.md` carries inline
-            // `<!-- mode:<predicate>:<key> -->` markers for the Calendar block
-            // and routes other integrations through their per-skill bodies. The
-            // loader correctly falls back, so the missing variant is not a real
-            // configuration gap.
-            //
-            // Skill variants remain strict — a missing `SKILL.<mode>.<backend>.md`
-            // leaves the agent with no per-mode body for the integration, which
-            // IS a real gap. The strict check above (no leniency branch) handles
-            // that.
-            const basePath = join(taskFlowsRoot, `${flowKey}.md`);
-            if (!existsSync(basePath)) {
-                taskFlows.add(variantPath);
-            }
-        }
-    }
-    return { skills: [...skills], taskFlows: [...taskFlows] };
-}
 /**
  * Materializes backend-specific instruction files for session workdirs
  * by reading directly from the source tree (agent-assets/agent-profiles/ and
@@ -272,7 +86,7 @@ export class SkillsCompiler {
     /**
      * P22 — skill-curation overlay context. When set, the materializer runs an
      * extra pass that resolves `<!-- CURATION:<kind> id="<id>" -->` anchors in
-     * each skill's SKILL.md against `<dataDir>/skills/overlays/<slug>/<id>.json`
+     * each skill's SKILL.md against `<dataDir>/skill-curation-overlays/<slug>/<id>.json`
      * (overlay) or `agent-assets/skills/<slug>/seeds/<id>.seed.json` (seed).
      *
      * Optional and default-OFF — daemon code is expected to call
@@ -302,10 +116,10 @@ export class SkillsCompiler {
      * §4.7 "Missing-variant policy": if any paths come back, the caller
      * should refuse to enter delegated mode or at least log a loud warning.
      * The per-integration variant for the hypothetical PATCH path lives in
-     * the standalone `missingDelegatedVariants` helper below; this method
-     * aggregates across every currently-delegated integration using its
-     * declared `delegatedBackend` (not the session backend — see the helper
-     * docstring for the rationale).
+     * `missingDelegatedVariants` in `./skills-compiler-variants.js`; this
+     * method aggregates across every currently-delegated integration using
+     * its declared `delegatedBackend` (not the session backend — see the
+     * helper docstring for the rationale).
      */
     validateDelegatedVariants() {
         const skills = [];
@@ -389,10 +203,17 @@ export class SkillsCompiler {
         // means "no skills." `null` keeps manifest behavior — the override is a
         // partial replacement so a future caller can pass just `profileBody`
         // without affecting skill selection.
-        const skills = params.override?.skillSlugs !== null
+        const baseSkills = params.override?.skillSlugs !== null
             && params.override?.skillSlugs !== undefined
             ? [...params.override.skillSlugs]
             : manifestSkills;
+        // AGENT_DEFINITIONS_DESIGN.md §4.2 — fold the firing Agent's `tools.skills`
+        // onto the resolved bundle (union, or replace when `skillsReplace`). A
+        // no-op when `extraSkills` is empty/absent, so every non-Agent site keeps
+        // its prior set verbatim. Applied AFTER the bang-command override so the
+        // two surfaces never silently fight; in practice they never co-occur (an
+        // Agent firing carries no `override`).
+        const skills = composeSkillSet(baseSkills, params.extraSkills, params.skillsReplace ?? false);
         const profileBodyOverride = params.override?.profileBody ?? null;
         // Always materialize the `mail` skill when the manifest asks for it —
         // even if the current account list is empty. The skill is inert when
@@ -1029,1018 +850,3 @@ export class SkillsCompiler {
         writeFileSync(join(sessionDir, cliInstructionFileName(backendId)), instruction, "utf-8");
     }
 }
-export const EMPTY_MAIL_ACCOUNTS_MD = [
-    "# Mail accounts",
-    "",
-    "No active mail accounts are configured right now. The `mail` skill's API",
-    "calls will fail without an `accountId` — do NOT guess account ids. If no",
-    "account matches, tell the user no active mail account is configured and",
-    "stop — account setup is outside this skill's scope.",
-    "",
-].join("\n");
-export function renderMailAccountsMd(accounts) {
-    const rows = accounts.map((a) => {
-        const label = a.label ? ` (${a.label})` : "";
-        return `| \`${a.id}\` | ${a.kind} | ${a.email}${label} | ${a.idleEnabled ? "IDLE" : "poll"} |`;
-    });
-    return [
-        "# Mail accounts",
-        "",
-        "Active mail accounts this session can use. Resolve `accountId` from this",
-        "table before calling `/api/mail/:accountId/*`. Inactive / unhealthy",
-        "accounts are omitted by design — no global \"primary\" default exists;",
-        "pick the account from conversation context (reply thread, user mention,",
-        "or a single active row) and ask when ambiguous.",
-        "",
-        "| accountId | kind | email | transport |",
-        "|---|---|---|---|",
-        ...rows,
-        "",
-    ].join("\n");
-}
-/**
- * docs/design/appendices/opencode-backend.md §10 D6 — opencode 1.14.50 documents
- * `[a-z0-9-]{1,64}` as the legal skill-slug pattern. Aitne's existing
- * built-ins all conform; this helper is the predicate the build-time
- * validator (`validateBuiltinSkillSourceTree`) and the user-skill PUT
- * endpoint both gate on.
- *
- * docs/design/appendices/skills-unification.md Phase 1 §R5 / item 6 — promoted from a
- * runtime warn to a build-time throw at SkillsCompiler construction so
- * a malformed source tree refuses to boot the daemon.
- *
- * Exported for unit testing (`skills-compiler.test.ts` regression).
- */
-export function isValidSkillSlug(slug) {
-    return /^[a-z0-9-]{1,64}$/.test(slug);
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §R5 / item 6 — build-time invariant
- * pass over `agent-assets/skills/`. Throws on:
- *   - Any built-in slug that doesn't match `[a-z0-9-]{1,64}`.
- *   - Any SKILL.md (incl. variants like `SKILL.delegated.<backend>.md`)
- *     whose `description` exceeds `SKILL_DESCRIPTION_MAX_LENGTH`.
- *   - Any SKILL.md missing `name` or `description`.
- *
- * No-op when the source tree is absent (test workspaces / partial-clone
- * scenarios). Memoised per workspace dir + skill-tree fingerprint so
- * repeated SkillsCompiler constructions in the same process don't pay
- * the walk cost twice; tests that mutate source between constructions
- * get fresh validation because the fingerprint shifts.
- *
- * Exported for tests that exercise the failure paths in isolation.
- */
-export function validateBuiltinSkillSourceTree(skillsRoot) {
-    if (!existsSync(skillsRoot))
-        return;
-    const fingerprint = computeSkillTreeFingerprint(skillsRoot);
-    const cached = validatedTreeCache.get(skillsRoot);
-    if (cached === fingerprint)
-        return;
-    for (const slug of listBuiltinSlugs(skillsRoot)) {
-        if (!isValidSkillSlug(slug)) {
-            throw new Error(`skills_compiler.invalid_slug: ${slug} (expected [a-z0-9-]{1,64})`);
-        }
-        const skillDir = resolveBuiltinSkillDir(skillsRoot, slug);
-        const skillMdPath = join(skillDir, "SKILL.md");
-        if (!existsSync(skillMdPath))
-            continue; // skip slugs that ship only a variant
-        const primaryContent = readFileSync(skillMdPath, "utf-8");
-        const primaryFm = parseSkillFrontmatter(primaryContent);
-        // Stub primary (no frontmatter) — treat the whole skill as a test
-        // scaffold and skip its variants too. Production builds always have
-        // proper frontmatter; the fingerprint cache picks up any future
-        // primary-content fix automatically.
-        if (!primaryFm.name && !primaryFm.description)
-            continue;
-        if (!primaryFm.name) {
-            throw new Error(`skills_compiler.missing_frontmatter_name: ${slug}/SKILL.md`);
-        }
-        if (!primaryFm.description) {
-            throw new Error(`skills_compiler.missing_frontmatter_description: ${slug}/SKILL.md`);
-        }
-        if (primaryFm.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
-            throw new Error(`skills_compiler.description_too_long: ${slug}/SKILL.md `
-                + `(${primaryFm.description.length} > ${SKILL_DESCRIPTION_MAX_LENGTH})`);
-        }
-        // Variant validation — only run when the primary is well-formed. Each
-        // variant is shipped to the model the same way the primary is, so the
-        // same description-length cap applies. Variants that are stub
-        // sentinels in tests are caught by the primary-stub short-circuit
-        // above (this loop never runs for those).
-        const entries = readdirSync(skillDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            const name = entry.name;
-            if (!name.startsWith("SKILL.") || !name.endsWith(".md"))
-                continue;
-            if (name === "SKILL.base.md")
-                continue; // base partial — frontmatter optional
-            const variantContent = readFileSync(join(skillDir, name), "utf-8");
-            const variantFm = parseSkillFrontmatter(variantContent);
-            if (!variantFm.name || !variantFm.description) {
-                throw new Error(`skills_compiler.variant_missing_frontmatter: ${slug}/${name}`);
-            }
-            if (variantFm.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
-                throw new Error(`skills_compiler.description_too_long: ${slug}/${name} `
-                    + `(${variantFm.description.length} > ${SKILL_DESCRIPTION_MAX_LENGTH})`);
-            }
-        }
-    }
-    validatedTreeCache.set(skillsRoot, fingerprint);
-}
-const validatedTreeCache = new Map();
-function computeSkillTreeFingerprint(skillsRoot) {
-    // mtime-only fingerprint over SKILL*.md files: enough to bust the
-    // cache on a source-tree edit between constructions without paying
-    // the cost of a full content hash. Tests that mutate files within
-    // the same millisecond should call SkillsCompiler.invalidateValidator()
-    // — but in practice the millisecond resolution suffices.
-    const parts = [];
-    for (const slug of listBuiltinSlugs(skillsRoot).sort()) {
-        const skillDir = resolveBuiltinSkillDir(skillsRoot, slug);
-        let entries;
-        try {
-            entries = readdirSync(skillDir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const e of entries) {
-            if (!e.isFile())
-                continue;
-            const name = e.name;
-            if (!name.startsWith("SKILL") || !name.endsWith(".md"))
-                continue;
-            try {
-                const stat = statSync(join(skillDir, name));
-                parts.push(`${slug}/${name}:${stat.mtimeMs}:${stat.size}`);
-            }
-            catch { /* ignore */ }
-        }
-    }
-    return parts.join("|");
-}
-/**
- * Return the backend-specific dotfile namespace name for a given backend's
- * skill directory, **without** the trailing `skills` segment — callers
- * join `skills` themselves. Returns `null` only for Claude (which is
- * dispatched through `materializeClaudeSession` and writes
- * `<sessionDir>/.claude/skills/` directly).
- *
- * docs/design/appendices/skills-unification.md Phase 1 — every non-Claude backend now writes
- * to its own brand-aligned namespace:
- *   - `codex`    → `.codex`
- *   - `gemini`   → `.gemini`
- *   - `opencode` → `.opencode` (V2 path (c); flipped from prior `.claude/`
- *                  redundancy-avoiding alias).
- */
-export function cliSkillsDirName(backendId) {
-    switch (backendId) {
-        case "codex": return ".codex";
-        case "gemini": return ".gemini";
-        case "opencode": return ".opencode";
-        default: return null;
-    }
-}
-/**
- * Return the CLI instruction-file name for a given backend. Codex and
- * OpenCode both auto-discover `AGENTS.md` from cwd; Gemini reads
- * `GEMINI.md`. Throws for `claude` — the Claude SDK consumes a per-cwd
- * `CLAUDE.md` written by `materializeClaudeSession`, not an instruction
- * file from this helper.
- *
- * Single helper so the choice is consistent between the wide
- * `materializeCliSession` and the slim `materializeFetchWindowCliSession`
- * paths (docs/design/appendices/fetch-window-cost-reduction.md §4.5.7).
- */
-export function cliInstructionFileName(backendId) {
-    switch (backendId) {
-        case "codex":
-        case "opencode":
-            return "AGENTS.md";
-        case "gemini":
-            return "GEMINI.md";
-    }
-}
-/**
- * Session instruction files the live-overwrite path (design §15.6.1 /
- * §15.9) walks when the owner PATCHes `character` mid-session. Each file
- * corresponds to a backend (CLAUDE.md = Claude Code SDK, AGENTS.md =
- * Codex CLI, GEMINI.md = Gemini CLI). A workdir that has already seen a
- * heavy-tier fallback can contain two of these side-by-side — see
- * CLAUDE.md "Fallback re-materialization".
- */
-const CHARACTER_INSTRUCTION_FILES = [
-    "CLAUDE.md",
-    "AGENTS.md",
-    "GEMINI.md",
-];
-/**
- * Rewrite the `## Character (user-defined)` block inside every backend
- * instruction file that currently lives in `workdir`. Used by the
- * `PATCH /api/config` live-overwrite path (§15.6.1) so an owner editing
- * character on the dashboard doesn't have to wait for the next session
- * spawn for the change to land.
- *
- * Multi-backend aware: a workdir that has seen a Claude→Codex fallback
- * contains both CLAUDE.md and AGENTS.md, and both must end up byte-
- * identical in their character block. Each write is atomic (tmp +
- * rename, both on the same filesystem so rename stays cheap) and
- * per-file errors are logged without failing the whole call.
- *
- * Returns a summary of how many files were rewritten. Useful for
- * instrumentation and for the dashboard PATCH handler to log.
- *
- * The helper is an FS wrapper: its pure parse/compose half lives in
- * `character-block.ts` and is covered 100% there. This side is excluded
- * from coverage along with the rest of `skills-compiler.ts`.
- */
-export function rewriteCharacterBlock(workdir, character) {
-    const summary = { rewritten: 0, skipped: 0, failed: 0 };
-    const targets = CHARACTER_INSTRUCTION_FILES.map((name) => join(workdir, name));
-    // docs/design/appendices/opencode-backend.md §6.5 — opencode also carries the character
-    // block inside `.opencode/agent/<slug>.md` (the per-process persona
-    // body). Walk the dir so a mid-session character PATCH lands on every
-    // active opencode agent file (typically one per workdir). Defensive
-    // existence check below — a non-opencode workdir simply has no
-    // `.opencode/agent/` dir and contributes zero rewrites.
-    const opencodeAgentDir = join(workdir, ".opencode", "agent");
-    if (existsSync(opencodeAgentDir)) {
-        try {
-            for (const entry of readdirSync(opencodeAgentDir, { withFileTypes: true })) {
-                if (entry.isFile() && entry.name.endsWith(".md")) {
-                    targets.push(join(opencodeAgentDir, entry.name));
-                }
-            }
-        }
-        catch (err) {
-            logger.warn({ err, opencodeAgentDir }, "rewriteCharacterBlock failed to enumerate opencode agent dir");
-        }
-    }
-    for (const target of targets) {
-        if (!existsSync(target)) {
-            summary.skipped++;
-            continue;
-        }
-        try {
-            const current = readFileSync(target, "utf-8");
-            const next = applyCharacterBlockRewrite(current, character);
-            if (next === current) {
-                summary.skipped++;
-                continue;
-            }
-            // `.tmp` lives next to the target so the rename stays on one
-            // filesystem (design R1 mitigation).
-            const tmp = `${target}.tmp`;
-            writeFileSync(tmp, next, "utf-8");
-            renameSync(tmp, target);
-            summary.rewritten++;
-        }
-        catch (err) {
-            // Per-file logging so a partial failure (e.g. CLAUDE.md written,
-            // AGENTS.md EACCES) is recoverable post-hoc — the outer PATCH
-            // handler only sees aggregate totals.
-            logger.warn({ err, target }, "rewriteCharacterBlock failed to update instruction file");
-            summary.failed++;
-        }
-    }
-    return summary;
-}
-function renderCliInstructionFile(params) {
-    const toolName = cliInstructionFileName(params.backendId);
-    const parts = [
-        `# ${APP_NAME} ${toolName}`,
-        "",
-        `Process key: \`${params.processKey}\``,
-        `Profile: \`${params.profileName}\``,
-        "",
-    ];
-    // Safety invariants at top level for prominence — CLI backends don't
-    // have a separate project-instruction layer, so burying safety inside
-    // the profile section risks it being overlooked by weaker models.
-    if (params.safetyContent) {
-        parts.push(params.safetyContent, "");
-    }
-    // User-defined character sits immediately after safety so it strictly
-    // outranks every profile / skill / task-flow layer below it, and
-    // strictly below safety (design §15.4.2 / §15.5).
-    if (params.characterBlock) {
-        parts.push(params.characterBlock, "");
-    }
-    // DELEGATED-MODE-V2-DESIGN.md §4.3.4 — same-backend integration deny block.
-    // Sits right after character / safety (above behavioral rules + skills) so
-    // weak models cannot miss it. For Codex this is the only enforcement
-    // surface; for Gemini it duplicates the admin-policy hard-deny.
-    if (params.sameBackendDenyBlock) {
-        parts.push(params.sameBackendDenyBlock, "");
-    }
-    // Output-language pointer paragraph (design `output-language-policy.md`
-    // §13.3). Identical byte-for-byte across CLAUDE.md / AGENTS.md /
-    // GEMINI.md — declarative only, never inlines the current
-    // `primaryLanguage` (that lives in the per-turn XML and would go
-    // stale here on a PATCH /api/config mid-session).
-    parts.push(renderOutputLanguagePolicyPointer(), "");
-    // Behavioral rules that Claude Code receives via system prompt append but
-    // CLI backends don't have a system prompt layer for.
-    parts.push("## Behavioral rules", "", "- WhatsApp outbound messages are prefixed by the daemon. Do not add that prefix yourself unless the user explicitly asks.", "");
-    // Daemon-API usage hoisted ABOVE the skills (was: appended at the end
-    // of the file). Skill bodies inline below carry hundreds of `curl
-    // http://localhost:8321/api/...` examples; for Codex specifically those
-    // examples target endpoints that return 401 because Codex does not
-    // hold the read-sensitive token. Surfacing the constraint up-front
-    // gives the agent the routing rule before it reads the first skill.
-    // For Gemini / Claude the section is informational; the position is
-    // kept consistent so the rendered file shape is uniform.
-    parts.push(renderDaemonApiUsageSection(params.backendId !== "codex"), "");
-    // docs/design/appendices/skills-unification.md Phase 1 §R2 — preamble + `<skill-index>`
-    // sit after Character (already emitted above) and **before** the
-    // Runtime profile (which carries the integration routing table
-    // substitution). Codex / Gemini only — `skillPreamble` and
-    // `skillIndexBlock` are `null` for OpenCode (R3) so the section is
-    // suppressed entirely and the `## Skills` slug manifest below holds.
-    if (params.skillPreamble) {
-        parts.push(params.skillPreamble.trim(), "");
-    }
-    if (params.skillIndexBlock) {
-        parts.push(params.skillIndexBlock, "");
-    }
-    parts.push("## Runtime profile", "", params.profileContent.trim(), "");
-    // docs/design/appendices/skills-unification.md Phase 1 §R3 — the `## Skills` slug manifest
-    // only fires for OpenCode (no `<skill-index>` block; cwd auto-discovery
-    // already enumerates the skills, but the manifest pins the per-turn
-    // active set so the agent doesn't grab unrelated user skills). Codex /
-    // Gemini suppress this section since their `<skill-index>` above already
-    // serves as the canonical listing — duplicating it here would risk the
-    // agent mistaking the manifest for the authoritative path source.
-    if (!params.skillIndexBlock) {
-        parts.push("## Skills", "");
-        if (params.skillSlugs.length === 0) {
-            parts.push("No process-scoped built-in skills were selected for this turn.", "");
-        }
-        else {
-            parts.push("Active built-in skills for this turn (cwd auto-discovery loads them):", "");
-            for (const slug of params.skillSlugs) {
-                parts.push(`- \`${slug}\``);
-            }
-            parts.push("");
-        }
-        parts.push("User-authored skills may also be discovered from the same directory.");
-    }
-    return parts.join("\n");
-}
-function renderDaemonApiUsageSection(readSensitiveAvailable) {
-    const lines = [
-        "## Daemon API Usage",
-        "",
-        "- Use plain `curl` for daemon API calls. The daemon prepends a session-local wrapper on PATH.",
-        "- Never use absolute curl paths, alternative HTTP clients, connection overrides, or custom auth headers.",
-    ];
-    if (readSensitiveAvailable) {
-        lines.push("- The wrapper auto-attaches session auth for read-sensitive endpoints.");
-    }
-    else {
-        lines.push("", "### Read-sensitive endpoints are UNAVAILABLE on this backend", "", "Codex sessions do not receive the read-sensitive daemon token. The", "wrapper still prepends headers it can supply, but the daemon answers", "personal-data reads with `401 Unauthorized` regardless. Endpoints", "below are affected; the per-skill `SKILL.md` files under", "`.codex/skills/<name>/` listed in `<skill-index>` describe them as if", "they were available — treat their `curl /api/*` examples as a", "contract you cannot satisfy on this backend.", "", "- Context vault: `GET /api/context/*`, `GET /api/context/list/*`", "- Mail (multi-provider): `GET /api/mail/*` (read), search, providers", "- Calendar (direct mode): `GET /api/calendar/*`", "- Notion (direct mode): `GET /api/notion/{query,search,pages}`", "- Obsidian: `GET /api/obsidian/*`", "- Observations: `GET /api/observations`", "- Reading list / receipts / travel bookings", "", "If a skill body directs you at one of these reads, stop and tell", "the user the task needs a different backend (Claude or Gemini).", "Do not hammer the endpoint — the 401 is permanent for this", "session, not transient. Writes and autonomous-tier endpoints", "stay reachable; the gate is read-sensitive scope only.");
-    }
-    return lines.join("\n");
-}
-/**
- * Strip service sections from external-services/SKILL.md that correspond to
- * unconfigured integrations. Sections are delimited by HTML comments:
- *   <!-- service:calendar --> ... <!-- /service:calendar -->
- * When `configuredServices` is empty the content is returned unchanged — the
- * "no services configured yet" case keeps every section so the agent can see
- * the full menu. Only strips once the user has configured at least one
- * service (and therefore expressed an intent to narrow the surface).
- */
-export function stripUnconfiguredServices(content, configuredServices) {
-    if (configuredServices.size === 0)
-        return content;
-    const servicePattern = /<!-- service:(\w+) -->\n([\s\S]*?)<!-- \/service:\1 -->\n?/g;
-    return content.replace(servicePattern, (match, service) => configuredServices.has(service) ? match : "");
-}
-/** Strip YAML frontmatter (--- ... ---) from markdown content. */
-function stripFrontmatter(content) {
-    if (!content.startsWith("---"))
-        return content;
-    const endIdx = content.indexOf("\n---", 3);
-    if (endIdx < 0)
-        return content;
-    return content.slice(endIdx + 4).replace(/^\n+/, "");
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 — parse the `name` and `description`
- * single-line YAML scalars out of a SKILL.md frontmatter block. Returns
- * `{ name: null, description: null }` when no frontmatter is present or
- * neither key is set. Multi-line block scalars (`description: |` /
- * `description: >`) are rejected at the regex level — the schema enforces
- * single-line scalars across all backends (R6).
- */
-export function parseSkillFrontmatter(content) {
-    if (!content.startsWith("---"))
-        return { name: null, description: null };
-    const endIdx = content.indexOf("\n---", 3);
-    if (endIdx < 0)
-        return { name: null, description: null };
-    const fm = content.slice(4, endIdx);
-    const nameMatch = fm.match(/^name:\s*(.+)$/m);
-    const descMatch = fm.match(/^description:\s*(.+)$/m);
-    return {
-        name: nameMatch ? nameMatch[1].trim() : null,
-        description: descMatch ? descMatch[1].trim() : null,
-    };
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §R5 — hard upper bound on a
- * SKILL.md `description` scalar. Enforced at SkillsCompiler construction
- * for built-in skills (refuses to boot on violation) and at
- * `PUT /api/skills/<slug>` for user-authored skills (HTTP 400). Sized to
- * fit the model's selection decision without pinning enough prose to
- * encode body content.
- */
-export const SKILL_DESCRIPTION_MAX_LENGTH = 280;
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §"Codex read-sensitive banner
- * inheritance" — endpoints flagged `RiskTier.ReadSensitive` by
- * `safety/risk-classifier.ts` that a Codex session cannot satisfy (no
- * read-sensitive token). Any SKILL.md whose body references one of these
- * prefixes triggers a one-line banner prepend on the Codex copy. Listed
- * literally (not derived from `API_RISK` at module-load time) so the
- * core/skills-compiler module stays independent of safety/risk-classifier
- * — a circular import would invert the bootstrap order.
- *
- * Drift guard: `skills-compiler.test.ts` pins this list against the
- * RiskTier.ReadSensitive GET-prefix set in `risk-classifier.ts` so a new
- * read-sensitive endpoint added to API_RISK surfaces here at test time
- * instead of as silent 401 retries in a future Codex session.
- *
- * Exported for the drift-guard regression test only — production code
- * MUST use {@link skillBodyTouchesReadSensitive} to keep the
- * "literal prefix" decision encapsulated.
- */
-export const READ_SENSITIVE_API_PREFIXES = [
-    "/api/apple-calendar",
-    "/api/books",
-    "/api/calendar",
-    "/api/context",
-    "/api/entities",
-    "/api/mail",
-    "/api/mcp/servers",
-    "/api/notion",
-    "/api/observations",
-    "/api/obsidian",
-    "/api/receipts",
-    "/api/travel-bookings",
-];
-function skillBodyTouchesReadSensitive(skillBody) {
-    return READ_SENSITIVE_API_PREFIXES.some((prefix) => skillBody.includes(prefix));
-}
-const CODEX_READ_SENSITIVE_BANNER_HEADER = "<!-- codex-read-sensitive-banner -->";
-const CODEX_READ_SENSITIVE_BANNER = [
-    CODEX_READ_SENSITIVE_BANNER_HEADER,
-    "> NOTE (Codex session): Some endpoints in this skill are read-sensitive and",
-    "> return 401 here. See `## Read-sensitive endpoints are UNAVAILABLE` in",
-    "> AGENTS.md before invoking. Do not retry on 401 — stop and notify the user.",
-    "",
-].join("\n");
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §"Codex read-sensitive banner
- * inheritance" — prepend the 3-line caveat banner to a Codex skill body
- * whose contents reference any read-sensitive `/api/*` endpoint. The
- * banner sits immediately after the YAML frontmatter (so the frontmatter
- * parser on the agent side still picks up `name`/`description`/
- * `allowed-tools` first) and is idempotent — re-running on an already-
- * banner-bearing file is a no-op (the HTML-comment sentinel lets us
- * detect prior insertion without false positives from user prose).
- *
- * No-op when:
- *  - The skill body references zero read-sensitive endpoints.
- *  - The banner is already present (sentinel hit).
- */
-function prependCodexReadSensitiveBanner(skillMdPath) {
-    if (!existsSync(skillMdPath))
-        return;
-    const content = readFileSync(skillMdPath, "utf-8");
-    if (!skillBodyTouchesReadSensitive(content))
-        return;
-    if (content.includes(CODEX_READ_SENSITIVE_BANNER_HEADER))
-        return;
-    if (!content.startsWith("---")) {
-        writeFileSync(skillMdPath, CODEX_READ_SENSITIVE_BANNER + content, "utf-8");
-        return;
-    }
-    const fmCloseIdx = content.indexOf("\n---", 3);
-    if (fmCloseIdx < 0) {
-        writeFileSync(skillMdPath, CODEX_READ_SENSITIVE_BANNER + content, "utf-8");
-        return;
-    }
-    const afterFm = fmCloseIdx + 4; // include `\n---`
-    // Skip a single trailing newline after `---` so the banner sits on its
-    // own line cleanly. If no newline follows, we still emit one before the
-    // banner so the prose split is unambiguous.
-    const head = content.slice(0, afterFm);
-    const tail = content.slice(afterFm).replace(/^\n+/, "");
-    writeFileSync(skillMdPath, `${head}\n\n${CODEX_READ_SENSITIVE_BANNER}${tail ? `\n${tail}` : ""}`, "utf-8");
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §"Skill preamble" — load the static
- * preamble shipped at
- * `agent-assets/system-prompts/skill-index-instruction.md`. The preamble
- * is constant per backend (Codex / Gemini) and explains the on-demand
- * skill-load protocol. Returns a built-in minimal fallback when the asset
- * is missing so tests that don't seed the system-prompts dir still
- * produce deterministic output.
- */
-function loadSkillIndexPreamble(workspaceDir) {
-    const path = join(workspaceDir, "agent-assets", "system-prompts", "skill-index-instruction.md");
-    if (existsSync(path)) {
-        return readFileSync(path, "utf-8").trim();
-    }
-    return [
-        "## Skills",
-        "",
-        "Skills are materialised on disk under the per-backend dotfile",
-        "directory. When your task matches an entry in `<skill-index>` below,",
-        "`Read` its `SKILL.md` and follow the contents.",
-    ].join("\n");
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §"`<skill-index>` block" — render
- * the per-slug index from the **materialised** SKILL.md frontmatter on
- * disk. Walking the destination dir (instead of the source manifest)
- * keeps the index in sync with what the agent will actually find when
- * it reads:
- *
- *   - Same-backend native MCP slugs whose variant resolved to `null` are
- *     correctly omitted (no SKILL.md was written).
- *   - User-authored slugs synced AFTER `writeSkillsDir` (via
- *     `syncAllUserSkills` from the workdir layer) appear automatically
- *     when this is called from the post-sync refresh helper.
- *   - Frontmatter that has gone through curation / mode filter / deny
- *     pass / read-sensitive banner reflects the post-pipeline state.
- *
- * The block is emitted with a fixed XML-style envelope so tests can pin
- * its placement and the splicer in `refreshSkillIndexBlock` can locate
- * it for in-place rewrites between turns.
- *
- * `destSkillsRootRelative` is the on-disk path the agent should Read
- * (`.codex/skills` or `.gemini/skills`); it gets embedded in the header
- * sentence verbatim. Built-ins and user-authored slugs are not
- * distinguished here — see R4.
- */
-/**
- * docs/design/appendices/skills-unification.md Phase 1 — splice sentinels.
- *
- * The visible `<skill-index>` / `</skill-index>` XML-style tags are the
- * agent-facing contract; they MUST stay in the rendered output for the
- * preamble's protocol to make sense. But using them as the splicer's
- * region markers is fragile — any profile body, skill body, or user
- * prose that quotes the tag verbatim would be misidentified as the
- * splice region and silently corrupted on `refreshSkillIndexBlock`.
- *
- * The sentinels below are unique HTML comments emitted immediately
- * outside the visible tags. The splicer keys on them instead, so even
- * a profile that quotes `<skill-index>` cannot collide with the splice
- * region. Comments render as low-signal tokens to the model and add
- * ~50 bytes per session — negligible against the ~3 KB block.
- */
-const SKILL_INDEX_START_SENTINEL = "<!-- skill-index:start -->";
-const SKILL_INDEX_END_SENTINEL = "<!-- skill-index:end -->";
-export function renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative) {
-    const lines = [
-        SKILL_INDEX_START_SENTINEL,
-        "<skill-index>",
-        `The following skills are materialized at \`${destSkillsRootRelative}/<name>/SKILL.md\`.`,
-        "When your task matches a skill's `description`, `Read` the `SKILL.md`",
-        "to load its guidance and follow it. Skill bodies are NOT inlined in",
-        "this prompt — read them on demand. Multiple skills may be loaded in",
-        "one turn.",
-        "",
-    ];
-    let entryCount = 0;
-    if (existsSync(destSkillsRootAbs)) {
-        const slugs = readdirSync(destSkillsRootAbs, { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort((a, b) => a.localeCompare(b));
-        for (const slug of slugs) {
-            const skillMdPath = join(destSkillsRootAbs, slug, "SKILL.md");
-            if (!existsSync(skillMdPath))
-                continue;
-            const fm = parseSkillFrontmatter(readFileSync(skillMdPath, "utf-8"));
-            if (!fm.name || !fm.description)
-                continue;
-            lines.push(`- name: ${fm.name}`);
-            lines.push(`  description: ${fm.description}`);
-            entryCount++;
-        }
-    }
-    if (entryCount === 0) {
-        lines.push("(No skills materialized this turn — proceed with the runtime profile only.)");
-    }
-    lines.push("</skill-index>", SKILL_INDEX_END_SENTINEL);
-    return lines.join("\n");
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 — re-render the `<skill-index>` block
- * inside an existing instruction file. Called by the workdir layer AFTER
- * `syncAllUserSkills` so user-authored slugs land in the index alongside
- * the built-ins (`renderSkillIndexBlock` reads the dest dir on disk, so a
- * post-sync re-render naturally picks them up).
- *
- * No-op when:
- *  - The backend is Claude (no instruction file with `<skill-index>`).
- *  - The instruction file is missing (the session has not been
- *    materialised yet).
- *  - The instruction file carries no `<skill-index>` block (slim
- *    fetch_window sessions, or future backends that opt out).
- *
- * Idempotent — re-running with the same dest contents produces an
- * identical instruction file.
- */
-export function refreshSkillIndexBlock(sessionDir, backendId) {
-    // docs/design/appendices/skills-unification.md Phase 1 §R3 — OpenCode never gets a
-    // `<skill-index>` block. The cwd auto-discovery loader is the source
-    // of truth; emitting an index would inject a second listing the
-    // runtime ignores. Also matters in fallback workdirs where codex and
-    // opencode share AGENTS.md: a stray opencode refresh would clobber
-    // the codex-rendered sentinels with opencode's skill listing.
-    if (backendId === "claude" || backendId === "opencode")
-        return;
-    const cliRoot = cliSkillsDirName(backendId);
-    if (cliRoot === null)
-        return;
-    const destSkillsRootRelative = join(cliRoot, "skills");
-    const destSkillsRootAbs = join(sessionDir, destSkillsRootRelative);
-    const fileName = backendId === "gemini" ? "GEMINI.md" : "AGENTS.md";
-    const instructionPath = join(sessionDir, fileName);
-    if (!existsSync(instructionPath))
-        return;
-    const current = readFileSync(instructionPath, "utf-8");
-    // Splice on the HTML-comment sentinels, NOT on the visible
-    // `<skill-index>` tags — the sentinels are unique enough that a
-    // profile body or user-authored skill that quotes the visible tag
-    // cannot collide with the splice region.
-    const startIdx = current.indexOf(SKILL_INDEX_START_SENTINEL);
-    const endIdx = startIdx >= 0
-        ? current.indexOf(SKILL_INDEX_END_SENTINEL, startIdx + SKILL_INDEX_START_SENTINEL.length)
-        : -1;
-    if (startIdx < 0 || endIdx < 0)
-        return; // OpenCode (no index) or slim path
-    const replacement = renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative);
-    const next = current.slice(0, startIdx) +
-        replacement +
-        current.slice(endIdx + SKILL_INDEX_END_SENTINEL.length);
-    if (next !== current) {
-        writeFileSync(instructionPath, next, "utf-8");
-    }
-}
-/**
- * docs/design/appendices/skills-unification.md Phase 1 §R6 — `adaptSkillForCli` (which used
- * to retain only `name`/`description`/`when_to_use` and strip
- * `allowed-tools` from CLI-bound copies) is deleted. The source
- * SKILL.md frontmatter is byte-identical across all backends post-
- * materialisation. Codex / Gemini tolerate unknown YAML keys; OpenCode's
- * permissive frontmatter parser does too (verified against
- * `docs/design/appendices/opencode-backend.md` §5.5). The `when_to_use:` field has been
- * dropped from every built-in SKILL.md (Phase 0.1 of the sister doc) so
- * there is no per-backend fork to maintain.
- */
-/**
- * Resolve `{{> base }}` include directives in a skill/task-flow variant file.
- * Reads `SKILL.base.md` (or `<key>.base.md` for task flows) from `basePath`
- * and replaces every occurrence of `{{> base }}` with the base file's content
- * (frontmatter stripped). A missing or empty base file is silently ignored.
- *
- * Only `{{> base }}` is supported — this is intentionally minimal (§4.7
- * design note: "~40 lines of pure TS").
- *
- * @deprecated DELEGATED-PROXY-API-DESIGN.md §11 — after Phase D no in-tree
- * skill uses `{{> base }}`: mail / external-services unified their bodies
- * during Phase D, and the lone surviving `notion/SKILL.base.md` was
- * removed in Phase 9 (its hourly-check read-only constraint moved to
- * `routine.hourly_check.md` task-flow where the rule applies in every
- * integration mode, including same-backend delegated where the skill
- * body is dropped). The helper is retained for future composition needs;
- * remove the call sites in `materializeClaudeSession` /
- * `materializeCliSession` when no consumer reappears.
- */
-export function renderPartialIncludes(content, basePath) {
-    if (!content.includes("{{> base }}"))
-        return content;
-    if (!existsSync(basePath))
-        return content.replace(/\{\{> base \}\}/g, "");
-    const baseRaw = readFileSync(basePath, "utf-8");
-    const baseContent = stripFrontmatter(baseRaw).trim();
-    return content.replace(/\{\{> base \}\}/g, baseContent);
-}
-/**
- * Resolve `{{> ref:<name> }}` directives in a skill body by inlining
- * `references/<name>.md` (frontmatter stripped) from the skill's source dir.
- *
- * Mirrors `renderPartialIncludes` but is intra-skill, not cross-skill: each
- * skill carries its own `references/` dir. Used by progressive-disclosure
- * skills (planned for `mail`, `roadmap`, `reading`, `user-interview` after
- * Phase 2-B) so heavy reference tables can live next to the skill body
- * without bloating the navigation overview.
- *
- * Behaviour:
- *  - Missing `references/<name>.md` → directive replaced with empty string;
- *    logged at WARN. (Mirrors the deprecated helper's missing-base behaviour.)
- *  - The directive matches `{{> ref:<name> }}` with the strict-kebab name
- *    pattern `[a-z][a-z0-9-]*`. Path-traversal (`../`, leading underscore,
- *    uppercase) is rejected at the regex level — `existsSync` is never
- *    consulted for invalid names.
- *  - Multiple occurrences each inline the same file's content (re-read per
- *    occurrence — pinned by the unit tests so a later caching refactor must
- *    surface as a deliberate change).
- *  - Frontmatter on the reference file (if present) is stripped before
- *    inline, so reference files can carry `---\nkind: reference\n---`
- *    headers for tooling without leaking YAML into skill bodies.
- *  - The resolver is NOT fence-aware; a directive inside a triple-backtick
- *    fence is still expanded. This matches `renderPartialIncludes` and is
- *    deliberate for v1 — fence-aware resolution would be a separate refactor.
- *
- * Phase 2-A ships compiler-only; no in-tree skill carries a directive yet
- * (`skills-manifest.test.ts` pins `0` as the lockstep count). Phase 2-B
- * starts emitting them per the migration map in `SKILLS-PHASE-2-PLAN.md`.
- */
-export function renderReferenceIncludes(content, skillSrcDir) {
-    return content.replace(/\{\{> ref:([a-z][a-z0-9-]*) \}\}/g, (_match, name) => {
-        const refPath = join(skillSrcDir, "references", `${name}.md`);
-        if (!existsSync(refPath)) {
-            logger.warn({ skillSrcDir, name }, "renderReferenceIncludes: missing reference file");
-            return "";
-        }
-        return stripFrontmatter(readFileSync(refPath, "utf-8")).trim();
-    });
-}
-/**
- * §7.7 — apply the per-integration tool-deny policy to a delegated skill
- * body. Two enforcement modes:
- *
- *  - **Claude (hard enforcement):** parse the YAML frontmatter and remove
- *    every `allowed-tools` entry whose unsuffixed name (after the
- *    descriptor's `toolNamespace`) is in `deniedTools`. The Claude Agent
- *    SDK refuses to invoke any tool not present in `allowed-tools`, so
- *    this is hard enforcement at the SDK boundary.
- *
- *  - **Codex / Gemini (soft enforcement):** append a "Denied tools (do
- *    not invoke)" prose block at the end of the skill body listing the
- *    full namespaced tool names. The CLI surfaces have no per-tool deny
- *    mechanism comparable to Claude's `allowed-tools`; the prose is the
- *    only guard. Documented soft-enforcement gap.
- *
- * Stale entries (a deniedTools name that doesn't match any tool in the
- * active backend's `capabilityTools`) are silently ignored — the API
- * already rejects them at PATCH time, but a delegatedBackend swap can
- * leave Claude-namespaced names in a list now active for Codex.
- *
- * Run AFTER `renderPartialIncludes` and `stripUnconfiguredServices` so
- * partial includes and service-section gating land first.
- */
-export function applyDeniedTools(content, integrationKey, backendId, deniedTools) {
-    if (deniedTools.length === 0)
-        return content;
-    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
-    const connector = descriptor.backendConnectors[backendId];
-    if (!connector)
-        return content;
-    const { active } = filterDeniedToolsForBackend(integrationKey, backendId, deniedTools);
-    if (active.length === 0)
-        return content;
-    const namespacedDenied = active.map((t) => `${connector.toolNamespace}${t}`);
-    if (backendId === "claude") {
-        return filterClaudeAllowedTools(content, new Set(namespacedDenied));
-    }
-    return appendCliDenyBlock(content, namespacedDenied);
-}
-/**
- * Strip every `allowed-tools` frontmatter entry whose name appears in
- * `deniedSet`. Preserves frontmatter ordering, line breaks, and any other
- * fields. Tolerates two YAML shapes:
- *
- *   allowed-tools:
- *     - name1
- *     - name2
- *
- *   allowed-tools: [name1, name2]
- *
- * The first form is what every skill in `agent-assets/skills/` uses today;
- * the inline form is supported because it's valid YAML and the API + UI
- * have no way to prevent a hand-edited skill from using it.
- */
-function filterClaudeAllowedTools(content, deniedSet) {
-    if (!content.startsWith("---"))
-        return content;
-    const endIdx = content.indexOf("\n---", 3);
-    if (endIdx < 0)
-        return content;
-    const frontmatter = content.slice(4, endIdx);
-    const body = content.slice(endIdx + 4);
-    const lines = frontmatter.split("\n");
-    const out = [];
-    let inAllowedTools = false;
-    for (const line of lines) {
-        if (/^allowed-tools:\s*\[/.test(line)) {
-            // Inline-array form: parse, filter, re-emit on one line.
-            const m = /^(allowed-tools:\s*)\[([^\]]*)\]/.exec(line);
-            if (m) {
-                const items = m[2]
-                    .split(",")
-                    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
-                    .filter((s) => s.length > 0 && !deniedSet.has(s));
-                out.push(`${m[1]}[${items.join(", ")}]`);
-                continue;
-            }
-        }
-        if (/^allowed-tools:\s*$/.test(line)) {
-            inAllowedTools = true;
-            out.push(line);
-            continue;
-        }
-        if (inAllowedTools) {
-            // Block-list form continuation. A block-list item is `  - <name>`;
-            // anything else (next top-level key, blank, or end of frontmatter)
-            // ends the section.
-            const itemMatch = /^\s*-\s*(.+?)\s*$/.exec(line);
-            if (itemMatch) {
-                const name = itemMatch[1].replace(/^["']|["']$/g, "");
-                if (!deniedSet.has(name))
-                    out.push(line);
-                continue;
-            }
-            // Anything else closes the block.
-            inAllowedTools = false;
-        }
-        out.push(line);
-    }
-    return `---\n${out.join("\n")}\n---${body}`;
-}
-/**
- * DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — render a top-level prose
- * deny block listing every same-backend integration tool the user has
- * denied. Returns `null` when no integration is in same-backend mode for
- * this backend or the deny lists are empty.
- *
- * Codex (γ outcome): this prose is the ONLY enforcement surface — the
- * Codex CLI's connector apps have no admin-policy or per-tool deny config.
- * The agent profile (`AGENTS.md`) inlines this block above the behavioral
- * rules so it is impossible to miss.
- *
- * Gemini: duplicate intent — admin-policy already hard-denies these tools
- * (§4.3.3 hard enforcement), but echoing the deny in prose saves tokens
- * the model would otherwise spend drafting a doomed call.
- */
-export function buildSameBackendDenyBlock(integrations, sessionBackend) {
-    const map = collectSessionDeniedTools(integrations, sessionBackend);
-    if (map.size === 0)
-        return null;
-    const lines = [
-        "## Denied tools (per-integration)",
-        "",
-        "The user has restricted the following connector tools for this session.",
-        "Do NOT invoke them in any flow — including hourly check, morning routine,",
-        "or DM responses. If a workflow appears to require one, stop and tell the",
-        "user the tool is denied.",
-    ];
-    for (const [key, names] of map.entries()) {
-        lines.push("", `### ${key}`, "");
-        for (const n of names)
-            lines.push(`- \`${n}\``);
-    }
-    return lines.join("\n");
-}
-/**
- * Append a soft-enforcement deny block to a CLI skill body. The block is
- * idempotent — re-running with the same denied set produces identical
- * output.
- */
-function appendCliDenyBlock(content, namespacedDenied) {
-    // Strip any prior deny block we wrote, so re-materialization with a
-    // changed list doesn't accumulate stale ones. The block starts with
-    // `\n## Denied tools (do not invoke)` (one preceding newline, the join
-    // contributes the second) and runs until either the next `## ` heading
-    // or end of file.
-    const stripped = content.replace(/\n+## Denied tools \(do not invoke\)[\s\S]*?(?=\n## (?!Denied tools)|$)/, "");
-    const items = namespacedDenied.map((n) => `- \`${n}\``).join("\n");
-    // Two leading empty strings → block begins with "\n\n## " so the heading
-    // sits on its own paragraph (markdown convention) regardless of what
-    // trailing whitespace the body carried.
-    const block = [
-        "",
-        "",
-        "## Denied tools (do not invoke)",
-        "",
-        "The user has restricted these connector tools for this integration. Do",
-        "NOT invoke them in any flow — including hourly check, morning routine,",
-        "or DM responses. If a workflow appears to require one, stop and tell",
-        "the user the tool is denied.",
-        "",
-        items,
-        "",
-    ].join("\n");
-    return stripped.replace(/\s*$/, "") + block;
-}
-/**
- * Apply the deny pass for every integration whose `skillsTouched` OR
- * `deniedToolsAppliesToSkills` includes the given skill slug. A skill that
- * touches no integration leaves content unchanged. Touching multiple
- * integrations runs the pass once per integration so each contributes its
- * own deny list.
- *
- * Hard enforcement of the same deny list for cross-backend delegated
- * calls lives at the `POST /api/integrations/:key/exec` task-mode
- * chokepoint (DELEGATED-MODE-V2-DESIGN.md §4.3.2; the legacy `/invoke`
- * RPC was retired 2026-05-01). For same-backend native MCP it is
- * enforced via SDK `disallowedTools` (Claude) / admin policy (Gemini);
- * see `collectSessionDeniedTools` (§4.3.3).
- */
-export function applyAllDeniedToolsForSkill(content, skillSlug, backendId, integrations) {
-    let result = content;
-    for (const key of INTEGRATION_KEYS) {
-        const descriptor = INTEGRATION_DESCRIPTORS[key];
-        const touched = descriptor.skillsTouched.includes(skillSlug)
-            || (descriptor.deniedToolsAppliesToSkills?.includes(skillSlug) ?? false);
-        if (!touched)
-            continue;
-        const state = integrations[key];
-        if (!state)
-            continue;
-        if (state.mode !== "delegated")
-            continue;
-        if (!state.delegatedBackend || state.delegatedBackend !== backendId)
-            continue;
-        const denied = state.deniedTools ?? [];
-        if (denied.length === 0)
-            continue;
-        result = applyDeniedTools(result, key, backendId, denied);
-    }
-    return result;
-}
-/**
- * Remove any built-in skill directory under `destRoot` whose slug is not
- * in `keep`. Recognises a directory as a built-in by its presence under
- * the source `agent-assets/skills/` tree — anything else (user-authored
- * skill, accounts.md, etc.) is left alone, since `syncAllUserSkills` is
- * the canonical writer for those.
- *
- * Idempotent and side-effect-free when there is nothing to prune.
- * Exported for unit testing only.
- */
-export function pruneStaleBuiltinSkillDirs(destRoot, sourceSkillsRoot, keep) {
-    if (!existsSync(destRoot))
-        return;
-    if (!existsSync(sourceSkillsRoot))
-        return;
-    const keepSet = new Set(keep);
-    // `listBuiltinSlugs` recurses one level into category subdirs (e.g.
-    // WIKI_BUILDER_DESIGN.md §9.1 `wiki/`) so wiki slugs are recognised
-    // as built-ins for prune purposes even though their source dir is
-    // nested. Destination layout stays flat — `<destRoot>/<slug>/` for
-    // every slug regardless of source category.
-    const builtinSlugs = new Set(listBuiltinSlugs(sourceSkillsRoot));
-    for (const entry of readdirSync(destRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory())
-            continue;
-        if (!builtinSlugs.has(entry.name))
-            continue;
-        if (keepSet.has(entry.name))
-            continue;
-        rmSync(join(destRoot, entry.name), { recursive: true, force: true });
-    }
-}
-function readTreeFiles(root) {
-    if (!existsSync(root)) {
-        return [];
-    }
-    const files = [];
-    for (const relPath of walkTree(root)) {
-        const absPath = join(root, relPath);
-        const stat = statSync(absPath);
-        files.push({
-            path: relPath,
-            content: readFileSync(absPath, "utf-8"),
-            updatedAt: stat.mtime.toISOString(),
-        });
-    }
-    return files;
-}
-function walkTree(root, current = root) {
-    if (!existsSync(current)) {
-        return [];
-    }
-    const entries = readdirSync(current, { withFileTypes: true });
-    const files = [];
-    for (const entry of entries) {
-        const absPath = join(current, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...walkTree(root, absPath));
-            continue;
-        }
-        files.push(relative(root, absPath));
-    }
-    return files.sort();
-}
-//# sourceMappingURL=skills-compiler.js.map