berry-agent 0.1.0-alpha.1

package/dist/subagent/tool.js

@@ -0,0 +1,153 @@
+/**
+ * 委派工具族（04 §10 委派面 = 静态绑定）：通用委派工具 `agent`（缺省路由
+ * 'in-process'）+ 声明式子代理静态工具 `agent_<name>`（闭包绑定 def——
+ * 发现/信任/frontmatter 基建镜像技能，06 §11.6）。
+ *
+ * effect 面：委派工具本身 'read'（子代理的工具面自带各自 effect 与审批
+ * 路由——审批型升权走父会话审批面，不因委派而放大父侧效果面）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+import { AGENT_TOOL_NAME, AGENT_TOOL_PREFIX } from './types.js';
+/**
+ * 执行时语境解析（两装载形合流单源）：parentSessionId = 执行会话（boot 形）
+ * ?? 静态闭包位；深度/工具面 = sessionContext 产物 ?? 静态位。两源俱缺席 =
+ * 语境不可路由（诚实拒——isError 回执不伪装起跑）。
+ */
+function resolveToolContext(deps, toolCtx) {
+    const sessionId = toolCtx?.sessionId;
+    const fromSession = sessionId !== undefined ? deps.sessionContext?.(sessionId) : undefined;
+    const parentSessionId = sessionId ?? deps.parentSessionId;
+    const depth = fromSession?.depth ?? deps.depth ?? 1;
+    const availableTools = fromSession?.availableTools ?? (deps.availableTools !== undefined ? deps.availableTools() : undefined);
+    return {
+        ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+        depth,
+        ...(availableTools !== undefined ? { availableTools } : {}),
+    };
+}
+/** 委派回执渲染（one-shot 结果 / background Job 身份——模型面统一文案） */
+function renderOutcome(outcome) {
+    if (outcome.mode === 'background') {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `子代理「${outcome.jobName}」已后台起跑（Job ${outcome.jobId}）——终态时将注入结算通知。`,
+                },
+            ],
+        };
+    }
+    const { result } = outcome;
+    const isError = result.stopReason !== 'stop';
+    const lines = [result.output];
+    if (result.diagnostic !== undefined && result.diagnostic !== '')
+        lines.push(`诊断：${result.diagnostic}`);
+    return {
+        content: [{ type: 'text', text: lines.filter((line) => line !== '').join('\n') || '（空输出）' }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/**
+ * 通用委派工具 `agent`：schema 只暴露 prompt/background（provider 路由、
+ * 白名单、深度均机器位——模型不可见动态选择器）。
+ */
+export function createAgentTool(deps) {
+    return {
+        name: AGENT_TOOL_NAME,
+        description: '委派一个子代理执行任务（黑盒——只见结果不见过程；缺省同步等待，background=true 后台起跑终态注入结算通知）',
+        effect: 'read',
+        parameters: Type.Object({
+            prompt: Type.String({ description: '委派目标提示（子代理的唯一任务输入）' }),
+            background: Type.Optional(Type.Boolean({ description: '后台收场（缺省 false = 父同步等结果）' })),
+            name: Type.Optional(Type.String({ description: '诊断名（Job 名与通知文案显示位）' })),
+        }),
+        async execute(args, toolCtx) {
+            // 执行时语境解析（两装载形合流——boot 形 toolCtx.sessionId 胜出）
+            const ctx = resolveToolContext(deps, toolCtx);
+            if (ctx.parentSessionId === undefined) {
+                return {
+                    content: [
+                        { type: 'text', text: 'SUBAGENT_CONTEXT_MISSING：委派语境不可路由（无父会话 id——工具须经会话驱动执行）' },
+                    ],
+                    isError: true,
+                };
+            }
+            try {
+                const outcome = await deps.service.run({
+                    prompt: String(args.prompt ?? ''),
+                    ...(args.background === true ? { background: true } : {}),
+                    ...(typeof args.name === 'string' && args.name !== '' ? { name: args.name } : {}),
+                    parentSessionId: ctx.parentSessionId,
+                    depth: ctx.depth,
+                    ...(ctx.availableTools !== undefined ? { availableTools: ctx.availableTools } : {}),
+                });
+                return renderOutcome(outcome);
+            }
+            catch (err) {
+                // 机器面拒（深度帽/预检闸/路由）→ isError 数据面回执（码 + 人读）
+                if (err instanceof BaseError) {
+                    return { content: [{ type: 'text', text: `${err.code}：${err.message}` }], isError: true };
+                }
+                throw err;
+            }
+        },
+    };
+}
+/**
+ * 声明式子代理静态工具 `agent_<name>`（闭包绑定 def——工具面 = 装配期
+ * 物化，06 §11.6 模型面静态多工具律）。description = 文件 description
+ * （披露段清单行 = 模型选择依据）；def 字段（tools/requires/model/
+ * systemPrompt）全部闭包绑定——模型只出 prompt。def 形 = 声明式与程序化
+ * 两腿共享（filePath 位非工具构造消费——Omit 宽形两腿同构，D 批 D-2）。
+ */
+export function createDeclarativeAgentTool(def, deps) {
+    return {
+        name: `${AGENT_TOOL_PREFIX}${def.name}`,
+        description: def.description,
+        effect: 'read',
+        parameters: Type.Object({
+            prompt: Type.String({ description: '委派目标提示' }),
+            background: Type.Optional(Type.Boolean({ description: '后台收场（缺省 false = 父同步等结果）' })),
+        }),
+        async execute(args, toolCtx) {
+            // 执行时语境解析（两装载形合流——boot 形 toolCtx.sessionId 胜出）
+            const ctx = resolveToolContext(deps, toolCtx);
+            if (ctx.parentSessionId === undefined) {
+                return {
+                    content: [
+                        { type: 'text', text: 'SUBAGENT_CONTEXT_MISSING：委派语境不可路由（无父会话 id——工具须经会话驱动执行）' },
+                    ],
+                    isError: true,
+                };
+            }
+            try {
+                const outcome = await deps.service.run({
+                    providerName: def.name,
+                    prompt: String(args.prompt ?? ''),
+                    ...(args.background === true ? { background: true } : {}),
+                    ...(def.tools !== undefined ? { tools: def.tools } : {}),
+                    ...(def.requires !== undefined ? { requiresTools: def.requires } : {}),
+                    ...(def.model !== undefined ? { model: def.model } : {}),
+                    systemPrompt: def.systemPrompt,
+                    name: def.name,
+                    parentSessionId: ctx.parentSessionId,
+                    depth: ctx.depth,
+                    ...(ctx.availableTools !== undefined ? { availableTools: ctx.availableTools } : {}),
+                });
+                return renderOutcome(outcome);
+            }
+            catch (err) {
+                if (err instanceof BaseError) {
+                    return { content: [{ type: 'text', text: `${err.code}：${err.message}` }], isError: true };
+                }
+                throw err;
+            }
+        },
+    };
+}
+// 程序化注册位的消费腿已改动词层即时物化（遗漏审计批 G——03 §2.2 行 109
+// 「注册即派生」）：ctx.agent.registerSubagentProvider 内 service 位落册后
+// 经装配链注入的物化回调单条派生（createDeclarativeAgentTool 单源）入 boot
+// 全局层；原批量快照物化函数（createProgrammaticTools）随之退役删除——
+// programmaticProviders() 读面保留作注册册标准读面。

package/dist/subagent/types.js

@@ -0,0 +1,25 @@
+/** 通用委派工具名（04 §10 委派面静态绑定——缺省路由 'in-process'） */
+export const AGENT_TOOL_NAME = 'agent';
+/**
+ * named provider 派生工具名前缀（**保留字段**——03 §2.7 行 254）：`agent_<name>`
+ * 段专属 named provider 派生工具，插件经 ctx.tools.register 携此前缀即拒
+ * TOOL_NAME_CONFLICT（保留字在注册面执法——先占位即反锁后续 named provider
+ * 注册；执法位在 host ctx.tools.register 包装道，机器侧放行 host 物化腿）。
+ */
+export const AGENT_TOOL_PREFIX = 'agent_';
+/** 缺省委派路由（通用 agent 工具的 providerName 缺省值） */
+export const DEFAULT_SUBAGENT_PROVIDER = 'in-process';
+/**
+ * 派生工具面结构性排除五名（04 §10）：fs read/write/edit/ls + bash。
+ * - fs 四名：子自建 fs 族（驱动层注册——结构性不入派生集）；
+ * - bash：永不升格总则下的特例条款（子管道无人在场应答 def 内部升权）。
+ */
+export const EXCLUDED_FROM_DERIVED_SURFACE = ['read', 'write', 'edit', 'ls', 'bash'];
+/** in-process 子代理的能力面（真工厂独立装配全套——五布尔恒真） */
+export const IN_PROCESS_CAPABILITIES = {
+    tools: true,
+    streaming: true,
+    cancel: true,
+    background: true,
+    structuredOutput: true,
+};

package/dist/tools/apply-patch.js

@@ -0,0 +1,164 @@
+/**
+ * L2 tools — apply_patch 补丁格式（codex 原创；04 §7 fs 族 edit 段拍板采纳
+ * 为本仓 edit 工具格式，in-process 应用——码面按协议新写）。
+ *
+ * 支持的最小子集（M1）：
+ *
+ *   *** Begin Patch
+ *   *** Update File: path/to/file
+ *   context 行（定位锚，原样保留进新内容）
+ *   -被删除的行
+ *   +替换后的新行
+ *   *** Add File: new.txt
+ *   +整文件内容逐行
+ *   *** Delete File: old.txt
+ *   *** End Patch
+ *
+ * 语义声明（照实文档化，非缺陷）：跨文件顺序应用、**非原子**、无回滚——中
+ * 途失败停在失败处（已应用文件保留）。fs 工具族在应用前**全部文件先过
+ * CAS + fence 校验、全部补丁先解析算内容**，把「半途而废」窗口压到最小
+ * （两阶段：校验段全过 → 顺序应用段——04 §7 edit 细则）。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 补丁解析/应用失败统一形态（message 细说行号与原因） */
+function patchError(message) {
+    return new BaseError('FS_PATCH_FAILED', `[FS_PATCH_FAILED] ${message}`);
+}
+/**
+ * 解析 apply_patch 文本 → 操作列表。
+ * 行首标记：`*** ` 段指令；`+` 新增；`-` 删除；空格前缀（或裸空行，宽容收）
+ * = 上下文行。首尾必须恰是 Begin/End Patch；空补丁（零文件操作段）拒绝。
+ */
+export function parseApplyPatch(text) {
+    const lines = text.split('\n');
+    // split 的尾部换行产物（空串尾巴）先剥——其余空行是合法的空上下文行
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    const first = lines[0];
+    if (first === undefined || first.trim() !== '*** Begin Patch') {
+        throw patchError(`补丁必须以 "*** Begin Patch" 开头（实际首行：${JSON.stringify(first ?? '')}）`);
+    }
+    const last = lines[lines.length - 1];
+    if (last === undefined || last.trim() !== '*** End Patch') {
+        throw patchError(`补丁必须以 "*** End Patch" 结尾（实际末行：${JSON.stringify(last ?? '')}）`);
+    }
+    const ops = [];
+    /** 当前段累积器（Update/Add 的行流；Delete 无行流） */
+    let current;
+    /** 至少出现过一个文件操作段（空补丁拒绝） */
+    let sawOperation = false;
+    /** 收束当前段入列（空行流校验在收束点——段完整性最末判定） */
+    const finishCurrent = () => {
+        if (current === undefined)
+            return;
+        if (current.kind === 'add' && current.lines.length === 0) {
+            throw patchError(`*** Add File: ${current.path} 无内容行（新增文件至少一行 "+"）`);
+        }
+        if (current.kind === 'update' && current.lines.length === 0) {
+            throw patchError(`*** Update File: ${current.path} 无行（更新至少一行上下文/增删）`);
+        }
+        ops.push(current);
+        current = undefined;
+    };
+    // 首尾行已校验，循环体只走中间行
+    for (let i = 1; i < lines.length - 1; i++) {
+        const raw = lines[i];
+        if (raw.startsWith('*** ')) {
+            // 段指令：收束上一段、开新段
+            finishCurrent();
+            const directive = raw.slice(4).trim();
+            if (directive.startsWith('Update File:')) {
+                current = { kind: 'update', path: directive.slice('Update File:'.length).trim(), lines: [] };
+            }
+            else if (directive.startsWith('Add File:')) {
+                current = { kind: 'add', path: directive.slice('Add File:'.length).trim(), lines: [] };
+            }
+            else if (directive.startsWith('Delete File:')) {
+                current = { kind: 'delete', path: directive.slice('Delete File:'.length).trim() };
+            }
+            else if (directive.startsWith('End Patch')) {
+                // 末行已保证 End Patch；中途出现 = 多余段指令
+                throw patchError(`第 ${i + 1} 行出现多余的 "*** End Patch"`);
+            }
+            else {
+                throw patchError(`第 ${i + 1} 行未知段指令：${JSON.stringify(directive)}（M1 仅支持 Update File / Add File / Delete File）`);
+            }
+            sawOperation = true;
+            continue;
+        }
+        if (current === undefined) {
+            throw patchError(`第 ${i + 1} 行出现在任何 *** 段指令之前：${JSON.stringify(raw)}`);
+        }
+        if (current.kind === 'delete') {
+            throw patchError(`*** Delete File: ${current.path} 之后不允许行内容（第 ${i + 1} 行）`);
+        }
+        if (raw.startsWith('+')) {
+            current.lines.push({ tag: 'added', text: raw.slice(1) });
+        }
+        else if (raw.startsWith('-')) {
+            if (current.kind === 'add') {
+                throw patchError(`*** Add File: ${current.path} 段内不允许 "-" 删除行（第 ${i + 1} 行）`);
+            }
+            current.lines.push({ tag: 'removed', text: raw.slice(1) });
+        }
+        else if (raw.startsWith(' ')) {
+            current.lines.push({ tag: 'context', text: raw.slice(1) });
+        }
+        else if (raw === '') {
+            // 裸空行按空上下文行收（codex 格式规范形是 " "，裸空行更常见——宽容）
+            current.lines.push({ tag: 'context', text: '' });
+        }
+        else {
+            throw patchError(`第 ${i + 1} 行无行首标记（应为 "+" / "-" / " " 之一）：${JSON.stringify(raw)}`);
+        }
+    }
+    finishCurrent();
+    if (!sawOperation) {
+        throw patchError('补丁不含任何文件操作段（Update File / Add File / Delete File）');
+    }
+    return ops;
+}
+/**
+ * 对单文件内容应用 Update 行流：在原行序列中滑窗找**首个**完全匹配点，替
+ * 换后返回新内容。匹配 = 行流中 context/removed 行与原文连续片段逐行全等
+ * （added 行不参与匹配）；无匹配点 = 补丁基于过时内容，FS_PATCH_FAILED 拒。
+ */
+export function applyUpdateLines(path, source, patchLines) {
+    const original = source.split('\n');
+    // 尾换行剥除记号：原文以 \n 收尾时 split 产空尾，应用后按原样补回
+    const hadTrailingNewline = source.endsWith('\n');
+    if (hadTrailingNewline)
+        original.pop();
+    /** 参与匹配的行（context+removed 按序——added 不参与定位） */
+    const matchSeq = patchLines.filter((line) => line.tag !== 'added');
+    if (matchSeq.length === 0) {
+        throw patchError(`${path}：hunk 无 context/- 行，无法定位（至少一行定位锚）`);
+    }
+    // 滑窗找首个匹配点（贪心首匹配——多个匹配取最先出现处）
+    let matchAt = -1;
+    outer: for (let start = 0; start + matchSeq.length <= original.length; start++) {
+        for (let j = 0; j < matchSeq.length; j++) {
+            if (original[start + j] !== matchSeq[j].text)
+                continue outer;
+        }
+        matchAt = start;
+        break;
+    }
+    if (matchAt < 0) {
+        throw patchError(`${path}：hunk 定位失败——补丁 context/- 行在文件中无连续匹配（期望片段首行：${JSON.stringify(matchSeq[0].text)}）。文件在读取后可能已被修改`);
+    }
+    // 重组：匹配点之前 + 行流展开（context/added 落为新内容，removed 丢弃）+ 匹配窗口之后
+    const replacement = [];
+    for (const line of patchLines) {
+        if (line.tag === 'removed')
+            continue;
+        replacement.push(line.text);
+    }
+    const merged = [...original.slice(0, matchAt), ...replacement, ...original.slice(matchAt + matchSeq.length)];
+    return merged.length === 0 ? '' : `${merged.join('\n')}${hadTrailingNewline ? '\n' : ''}`;
+}
+/** Add 行流 → 文件内容（全 added；context 行在 Add 语义下也按内容收——宽容） */
+export function addLinesToContent(lines) {
+    const texts = lines.map((line) => line.text);
+    return texts.length === 0 ? '' : `${texts.join('\n')}\n`;
+}

package/dist/tools/codes.js

@@ -0,0 +1,109 @@
+/**
+ * tools 域错误码注册（04 §7 三段管道 + 注册面 + fs 工具族——TOOL_/FS_ 前缀族首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1）；码名清
+ * 单与语义真源 = 02 篇 §5.3 TOOL_/FS_ 族明列段（2026-09-06 tools 纵切批）。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：写入点文件必须实际 import 本
+ * 文件注册才发生——与 llm/session/persist 的 codes.ts 同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    // ---- TOOL_ 族（管道与注册面）----
+    {
+        code: 'TOOL_INVALID_ARGS',
+        module: 'tools',
+        description: 'schema 段参数校验拒（04 §7 段 1）——模型拿到的可纠正错误回执',
+    },
+    {
+        code: 'TOOL_BLOCKED',
+        module: 'tools',
+        description: '守门段 block 短路（04 §7 段 2）——拒绝原因随码入结果，模型可见可自纠',
+    },
+    {
+        code: 'TOOL_GATE_FAILED',
+        module: 'tools',
+        description: '守门监听器自身抛错——fail-closed 视同 block（先落 gate/decision 再拒）',
+    },
+    {
+        code: 'TOOL_TIMEOUT',
+        module: 'tools',
+        description: '执行段单工具预算超时（def.timeoutMs 或缺省 60s）——竞速先到即拒',
+    },
+    {
+        code: 'TOOL_NAME_CONFLICT',
+        module: 'tools',
+        description: '注册撞名拒绝式（03 §2.7——碰撞域内双向对称：宿主内建/官方件/兄弟插件）',
+    },
+    {
+        code: 'TOOL_DESCRIPTION_REJECTED',
+        module: 'tools',
+        description: '描述注入模式扫描命中拒注册（03 §2.8——任何来源同一防线，官方件同受管）',
+    },
+    {
+        code: 'TOOL_REGISTRY_CAPACITY',
+        module: 'tools',
+        description: '注册表两层合计达 10^3 总量帽（03 §3.4 双帽之一）——超限拒新注册',
+    },
+    {
+        code: 'TOOL_CHANGE_RATE_LIMITED',
+        module: 'tools',
+        description: 'register/unregister 令牌桶空拒（03 §3.4 双帽之二——容量 240、回填 600/分钟）',
+    },
+    {
+        code: 'TOOL_SCHEMA_INVALID',
+        module: 'tools',
+        description: 'parameters 根节点非 object——注册即拒（provider 声明契约只认根 object）',
+    },
+    // ---- FS_ 族（fs 工具族）----
+    {
+        code: 'FS_NOT_OBSERVED',
+        module: 'tools',
+        description: '未观察径直写拒（04 §7 CAS 观察态）——先读后写是结构纪律',
+    },
+    {
+        code: 'FS_VERSION_CONFLICT',
+        module: 'tools',
+        description: '观察指纹不符/读后他方并发创建/读后删除——丢失更新守卫，重新 read 再写',
+    },
+    {
+        code: 'FS_OUTSIDE_WRITABLE_ROOTS',
+        module: 'tools',
+        description: '写目标 canonical 化后不在任何可写根内（04 §7 fence）',
+    },
+    {
+        code: 'FS_WRITE_TARGET_DRIFTED',
+        module: 'tools',
+        description: '写串行链段内写目标漂移（符号链被换/目录被移）——重验不过拒落盘',
+    },
+    {
+        code: 'FS_NOT_FOUND',
+        module: 'tools',
+        description: 'read/ls 目标不存在（read 仍登记 absent 观察——「这里没有文件」也是观察）',
+    },
+    {
+        code: 'FS_DECODE_NON_UTF8',
+        module: 'tools',
+        description: '文本读 UTF-8 严格解码 lossy 拒（04 §7 编码纪律——防 mojibake 静默进上下文）',
+    },
+    {
+        code: 'FS_PATCH_FAILED',
+        module: 'tools',
+        description: 'apply_patch 补丁格式解析失败或 update 定位失败（context 行锚不在场即拒）',
+    },
+    {
+        code: 'FS_READ_PROTECTED',
+        module: 'tools',
+        description: '读目标命中敏感件保护面硬拒（04 §7 读侧 carve-out）——密钥与免问面恒不可读，fail-closed 无审批出路',
+    },
+    // ---- FS_ 族 worktree 三码（04 §7 worktree 条——批 16 worktree 工具族）----
+    {
+        code: 'FS_WORKTREE_EXISTS',
+        module: 'tools',
+        description: 'worktree/同名分支已存在拒建（名字即分支名——双域撞名同码）',
+    },
+    {
+        code: 'FS_WORKTREE_DIRTY',
+        module: 'tools',
+        description: 'worktree 有未提交变更拒拆（防误清宁拒勿删——force 形显式覆盖）',
+    },
+]);