@aitne/daemon 0.1.8 → 0.1.9

package/dist/core/skills-compiler-cli-renderer.js

@@ -0,0 +1,289 @@
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { APP_NAME } from "@aitne/shared";
+import { createLogger } from "../logging.js";
+import { applyCharacterBlockRewrite } from "./character-block.js";
+import { renderOutputLanguagePolicyPointer } from "./output-language-policy.js";
+import { skillBodyTouchesReadSensitive } from "./skills-compiler-variants.js";
+// Peer logger for this module — the `rewriteCharacterBlock` path emits
+// per-file warnings on filesystem errors. Module-scoped so a future test
+// can spy on it without crossing the `skills-compiler.ts` boundary.
+const logger = createLogger("skills-compiler-cli-renderer");
+/**
+ * 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;
+}
+export 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");
+}
+/**
+ * Daemon-API usage section. Pulled by `renderCliInstructionFile` for CLI
+ * backends (passing `params.backendId !== "codex"`) and by
+ * `SkillsCompiler.materializeClaudeSession` for the Claude SDK path
+ * (always `true` — Claude holds the read-sensitive token). The single
+ * source of truth keeps the rendered prose byte-identical across all four
+ * backends.
+ */
+export 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");
+}
+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).
+ */
+export 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");
+}

package/dist/core/skills-compiler-denied-tools.d.ts

@@ -0,0 +1,57 @@
+import { type BackendId, type IntegrationKey, type IntegrationState } from "@aitne/shared";
+/**
+ * §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 declare function applyDeniedTools(content: string, integrationKey: IntegrationKey, backendId: BackendId, deniedTools: readonly string[]): string;
+/**
+ * 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 declare function buildSameBackendDenyBlock(integrations: Partial<Record<IntegrationKey, IntegrationState>>, sessionBackend: BackendId): string | null;
+/**
+ * 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). For same-backend
+ * native MCP it is
+ * enforced via SDK `disallowedTools` (Claude) / admin policy (Gemini);
+ * see `collectSessionDeniedTools` (§4.3.3).
+ */
+export declare function applyAllDeniedToolsForSkill(content: string, skillSlug: string, backendId: BackendId, integrations: Partial<Record<IntegrationKey, IntegrationState>>): string;

package/dist/core/skills-compiler-denied-tools.js

@@ -0,0 +1,204 @@
+import { INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, collectSessionDeniedTools, filterDeniedToolsForBackend, } from "@aitne/shared";
+/**
+ * §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). 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;
+}

package/dist/core/skills-compiler-skill-index.d.ts

@@ -0,0 +1,117 @@
+import type { BackendId } from "@aitne/shared";
+export declare const logger: import("pino").Logger<never, boolean>;
+/**
+ * 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 declare function stripUnconfiguredServices(content: string, configuredServices: ReadonlySet<string>): string;
+/**
+ * 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 declare function loadSkillIndexPreamble(workspaceDir: string): string;
+/**
+ * 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 declare function renderSkillIndexBlock(destSkillsRootAbs: string, destSkillsRootRelative: string): string;
+/**
+ * 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 declare function refreshSkillIndexBlock(sessionDir: string, backendId: BackendId): void;
+/**
+ * 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 declare function renderPartialIncludes(content: string, basePath: string): string;
+/**
+ * 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 declare function renderReferenceIncludes(content: string, skillSrcDir: string): string;