berry-agent 0.1.0-alpha.1

package/dist/contracts/llm.js

@@ -0,0 +1,12 @@
+/**
+ * L0 contracts — LLM 边界消息基础件（04 篇 §3 StreamFn 契约 + §5 模型层）。
+ *
+ * 承 berry 同款关键决策：agent loop 不 import llm（02 篇 §4.2 关键不依赖第
+ * 一条），StreamFn 签名与消息形状收进 contracts——pi-ai 产生的消息值可原样
+ * 赋给这里的类型（标准三角色零转换直通）。
+ *
+ * 兼容策略：字段取 pi-ai 0.84.4 对应接口的**超集兼容子集**——本文件要求的
+ * 必填字段在 pi-ai 中全部存在且同名同型；pi-ai 独有的字段（api/responseModel/
+ * deferred 等）不在此收口，多出的字段对结构化赋值透明。
+ */
+export {};

package/dist/contracts/messages.d.ts

@@ -0,0 +1,63 @@
+/**
+ * L0 contracts — 消息模型与自定义角色注册（04 篇 §2「AgentMessage 与自定义角色」）。
+ *
+ * 消息模型 = 标准三角色（llm.ts Message）∪ 自定义角色（CustomMessage）。自定义
+ * 角色经 registerMessageRole 注册（render/toLlm 双写映射 + hidden 位），域名前缀
+ * 两段式强制（`memory/recall` 式——与 03 篇 §2.7 prompt slot 同构的域名纪律）。
+ * 宿主不预注册任何自定义角色；conversation 按需注册（04 §2）。
+ *
+ * 单入口裁决（本仓 vs berry 蓝本差异①）：蓝本双入口（registerAppMessageRole /
+ * registerHostMessageRole）不采纳——扩展单位既归一为插件，宿主件与插件同走
+ * registerMessageRole 单入口、同守域名前缀纪律，无宿主单段自留地。
+ */
+import type { Message } from './llm.js';
+/**
+ * 标准角色名闭集（convertToLlm 透传的标准半边；自定义角色撞此集任何一名即拒）。
+ * 与 llm.ts Message 三角色判别位一一对应。
+ */
+export declare const STANDARD_MESSAGE_ROLES: ReadonlySet<string>;
+/** 自定义角色消息（content 载荷形状由角色定义自裁——toLlm 映射的输入） */
+export interface CustomMessage {
+    /** 自定义角色名（域名两段式） */
+    role: string;
+    /** 载荷（角色定义自裁其形状） */
+    content: unknown;
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+}
+/** 消息模型全集：标准三角色 ∪ 自定义角色（loop 与驱动侧的共同消息面） */
+export type AgentMessage = Message | CustomMessage;
+/** 呈现意图（render 映射的输出半边；hidden = 瞬态注入不进用户可见流） */
+export interface MessageRoleRender {
+    /** inline = 进对话流；status = 状态行；hidden = 不可见（模型可见但用户不可见的瞬态注入） */
+    intent: 'inline' | 'status' | 'hidden';
+    /** 呈现标签（UI 折行显示用） */
+    label?: string;
+}
+/** 角色定义：toLlm 映射（进模型上下文的降写）+ render 呈现（用户可见面） */
+export interface MessageRoleDefinition {
+    /**
+     * 自定义消息 → LLM 消息的转写：返回 Message（降写为标准角色）、Message[]
+     * （一拆多）或 null（剥离——瞬态注入本轮用毕即隐）。
+     */
+    toLlm?: (message: CustomMessage) => Message | Message[] | null;
+    /** 呈现映射（缺省无 render = 不可见） */
+    render?: MessageRoleRender;
+}
+/**
+ * 注册自定义消息角色（ctx.agent.registerMessageRole 的本体——单入口）。
+ *
+ * 拒绝式两码（03 篇 §2.7 消息面行）：撞标准角色名或在册角色 → AGENT_ROLE_EXISTS；
+ * 域名前缀两段式违例 → AGENT_ROLE_INVALID。注册失败零记账（无半注册残留）。
+ *
+ * @param role 角色名（域名两段式，如 `memory/recall`）
+ * @param definition 角色定义（toLlm/render 双写映射）
+ * @returns disposer——仅当注册表内仍是**本定义**时移除（防误摘后来同名胜出者）
+ */
+export declare function registerMessageRole(role: string, definition: MessageRoleDefinition): () => void;
+/** 查询角色定义（标准角色与未注册角色返回 undefined） */
+export declare function getMessageRoleDefinition(role: string): MessageRoleDefinition | undefined;
+/** 在册自定义角色名枚举（诊断/目录面） */
+export declare function listMessageRoleNames(): string[];
+/** 标准消息窄化守卫（正向判窄化——自定义消息判别用 !isStandardMessage） */
+export declare function isStandardMessage(message: AgentMessage): message is Message;

