berry-agent 0.1.0-alpha.1

package/dist/skills/registry.js

@@ -0,0 +1,138 @@
+/**
+ * 技能注册表（06 §11.3 护栏②注册表层 + 03 skills_change 事件面）。
+ *
+ * - provider 注册序即优先序（06 §11.3）；同名 first-wins 由扫描序表达，冲突带
+ *   collision 诊断（winner/loser 双路径）；
+ * - 快照数帽 100：超帽裁尾 + capacity 诊断列被裁计数（provider 注册序即裁序
+ *   ——最低优先层先出局）；
+ * - refresh() 全量重扫（/reload 正口与 skill_manage 写后自动刷新共用一径）；
+ * - onChange 监听面 = 03 skills_change 事件的装配桥（载荷 = 现行 provider id
+ *   清单，消费 = 渐进披露清单重物化）；
+ * - 并发 refresh 串行化（承诺链——后到刷新在先到落定后重扫，末笔即最新快照；
+ *   与 exec 登记簿持久化链同律）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { SKILL_SNAPSHOT_CAP } from './types.js';
+/**
+ * 创建技能注册表。
+ *
+ * @param options.cap 快照数帽（缺省 100）
+ */
+export function createSkillsRegistry(options = {}) {
+    const cap = options.cap ?? SKILL_SNAPSHOT_CAP;
+    const providers = [];
+    const providerById = new Map();
+    let snapshot = [];
+    let lastDiagnostics = [];
+    let lastReport = { providers: 0, total: 0, droppedByCap: 0, collisions: 0 };
+    const listeners = new Set();
+    let refreshChain = Promise.resolve(lastReport);
+    const runRefresh = async () => {
+        const merged = new Map(); // name → skill（first-wins）
+        const diagnostics = [];
+        let collisions = 0;
+        // pass 域去重集：本轮 refresh 新铸（层间同文件 realpath 去重锚）——
+        // 不跨 refresh 持久（曾因持久共享集致二次 refresh 起整册静默清空）
+        const passSeen = new Set();
+        for (const provider of providers) {
+            let scan;
+            try {
+                scan = await provider.scan(passSeen);
+            }
+            catch (error) {
+                // 单 provider 扫描炸不拖垮其余层（坏层诊断降级——其余层技能照常服务）
+                diagnostics.push({
+                    type: 'warning',
+                    message: `provider ${provider.id} 扫描失败：${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            for (const diagnostic of scan.diagnostics)
+                diagnostics.push(diagnostic);
+            for (const skill of scan.skills) {
+                const existing = merged.get(skill.name);
+                if (existing !== undefined) {
+                    collisions += 1;
+                    diagnostics.push({
+                        type: 'collision',
+                        message: `技能同名冲突：${skill.name}（${existing.providerId} 层 ${existing.filePath} 压过 ${skill.providerId} 层 ${skill.filePath}）`,
+                        path: skill.filePath,
+                    });
+                    continue; // first-wins：扫描序（即 provider 注册序）在先者胜
+                }
+                merged.set(skill.name, skill);
+            }
+        }
+        // 快照帽：按优先序裁尾（最低优先层先出局）+ capacity 诊断（作者侧反馈）
+        let droppedByCap = 0;
+        if (merged.size > cap) {
+            droppedByCap = merged.size - cap;
+            const kept = [...merged.entries()].slice(0, cap);
+            diagnostics.push({
+                type: 'capacity',
+                message: `技能快照超帽 ${cap}——按优先序裁尾 ${droppedByCap} 件（低优先层先出局；同名覆盖或精简低优先层）`,
+            });
+            snapshot = kept.map(([, skill]) => skill);
+        }
+        else {
+            snapshot = [...merged.values()];
+        }
+        lastDiagnostics = diagnostics;
+        lastReport = {
+            providers: providers.length,
+            total: snapshot.length,
+            droppedByCap,
+            collisions,
+        };
+        for (const listener of listeners)
+            listener(lastReport);
+        return lastReport;
+    };
+    return {
+        registerProvider(provider) {
+            if (providerById.has(provider.id)) {
+                throw new BaseError('SKILLS_PROVIDER_CONFLICT', `[SKILLS_PROVIDER_CONFLICT] 技能 provider 撞名：${provider.id} 已注册——provider id 即层身份（skills_change 载荷成员），装配序须唯一`);
+            }
+            providerById.set(provider.id, provider);
+            providers.push(provider); // 注册序即优先序——后注册者优先级低
+        },
+        unregisterProvider(id) {
+            const provider = providerById.get(id);
+            if (provider === undefined)
+                return false;
+            providerById.delete(id);
+            providers.splice(providers.indexOf(provider), 1);
+            return true;
+        },
+        providerIds() {
+            return providers.map((p) => p.id);
+        },
+        getProvider(id) {
+            return providerById.get(id);
+        },
+        scanRoots() {
+            const roots = [];
+            for (const provider of providers)
+                roots.push(...provider.roots);
+            return roots;
+        },
+        refresh() {
+            // 串行承诺链：并发 refresh 按到达序逐笔重扫，末笔即最新快照
+            refreshChain = refreshChain.then(runRefresh, runRefresh);
+            return refreshChain;
+        },
+        get(name) {
+            return snapshot.find((skill) => skill.name === name);
+        },
+        list() {
+            return snapshot;
+        },
+        diagnostics() {
+            return lastDiagnostics;
+        },
+        onChange(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/skills/render.js

@@ -0,0 +1,124 @@
+/**
+ * 渐进披露渲染层（06 §11.3 护栏③ + §11.5 激活包装）。
+ *
+ * 清单块（护栏③）：name+description+location「一技能一块」；字节帽 64KiB
+ * 整件裁尾（半件截断会让模型读到残缺描述做错误选择——整件进出）；达限截断
+ * 必须带块内注释就地披露（一切截断必须带作者侧反馈——禁静默）。
+ *
+ * 激活包装（§11.5(b)）：/skill:name 显式激活把全文包装为具名块注入（不走
+ * FS）；包装形镜像 pi（name/location 属性 + 引用相对路径解析锚句 + 正文 +
+ * 可选 args 尾段）；parseSkillInvocation 是包装的镜像解析（TUI 命令面展开
+ * 与会话回放侧共用——具名块是往返可逆的）。
+ */
+import { SKILL_MANIFEST_BYTE_CAP } from './types.js';
+/** XML 转义（属性与文本共用——& 先行防双转义） */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/** 描述折行归一（清单行单行化——换行/制表/连续空格折成一空格） */
+function normalizeDescription(description) {
+    return description.replace(/\s+/g, ' ').trim();
+}
+/**
+ * 渲染渐进披露清单块（一技能一块：name/description/location）。
+ *
+ * - disable-model-invocation 件滤除（模型自动路径不见——显式激活面仍可达）；
+ * - 字节帽整件裁尾：逐件累加，装得下一件才列一件；装不下即停 + 块内注释
+ *   披露未列件数（模型与作者两侧都看得见被裁的事实）；
+ * - 描述折行归一空格（frontmatter 折行书写不破清单行结构）。
+ */
+export function renderAvailableSkills(skills, options = {}) {
+    const byteCap = options.byteCap ?? SKILL_MANIFEST_BYTE_CAP;
+    const visible = skills.filter((skill) => !skill.disableModelInvocation);
+    if (visible.length === 0) {
+        return { text: '', omitted: 0, truncated: false };
+    }
+    const header = [
+        '以下技能为特定任务提供专门指令。',
+        '当任务与某技能的描述匹配时，用 load_skill 工具按名装载该技能全文或节（section 节寻址），或用 read 工具按 location 直读全文。',
+        '技能正文引用相对路径时，以技能目录（SKILL.md 父目录）为根解析为绝对路径后再使用。',
+        '',
+        '<available_skills>',
+    ];
+    const footer = '</available_skills>';
+    const headerBytes = Buffer.byteLength(header.join('\n') + '\n', 'utf8');
+    const blocks = visible.map((skill) => [
+        '  <skill>',
+        `    <name>${escapeXml(skill.name)}</name>`,
+        `    <description>${escapeXml(normalizeDescription(skill.description))}</description>`,
+        `    <location>${escapeXml(skill.filePath)}</location>`,
+        '  </skill>',
+    ].join('\n'));
+    // 整件累加：固定头脚 + 已列块装得下下一件才列（半件不截）
+    let used = headerBytes + Buffer.byteLength(footer, 'utf8');
+    let listed = 0;
+    for (const block of blocks) {
+        const cost = Buffer.byteLength(block, 'utf8') + 1; // +1 = 块间换行
+        if (used + cost > byteCap)
+            break;
+        used += cost;
+        listed += 1;
+    }
+    const omitted = visible.length - listed;
+    if (listed === 0) {
+        // 头脚即超帽的极端形态：空清单 + 披露注释仍是完整反馈面
+        const disclosure = `<!-- 清单超 ${byteCap} 字节帽——${visible.length} 件全部未列（精简低优先层或拆分技能） -->`;
+        const text = [...header, disclosure, footer].join('\n');
+        return { text, omitted, truncated: true };
+    }
+    if (omitted === 0) {
+        return { text: [...header, ...blocks.slice(0, listed), footer].join('\n'), omitted: 0, truncated: false };
+    }
+    const disclosure = `<!-- 清单超 ${byteCap} 字节帽——另有 ${omitted} 件未列（read 对应 location 或精简低优先层） -->`;
+    return {
+        text: [...header, ...blocks.slice(0, listed), disclosure, footer].join('\n'),
+        omitted,
+        truncated: true,
+    };
+}
+/**
+ * 具名技能块单源（§11.5 具名块三消费面共用：显式激活包装 / load_skill 工具
+ * 回执 / skills 键 spawn 注入——06 §11.6）。
+ *
+ * content 由调用方给定（全文 / 命中节重建 / mode 过滤形）——回执与激活包装
+ * 同形同源（formatSkillInvocation = 本件 + args 尾段）。引导句钉相对路径
+ * 解析锚（baseDir）——模型 follow-up 引用 references/ 等相对路径时的解析
+ * 约定（06 §11.3 细化②薄主文件范式的配套面）。
+ */
+export function formatSkillBlock(skill, content) {
+    const head = `<skill name="${escapeXml(skill.name)}" location="${escapeXml(skill.filePath)}">`;
+    const body = `引用相对路径以 ${skill.baseDir} 为根解析。\n\n${content}`;
+    return `${head}\n${body}\n</skill>`;
+}
+/**
+ * 显式激活包装（§11.5(b)）：全文包装为具名 user message 注入（不走 FS）。
+ */
+export function formatSkillInvocation(skill, args) {
+    const block = formatSkillBlock(skill, skill.content);
+    const tail = args !== undefined && args.trim() !== '' ? `\n\n${args}` : '';
+    return `${block}${tail}`;
+}
+/**
+ * 激活块镜像解析（formatSkillInvocation 的逆；形镜像 pi parseSkillBlock）。
+ * 非激活块文本返回 null（判据形不匹配即非——不猜）。
+ */
+export function parseSkillInvocation(text) {
+    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (match === null)
+        return null;
+    const anchor = '引用相对路径以 ';
+    const content = match[3] ?? '';
+    if (!content.startsWith(anchor))
+        return null; // 包装头句是契约的一部分
+    return {
+        name: match[1] ?? '',
+        location: match[2] ?? '',
+        content,
+        ...(match[4] !== undefined && match[4].trim() !== '' ? { args: match[4] } : {}),
+    };
+}

package/dist/skills/sections.js

@@ -0,0 +1,171 @@
+/**
+ * 渐进披露第三层细化三件（06 §11.3——2026-09-06 技术调研消化批增补）：
+ *
+ * ① 节级寻址——SKILL.md 按标题建节骨架（split_sections 形），深读可按祖先路径
+ *    寻址节（'Mode 3 > Workflow' 式——只读命中节不读全文）；歧义多匹配报错
+ *    不猜（猜错节的注入比不注入更坏——错误指导比无指导危害大）；
+ * ② 薄主文件——作者侧范式（主文件只留触发+路由、深度进 references/），机制面
+ *    仅此件：引用路径按 baseDir 解析的约定（read 路径消费，无新通道）；
+ * ③ 行级过滤——命中注入前按运行参数行级过滤（ponytail filterSkillBodyForMode
+ *    形：强度表行按模式名匹配、带引号防普通规则行误杀——一份本体服务多档）。
+ *
+ * 三层的成本纪律同 06 §11.3 总则：节骨架与路由行是常驻清单成本、深读仍按需
+ * ——渐进披露 O(1) 不破（细化的是第三层「read 全文」的粒度，不动清单层）。
+ */
+/** ATX 标题行（CommonMark 形：≤3 前导空格 + 1-6 个 # + 空白 + 文本；尾 # 串修剪） */
+const HEADING_RE = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+/** 围栏代码块开栏行（``` 或 ~~~ ≥3 个；缩进 ≤3；fence 标记后的 info 串不参与判定） */
+const FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})/;
+/** 闭栏行（CommonMark：闭栏只许 fence 字符 + 空白——```js 带 info 串不闭栏） */
+const FENCE_CLOSE_RE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+/**
+ * 按标题切节（split_sections 形）。
+ *
+ * 围栏代码块内的 `#` 行不是标题（fence 追踪——同字符开关，``` 开 ``` 关）；
+ * 节正文到下一「同级或更高级」标题前收口；首个标题之前的引导文本不产节
+ * （无标题路径可寻址——引导文本随全文 read 路径在场，不丢内容）。
+ * 同父同名兄弟标题会产出重复 path——寻址歧义由 findSkillSection 报不猜。
+ */
+export function splitSkillSections(body) {
+    const lines = body.split('\n');
+    // 尾随换行的空串尾巴是切分伪影（'a\n'.split → ['a','']）——剥掉防末节 endLine 虚增
+    if (lines.length > 0 && (lines[lines.length - 1] ?? '') === '')
+        lines.pop();
+    const sections = [];
+    // 祖先栈：[{level, title}]——遇到 ≤ 栈顶级别的标题先弹栈再入栈
+    const stack = [];
+    let openFence = null; // 在栏 fence 字符（'```' / '~~~'）
+    let current = null;
+    let startBodyIndex = -1; // 当前节正文首行（含）
+    const closeSection = (endLineExclusive) => {
+        if (current === null)
+            return;
+        // endLineExclusive 是 0 起半开区间右端——换 1 起含端恰为「末行行号」；
+        // 空节（标题紧邻下一标题/文末）时退化为 startLine（标题行自身）
+        const endLine = Math.max(endLineExclusive, current.startLine);
+        sections.push({
+            path: current.path,
+            level: current.level,
+            title: current.title,
+            body: lines.slice(startBodyIndex, endLineExclusive).join('\n'),
+            startLine: current.startLine,
+            endLine,
+        });
+        current = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (openFence !== null) {
+            const closeMatch = FENCE_CLOSE_RE.exec(line);
+            // 闭栏须同字符（``` 开 ``` 关——``` 块内的 ~~~ 行是内容不是栏）
+            if (closeMatch !== null && (closeMatch[1] ?? '').startsWith(openFence)) {
+                openFence = null;
+            }
+            continue; // 栏内行不参与标题切分（正文由行区间还原）
+        }
+        const fenceMatch = FENCE_OPEN_RE.exec(line);
+        if (fenceMatch !== null) {
+            openFence = (fenceMatch[1] ?? '').slice(0, 3); // 同字符判定取前三位（``` 与 ```` 互闭）
+            continue;
+        }
+        const headingMatch = HEADING_RE.exec(line);
+        if (headingMatch === null)
+            continue;
+        const level = (headingMatch[1] ?? '').length;
+        const title = headingMatch[2] ?? '';
+        closeSection(i); // 上一节在标题行前收口
+        while (stack.length > 0 && (stack[stack.length - 1]?.level ?? 0) >= level)
+            stack.pop();
+        stack.push({ level, title });
+        current = {
+            path: stack.map((s) => s.title).join(' > '),
+            level,
+            title,
+            startLine: i + 1, // 1 起行号
+        };
+        startBodyIndex = i + 1; // 正文自标题行之后（0 起）
+    }
+    closeSection(lines.length);
+    return sections;
+}
+/**
+ * 按祖先路径寻址节（'Mode 3 > Workflow' 式）。
+ *
+ * 歧义多匹配报错不猜（06 §11.3 细化①——错误指导比无指导危害大）；未命中时
+ * candidates = 全部可寻址 path（人面呈现「可用节」——指路而非裸拒）。
+ */
+export function findSkillSection(body, path) {
+    const sections = splitSkillSections(body);
+    const hits = sections.filter((s) => s.path === path);
+    if (hits.length === 1) {
+        const section = hits[0];
+        if (section !== undefined)
+            return { ok: true, section };
+    }
+    if (hits.length > 1) {
+        return { ok: false, reason: 'ambiguous', candidates: hits.map((s) => `${s.path}（L${s.startLine}）`) };
+    }
+    return { ok: false, reason: 'not-found', candidates: sections.map((s) => s.path) };
+}
+/** 强度表行模式标签（`| **label** | …`——行级过滤与模式词表推导共用判据） */
+const MODE_TABLE_LABEL_RE = /^\|\s*\*\*(.+?)\*\*\s*\|/;
+/** 带引号工作示例行模式标签（`- label: "…"`——引号是判据的一部分） */
+const MODE_EXAMPLE_LABEL_RE = /^-\s*([^:]+):\s*"/;
+/**
+ * 行级过滤（ponytail filterSkillBodyForMode 形泛化——06 §11.3 细化③）。
+ *
+ * 只有两种行是模式专属、参与裁剪，其余行一律原样保留（普通规则行绝不误杀）：
+ *  - 强度表行：`| **label** | …`——label 命中模式词汇时，仅当前模式行保留；
+ *  - 带引号的工作示例行：`- label: "…"`——引号是判据的一部分（`- Full: …`
+ *    无引号形是普通规则行，略读误杀即静默改行为——ponytail 实测教训）。
+ * 输入须为正文（frontmatter 已剥——装载态 content 即此形）。
+ */
+export function filterSkillBody(body, options) {
+    const normalize = (label) => label.trim().toLowerCase();
+    const modeSet = new Set(options.modes.map(normalize));
+    const active = normalize(options.active);
+    return body
+        .split('\n')
+        .filter((line) => {
+        const tableMatch = MODE_TABLE_LABEL_RE.exec(line);
+        if (tableMatch !== null) {
+            const label = normalize(tableMatch[1] ?? '');
+            if (modeSet.has(label))
+                return label === active;
+        }
+        const exampleMatch = MODE_EXAMPLE_LABEL_RE.exec(line);
+        if (exampleMatch !== null) {
+            const label = normalize(exampleMatch[1] ?? '');
+            if (modeSet.has(label))
+                return label === active;
+        }
+        return true;
+    })
+        .join('\n');
+}
+/**
+ * 模式词表双形交集推导（06 §11.5 load_skill mode 判据）。
+ *
+ * 词表 = 强度表行标签 ∩ 带引号示例行标签（双形同现才认模式名——单形如
+ * `| **Version** |` 只是普通表行，入词表会把非模式正文误裁）；推导域 =
+ * 待过滤正文自身（作者在正文里写了什么模式，模型就只能选什么——无第三真源）。
+ * trim+小写归一与 filterSkillBody 比对同源。
+ */
+export function deriveModeVocabulary(body) {
+    const normalize = (label) => label.trim().toLowerCase();
+    const table = new Set();
+    const example = new Set();
+    for (const line of body.split('\n')) {
+        const tableMatch = MODE_TABLE_LABEL_RE.exec(line);
+        if (tableMatch !== null) {
+            table.add(normalize(tableMatch[1] ?? ''));
+            continue;
+        }
+        const exampleMatch = MODE_EXAMPLE_LABEL_RE.exec(line);
+        if (exampleMatch !== null) {
+            example.add(normalize(exampleMatch[1] ?? ''));
+        }
+    }
+    // 交集（table 迭代序 = 正文出现序——词表呈现稳定）
+    return [...table].filter((label) => example.has(label));
+}

package/dist/skills/types.js

@@ -0,0 +1,21 @@
+/**
+ * skills 域类型与常量（06 篇 §11 全线——双层结构/渐进披露三层护栏/发现六位序列）。
+ *
+ * 词汇面（02 §4.1 席 13）：definition/provider 词汇族——Skill 是纯数据契约，
+ * SkillsProvider 是发现层实现方；注册表按 provider 注册序（即优先序）合并。
+ */
+/** 技能名长度帽（agentskills.io 标准；06 §11.2） */
+export const SKILL_NAME_MAX = 64;
+/** 描述长度帽——装载层超限截断装载（全文仍可经 read 路径读原文件；06 §11.3 护栏①） */
+export const SKILL_DESCRIPTION_MAX = 1024;
+/** 注册表快照数帽——超帽裁尾 + capacity 诊断列被裁计数（06 §11.3 护栏②） */
+export const SKILL_SNAPSHOT_CAP = 100;
+/** 渐进披露清单块字节帽——达限截断 + 块内注释就地披露（06 §11.3 护栏③） */
+export const SKILL_MANIFEST_BYTE_CAP = 64 * 1024;
+/** provenance.memories 上限（06 §9.1 第 2 项——source_refs 50 同族） */
+export const SKILL_PROVENANCE_MEMORIES_MAX = 50;
+/**
+ * 单条 skills 引用清单帽（agents frontmatter `skills` 键 / SubagentRequest.skills
+ * 两面同判——06 §11.6 第五键；spawn 永久注入位防正文膨胀的形状护栏之一）
+ */
+export const SKILL_REFS_MAX = 8;

package/dist/subagent/codes.js

@@ -0,0 +1,50 @@
+/**
+ * subagent 域错误码注册（04 §10——SUBAGENT_/JOB_ 前缀族；02 §5.3 批 15c
+ * 明列五码，SUBAGENT_DEPTH_EXCEEDED/JOB_KIND_UNKNOWN 承 04 §10 定名）。
+ *
+ * 码语义分层：SUBAGENT_DEPTH_EXCEEDED 管委派深度帽（防自嵌套爆栈）；
+ * SUBAGENT_PRECHECK_FAILED 管 spawn 前预检闸（fail-ask 不降级瞎跑）；
+ * SUBAGENT_PROVIDER_UNKNOWN 管静态绑定路由；JOB_KIND_UNKNOWN 管 kind
+ * 词汇登记（词汇注册表纪律）；JOB_LIMIT_REACHED 管 Job 并行帽（形随
+ * issue 件落码批定值）；SUBAGENT_NAME_INVALID 管程序化注册槽 name 裸词
+ * 词法（D 批——03 §2.7 行 262「本批新码」）。本文件由模块公开面 index.ts
+ * 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'SUBAGENT_DEPTH_EXCEEDED',
+        module: 'subagent',
+        description: '委派深度超帽 3 拒——防自嵌套爆栈（04 §10 委派边界③）',
+    },
+    {
+        code: 'SUBAGENT_PRECHECK_FAILED',
+        module: 'subagent',
+        description: 'spawn 前能力/权限预检闸拒——委派 def 前置要求（requiresTools）工具缺席即拒起跑并回执缺口清单，fail-ask 不降级瞎跑（04 §10 静默退化防御②；与 tools 白名单正交——白名单缺了照样跑、前置要求缺了不起跑）',
+    },
+    {
+        code: 'SUBAGENT_PROVIDER_UNKNOWN',
+        module: 'subagent',
+        description: '委派路由命中未注册 provider 拒——委派面静态绑定（通用 agent 工具缺省路由 in-process）',
+    },
+    {
+        code: 'SUBAGENT_PROVIDER_EXISTS',
+        module: 'subagent',
+        description: 'named provider 撞名拒——服务面注册（声明式子代理每文件一 named provider，扫描序 first-wins 由发现层表达、注册面撞名响亮拒）',
+    },
+    {
+        code: 'JOB_KIND_UNKNOWN',
+        module: 'subagent',
+        description: 'registerKind 未登记种类拒——防随手字符串当 kind 用（词汇注册表纪律同 04 §6）',
+    },
+    {
+        code: 'JOB_LIMIT_REACHED',
+        module: 'subagent',
+        description: 'Job 并行帽拒——同刻在飞 Job 数达按 kind 分帽上限（缺省无帽；缺省值随 issue 件落码批定——04 §10 issue 立题批钉位）',
+    },
+    {
+        code: 'SUBAGENT_NAME_INVALID',
+        module: 'subagent',
+        description: '程序化注册槽 name 词法违例拒——非裸词（06 §11.6 声明式 name 同形、词法承 §11.2「小写连字符与数字」——词法真源 06:386）；执法序同 AGENT_ROLE 注记：撞名闸前置格式闸（03 §2.7 行 262；2026-09-07 冷读闸 blocker 修复批拍板案 a 改形——原「非域名两段式」弃）',
+    },
+]);

package/dist/subagent/declarative.js

@@ -0,0 +1,55 @@
+import { BaseError } from '../contracts/index.js';
+import { createDeclarativeAgentTool } from './tool.js';
+import { DEFAULT_SUBAGENT_PROVIDER, IN_PROCESS_CAPABILITIES } from './types.js';
+/**
+ * def → named provider（late-binding def-defaults 包装）：路由到本 def 的
+ * 委派请求缺省字段由此合流（模型侧经静态工具携带、程序侧直呼 service.run
+ * 两条道同折）；真身始终 'in-process' 基 provider——独立装配全套的
+ * 黑盒契约不因声明式形态而二轨。def 形两腿共享（声明式 SubagentDef /
+ * 程序化 ProgrammaticSubagentDef——filePath 位非本桥消费，Omit 宽形；
+ * D 批 D-2 程序化腿复用同桥）。
+ */
+export function defBoundProvider(def, service) {
+    return {
+        capabilities: IN_PROCESS_CAPABILITIES,
+        async run(request) {
+            const base = service.getProvider(DEFAULT_SUBAGENT_PROVIDER);
+            if (base === undefined) {
+                throw new BaseError('SUBAGENT_PROVIDER_UNKNOWN', `声明式子代理「${def.name}」的基工厂 'in-process' 未注册——host 装配批接线位（06 §11.6 桥条款）`);
+            }
+            // def 缺省合流（请求已有值胜出——静态工具道 service 已合流过一次，
+            // 幂等；程序直呼 provider 道由此兜底）
+            const merged = {
+                ...request,
+                ...(request.model === undefined && def.model !== undefined ? { model: def.model } : {}),
+                ...(request.systemPrompt === undefined ? { systemPrompt: def.systemPrompt } : {}),
+                ...(request.tools === undefined && def.tools !== undefined ? { tools: [...def.tools] } : {}),
+                ...(request.skills === undefined && def.skills !== undefined ? { skills: [...def.skills] } : {}),
+                name: request.name ?? def.name,
+            };
+            return base.run(merged);
+        },
+    };
+}
+/**
+ * 批量物化声明式子代理：每 def 一 named provider + 一静态工具。
+ * 撞名（named provider 或既有工具名）响亮拒——坏 def 已在解析层跳过，
+ * 这里的拒是装配态冲突（fail-loud；调用方可折 warn 降级——发现层
+ * first-wins 已表达同层同名，跨层冲突走注册面）。
+ */
+export function materializeDeclarativeSubagents(defs, service, deps, opts) {
+    const names = [];
+    const tools = [];
+    const disposeProviders = [];
+    for (const def of defs) {
+        disposeProviders.push(service.registerProvider(def.name, defBoundProvider(def, service), { owner: opts?.owner }));
+        names.push(def.name);
+        tools.push(createDeclarativeAgentTool(def, { ...deps, service }));
+    }
+    // 撤位逆注册序（镜像 tools 撤位律）；索引逆扫免 reverse 变异（重入安全）
+    const dispose = () => {
+        for (let i = disposeProviders.length - 1; i >= 0; i--)
+            disposeProviders[i]?.();
+    };
+    return { names, tools, dispose };
+}

package/dist/subagent/index.js

@@ -0,0 +1,19 @@
+/**
+ * subagent 件公开面（04 §10——ctx.jobs 注册表 + SubagentProvider 委派机器）。
+ *
+ * 消费方：host 装配根（in-process 真工厂接线 + provideJobsService）、
+ * exec/issue 同表消费件（registerKind 'process'/'issue'）、组合根（通知面
+ * 与结算钩子桥接）。in-process 真工厂本体归 host 装配批——本件提供机器
+ * 与 late-binding 接缝（15a/15b 先例：装载态挂账、批内机器先行）。
+ * 程序化注册面（registerProgrammatic——03 §2.2 第十二动词受局面，D 批
+ * D-2）：注册表机器与执法序在本件，ctx 动词包装在 host/plugin-context。
+ */
+import './codes.js';
+export { isTerminalStatus, JOB_RETENTION_CAP, createJobRegistry } from './registry.js';
+export { AGENT_TOOL_NAME, DEFAULT_SUBAGENT_PROVIDER, EXCLUDED_FROM_DERIVED_SURFACE, IN_PROCESS_CAPABILITIES, } from './types.js';
+export { deriveToolSurface, findPrecheckGaps, intersectToolWhitelist } from './surface.js';
+export { subagentSettledContent } from './notify.js';
+export { createSubagentService, DEFAULT_SUBAGENT_FANOUT_LIMIT, ENV_MAX_CONCURRENT_SUBAGENTS, resolveSubagentFanoutLimit, } from './service.js';
+export { createAgentTool, createDeclarativeAgentTool } from './tool.js';
+export { defBoundProvider, materializeDeclarativeSubagents } from './declarative.js';
+export { JOBS_SERVICE_NAME, provideJobsService } from './provide.js';

package/dist/subagent/notify.js

@@ -0,0 +1,51 @@
+/** 通知内输出预览帽（人读通知不刷屏——全文在子会话日志可回看） */
+const OUTPUT_PREVIEW_MAX = 512;
+/** 输出预览截断（保头——通知是索引非全文载体） */
+function preview(text) {
+    if (text.length <= OUTPUT_PREVIEW_MAX)
+        return text;
+    return `${text.slice(0, OUTPUT_PREVIEW_MAX)}…（已截断——全文见子会话日志）`;
+}
+/** 终态人读词（stopReason → 通知文案行） */
+function stopWord(stopReason) {
+    if (stopReason === 'stop')
+        return '已完成';
+    if (stopReason === 'aborted')
+        return '已中止';
+    return '失败';
+}
+/**
+ * 结算通知的子会话指针行（RP3——收果拉取面轻量案：通知携指针非全文）。
+ * 取数自宿主机器账（in-process 工厂铸造位 structured）——第三方 provider
+ * 自有形无此字段则指针行诚实缺席（防御 guard：只认 in-process v1 形的
+ * string childSessionId + number messageCount，缺任一即视无指针）。
+ */
+function childSessionPointerLine(result) {
+    const account = result.structured;
+    if (account === null || typeof account !== 'object')
+        return undefined;
+    const { childSessionId, messageCount } = account;
+    if (typeof childSessionId !== 'string' || childSessionId === '')
+        return undefined;
+    if (typeof messageCount !== 'number' || !Number.isInteger(messageCount) || messageCount < 0) {
+        return undefined;
+    }
+    return `子会话 ${childSessionId}（${messageCount} 条消息）`;
+}
+/**
+ * 结算通知 content（subagent-settled 注入体的唯一文案真源）。
+ */
+export function subagentSettledContent(input) {
+    const { jobName, result } = input;
+    const lines = [`子代理「${jobName}」${stopWord(result.stopReason)}。`];
+    const pointer = childSessionPointerLine(result);
+    if (pointer !== undefined)
+        lines.push(pointer);
+    if (result.output !== '')
+        lines.push(`输出：${preview(result.output)}`);
+    // 降级上报如实呈现（禁伪装——上报表是知情面三律之一）
+    if (result.diagnostic !== undefined && result.diagnostic !== '') {
+        lines.push(`诊断：${result.diagnostic}`);
+    }
+    return lines.join('\n');
+}

package/dist/subagent/provide.js

@@ -0,0 +1,7 @@
+/** 服务词汇名（ctx.jobs——02 §4.1 #15 行 2026-09-07 批 15c 改名收口） */
+export const JOBS_SERVICE_NAME = 'jobs';
+/** provide 注册表到 scope（host 装配根调用——先于一切消费件起跑） */
+export function provideJobsService(scope, registry) {
+    scope.provide(JOBS_SERVICE_NAME, registry);
+    return registry;
+}