@aitne/daemon 0.1.8 → 0.1.9

package/dist/core/skills-compiler-skill-index.js

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../logging.js";
+import { parseSkillFrontmatter } from "./skills-compiler-variants.js";
+// Peer logger for this module. Exported so tests can spy on `logger.warn`
+// (specifically the missing-reference branch of `renderReferenceIncludes`).
+// Production callers do not import it.
+export const logger = createLogger("skills-compiler-skill-index");
+/**
+ * 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 §"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.
+ */
+export 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 — 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 -->";
+/**
+ * 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.
+ */
+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.
+    //
+    // Backend→dotfile dir mapping is inlined here (rather than imported from
+    // skills-compiler-cli-renderer) so this module sits at the same DAG
+    // level as cli-renderer — both depend only on `variants`. The mapping
+    // is two cases and changes once per new backend; the cost of duplication
+    // is bounded.
+    let cliRoot;
+    if (backendId === "codex")
+        cliRoot = ".codex";
+    else if (backendId === "gemini")
+        cliRoot = ".gemini";
+    else
+        return; // claude / opencode / future backends without `<skill-index>`
+    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");
+    }
+}
+/**
+ * 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();
+    });
+}

package/dist/core/skills-compiler-tree.d.ts

@@ -0,0 +1,38 @@
+import type { MailAccount } from "../services/mail/provider.js";
+export interface SkillCompilerFile {
+    path: string;
+    content: string;
+    updatedAt: string | null;
+}
+/**
+ * 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.
+ */
+export declare function substituteBrandTokensInDir(dir: string): void;
+interface WikiWorkspaceTokens {
+    vault_path: string;
+    language: string;
+    workspace_name: string;
+    schema_version: string;
+}
+export declare function setWikiWorkspaceTokenResolver(resolver: ((processKey: string, workspaceName?: string) => WikiWorkspaceTokens | null) | null): void;
+export declare function substituteWikiWorkspaceTokens(content: string, processKey: string | null | undefined, workspaceName: string | undefined): string;
+export declare function substituteWikiWorkspaceTokensInDir(dir: string, processKey: string | null | undefined, workspaceName: string | undefined): void;
+export declare const EMPTY_MAIL_ACCOUNTS_MD: string;
+export declare function renderMailAccountsMd(accounts: readonly MailAccount[]): string;
+/**
+ * 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 declare function pruneStaleBuiltinSkillDirs(destRoot: string, sourceSkillsRoot: string, keep: readonly string[]): void;
+export declare function readTreeFiles(root: string): SkillCompilerFile[];
+export {};

package/dist/core/skills-compiler-tree.js

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { substituteBrandTokens } from "@aitne/shared";
+import { listBuiltinSlugs } from "./skill-source-paths.js";
+/**
+ * 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.
+ */
+export 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;
+}
+export 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);
+}
+export 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 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");
+}
+/**
+ * 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 });
+    }
+}
+export 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();
+}

package/dist/core/skills-compiler-types.d.ts

@@ -0,0 +1,46 @@
+import type { BackendId, ProcessKey } from "@aitne/shared";
+/**
+ * Shape consumed by `renderCliInstructionFile` (now in
+ * `skills-compiler-cli-renderer.ts`). The owning `SkillsCompiler` class
+ * composes every field in `materializeCliSession` / `materializeOpencodeSession`.
+ *
+ * Lives in its own module so the renderer can import the type without
+ * pulling the 1100-line class file. `SessionPromptBundleParams` (the
+ * params shape `materializeSessionBundle` itself takes) is internal to
+ * the class and stays in `skills-compiler.ts`.
+ */
+export interface SessionInstructionParams {
+    backendId: Exclude<BackendId, "claude">;
+    processKey: ProcessKey | string;
+    profileName: string;
+    profileContent: string;
+    safetyContent: string | null;
+    /**
+     * Fully-rendered `## Character (user-defined)` block (from
+     * `buildCharacterBlock`), or `null` when the user has no character set.
+     */
+    characterBlock: string | null;
+    /** Slug list rendered into the `## Skills` manifest section for OpenCode
+     *  (slug listing only, no path) and ignored by Codex / Gemini (which
+     *  pivot to the on-demand `<skill-index>` block below). */
+    skillSlugs: string[];
+    /**
+     * docs/design/appendices/skills-unification.md Phase 1 — preamble + index pair emitted for
+     * Codex / Gemini only. The preamble is the universal "how to use skills"
+     * paragraph loaded from `agent-assets/system-prompts/skill-index-instruction.md`;
+     * the index block is the per-slug `name`/`description` listing rendered
+     * from the materialised SKILL.md frontmatter. Both `null` for OpenCode,
+     * where cwd auto-discovery removes the need for either (R3 — emitting
+     * either to OpenCode could shadow its native loader).
+     */
+    skillPreamble: string | null;
+    skillIndexBlock: string | null;
+    /**
+     * DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — same-backend integration deny
+     * list rendered as a top-level prose block. For Codex this is the only
+     * enforcement surface (γ outcome — no MCP-tool deny mechanism); for Gemini
+     * it duplicates the admin-policy hard-deny as belt-and-suspenders prose.
+     * `null` when no same-backend integration has deniedTools entries.
+     */
+    sameBackendDenyBlock: string | null;
+}

package/dist/core/skills-compiler-types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/skills-compiler-variants.d.ts

@@ -0,0 +1,117 @@
+import { type BackendId, type IntegrationKey } from "@aitne/shared";
+/**
+ * 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`
+ */
+export declare function missingDelegatedVariants(workspaceDir: string, integrationKey: IntegrationKey, delegatedBackend: BackendId): {
+    skills: string[];
+    taskFlows: string[];
+};
+/**
+ * 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 declare function missingNativeVariants(workspaceDir: string, integrationKey: IntegrationKey, nativeBackend: BackendId): {
+    skills: string[];
+    taskFlows: string[];
+};
+/**
+ * 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 declare function isValidSkillSlug(slug: string): boolean;
+/**
+ * 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 declare function validateBuiltinSkillSourceTree(skillsRoot: string): void;
+/**
+ * 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 declare function parseSkillFrontmatter(content: string): {
+    name: string | null;
+    description: string | 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 declare 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 declare const READ_SENSITIVE_API_PREFIXES: readonly ["/api/apple-calendar", "/api/books", "/api/browser-task", "/api/calendar", "/api/context", "/api/entities", "/api/mail", "/api/mcp/servers", "/api/notion", "/api/observations", "/api/obsidian", "/api/receipts", "/api/travel-bookings"];
+export declare function skillBodyTouchesReadSensitive(skillBody: string): boolean;