package/dist/contracts/messages.js

@@ -0,0 +1,65 @@
+/**
+ * L0 contracts — 消息模型与自定义角色注册（04 篇 §2「AgentMessage 与自定义角色」）。
+ *
+ * 消息模型 = 标准三角色（llm.ts Message）∪ 自定义角色（CustomMessage）。自定义
+ * 角色经 registerMessageRole 注册（render/toLlm 双写映射 + hidden 位），域名前缀
+ * 两段式强制（`memory/recall` 式——与 03 篇 §2.7 prompt slot 同构的域名纪律）。
+ * 宿主不预注册任何自定义角色；conversation 按需注册（04 §2）。
+ *
+ * 单入口裁决（本仓 vs berry 蓝本差异①）：蓝本双入口（registerAppMessageRole /
+ * registerHostMessageRole）不采纳——扩展单位既归一为插件，宿主件与插件同走
+ * registerMessageRole 单入口、同守域名前缀纪律，无宿主单段自留地。
+ */
+import { BaseError } from './errors.js';
+/**
+ * 标准角色名闭集（convertToLlm 透传的标准半边；自定义角色撞此集任何一名即拒）。
+ * 与 llm.ts Message 三角色判别位一一对应。
+ */
+export const STANDARD_MESSAGE_ROLES = new Set(['user', 'assistant', 'toolResult']);
+/**
+ * 自定义域名前缀两段式判据（03 篇 §2.7 消息面行）：恰含一个 `/`、两段均
+ * 小写字母数字连字符且段首为字母（`memory/recall` 合法；`Memory/recall`、
+ * `memory`、`a/b/c` 均非法）。
+ */
+const CUSTOM_ROLE_RE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+/** 角色注册表本体（role → 定义；进程级单表，宿主件与插件共用） */
+const roleRegistry = new Map();
+/**
+ * 注册自定义消息角色（ctx.agent.registerMessageRole 的本体——单入口）。
+ *
+ * 拒绝式两码（03 篇 §2.7 消息面行）：撞标准角色名或在册角色 → AGENT_ROLE_EXISTS；
+ * 域名前缀两段式违例 → AGENT_ROLE_INVALID。注册失败零记账（无半注册残留）。
+ *
+ * @param role 角色名（域名两段式，如 `memory/recall`）
+ * @param definition 角色定义（toLlm/render 双写映射）
+ * @returns disposer——仅当注册表内仍是**本定义**时移除（防误摘后来同名胜出者）
+ */
+export function registerMessageRole(role, definition) {
+    // 撞名检查前置于格式检查：标准角色名（user 等单段）先撞此闸——「名字已被
+    // 占用」比「格式违例」更指向根因（03 §2.7：撞标准角色或在册角色均 AGENT_ROLE_EXISTS）
+    if (STANDARD_MESSAGE_ROLES.has(role) || roleRegistry.has(role)) {
+        throw new BaseError('AGENT_ROLE_EXISTS', `消息角色 ${role} 已在册（标准角色或在册自定义角色），重影即消息转写分叉`);
+    }
+    if (!CUSTOM_ROLE_RE.test(role)) {
+        throw new BaseError('AGENT_ROLE_INVALID', `角色名 ${JSON.stringify(role)} 违域名前缀两段式纪律（恰含一个 /、两段均小写字母数字连字符，如 memory/recall）`);
+    }
+    roleRegistry.set(role, definition);
+    return () => {
+        // 仅当仍是本定义时移除——后来者不可能同名胜出（拒绝式），此守卫防的是
+        // disposer 持有过期时序下的误摘（先 dispose 后重注册再 dispose 的序列）
+        if (roleRegistry.get(role) === definition)
+            roleRegistry.delete(role);
+    };
+}
+/** 查询角色定义（标准角色与未注册角色返回 undefined） */
+export function getMessageRoleDefinition(role) {
+    return roleRegistry.get(role);
+}
+/** 在册自定义角色名枚举（诊断/目录面） */
+export function listMessageRoleNames() {
+    return [...roleRegistry.keys()];
+}
+/** 标准消息窄化守卫（正向判窄化——自定义消息判别用 !isStandardMessage） */
+export function isStandardMessage(message) {
+    return STANDARD_MESSAGE_ROLES.has(message.role);
+}

