berry-agent-sdk 0.1.0-alpha.2

package/dist/src/contracts/llm.d.ts

@@ -0,0 +1,278 @@
+/**
+ * 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 等）不在此收口，多出的字段对结构化赋值透明。
+ */
+/** 文本块（user/assistant/toolResult 通用） */
+export interface TextContent {
+    type: 'text';
+    text: string;
+    /** 供应商侧文本签名（回放用；透传） */
+    textSignature?: string;
+}
+/** 思考块（仅 assistant；供应商推理内容回放） */
+export interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+    /** 供应商不透明签名（推理上下文复用；透传） */
+    thinkingSignature?: string;
+    /** 安全过滤已遮蔽的思考（加密载荷存 thinkingSignature 透传回 API） */
+    redacted?: boolean;
+}
+/** 图片块（多模态附件；base64 数据） */
+export interface ImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+/** 工具调用块（仅 assistant 内联；arguments 已是解析后的对象） */
+export interface ToolCallBlock {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * 一次 LLM 调用的 token 用量（pi-ai 同构）：cacheRead/cacheWrite 独立拆桶，
+ * cacheWrite1h（仅 Anthropic 上报拆分）与 reasoning（已含于 output，供应商
+ * 不报则缺省）为可选子集。
+ */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** cacheWrite 中 1h 保留的子集（仅 Anthropic 上报拆分） */
+    cacheWrite1h?: number;
+    /** 推理 token 子集（已含于 output；供应商不报则缺省） */
+    reasoning?: number;
+    totalTokens: number;
+    /** 费用（供应商可解析时填充） */
+    cost?: {
+        total: number;
+        input?: number;
+        output?: number;
+        currency?: string;
+    };
+}
+/**
+ * 计量四桶形（05 篇 §1.1 llm/usage 事件载荷 usage 字段形）：input/output/
+ * cacheRead/cacheWrite 四桶必落（供应商恒报），cacheWrite1h/reasoning 上报才落；
+ * totalTokens（派生）与 cost（折算）**不入账**——token 原始值入账、货币折算
+ * 在投影查询做（价格表更新不回改历史）。
+ */
+export interface UsageBuckets {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** cacheWrite 中 1h 保留的子集（仅 Anthropic 上报拆分；上报才落） */
+    cacheWrite1h?: number;
+    /** 推理 token 子集（已含于 output；上报才落） */
+    reasoning?: number;
+}
+/**
+ * LLM 调用终态（pi-ai 同构七值）。
+ * loop 只消费 error/aborted（终态短路）与 length（截断防御）；
+ * deferred 是 pi-ai 原生延迟工具装载透传值，v1 不产生但词汇保留。
+ */
+export type StopReason = 'pending' | 'stop' | 'length' | 'toolUse' | 'error' | 'aborted' | 'deferred';
+/**
+ * 错误四桶（04 §3.5 表）。词汇归 contracts 单源（批 11b 契约先行）：唯一实现
+ * 在 llm（classifyError 纯函数表），conversation（runTurns 重试循环与溢出
+ * 兜底）经装配注入消费同形——两侧零词汇漂移（04 §3.5 消费通路条款）。
+ * transient/non-retryable/quota 是消费动作桶（每桶一个动作无歧义态），
+ * overflow 只分类不消费（动作挂溢出兜底纵切 04 §3.4）。
+ */
+export type ErrorBucket = 'transient' | 'non-retryable' | 'quota' | 'overflow';
+/**
+ * 用户消息（content 允许纯文本或图文块数组）。
+ * source 归因复用会话事件词汇闭集 EventSource（05 §3.1 单源——durable 落账
+ * 与 LLM 边界同一名；pi-ai UserMessage 不带此字段，多出字段对直通透明）。
+ */
+export interface UserMessage {
+    role: 'user';
+    content: string | (TextContent | ImageContent)[];
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 输入归因（缺省视为 'user'；投影带出、durable 原样落账） */
+    source?: import('./types.js').EventSource;
+    /**
+     * 幂等去重键（05 §1.1 user/message 行：调用方自选、可选字段——serve 面
+     * 幂等 admit 语义真源 05 §3.5；UI 侧不带零影响）。子代理审批挂起通知等
+     * 「恰一条」机器注入以本键承载去重判据（04 §10）。
+     */
+    dedupeKey?: string;
+}
+/** 助手消息（流式组装终值；stopReason=error/aborted 时错误即数据，见 AssistantStream） */
+export interface AssistantMessage {
+    role: 'assistant';
+    content: (TextContent | ThinkingContent | ToolCallBlock)[];
+    usage: Usage;
+    stopReason: StopReason;
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 模型标识（provider 内模型 id；llm 模块解析） */
+    model?: string;
+    /** 供应商标识 */
+    provider?: string;
+    /** stopReason=error/aborted 时的错误说明（错误是数据契约之一） */
+    errorMessage?: string;
+    /**
+     * 错误码（04 §3.5 判定序的机器判定位）：宿主合成错误携带 LLM_ 码（如
+     * LLM_INFLIGHT_LIMIT 帽拒绝）；provider 真错误码归一挂 provider 钩子纵切。
+     * classifyError 判定时在场码优先、文案正则兜底。
+     */
+    errorCode?: string;
+    /** 脱敏诊断（恢复与审计用） */
+    diagnostics?: unknown[];
+}
+/** 工具结果消息（与 assistant 内 toolCall 按 toolCallId 配对） */
+export interface ToolResultMessage {
+    role: 'toolResult';
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    isError: boolean;
+    /** Unix 毫秒时间戳 */
+    timestamp: number;
+    /** 供日志/UI 的结构化明细（不进主上下文计费） */
+    details?: unknown;
+    /** 工具执行自身的用量（若可得上报；不进主上下文计费） */
+    usage?: Usage;
+    /** 本次结果后新可用的工具名（延迟装载透传） */
+    addedToolNames?: string[];
+}
+/** LLM 边界标准三角色（convertToLlm 透传的标准半边） */
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+/** LLM 工具描述（parameters 为 JSON Schema——typebox 产物即此形状） */
+export interface LlmTool {
+    name: string;
+    description: string;
+    /** JSON Schema 参数描述（typebox 产物或等价 JSON Schema 对象；宽收 object 兼容构建器类型） */
+    parameters: object;
+}
+/** 单次 LLM 请求上下文（StreamFn 第一参数；04 §3.1） */
+export interface LlmContext {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: LlmTool[];
+}
+/**
+ * 模型目录只读投影（listModels()/getModel() 返回形）：pi-ai Model 的应用友好
+ * 子集——枚举/展示/能力判别所需字段直通，传输与 provider 配置面（baseUrl/
+ * headers/samplingParams/compat）不披露（宿主数据只经服务面，03 篇 §3.2
+ * 「防双实例」纪律的读侧配套）。
+ */
+export interface ModelInfo {
+    /** 模型标识（"provider/model-id" 全形——resolveModel 可解析的同一名） */
+    readonly id: string;
+    /** 展示名（人类可读） */
+    readonly name: string;
+    /** 所属 provider id（目录分组用） */
+    readonly provider: string;
+    /** 是否推理模型（思考档位面可用性判据） */
+    readonly reasoning: boolean;
+    /** 输入模态清单 */
+    readonly input: readonly ('text' | 'image')[];
+    /** 上下文窗口（tokens） */
+    readonly contextWindow: number;
+    /** 单请求输出上限（tokens） */
+    readonly maxTokens: number;
+}
+/** 思考档位（pi-ai 同构七值；xhigh/max 仅部分模型家族支持——会话态非 run 态，04 §5） */
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** StreamFn 每次调用的选项（model 为模型 id 字符串——解析归 llm 模块，loop 不持模型对象） */
+export interface StreamFnOptions {
+    /** 模型 id（llm 模块解析为具体 provider/model；可逐轮替换） */
+    model: string;
+    thinkingLevel?: ThinkingLevel;
+    /** 凭证（缺省 undefined 由 llm 层走持久化凭证链） */
+    apiKey?: string;
+}
+/**
+ * 模型层注入签名（llm 模块整体替换位——agent 与 llm 两模块的唯一会合点，故落在
+ * contracts）。契约：**永不抛错**（04 §3）——一切失败编码为返回流的 error 终止
+ * 事件 + 最终消息 stopReason='error'|'aborted' + errorMessage（AssistantStream
+ * 契约注释）。这是 loop 零 try/catch 的契约根基：错误是数据不是异常。
+ */
+export type StreamFn = (context: LlmContext, options: StreamFnOptions, signal?: AbortSignal) => AssistantStream | Promise<AssistantStream>;
+/**
+ * 流式事件（pi-ai AssistantMessageEvent 同构 12 型）。
+ * 协议：正常形 `start` 先行 → 各内容块 start/delta/end 交错（partial 携带累计
+ * 快照）→ 以 `done`（成功）或 `error`（stopReason=error/aborted）收尾。
+ * **error 可无 start 前导**（04 §3 2026-09-14 定形）：provider 前置失败形
+ * （请求创建失败）只发单个 `error` 即收尾——「start 先行」非流的隐含序约束，
+ * 消费面终值落位须判占位在场（未见 start 走 append，不尾替换）。
+ */
+export type AssistantStreamEvent = {
+    type: 'start';
+    partial: AssistantMessage;
+} | {
+    type: 'text_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'text_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'text_end';
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'thinking_end';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_start';
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_delta';
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: 'toolcall_end';
+    contentIndex: number;
+    toolCall: ToolCallBlock;
+    partial: AssistantMessage;
+} | {
+    type: 'done';
+    reason: Extract<StopReason, 'stop' | 'length' | 'toolUse' | 'deferred'>;
+    message: AssistantMessage;
+} | {
+    type: 'error';
+    reason: Extract<StopReason, 'aborted' | 'error'>;
+    error: AssistantMessage;
+};
+/**
+ * 流式响应：异步迭代事件 + 最终消息取值口。
+ * 契约（04 §3「永不抛」，loop 零 try/catch 的根基）：**永不抛错**——一切失败
+ * 编码为流内 `error` 终止事件 + 最终 AssistantMessage 的 stopReason='error'|
+ * 'aborted' + errorMessage。错误是数据不是异常（金样回放轨的替换点 seam）。
+ */
+export interface AssistantStream {
+    /** 迭代流事件（以 done/error 收尾后结束） */
+    [Symbol.asyncIterator](): AsyncIterator<AssistantStreamEvent>;
+    /** 取最终 AssistantMessage（流耗尽后 resolve；失败编码在 stopReason/errorMessage 上） */
+    result(): Promise<AssistantMessage>;
+}

package/dist/src/contracts/llm.js

@@ -0,0 +1,13 @@
+/**
+ * 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 {};
+//# sourceMappingURL=llm.js.map

package/dist/src/contracts/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../../../src/contracts/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/src/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/src/contracts/messages.js

@@ -0,0 +1,66 @@
+/**
+ * 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);
+}
+//# sourceMappingURL=messages.js.map

package/dist/src/contracts/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../../../src/contracts/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;AAExG;;;;GAIG;AACH,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAkC5D,wCAAwC;AACxC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,UAAiC;IACjF,yCAAyC;IACzC,yDAAyD;IACzD,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CAAC,mBAAmB,EAAE,QAAQ,IAAI,8BAA8B,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,oBAAoB,EACpB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,kDAAkD,CAC9E,CAAC;IACJ,CAAC;IACD,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACnC,OAAO,GAAG,EAAE;QACV,qCAAqC;QACrC,mDAAmD;QACnD,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU;YAAE,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvE,CAAC,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,OAAO,sBAAsB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/src/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;