@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/profile/types.d.ts

@@ -0,0 +1,321 @@
+/**
+ * WorkspaceProfile（数字人）— harness 元机制的数据定义。
+ * 引用现有窄 AgentPreset，不修改它；plugins/skills/mcp/agents 在激活时
+ * 展开为 capabilityOverrides 形状的 force-enable 快照（见 activation.ts）。
+ * 设计稿：docs/superpowers/specs/2026-07-15-workspace-profile-design.md
+ */
+import { z } from "zod";
+/** 目录名即机器标识：小写字母/数字开头，可含 - _，防路径逃逸。 */
+export declare const WORKSPACE_PROFILE_NAME_RE: RegExp;
+/**
+ * `owner/repo`。收紧到 GitHub 允许的字符集，且两段都不能以 `-`/`.` 开头 ——
+ * 这个值会作为参数传给 `npx skills add`，必须挡住 `--flag`、`../` 一类注入。
+ */
+export declare const SKILL_REPO_RE: RegExp;
+/** 纯数字点分版本，避免把任意字符串塞进版本比较。 */
+export declare const TOOL_VERSION_RE: RegExp;
+/** 持久化与提示注入的防滥用边界；Desktop 编辑器应保持相同上限。 */
+export declare const WORKSPACE_PROFILE_LIMITS: {
+    readonly label: 120;
+    readonly description: 4096;
+    readonly basePreset: 128;
+    readonly mainInstruction: 32768;
+    readonly version: 128;
+    readonly capabilityCount: 128;
+    readonly capabilityName: 256;
+    /** requires.skills / requires.tools 各自的条目上限。 */
+    readonly requirementCount: 16;
+};
+/**
+ * 依赖来源：数字人自带的「怎么把能力弄来」声明。
+ *
+ * 与 plugins/skills/mcp/agents 的分工：那四个是 force-enable 开关（只能打开
+ * 磁盘上已存在的东西），`requires` 才是获取步骤。没有 `requires` 的旧 profile
+ * 行为完全不变。
+ *
+ * 解析、冲突预检与安装见 requirements.ts —— 安装涉及克隆远程仓库与执行
+ * `npx skills add`，必须先经用户确认，绝不静默执行。
+ */
+declare const skillRequirementSchema: z.ZodObject<{
+    /** 目前只支持 github；保留判别字段以便后续扩展。 */
+    source: z.ZodLiteral<"github">;
+    /** `owner/repo` 形式。 */
+    repo: z.ZodString;
+    /** 只装这些 skill；省略表示装全部（`--all`）。 */
+    skills: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    /**
+     * project → `<cwd>/.agents/skills`（scanner 认）。
+     * user 级 `npx skills add -g` 落在 `~/.claude/skills`，**不在 scanner 的三个根里**，
+     * 装了会扫不到，故不开放该 scope。
+     */
+    scope: z.ZodDefault<z.ZodLiteral<"project">>;
+    /** 仓库根有 SKILL.md 时也继续深搜子目录。 */
+    fullDepth: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    source: "github";
+    scope: "project";
+    repo: string;
+    fullDepth: boolean;
+    skills?: string[] | undefined;
+}, {
+    source: "github";
+    repo: string;
+    scope?: "project" | undefined;
+    skills?: string[] | undefined;
+    fullDepth?: boolean | undefined;
+}>;
+/** 装不了、只能检测的外部命令（ffmpeg / node …）。缺失时提前失败，而不是渲染到一半才炸。 */
+declare const toolRequirementSchema: z.ZodObject<{
+    bin: z.ZodString;
+    /** 形如 "22"、"22.1"、"22.1.0"，与 `--version` 输出的首个版本号比较。 */
+    minVersion: z.ZodOptional<z.ZodString>;
+    /** 缺失时展示给用户的安装建议，例如 "brew install ffmpeg"。 */
+    hint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bin: string;
+    minVersion?: string | undefined;
+    hint?: string | undefined;
+}, {
+    bin: string;
+    minVersion?: string | undefined;
+    hint?: string | undefined;
+}>;
+export declare const WorkspaceProfileRequirementsSchema: z.ZodObject<{
+    skills: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** 目前只支持 github；保留判别字段以便后续扩展。 */
+        source: z.ZodLiteral<"github">;
+        /** `owner/repo` 形式。 */
+        repo: z.ZodString;
+        /** 只装这些 skill；省略表示装全部（`--all`）。 */
+        skills: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+        /**
+         * project → `<cwd>/.agents/skills`（scanner 认）。
+         * user 级 `npx skills add -g` 落在 `~/.claude/skills`，**不在 scanner 的三个根里**，
+         * 装了会扫不到，故不开放该 scope。
+         */
+        scope: z.ZodDefault<z.ZodLiteral<"project">>;
+        /** 仓库根有 SKILL.md 时也继续深搜子目录。 */
+        fullDepth: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        source: "github";
+        scope: "project";
+        repo: string;
+        fullDepth: boolean;
+        skills?: string[] | undefined;
+    }, {
+        source: "github";
+        repo: string;
+        scope?: "project" | undefined;
+        skills?: string[] | undefined;
+        fullDepth?: boolean | undefined;
+    }>, "many">>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        bin: z.ZodString;
+        /** 形如 "22"、"22.1"、"22.1.0"，与 `--version` 输出的首个版本号比较。 */
+        minVersion: z.ZodOptional<z.ZodString>;
+        /** 缺失时展示给用户的安装建议，例如 "brew install ffmpeg"。 */
+        hint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        bin: string;
+        minVersion?: string | undefined;
+        hint?: string | undefined;
+    }, {
+        bin: string;
+        minVersion?: string | undefined;
+        hint?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    skills: {
+        source: "github";
+        scope: "project";
+        repo: string;
+        fullDepth: boolean;
+        skills?: string[] | undefined;
+    }[];
+    tools: {
+        bin: string;
+        minVersion?: string | undefined;
+        hint?: string | undefined;
+    }[];
+}, {
+    skills?: {
+        source: "github";
+        repo: string;
+        scope?: "project" | undefined;
+        skills?: string[] | undefined;
+        fullDepth?: boolean | undefined;
+    }[] | undefined;
+    tools?: {
+        bin: string;
+        minVersion?: string | undefined;
+        hint?: string | undefined;
+    }[] | undefined;
+}>;
+export type SkillRequirement = z.infer<typeof skillRequirementSchema>;
+export type ToolRequirement = z.infer<typeof toolRequirementSchema>;
+export type WorkspaceProfileRequirements = z.infer<typeof WorkspaceProfileRequirementsSchema>;
+export declare const WorkspaceProfileSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /** 引用现有 AgentPreset 名（如 "general"）；不在 schema 层校验存在性，解析时才校验。 */
+    basePreset: z.ZodString;
+    /** 可选：省略即旧行为（只 enable，不获取）。 */
+    requires: z.ZodOptional<z.ZodObject<{
+        skills: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** 目前只支持 github；保留判别字段以便后续扩展。 */
+            source: z.ZodLiteral<"github">;
+            /** `owner/repo` 形式。 */
+            repo: z.ZodString;
+            /** 只装这些 skill；省略表示装全部（`--all`）。 */
+            skills: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+            /**
+             * project → `<cwd>/.agents/skills`（scanner 认）。
+             * user 级 `npx skills add -g` 落在 `~/.claude/skills`，**不在 scanner 的三个根里**，
+             * 装了会扫不到，故不开放该 scope。
+             */
+            scope: z.ZodDefault<z.ZodLiteral<"project">>;
+            /** 仓库根有 SKILL.md 时也继续深搜子目录。 */
+            fullDepth: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            source: "github";
+            scope: "project";
+            repo: string;
+            fullDepth: boolean;
+            skills?: string[] | undefined;
+        }, {
+            source: "github";
+            repo: string;
+            scope?: "project" | undefined;
+            skills?: string[] | undefined;
+            fullDepth?: boolean | undefined;
+        }>, "many">>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            bin: z.ZodString;
+            /** 形如 "22"、"22.1"、"22.1.0"，与 `--version` 输出的首个版本号比较。 */
+            minVersion: z.ZodOptional<z.ZodString>;
+            /** 缺失时展示给用户的安装建议，例如 "brew install ffmpeg"。 */
+            hint: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }, {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        skills: {
+            source: "github";
+            scope: "project";
+            repo: string;
+            fullDepth: boolean;
+            skills?: string[] | undefined;
+        }[];
+        tools: {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }[];
+    }, {
+        skills?: {
+            source: "github";
+            repo: string;
+            scope?: "project" | undefined;
+            skills?: string[] | undefined;
+            fullDepth?: boolean | undefined;
+        }[] | undefined;
+        tools?: {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }[] | undefined;
+    }>>;
+    /**
+     * true → 独占工作面：激活时把**未声明**的 skill/plugin/mcp/agent 显式关掉，
+     * 而不是与用户已开启的取并集。
+     *
+     * 默认 false（并集）是安全的：数字人只保证「该有的能力一定在」，绝不静默
+     * 关掉用户手动开的东西。独占是更强的意图——「切到这个数字人就只用这套工具」
+     * ——上下文更干净，但代价是用户会发现自己开的东西不见了，所以必须显式声明。
+     * 注意：用户在项目 settings 里手写的 override 优先级仍然最高（见 overlay.ts）。
+     */
+    exclusiveCapabilities: z.ZodDefault<z.ZodBoolean>;
+    plugins: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    skills: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    mcp: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    agents: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>>;
+    /** 数字人主指令，注入系统提示（优先级低于本地 CLAUDE.md，高于 preset sections）。 */
+    mainInstruction: z.ZodOptional<z.ZodString>;
+    /** true → 挂载 profiles/<name>/ 为第二记忆层（跟数字人走）。 */
+    portableMemory: z.ZodDefault<z.ZodBoolean>;
+    version: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    mcp: string[];
+    name: string;
+    label: string;
+    skills: string[];
+    plugins: string[];
+    agents: string[];
+    basePreset: string;
+    exclusiveCapabilities: boolean;
+    portableMemory: boolean;
+    version?: string | undefined;
+    description?: string | undefined;
+    requires?: {
+        skills: {
+            source: "github";
+            scope: "project";
+            repo: string;
+            fullDepth: boolean;
+            skills?: string[] | undefined;
+        }[];
+        tools: {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }[];
+    } | undefined;
+    mainInstruction?: string | undefined;
+}, {
+    name: string;
+    label: string;
+    basePreset: string;
+    version?: string | undefined;
+    mcp?: string[] | undefined;
+    description?: string | undefined;
+    skills?: string[] | undefined;
+    plugins?: string[] | undefined;
+    agents?: string[] | undefined;
+    requires?: {
+        skills?: {
+            source: "github";
+            repo: string;
+            scope?: "project" | undefined;
+            skills?: string[] | undefined;
+            fullDepth?: boolean | undefined;
+        }[] | undefined;
+        tools?: {
+            bin: string;
+            minVersion?: string | undefined;
+            hint?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    exclusiveCapabilities?: boolean | undefined;
+    mainInstruction?: string | undefined;
+    portableMemory?: boolean | undefined;
+}>;
+export type WorkspaceProfile = z.infer<typeof WorkspaceProfileSchema>;
+/**
+ * 写入侧类型：带 `.default()` 的字段（`exclusiveCapabilities`、`portableMemory`、
+ * 四个 capability 列表）在这里是可选的。
+ *
+ * 为什么需要它：`WorkspaceProfile` 是 schema 的**输出**类型，defaults 已解析，
+ * 所以每个字段都是必填。但接受「未解析的 profile 再 parse」的函数
+ * （如 `saveWorkspaceProfile`）实际契约是**输入**类型——用输出类型标注会强迫每个
+ * 调用方手写它本来就想让 schema 填的默认值。schema 新增一个带 default 的字段时，
+ * 这个错配会让所有既有调用方一起报错（`exclusiveCapabilities` 就是这么发生的）。
+ */
+export type WorkspaceProfileInput = z.input<typeof WorkspaceProfileSchema>;
+export {};

package/dist/profile/types.js

@@ -0,0 +1,104 @@
+/**
+ * WorkspaceProfile（数字人）— harness 元机制的数据定义。
+ * 引用现有窄 AgentPreset，不修改它；plugins/skills/mcp/agents 在激活时
+ * 展开为 capabilityOverrides 形状的 force-enable 快照（见 activation.ts）。
+ * 设计稿：docs/superpowers/specs/2026-07-15-workspace-profile-design.md
+ */
+import { z } from "zod";
+/** 目录名即机器标识：小写字母/数字开头，可含 - _，防路径逃逸。 */
+export const WORKSPACE_PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * `owner/repo`。收紧到 GitHub 允许的字符集，且两段都不能以 `-`/`.` 开头 ——
+ * 这个值会作为参数传给 `npx skills add`，必须挡住 `--flag`、`../` 一类注入。
+ */
+export const SKILL_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** 纯数字点分版本，避免把任意字符串塞进版本比较。 */
+export const TOOL_VERSION_RE = /^\d+(\.\d+){0,2}$/;
+/** 持久化与提示注入的防滥用边界；Desktop 编辑器应保持相同上限。 */
+export const WORKSPACE_PROFILE_LIMITS = {
+    label: 120,
+    description: 4_096,
+    basePreset: 128,
+    mainInstruction: 32_768,
+    version: 128,
+    capabilityCount: 128,
+    capabilityName: 256,
+    /** requires.skills / requires.tools 各自的条目上限。 */
+    requirementCount: 16,
+};
+const capabilityNameSchema = z.string().min(1).max(WORKSPACE_PROFILE_LIMITS.capabilityName);
+const capabilityListSchema = z
+    .array(capabilityNameSchema)
+    .max(WORKSPACE_PROFILE_LIMITS.capabilityCount)
+    .refine((items) => new Set(items).size === items.length, {
+    message: "capability entries must be unique",
+});
+/**
+ * 依赖来源：数字人自带的「怎么把能力弄来」声明。
+ *
+ * 与 plugins/skills/mcp/agents 的分工：那四个是 force-enable 开关（只能打开
+ * 磁盘上已存在的东西），`requires` 才是获取步骤。没有 `requires` 的旧 profile
+ * 行为完全不变。
+ *
+ * 解析、冲突预检与安装见 requirements.ts —— 安装涉及克隆远程仓库与执行
+ * `npx skills add`，必须先经用户确认，绝不静默执行。
+ */
+const skillRequirementSchema = z.object({
+    /** 目前只支持 github；保留判别字段以便后续扩展。 */
+    source: z.literal("github"),
+    /** `owner/repo` 形式。 */
+    repo: z.string().regex(SKILL_REPO_RE),
+    /** 只装这些 skill；省略表示装全部（`--all`）。 */
+    skills: capabilityListSchema.optional(),
+    /**
+     * project → `<cwd>/.agents/skills`（scanner 认）。
+     * user 级 `npx skills add -g` 落在 `~/.claude/skills`，**不在 scanner 的三个根里**，
+     * 装了会扫不到，故不开放该 scope。
+     */
+    scope: z.literal("project").default("project"),
+    /** 仓库根有 SKILL.md 时也继续深搜子目录。 */
+    fullDepth: z.boolean().default(false),
+});
+/** 装不了、只能检测的外部命令（ffmpeg / node …）。缺失时提前失败，而不是渲染到一半才炸。 */
+const toolRequirementSchema = z.object({
+    bin: z.string().min(1).max(WORKSPACE_PROFILE_LIMITS.capabilityName),
+    /** 形如 "22"、"22.1"、"22.1.0"，与 `--version` 输出的首个版本号比较。 */
+    minVersion: z.string().regex(TOOL_VERSION_RE).optional(),
+    /** 缺失时展示给用户的安装建议，例如 "brew install ffmpeg"。 */
+    hint: z.string().max(WORKSPACE_PROFILE_LIMITS.capabilityName).optional(),
+});
+export const WorkspaceProfileRequirementsSchema = z.object({
+    skills: z
+        .array(skillRequirementSchema)
+        .max(WORKSPACE_PROFILE_LIMITS.requirementCount)
+        .default([]),
+    tools: z.array(toolRequirementSchema).max(WORKSPACE_PROFILE_LIMITS.requirementCount).default([]),
+});
+export const WorkspaceProfileSchema = z.object({
+    name: z.string().regex(WORKSPACE_PROFILE_NAME_RE),
+    label: z.string().min(1).max(WORKSPACE_PROFILE_LIMITS.label),
+    description: z.string().max(WORKSPACE_PROFILE_LIMITS.description).optional(),
+    /** 引用现有 AgentPreset 名（如 "general"）；不在 schema 层校验存在性，解析时才校验。 */
+    basePreset: z.string().min(1).max(WORKSPACE_PROFILE_LIMITS.basePreset),
+    /** 可选：省略即旧行为（只 enable，不获取）。 */
+    requires: WorkspaceProfileRequirementsSchema.optional(),
+    /**
+     * true → 独占工作面：激活时把**未声明**的 skill/plugin/mcp/agent 显式关掉，
+     * 而不是与用户已开启的取并集。
+     *
+     * 默认 false（并集）是安全的：数字人只保证「该有的能力一定在」，绝不静默
+     * 关掉用户手动开的东西。独占是更强的意图——「切到这个数字人就只用这套工具」
+     * ——上下文更干净，但代价是用户会发现自己开的东西不见了，所以必须显式声明。
+     * 注意：用户在项目 settings 里手写的 override 优先级仍然最高（见 overlay.ts）。
+     */
+    exclusiveCapabilities: z.boolean().default(false),
+    plugins: capabilityListSchema.default([]),
+    skills: capabilityListSchema.default([]),
+    mcp: capabilityListSchema.default([]),
+    agents: capabilityListSchema.default([]),
+    /** 数字人主指令，注入系统提示（优先级低于本地 CLAUDE.md，高于 preset sections）。 */
+    mainInstruction: z.string().max(WORKSPACE_PROFILE_LIMITS.mainInstruction).optional(),
+    /** true → 挂载 profiles/<name>/ 为第二记忆层（跟数字人走）。 */
+    portableMemory: z.boolean().default(false),
+    version: z.string().max(WORKSPACE_PROFILE_LIMITS.version).optional(),
+});

package/dist/prompt/composer.d.ts

@@ -8,6 +8,8 @@
 import type { ToolDefinition, Message } from "../types.js";
 import { type ScanOptions } from "./instruction-scanner.js";
 import { type AgentPreset } from "../preset/index.js";
+import type { BuiltinTool } from "../tool-system/builtin/index.js";
+import type { CapabilityDynamicContextProvider } from "../capabilities/index.js";
 export interface ComposerOptions {
     cwd: string;
     model: string;
@@ -16,10 +18,46 @@ export interface ComposerOptions {
     preset?: AgentPreset;
     customSystemPrompt?: string;
     appendSystemPrompt?: string;
+    /** Prompt text and tool metadata supplied by this Engine's capability modules. */
+    capabilityPromptSections?: Readonly<Record<string, string>>;
+    /** Per-turn context owned by installed capability modules. */
+    dynamicContextProviders?: readonly CapabilityDynamicContextProvider[];
+    /**
+     * 已绑定数据源的 metadata 摘要（名称/scope/状态；无源返回 ""）。只走动态
+     * 上下文（不进可缓存 system 前缀），资源内容与 secret 永不注入（ADR §5/§7）。
+     */
+    sourcesContextProvider?: () => string | Promise<string>;
+    toolCatalog?: readonly BuiltinTool[];
     /** User's preferred response language (free text), injected as a stable system section. */
     responseLanguage?: string;
     /** How to address the user / short profile (free text). */
     userProfile?: string;
+    /**
+     * 激活数字人（WorkspaceProfile）的主指令。排序在 preset behavior 之后、
+     * appendSystemPrompt 之前 —— 本地 CLAUDE.md（user-context 消息）与用户
+     * append 都比它更“具体/优先”。来源：engine 经 resolveActiveWorkspaceProfile
+     * 解析后传入；composer 不自行读盘。
+     */
+    profileMainInstruction?: string;
+    /**
+     * Standing brief for this Session (see SessionState.sessionBrief) — team role,
+     * teammate Session ids, the lead's playbook. Part of the cached system prefix
+     * because it is fixed for the Session's lifetime, unlike the skills listing.
+     */
+    sessionBrief?: string;
+    /**
+     * Skills the active digital human declares (`WorkspaceProfile.skills`).
+     *
+     * Used only to warn when a declared skill is not actually installed here.
+     * `requires` installs per project, so a digital human summoned in a project
+     * that never got the install has an instruction telling it to use `/x` while
+     * `/x` does not exist — a real session then called `/hyperframes`, got
+     * "Skill not found", searched with Glob, and gave up. Stating the gap costs a
+     * line and stops the flailing.
+     */
+    profileDeclaredSkills?: readonly string[];
+    /** 激活数字人的可移植记忆层根目录（portableMemory=true 时由 engine 传入）。 */
+    profileMemoryDir?: string;
     /**
      * Skill names (full names including any "<plugin>:" prefix) the user
      * has disabled in settings. Filtered out of the LLM's skills listing
@@ -65,23 +103,24 @@ export declare class PromptComposer {
      * Build the userContext prefix message (CLAUDE.md content as <system-reminder>).
      */
     buildUserContextMessage(): Message | null;
-    /**
-     * Build the systemContext (gitStatus etc.) to append to system prompt.
-     * Only injects git status if the resolved preset opts in.
-     */
+    /** Build volatile context contributed by installed capability modules. */
     buildSystemContext(): Promise<string>;
     /**
      * Per-turn dynamic context, delivered as a trailing <system-reminder> user
      * message rather than baked into the system prefix.
      *
-     * Holds the two things that change *within* a session — the skills listing
-     * (changes when a skill is installed/disabled) and the git-status snapshot
-     * (changes whenever the working tree changes). Keeping them out of the
+     * Holds things that change *within* a session — the skills listing plus
+     * capability-owned volatile context. Keeping them out of the
      * system prompt means installing a skill or editing a file no longer
      * invalidates the cached system prefix. Placed at the END of the messages
      * array (after the user task) so it sits past the conversation's cache
      * breakpoint — a change here never re-bills the history prefix.
      */
+    /**
+     * Declared-but-absent skills, stated plainly. Rides the dynamic context (not
+     * the cached system prefix) because it depends on what is installed right now.
+     */
+    private buildDeclaredSkillGap;
     buildDynamicContextMessage(): Promise<Message | null>;
     private buildGoalToolContext;
     invalidateCache(sectionName?: string): void;