package/dist/contracts/redact.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 出口治理③ 凭据消毒（04 §7 执行段 2026-09-08 落码定形——出口层 redaction
+ * 纯函数单源；c-4 泄漏面净化④「server 工具结果回显 env 值」的收口批）。
+ *
+ * 词汇面与词面单源纪律（env-ref.ts 同先例）：放 contracts 使两消费方零新
+ * DAG 边——tools 管道链尾（模式 + 值基两腿）与 agent 错误包装位（纯模式
+ * 腿——错误即结果 ⑤ 与正常结果同一出口语义）。纯函数零依赖零状态，jiti
+ * 可载。
+ *
+ * 两腿：
+ * - **模式腿**（`redactSensitiveText`）：闭集正则三段——URL userinfo 剥离 /
+ *   URL query 敏感参数值剥离 / 敏感键名值脱敏（赋值形覆盖裸 =、:、JSON
+ *   引号形与 Authorization 头整行特例）。无外部数据依赖、恒在场。
+ * - **值基腿**（`redactKnownSecretValues` + `redactToolResultExit`）：装配
+ *   注入 credentials 库活值 provider——具名形态外的裸值回显收口；provider
+ *   缺席 = 纯模式执法（降级诚实）。
+ *
+ * 非静默原则（截断注记同律）：消毒以 `[REDACTED:<reason>]` 注记进上下文
+ * ——模型可见有物被消，非凭空篡改。幂等：注记自身不构成再触发形（回调内
+ * 显式判已注记即跳过）。
+ */
+import type { AgentToolResult } from './tools.js';
+/**
+ * 模式腿：出口文本消毒（04 §7 出口治理③模式集三段——纯函数、幂等、恒在场）。
+ *
+ * 覆盖面（闭集、大小写不敏感）：URL userinfo / URL query 敏感参数值 /
+ * 敏感键名赋值值（含 Authorization 头整行特例）。通用赋值形值长 < 4 跳过
+ * （散文冒号误伤面控制——"the token: is" 不触发；URL 两段上下文无歧义不设此阈）。
+ */
+export declare function redactSensitiveText(text: string): string;
+/**
+ * 值基腿：已知秘密活值整段置换（split/join 字面替换——值含正则元字符安全）。
+ *
+ * 长值先换（前缀包含关系下短值先换会破坏长值锚）；长度 < 8 不参与（短值
+ * 误伤普通文本的灾难面控制——04 §7 定形⑤）。provider 给值已是明文（装配
+ * 侧 credentials 库 live 读——本函数恒不取库，纯数据进出）。
+ */
+export declare function redactKnownSecretValues(text: string, values: readonly string[]): string;
+/**
+ * 工具结果出口消毒（管道链尾调用——04 §7 定形①：护栏之前一步）。
+ *
+ * 就地改写：文本 content 逐块消毒（图片等自有界块原样保留——与输出护栏
+ * 同判据）；details 深走字符串叶消毒（结构化明细同是 server 回显面）。
+ * 纯模式 + 值基两腿合流；provider 调用方恒传数组（装配闭包 live 读）。
+ */
+export declare function redactToolResultExit(result: AgentToolResult, sensitiveValues: readonly string[]): void;

package/dist/contracts/redact.js

@@ -0,0 +1,223 @@
+/**
+ * 出口治理③ 凭据消毒（04 §7 执行段 2026-09-08 落码定形——出口层 redaction
+ * 纯函数单源；c-4 泄漏面净化④「server 工具结果回显 env 值」的收口批）。
+ *
+ * 词汇面与词面单源纪律（env-ref.ts 同先例）：放 contracts 使两消费方零新
+ * DAG 边——tools 管道链尾（模式 + 值基两腿）与 agent 错误包装位（纯模式
+ * 腿——错误即结果 ⑤ 与正常结果同一出口语义）。纯函数零依赖零状态，jiti
+ * 可载。
+ *
+ * 两腿：
+ * - **模式腿**（`redactSensitiveText`）：闭集正则三段——URL userinfo 剥离 /
+ *   URL query 敏感参数值剥离 / 敏感键名值脱敏（赋值形覆盖裸 =、:、JSON
+ *   引号形与 Authorization 头整行特例）。无外部数据依赖、恒在场。
+ * - **值基腿**（`redactKnownSecretValues` + `redactToolResultExit`）：装配
+ *   注入 credentials 库活值 provider——具名形态外的裸值回显收口；provider
+ *   缺席 = 纯模式执法（降级诚实）。
+ *
+ * 非静默原则（截断注记同律）：消毒以 `[REDACTED:<reason>]` 注记进上下文
+ * ——模型可见有物被消，非凭空篡改。幂等：注记自身不构成再触发形（回调内
+ * 显式判已注记即跳过）。
+ */
+/** 消毒注记前缀（形如 `[REDACTED:<reason>]`——幂等判定的锚） */
+const MARK = '[REDACTED:';
+/** URL query 敏感参数名闭集（小写单源；匹配大小写不敏感） */
+const QUERY_TOKEN_PARAMS = [
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'client_secret',
+    'api_key',
+    'apikey',
+    'token',
+    'secret',
+    'password',
+    'passwd',
+    'signature',
+    'sig',
+    'key',
+];
+/** 敏感键名分段闭集（键名按 -_. 分段、**末段**命中即敏感；小写单源） */
+const SENSITIVE_NAME_SEGMENTS = new Set([
+    'token',
+    'tokens',
+    'secret',
+    'secrets',
+    'password',
+    'passwords',
+    'passwd',
+    'pass',
+    'pwd',
+    'apikey',
+    'key',
+    'keys',
+    'credential',
+    'credentials',
+    'signature',
+    'auth',
+    'authorization',
+    'bearer',
+]);
+/** 正则元字符转义（闭集参数名拼接进 alternation 前的安全化） */
+function escapeRe(s) {
+    return s.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+}
+/** 值是否已是消毒注记（幂等跳过锚） */
+function isMarked(value) {
+    return value.startsWith(MARK);
+}
+/**
+ * 键名是否敏感（**末段**判据——GITHUB_TOKEN / aws_secret_access_key / api-key
+ * 同判；末段判控制误伤面：token_type / token_url / secret_name 之类「敏感词
+ * 作前缀修饰、末段为中性词」的公开字段不触发）。
+ */
+function isSensitiveName(name) {
+    const segments = name
+        .toLowerCase()
+        .split(/[-_.]+/)
+        .filter((seg) => seg.length > 0);
+    const last = segments[segments.length - 1];
+    return last !== undefined && SENSITIVE_NAME_SEGMENTS.has(last);
+}
+/**
+ * URL query 敏感参数值剥离正则（`?token=…` / `&api_key=…`——参数名精确段
+ * 匹配：`[?&]` 前锚 + `=` 后锚，`token_type` 之类前缀词不误伤）。
+ */
+const QUERY_TOKEN_RE = new RegExp(`([?&])(${QUERY_TOKEN_PARAMS.map(escapeRe).join('|')})(=)([^&\\s#'"]*)`, 'gi');
+/**
+ * URL userinfo 剥离正则（`scheme://user:pass@`——冒号对形才命中，裸用户名
+ * 形不触发）。值两段排除 `[`：消毒注记形 `[REDACTED:...]` 不被当 user:pass
+ * 二次剥离（幂等锚的一环）。
+ */
+const URL_USERINFO_RE = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^\s"'<>@/[]+):([^\s"'<>@/[]+)@/g;
+/** Authorization 头整行特例（值含空格——`Bearer xyz` 裸赋值形只截到首词，特例整行收口） */
+const AUTHORIZATION_RE = /\b(proxy-authorization|authorization)(\s*[=:]\s*)([^\r\n]+)/gi;
+/**
+ * 通用赋值形正则：名字（裸词 / 引号词）+ 分隔（= 或 :）+ 值（引号串或裸串）。
+ * 敏感性与否经回调判名（分段闭集）——正则只负责形，语义在回调。
+ */
+const ASSIGNMENT_RE = /("[A-Za-z][A-Za-z0-9_.-]*"|[A-Za-z][A-Za-z0-9_.-]*)(\s*[=:]\s*)("[^"\n]*"|'[^'\n]*'|[^\s,;"'`&\]}]+)/g;
+/** 键名提取（剥引号——JSON 形 `"api_key"` 与裸形 `api_key` 同判） */
+function bareName(raw) {
+    return raw.startsWith('"') || raw.startsWith("'") ? raw.slice(1, -1) : raw;
+}
+/** 值替换形（保引号——JSON 形消毒产物仍是合法引号串） */
+function markedValue(raw) {
+    if (raw.startsWith('"'))
+        return '"[REDACTED:secret]"';
+    if (raw.startsWith("'"))
+        return "'[REDACTED:secret]'";
+    return '[REDACTED:secret]';
+}
+/**
+ * 模式腿：出口文本消毒（04 §7 出口治理③模式集三段——纯函数、幂等、恒在场）。
+ *
+ * 覆盖面（闭集、大小写不敏感）：URL userinfo / URL query 敏感参数值 /
+ * 敏感键名赋值值（含 Authorization 头整行特例）。通用赋值形值长 < 4 跳过
+ * （散文冒号误伤面控制——"the token: is" 不触发；URL 两段上下文无歧义不设此阈）。
+ */
+export function redactSensitiveText(text) {
+    // 段序：userinfo → query → Authorization → 通用赋值（特例先于通例——
+    // Authorization 整行形若先被通例截短即漏尾词）
+    let out = text.replace(URL_USERINFO_RE, '$1[REDACTED:url-userinfo]@');
+    out = out.replace(QUERY_TOKEN_RE, (full, q, name, eq, value) => isMarked(value) ? full : `${q}${name}${eq}[REDACTED:query-token]`);
+    out = out.replace(AUTHORIZATION_RE, (full, name, sep, value) => isMarked(value.trimStart()) ? full : `${name}${sep}[REDACTED:credential]`);
+    return redactAssignments(out);
+}
+/**
+ * 通用赋值形消毒（redactSensitiveText 第四段本体——独立函数供值内递归）。
+ * 非敏感名命中不吞段：裸值字符类允许 = 与全/半角冒号，形如
+ * `Error: 命令失败：GITHUB_TOKEN=x` 的前缀对会把后续敏感对并进自己的值区
+ * （正则消费区不再访）——值内递归再扫收口。递归操作于严格更短子串，深度
+ * 有界。
+ */
+function redactAssignments(text) {
+    return text.replace(ASSIGNMENT_RE, (full, rawName, sep, rawValue) => {
+        if (isMarked(rawValue))
+            return full;
+        if (!isSensitiveName(bareName(rawName))) {
+            return `${rawName}${sep}${redactAssignments(rawValue)}`;
+        }
+        // 裸值过短跳过（散文误伤阈——引号值不设阈：引号形即结构化语境）
+        if (!/["']/.test(rawValue[0] ?? '') && rawValue.length < 4)
+            return full;
+        return `${rawName}${sep}${markedValue(rawValue)}`;
+    });
+}
+/**
+ * 值基腿：已知秘密活值整段置换（split/join 字面替换——值含正则元字符安全）。
+ *
+ * 长值先换（前缀包含关系下短值先换会破坏长值锚）；长度 < 8 不参与（短值
+ * 误伤普通文本的灾难面控制——04 §7 定形⑤）。provider 给值已是明文（装配
+ * 侧 credentials 库 live 读——本函数恒不取库，纯数据进出）。
+ */
+export function redactKnownSecretValues(text, values) {
+    const eligible = values.filter((v) => typeof v === 'string' && v.length >= 8 && !v.includes(MARK));
+    const ordered = [...new Set(eligible)].sort((a, b) => b.length - a.length);
+    let out = text;
+    for (const value of ordered) {
+        if (!out.includes(value))
+            continue;
+        out = out.split(value).join('[REDACTED:credential]');
+    }
+    return out;
+}
+/** 两腿合流（值基先行——名形留下具名注记，模式腿补裸形） */
+function redactAll(text, values) {
+    return redactSensitiveText(redactKnownSecretValues(text, values));
+}
+/** details 深走上限（防御深度——病态深构不递归失控） */
+const DETAILS_DEPTH_CAP = 8;
+/** details 字符串叶消毒（结构保形——只改字符串叶，数与布尔不动） */
+function redactDetails(node, values, depth, seen) {
+    if (depth > DETAILS_DEPTH_CAP)
+        return;
+    if (typeof node === 'string')
+        return; // 字符串非对象——叶替换在调用处（readonly 容器内就地不可行，见下）
+    if (node === null || typeof node !== 'object')
+        return;
+    if (seen.has(node))
+        return; // 环防御（details 是工具产物，理论纯 JSON——防御位）
+    seen.add(node);
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            const item = node[i];
+            if (typeof item === 'string')
+                node[i] = redactAll(item, values);
+            else
+                redactDetails(item, values, depth + 1, seen);
+        }
+        return;
+    }
+    const record = node;
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        if (typeof value === 'string') {
+            // 对象键名敏感即整值脱敏（c-4 ④ 本体形态：结构化明细里敏感键携裸值——
+            // 字符串叶内无键名形可匹配，模式正则够不着；键名即结构化语境的赋值形，
+            // JSON 引号形的内存对偶，同律不设值阈）
+            record[key] = isSensitiveName(key) ? '[REDACTED:secret]' : redactAll(value, values);
+        }
+        else if (value !== null && typeof value === 'object')
+            redactDetails(value, values, depth + 1, seen);
+    }
+}
+/**
+ * 工具结果出口消毒（管道链尾调用——04 §7 定形①：护栏之前一步）。
+ *
+ * 就地改写：文本 content 逐块消毒（图片等自有界块原样保留——与输出护栏
+ * 同判据）；details 深走字符串叶消毒（结构化明细同是 server 回显面）。
+ * 纯模式 + 值基两腿合流；provider 调用方恒传数组（装配闭包 live 读）。
+ */
+export function redactToolResultExit(result, sensitiveValues) {
+    if (Array.isArray(result.content)) {
+        for (const block of result.content) {
+            if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+                block.text = redactAll(block.text, sensitiveValues);
+            }
+        }
+    }
+    if (result.details !== undefined && result.details !== null && typeof result.details === 'object') {
+        redactDetails(result.details, sensitiveValues, 0, new Set());
+    }
+}

package/dist/contracts/tools.d.ts

@@ -0,0 +1,197 @@
+/**
+ * L0 contracts — AgentTool 工具族类型（agent 件三段管道的执行体契约）。
+ *
+ * 裁决（本仓 vs berry 蓝本差异②）：蓝本 AgentTool 族先落 agent 件后迁
+ * contracts——本仓一步到位直上 contracts（插件 defineTool 的参数类型消费面，
+ * 避免落码即迁的双写窗口）。工具面三段管道（schema→守门→执行）本体在
+ * tools 件（后续批）；本件只钉**执行体形状**——loop 工具批的直接消费面。
+ */
+import type { ImageContent, TextContent, ToolCallBlock, Usage } from './llm.js';
+/** 工具执行结果（终值——错误也走 isError 数据面不走异常面） */
+export interface AgentToolResult {
+    /** 结果内容（与 ToolResultMessage.content 同形；空结果传空数组） */
+    content: (TextContent | ImageContent)[];
+    /** 供日志/UI 的结构化明细（不进主上下文计费） */
+    details?: unknown;
+    /** 错误标记（错误是数据契约之一：isError=true 的结果照常进上下文配对） */
+    isError?: boolean;
+    /** 工具执行自身的用量（若可得上报） */
+    usage?: Usage;
+    /** 本次结果后新可用的工具名（延迟装载透传） */
+    addedToolNames?: string[];
+    /** 终止旗标：批内全 terminate 才 terminate（批内一致裁决——单件否决不放大） */
+    terminate?: boolean;
+}
+/** 工具执行进度回调（tool_execution_update 事件的载荷源；promise 结算后的迟到进度被丢弃） */
+export type ToolUpdateCallback = (update: unknown) => void;
+/**
+ * 工具执行体（loop 工具批消费的最小形状——完整 defineTool 形在 tools 件）。
+ * execute 契约：一切失败编码为 isError 结果（数据面），同步抛错由执行器
+ * 包装兜底（tools-batch——loop 骨架零 try/catch 的配套执法位）。
+ */
+export interface AgentTool {
+    /** 工具名（模型可见清单词法面） */
+    name: string;
+    /** 工具描述（模型可见） */
+    description: string;
+    /** UI 呈现标签（缺省用 name） */
+    label?: string;
+    /** JSON Schema 参数描述（typebox 产物或等价 JSON Schema 对象） */
+    parameters: object;
+    /**
+     * 效果面（03 §2.3 一位两用——批调度与审批共此单键，不另设同义键）：
+     * ① 调度语义（tools-batch 批消费序执法——04 §2 尾句）：read（含缺省）批内
+     *   可并行调度、write 批边界串行（写前清空在飞只读）；
+     * ② 审批语义：write 触发审批对（守门段校验，审批编舞归 safety 件）。
+     */
+    effect?: ToolEffect;
+    /** 参数预处理钩子（执行前最后一改参数的机会；返回改后参数） */
+    prepareArguments?: (arguments_: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * 执行体：@param toolCallId 调用 id（与 assistant 内 toolCall 配对键）
+     * @param arguments_ 已解析参数 @param signal 中止信号（协作面）
+     * @param onUpdate 进度回调（迟到进度被丢弃）
+     */
+    execute: (toolCallId: string, arguments_: Record<string, unknown>, signal?: AbortSignal, onUpdate?: ToolUpdateCallback) => Promise<AgentToolResult>;
+}
+/** 工具批执行输入项（assistant 内联 toolCall 块的直取形） */
+export type AgentToolCall = ToolCallBlock;
+/**
+ * 工具效果面（03 §2.3 一位两用）——**工具档三值**（04 §9 定形块①，2026-09-11
+ * 审批分档批）：`read` = 只读（批内并行调度、不走审批对）；`write` = 写面
+ * （批边界串行屏障 + 审批对触发）；`exec` = 任意进程执行类（v1 升档清单恰
+ * 一处 = bash——exec/bash.ts；write/exec 同触发审批对、同走批边界串行）。
+ * **缺省 = exec**（未知缺省最危律——04 §9 定形块②；执法位在注册面归一
+ * `def.effect ?? 'exec'`，2026-09-11 缺省反转，原缺省 read 作废）。
+ * 审批编舞归 safety 件。
+ */
+export type ToolEffect = 'read' | 'write' | 'exec';
+/**
+ * 工具档偏序 rank（04 §9 定形块①：read < write < exec）。与 §8 沙箱档
+ * TIER_RANK（safety/approval 件内私有常量）**两轴分立**：工具档 = 该工具
+ * 固有风险位，沙箱档 = 本次运行许可面，互不推导。消费位：策略表条目
+ * `effect?` 限定的偏序包含判（safety 匹配引擎）、粘性/allow 授权不跨档
+ * 覆盖的比较面（04 §9 ①「write 档免问授权结构上不覆盖 exec 调用」）。
+ */
+export declare const TOOL_TIER_RANK: Readonly<Record<ToolEffect, number>>;
+/** 工具执行语境（管道构造后传给 ToolDefinition.execute 的第 2 参） */
+export interface ToolContext {
+    /** 调用 id（与 assistant 内联 toolCall 配对键） */
+    toolCallId: string;
+    /** 中止信号（协作面——超时/取消传播） */
+    signal?: AbortSignal;
+    /** 进度回调（迟到的进度被丢弃——loop 工具批侧语义） */
+    onUpdate?: ToolUpdateCallback;
+    /** 会话语境键（驱动层工具的 per-session 状态路由键——fs 观察态等） */
+    sessionId?: string;
+}
+/**
+ * 注册表内工具定义（03 §2.3 defineTool 形——插件注册动词 ctx.tools.register
+ * 的入参形状）。与 AgentTool（loop 直消费面）的分野：本形 execute 收
+ * (args, toolCtx) 插件便利签名；注册表经 toAgentTool 包装成三段管道执行体。
+ */
+export interface ToolDefinition {
+    /** 工具名（全局唯一；命名纪律与查重见 03 §2.7） */
+    name: string;
+    /** 模型可见描述（注册面注入模式扫描——03 §2.8） */
+    description: string;
+    /** JSON Schema 参数描述（typebox 产物或等价 JSON Schema 对象；根须 object） */
+    parameters: object;
+    /** 单次执行预算毫秒（正数；缺省走管道 60s——04 §7 执行段） */
+    timeoutMs?: number;
+    /** 效果面（一位两用——调度语义 + 审批触发；缺省 exec〔未知缺省最危律——04 §9 定形块②，2026-09-11 反转〕。03 §2.3） */
+    effect?: ToolEffect;
+    /**
+     * 幂等位（03 §2.3）：缺省 true；false = 禁静默重试——副作用型工具重放即
+     * 重复执行，重试决策须回模型或上抛不静默。框架侧重放机制（04 §2 call_id
+     * 幂等决策）已落码（agent 件 tools-batch 消费序 limiter——回执腿不重执行，
+     * 2026-09-09）；本位词面与其相容（重放回执既不构成「静默重试」）。
+     */
+    repeatable?: boolean;
+    /**
+     * 归因铸造位（03 §2.3 尾注——T9 案一批 R1 定形）：**注册面铸造、插件不可
+     * 自报**——ctx.tools.register 受理壳（fork 级闭包携 pluginId）无条件覆写
+     * 为注册者 pluginId，defineTool 输入形状无 owner 参数位（传入自报值恒不达
+     * 注册表——冒名结构性不存在）。值域 = 插件 id 裸词（官方件含 core: 前缀
+     * 形）+ 保留位 'core:host'（不经插件注册面的宿主装配工具——open 域
+     * fs/bash/todo 族 + 模型面八件 plugin_* + obs/control extraTools 族；缺省
+     * 盖章单点在 open-tools 注册处）。消费位 = tool/call 事件载荷 owner 位
+     * （05 §1.1 写时带出——读侧零 join）；读侧勿当件 id join 装机账本。
+     */
+    owner?: string;
+    /** 执行体：一切失败编码为 isError 结果（数据面）；抛错由管道/loop 包装兜底 */
+    execute: (args: Record<string, unknown>, toolCtx: ToolContext) => Promise<AgentToolResult>;
+}
+/** 守门段决策词汇（03 §2.4——拦截族 handler 控制输出同一套） */
+export type GateAction = {
+    action: 'allow';
+} | {
+    action: 'block';
+    reason: string;
+};
+/**
+ * 守门段 waterfall 载荷（04 §7 段 2）。**可变入参就地改写**：链上 gateInput
+ * 对象对整条链固定，守门者改 gateInput.args 即改执行段所见参数（mutate 语义
+ * 依赖此——置 mutated 旗供 durable 落账判定）。放行 = next(input) 委托下游；
+ * 拦截 = 不调 next 短路、置 outcome 后返回（waterfall 短路语义即 block 语义）。
+ */
+export interface GateInput {
+    /** 被调用工具（只读参考） */
+    tool: ToolDefinition;
+    /** 调用参数（可变——mutate 就地改写） */
+    args: Record<string, unknown>;
+    /** 调用 id */
+    toolCallId: string;
+    /**
+     * 会话键（管道签名本有——工具按会话键分派时透传进守门面；04 §7 批 15d
+     * 补注。消费先例 = core:checkpoint pre-mutation 捕获按会话判 per-run；
+     * 无会话场景〔测试/系统调用〕缺省不带）
+     */
+    sessionId?: string;
+    /** 中止信号（守门面构造审批 ask 载荷时携带） */
+    signal?: AbortSignal;
+    /** 参数已被改写旗（改参的守门者维护；落账 decision=mutate 的判据） */
+    mutated: boolean;
+    /**
+     * 放行来源标注（04 §9 命中审计条款）：免问面（跨会话工具策略表）命中的
+     * 守门者置 `policy-allow:<条目序>`（2026-09-11 审批分档批更词——原
+     * `allowlist:<条目序>` 词面作废，04 §9 定形块④；值域归 04 §9 单源），
+     * 管道落 gate/decision 时承接进 reason 位（放行仍可审计——「谁放的行」
+     * 指哪条既有授权放的行）；缺省 undefined = 普通放行，落账 reason 'ok'
+     */
+    allowReason?: string;
+    /** 拦截决策（block 者置；缺省 undefined = 放行沿链） */
+    outcome?: GateAction;
+}
+/** 执行段 waterfall 载荷（around-dispatch：T = 执行闭包，监听者包装后经 next 传播） */
+export type ExecuteInput = () => Promise<AgentToolResult>;
+/** 后处理段 waterfall 载荷（可就地改写 result——裁剪/spill/isError 改写） */
+export interface PostExecuteInput {
+    /** 被调用工具（只读参考） */
+    tool: ToolDefinition;
+    /** 调用参数（守门后终参） */
+    args: Record<string, unknown>;
+    /** 调用 id */
+    toolCallId: string;
+    /** 工具结果（可变——监听者就地改写） */
+    result: AgentToolResult;
+}
+/** gate/decision durable 落账记录（05 §1.1 词汇表 gate/decision 行的 data 形状） */
+export interface GateDecisionRecord {
+    /** 调用 id（与 tool/call·tool/result 配对键） */
+    toolCallId: string;
+    /** 决策三值（allow / block / mutate） */
+    decision: 'allow' | 'block' | 'mutate';
+    /** 决策理由（block 原因 / 放行来源标注；缺省 'ok'） */
+    reason: string;
+}
+/** gate/decision 落账 sink（装配根接 session.append；tools 不依赖 session——DAG 单向） */
+export type GateDecisionSink = (record: GateDecisionRecord) => void;
+/** 三段管道执行器（注册表 toAgentTool 的执行真身；抛 BaseError 由 loop 包装 isError） */
+export type ToolPipelineExecutor = (def: ToolDefinition, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal, onUpdate?: ToolUpdateCallback, sessionId?: string) => Promise<AgentToolResult>;
+export declare const TOOL_PRE_EXECUTE_EVENT = "tools_pre_execute";
+export declare const TOOL_EXECUTE_EVENT = "tools_execute";
+export declare const TOOL_POST_EXECUTE_EVENT = "tools_post_execute";
+export declare const TOOLS_CHANGE_EVENT = "tools_change";
+/** tools 件经 ctx 事件面消费的词汇全集（装配根注册清单单源） */
+export declare const TOOL_EVENT_NAMES: readonly string[];

package/dist/contracts/tools.js

@@ -0,0 +1,33 @@
+/**
+ * L0 contracts — AgentTool 工具族类型（agent 件三段管道的执行体契约）。
+ *
+ * 裁决（本仓 vs berry 蓝本差异②）：蓝本 AgentTool 族先落 agent 件后迁
+ * contracts——本仓一步到位直上 contracts（插件 defineTool 的参数类型消费面，
+ * 避免落码即迁的双写窗口）。工具面三段管道（schema→守门→执行）本体在
+ * tools 件（后续批）；本件只钉**执行体形状**——loop 工具批的直接消费面。
+ */
+/**
+ * 工具档偏序 rank（04 §9 定形块①：read < write < exec）。与 §8 沙箱档
+ * TIER_RANK（safety/approval 件内私有常量）**两轴分立**：工具档 = 该工具
+ * 固有风险位，沙箱档 = 本次运行许可面，互不推导。消费位：策略表条目
+ * `effect?` 限定的偏序包含判（safety 匹配引擎）、粘性/allow 授权不跨档
+ * 覆盖的比较面（04 §9 ①「write 档免问授权结构上不覆盖 exec 调用」）。
+ */
+export const TOOL_TIER_RANK = {
+    read: 0,
+    write: 1,
+    exec: 2,
+};
+/* 钩子词汇常量（03 §2.4 主表三段 + tools_change——词本体在 LIVE 词表，
+ * 装配根 registerEventNames 消费本清单；tools 件自用 + safety 守门行订阅面） */
+export const TOOL_PRE_EXECUTE_EVENT = 'tools_pre_execute';
+export const TOOL_EXECUTE_EVENT = 'tools_execute';
+export const TOOL_POST_EXECUTE_EVENT = 'tools_post_execute';
+export const TOOLS_CHANGE_EVENT = 'tools_change';
+/** tools 件经 ctx 事件面消费的词汇全集（装配根注册清单单源） */
+export const TOOL_EVENT_NAMES = [
+    TOOL_PRE_EXECUTE_EVENT,
+    TOOL_EXECUTE_EVENT,
+    TOOL_POST_EXECUTE_EVENT,
+    TOOLS_CHANGE_EVENT,
+];