berry-agent 0.1.0-alpha.1

package/dist/conversation/todo.js

@@ -0,0 +1,203 @@
+/**
+ * todo 机器（04 §8 todo 工具件 / 05 §1.1 todo/write 词行）——跨轮任务清单的
+ * durable 事实 + fold 推导 + 模型回看注入 + 工具件四件套。
+ *
+ * 语义单源 = 05 §1.1 词行：
+ *  - durable 词 `todo/write`（类别 surface，items 全量快照、last-write-wins）；
+ *  - **fold = 日志倒扫「最后一条可见 user/message 之后的最后一条本事件」**
+ *    （run 重置语义由推导规则承载、无显式 reset 词；遮蔽区间内的事件不参与
+ *    fold——occluded 的 user/message 不重置、occluded 的 todo/write 不成表，
+ *    两向同律：对模型不可见即从未发生）；
+ *  - 跨 turn 每轮注入当前全表（CC 式回看），走 context_transform 瀑布最后
+ *    关口的瞬态层——角色 `conversation/todo`（hidden 瞬态，不进 timeline 不落
+ *    durable，llmContext 每请求新建故零累积）；冷启动 resume 首请求同样覆盖
+ *    （fold 在请求时点对 durable 日志重放）；
+ *  - 工具形态 = 全量快照式提交（模型每次提交完整清单覆盖旧表）+ 一行计数
+ *    回执。
+ *
+ * 呈现投影（channels TodoItem 四态记号面板）与 durable 形有意分立：conversation
+ * 不得 import channels（DAG 边表），字段形状以注释互镜；status 四值两处同词表。
+ */
+import { Type } from 'typebox';
+import { getMessageRoleDefinition, registerMessageRole, } from '../contracts/index.js';
+import { occludedSeqs } from '../session/index.js';
+/** todo 回看注入角色名（域名前缀两段式——conversation 域） */
+export const TODO_ROLE = 'conversation/todo';
+/** status 四值词表（schema 与 fold 校验共用单源） */
+const TODO_STATUSES = ['pending', 'in-progress', 'completed', 'deferred'];
+/**
+ * 角色定义（模块级单例——身份同一性判据）：toLlm 全表渲染为一条 UserMessage
+ * 尾注（清空表返回 null 剥离）；render hidden（瞬态注入，呈现面不可见——
+ * UI 投影走 durable todo/write 事件，不经此角色）。
+ */
+const TODO_ROLE_DEFINITION = {
+    toLlm: (message) => {
+        const items = validateTodoItems(message.content);
+        if (items.length === 0)
+            return null;
+        return {
+            role: 'user',
+            content: renderTodoTable(items),
+            timestamp: message.timestamp,
+        };
+    },
+    render: { intent: 'hidden', label: '任务清单' },
+};
+/**
+ * 注册 todo 角色（幂等 + 身份守卫）：进程级注册表 + per-session 驱动 ⇒ 多次
+ * 调用常态。在册定义恰为本模块单例 → 幂等通过；在册定义另有其身 → 域名
+ * 被窃据，fail-loud（不静默借用他者转写——消息转写分叉比崩溃更难查）。
+ */
+export function ensureTodoRole() {
+    const existing = getMessageRoleDefinition(TODO_ROLE);
+    if (existing !== undefined) {
+        if (existing !== TODO_ROLE_DEFINITION) {
+            throw new Error(`消息角色 ${TODO_ROLE} 已被其他定义占用（conversation 域名窃据——todo 回看注入拒绝分叉转写）`);
+        }
+        return;
+    }
+    registerMessageRole(TODO_ROLE, TODO_ROLE_DEFINITION);
+}
+/**
+ * fold 当前任务清单（05 §1.1 倒扫规则，遮蔽感知）：
+ * 从日志尾向头扫**可见**事件——
+ *  - 先遇 `todo/write` → 其 items 即当前表（last-write-wins）；
+ *  - 先遇可见 `user/message` → 空表（用户出手即重置——重置语义由推导承载）；
+ *  - 扫到头 → 空表（从未建表）。
+ * assistant 消息与工具事件不参与判据（清单跨 assistant 轮持续——CC 语义）。
+ *
+ * goal 段升格（03 §10.5 计划态跨轮条）：scope 在场（goal active——组合根
+ * `goalScopeFor(sessionId)` 闭包注入）时 fold 边界从「用户输入段」升格
+ * 「goal 生命周期段」——倒扫只取激活锚 `activatedSeq` 之后的最后一条
+ * `todo/write`，**续跑轮 user/message 不再重置表**（计划状态结构性跨轮
+ * 存活）；goal 段载荷扩展字段（resumeWhen/role/taskClass/followUp/gate 等）
+ * 由 validateTodoItems 剥离（本 fold 只投影核心四字段——扩展语义归 goal 件
+ * fold 读侧，词面独立零 import）。
+ */
+export function foldTodoTable(events, scope) {
+    const occluded = occludedSeqs(events);
+    for (let seq = events.length - 1; seq >= 0; seq -= 1) {
+        if (occluded.has(seq))
+            continue;
+        const event = events[seq];
+        // goal 段边界：越激活锚即出段（锚前历史不成表——goal 生命周期段语义；
+        // 下标即 seq——「seq = 写入时 log.length」不变式下单源）
+        if (scope !== undefined && seq < scope.activatedSeq)
+            return [];
+        if (event.type === 'todo/write')
+            return validateTodoItems(event.data.items);
+        // goal 段内 user/message 不重置（跨轮存活）；无 scope 保持 run-scoped 重置
+        if (scope === undefined && event.type === 'user/message')
+            return [];
+    }
+    return [];
+}
+/** 四态中文计数（回执与渲染表头共用词面） */
+function countByStatus(items) {
+    const counts = { pending: 0, 'in-progress': 0, completed: 0, deferred: 0 };
+    for (const item of items)
+        counts[item.status] += 1;
+    return counts;
+}
+/**
+ * 渲染清单为模型可见文本（快照注入体 + 工具回执共用单源）：
+ * 表头一行计数总览 + 每条目一行（status 标签稳定英文词——模型可编程依赖；
+ * 进行中态 activeForm 优先于 content 呈现，与呈现投影同律）。
+ */
+export function renderTodoTable(items) {
+    if (items.length === 0)
+        return '';
+    const counts = countByStatus(items);
+    const header = `当前任务清单（共 ${items.length} 项：` +
+        `进行中 ${counts['in-progress']} · 待办 ${counts.pending} · ` +
+        `已完成 ${counts.completed} · 缓办 ${counts.deferred}）：`;
+    const lines = items.map((item, index) => {
+        const body = item.status === 'in-progress' && item.activeForm !== undefined ? item.activeForm : item.content;
+        return `${index + 1}. [${item.status}] ${body}`;
+    });
+    return [header, ...lines].join('\n');
+}
+/**
+ * 构建跨 turn 注入快照消息：空表返回 null（不注入——从未建表/已重置语义下
+ * 不打扰上下文）；非空走角色的 toLlm 转写（ensureTodoRole 自足——快照构建
+ * 不依赖驱动侧先行注册）。timestamp 取请求时点（注入体的时间面）。
+ * scope 在场 = goal 段 fold（升格语义见 foldTodoTable 头注）。
+ */
+export function todoSnapshotMessage(events, timestamp, scope) {
+    const items = foldTodoTable(events, scope);
+    if (items.length === 0)
+        return null;
+    ensureTodoRole();
+    const converted = TODO_ROLE_DEFINITION.toLlm?.({ role: TODO_ROLE, content: items, timestamp });
+    // 定义体在本模块单源——非空表必产单条 user；运行时窄化防御仅挡未来改动
+    if (converted === undefined || converted === null || Array.isArray(converted) || converted.role !== 'user') {
+        return null;
+    }
+    return converted;
+}
+/**
+ * todo 工具件（04 §8）：全量快照式提交——每次调用提交完整清单覆盖旧表
+ * （增删改全走同一路径，无局部更新动词面）。effect 'read'：写的是 surface
+ * 状态（todo/write 词）非文件系统，不触发审批对与守门拦截面。
+ *
+ * append 回调 = durable 写入面（装配层注入 session.append 闭包——本件不
+ * 直接依赖 SessionLog，纯函数件可独立测试）。
+ */
+export function createTodoTool(append) {
+    return {
+        name: 'todo',
+        description: '维护当前任务清单（全量快照式：每次调用提交完整清单覆盖旧表，含增删改与' +
+            '清空）。清单跨对话轮持续可见（每轮自动回看注入），用户出手后重置为空。' +
+            '适合多步骤任务的进度自查——一次只专注一件事，进行中的条目置 in-progress。',
+        parameters: Type.Object({
+            items: Type.Array(Type.Object({
+                status: Type.Union(TODO_STATUSES.map((status) => Type.Literal(status))),
+                content: Type.String(),
+                activeForm: Type.Optional(Type.String()),
+            }, 
+            // 条目面收紧：多余字段整体拒收（goal 段扩展字段不在此消化——
+            // GOAL_TODO_SCOPE 执法归 goal 件批，本件 schema 即第一道闸）
+            { additionalProperties: false })),
+        }, { additionalProperties: false }),
+        effect: 'read',
+        execute: async (args) => {
+            // 管道已按 schema 校验过参数；validate 再产新拷贝（append 快照拷贝前的
+            // 干净形——不带 undefined 可选腿）并防御读侧漂移
+            const items = validateTodoItems(args.items);
+            append({ items: items.map((item) => ({ ...item })) });
+            const counts = countByStatus(items);
+            const receipt = `已更新任务清单：${items.length} 项` +
+                `（进行中 ${counts['in-progress']} · 待办 ${counts.pending} · ` +
+                `已完成 ${counts.completed} · 缓办 ${counts.deferred}）`;
+            return { content: [{ type: 'text', text: receipt }] };
+        },
+    };
+}
+/**
+ * 未知载荷 → 条目形列表（fold 读侧与工具写侧共用的收窄面）：非对象元素 /
+ * status 出词表 / content 非串 → 整条丢弃（保守降级不 fail-loud——durable
+ * 日志受信但 owner 形演进不得崩读侧）；activeForm 仅收 string 型缺席剔除。
+ */
+function validateTodoItems(value) {
+    if (!Array.isArray(value))
+        return [];
+    const items = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const candidate = entry;
+        if (typeof candidate.status !== 'string' ||
+            !TODO_STATUSES.includes(candidate.status) ||
+            typeof candidate.content !== 'string') {
+            continue;
+        }
+        items.push(typeof candidate.activeForm === 'string'
+            ? {
+                status: candidate.status,
+                content: candidate.content,
+                activeForm: candidate.activeForm,
+            }
+            : { status: candidate.status, content: candidate.content });
+    }
+    return items;
+}

package/dist/conversation/types.js

@@ -0,0 +1,35 @@
+/** RetryPolicy 缺省（04 §3.3 条 6 定值：enabled / 3 次 / 1000ms 基值） */
+export const DEFAULT_RETRY_POLICY = {
+    enabled: true,
+    maxRetries: 3,
+    baseDelayMs: 1000,
+};
+/** 唤醒预算帽（04 §4 定值：连续后台唤醒计数上限——批消费位记账） */
+export const MAX_CONSECUTIVE_WAKES = 3;
+/**
+ * context_transform 钩子事件词（03 §2.4 主表 message 层行——mode waterfall）。
+ * LLM 请求组装最后关口：驱动发射、插件经 ctx.on 挂管线监听器（不调 next 即
+ * 短路——管线语义）。词汇注册双源幂等：bootPlugins 预注册 41 词在前，驱动
+ * 构造器自举在后（已注册词跳过——一词两册不撞名，open-tools 同律）。
+ */
+export const CONTEXT_TRANSFORM_EVENT = 'context_transform';
+/**
+ * agent_pre_step 钩子事件词（03 §2.4 主表 message 层行——mode waterfall）。
+ * 每次模型请求前发射（loop while 体顶、steering 消费与 turn_start 之前——
+ * 预算刹停不产生 dangling turn）：驱动发射、插件经 ctx.on 挂瀑布监听器。
+ * 消费例：goal 预算复验（04 §5 双轨第二腿——budgetExceeded 步间复查防
+ * 记账腿与执行腿竞速漏刹）、压缩压力挂点。词汇注册双源幂等：
+ * bootPlugins 预注册在前，驱动构造器自举在后（CONTEXT_TRANSFORM_EVENT
+ * 同律）。
+ */
+export const AGENT_PRE_STEP_EVENT = 'agent_pre_step';
+/**
+ * session/lifecycle 活体事件词（04 §6 在飞状态活体词——e-2 观测腿）。
+ * run 起/终态广播：驱动 kick 起拍 + runTurns finally 终态拍两发、宿主包装层
+ * 按订阅作用域（self|tree|all）过滤派发。**活体不落日志**（dispatch 内存
+ * 直推——job_settled 同律；durable 真源 = 事件流尾条推导〔03 §10.8〕——推送
+ * 是推导的投影非第二真相源）。词汇注册双源幂等：装配根预注册（插件装载期
+ * 订阅可达——boot 先于首会话起跑）在前、驱动构造器自举在后（已注册词跳过
+ * ——CONTEXT_TRANSFORM_EVENT 同律）。
+ */
+export const SESSION_LIFECYCLE_EVENT = 'session/lifecycle';

package/dist/conversation/wiring.js

@@ -0,0 +1,204 @@
+/**
+ * durable 接线器（驱动私有件——活体事件翻译 + 请求信封快照 + 锚 seq 记账）。
+ *
+ * 构造时从既有日志初始化三态（turn 开合 / header 在否 / 冷启动续接位）——
+ * 会话恢复与新建同路（05 §1.3 恢复 = 重放：接线器状态就是日志状态的折叠）。
+ */
+export class DurableWiring {
+    session;
+    /** durable turn 开合态（agent_end 安全网与 turn_start 判据共用） */
+    turnOpen;
+    /** 日志是否已有 request/header（initial 判据） */
+    hasHeader;
+    /** timeline 重建后的首请求标记（resume 判据——遮蔽重播种/冷启动置位） */
+    rebuildPending;
+    /** 上一信封快照的比对键（change 判据——JSON 序列化同构比对） */
+    lastEnvelopeKey;
+    /** 最后一条 assistant/message 的 seq（runTurns 遮蔽区间的起点锚） */
+    lastAssistantSeqValue;
+    /** 工具归因取值器（tool/call 载荷 owner 位——缺席 = 载荷不带 owner） */
+    resolveToolOwner;
+    constructor(session, options = {}) {
+        this.session = session;
+        this.resolveToolOwner = options.resolveToolOwner;
+        let depth = 0;
+        let header = false;
+        for (const event of session.events()) {
+            if (event.type === 'turn/start')
+                depth += 1;
+            else if (event.type === 'turn/end' && depth > 0)
+                depth -= 1;
+            else if (event.type === 'request/header')
+                header = true;
+        }
+        this.turnOpen = depth > 0;
+        this.hasHeader = header;
+        // 冷启动续接（日志已有 header）：首请求 resume 形——11d resume 续接的先手位
+        this.rebuildPending = header;
+    }
+    /** 最后一条 assistant/message 的锚 seq（重试遮蔽区间起点——驱动消费） */
+    get lastAssistantSeq() {
+        return this.lastAssistantSeqValue;
+    }
+    /** timeline 重建标记（重播种/压缩后置位——下一请求 header 落 resume） */
+    markRebuildPending() {
+        this.rebuildPending = true;
+    }
+    /**
+     * inject 通道直落账（04 §4 inject 行 / berry 停摆语义：只追加会话日志/
+     * 投影、不触发任何模型调用——「随下次启动带入」的 durable 承载）。durable
+     * 写点单归本件（驱动不绕过接线器直写 session）。
+     * @returns 落账 seq（inject 收执面）
+     */
+    appendInjectedUser(message) {
+        const event = this.session.append('user/message', {
+            content: message.content,
+            ...(message.source !== undefined ? { source: message.source } : {}),
+            ...(message.dedupeKey !== undefined ? { dedupeKey: message.dedupeKey } : {}),
+        });
+        return event.seq;
+    }
+    /**
+     * 请求信封快照（边界制——transformContext 关口调用，请求发出前落账）。
+     * initial / resume / change 三边界各落一条；稳态不落。
+     */
+    noteRequest(envelope) {
+        const key = JSON.stringify({
+            config: envelope.config,
+            systemPrompt: envelope.systemPrompt,
+            tools: envelope.toolSchemas,
+        });
+        let reason;
+        if (!this.hasHeader)
+            reason = 'initial';
+        else if (this.rebuildPending)
+            reason = 'resume';
+        else if (key !== this.lastEnvelopeKey)
+            reason = 'change';
+        else
+            return; // 稳态——最后一条基准仍真，不重复快照
+        this.session.append('request/header', {
+            config: envelope.config,
+            systemPrompt: envelope.systemPrompt,
+            toolSchemas: envelope.toolSchemas,
+            reason,
+        });
+        this.hasHeader = true;
+        this.rebuildPending = false;
+        this.lastEnvelopeKey = key;
+    }
+    /**
+     * 活体事件翻译（onEvent 汇的第一腿——外部汇是第二腿，两腿同源同序）。
+     * 只认消息级终值与轮边界；其余事件型零翻译（流式细节属活体层）。
+     */
+    onEvent(event) {
+        switch (event.type) {
+            case 'turn_start': {
+                // 无打开 durable turn 才开（工具批延续轮/重试续入轮同判据）
+                if (!this.turnOpen) {
+                    this.session.append('turn/start', {});
+                    this.turnOpen = true;
+                }
+                return;
+            }
+            case 'turn_end': {
+                if (!this.turnOpen)
+                    return; // 防御：配对外的 turn_end（不应出现）
+                // toolUse 不闭（轮内继续）；length 延到 agent_end（截断配对结果先落）
+                if (event.stopReason === 'toolUse' || event.stopReason === 'length')
+                    return;
+                this.closeTurn(turnEndReasonOf(event.stopReason));
+                return;
+            }
+            case 'agent_end': {
+                // 安全网：turn 仍开（工具批后打断/length 配对后）→ 按终态补收口
+                if (!this.turnOpen)
+                    return;
+                const reason = event.stopReason === 'length'
+                    ? 'max-tokens'
+                    : event.status === 'completed'
+                        ? 'completed'
+                        : event.status === 'aborted'
+                            ? 'aborted'
+                            : 'error';
+                this.closeTurn(reason);
+                return;
+            }
+            case 'message_end': {
+                this.appendMessage(event.message);
+                return;
+            }
+            default:
+                // message_start/update、tool_execution_*、agent_start——活体层专属
+                return;
+        }
+    }
+    /** 落 turn/end 并闭 turn（turn_end 与 agent_end 安全网共用） */
+    closeTurn(reason) {
+        this.session.append('turn/end', { reason });
+        this.turnOpen = false;
+    }
+    /** 消息级终值翻译（标准三角色各走各的 durable 词；自定义角色暂无 durable 写点） */
+    appendMessage(message) {
+        const role = message.role;
+        if (role === 'user') {
+            const user = message;
+            this.session.append('user/message', {
+                content: user.content,
+                ...(user.source !== undefined ? { source: user.source } : {}),
+                ...(user.dedupeKey !== undefined ? { dedupeKey: user.dedupeKey } : {}),
+            });
+            return;
+        }
+        if (role === 'assistant') {
+            const assistant = message;
+            // toolCall 块不内联（05 §1.1——内联+事件双载会在投影回读拼出重复块）；
+            // text/thinking 块原样透传（签名位随行——pi-ai 投影形状）
+            const content = assistant.content.filter((block) => block.type !== 'toolCall');
+            const event = this.session.append('assistant/message', {
+                content,
+                usage: assistant.usage,
+                stopReason: assistant.stopReason,
+                ...(assistant.errorMessage !== undefined ? { errorMessage: assistant.errorMessage } : {}),
+            });
+            this.lastAssistantSeqValue = event.seq;
+            // 工具调用分立落账：arguments 回写原始串（审计保真——读侧解析失败兜底 {}）；
+            // owner 归因位写时带出（05 §1.1——T9 案一批 R2 案 A：调用流直读「这次
+            // 调用是谁的」读侧零 join）。可选带出形（dedupeKey 同律）：resolver
+            // 缺席或未命中（装配残缺——模型调用的名必然在当次请求面内，未命中即
+            // 装配缺陷）不带 owner，不虚构归因
+            for (const block of assistant.content) {
+                if (block.type !== 'toolCall')
+                    continue;
+                const owner = this.resolveToolOwner?.(block.name);
+                this.session.append('tool/call', {
+                    toolCallId: block.id,
+                    name: block.name,
+                    arguments: JSON.stringify(block.arguments),
+                    ...(owner !== undefined ? { owner } : {}),
+                });
+            }
+            return;
+        }
+        if (role === 'toolResult') {
+            const result = message;
+            this.session.append('tool/result', {
+                toolCallId: result.toolCallId,
+                content: result.content,
+                ...(result.isError ? { error: true } : {}),
+            });
+            return;
+        }
+        // 自定义角色（memory/recall 等）：瞬态注入纪律不落 durable；非瞬态自定义
+        // 角色的落账词随 11f/记忆批纵切裁决——当前零写点，静默跳过即唯一诚实行为
+    }
+}
+/** loop 终态值 → durable turn/end reason（TurnEndReason 闭集内归位） */
+function turnEndReasonOf(stopReason) {
+    if (stopReason === 'aborted')
+        return 'aborted';
+    if (stopReason === 'error')
+        return 'error';
+    // stop / deferred——自然收尾（deferred 是延迟装载透传值，v1 不产生但词汇保留）
+    return 'completed';
+}

package/dist/credentials/codes.js

@@ -0,0 +1,59 @@
+/**
+ * credentials 域错误码注册（02 §5.3 族前缀 `CREDENTIALS_`——c-1 规范先行批
+ * 明列三码；03 §10.9 错误码族 bullet 真源）。
+ *
+ * 码语义分层：一码守 get 作用名缺席（NOT_FOUND——GOAL_NOT_FOUND 同构
+ * 守卫）；一码管 namespace 隔离与跨域门检（NAMESPACE_DENIED——同码分流：
+ * 未开门越域拒 / namespace 坏形拒，两档共用 message 底稿指路开门位写法）；
+ * 一码管受理窗外写拒（WRITE_WINDOW_CLOSED——宿主回调窗执法，12f-2a
+ * PLUGIN_WINDOW_CLOSED 唯一例外位的凭证面同律）；一码管注入腿引用形坏形
+ * （ENV_REF_INVALID——c-4：前缀命中而名空，exec env.ts 抛出）。
+ *
+ * oauth 流内码三枚（c-6 扩族——03 §10.9 错误码族 bullet 兑现）：用户拒授
+ * （DENIED——token 端点 access_denied，授权页明确拒绝）/ 态坏过期
+ * （EXPIRED——设备码轮询窗超窗 + expired_token + refresh 凭据失效 invalid_grant
+ * 三形同码：共同语义 = 授权态已坏、重试无益、须重新发起授权流）/ 协议传输
+ * 兜底（FLOW_FAILED——端点非预期应答/载荷坏形/网络错，重试可期）。
+ *
+ * 密钥物理面既有码 PERSIST_SECRET_UNREADABLE（05 §9）复用不重立。
+ *
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'CREDENTIALS_NOT_FOUND',
+        module: 'credentials',
+        description: 'get 作用名缺席守卫——自域/越域读命中不存在的凭证名响亮拒（GOAL_NOT_FOUND 同构）',
+    },
+    {
+        code: 'CREDENTIALS_NAMESPACE_DENIED',
+        module: 'credentials',
+        description: 'namespace 隔离执法——同码分流两档：未开门越域读拒（credentials.read-cross 高危面默认关，开门位 = 启用清单 opens）/ namespace 坏形拒（非 host 且非 plugin:<id> 值域）',
+    },
+    {
+        code: 'CREDENTIALS_WRITE_WINDOW_CLOSED',
+        module: 'credentials',
+        description: '受理窗外写拒——ctx.secrets.set 只在宿主回调窗内可达（用户发起 oauth 授权流 → 宿主回调插件 handler → 窗内写；03 §10.9 写入面复合案）',
+    },
+    {
+        code: 'CREDENTIALS_ENV_REF_INVALID',
+        module: 'credentials',
+        description: 'env 引用形坏形（c-4 注入腿）——set 值前缀 @credentials: 命中而名空，响亮拒字面注入；词面单源 contracts/env-ref.ts',
+    },
+    {
+        code: 'CREDENTIALS_OAUTH_DENIED',
+        module: 'credentials',
+        description: 'oauth 授权流用户拒授——token 端点 error=access_denied（授权页明确拒绝；重发流可再试）',
+    },
+    {
+        code: 'CREDENTIALS_OAUTH_EXPIRED',
+        module: 'credentials',
+        description: 'oauth 授权态坏过期（三形同码：设备码轮询窗超窗 / token 端点 error=expired_token / refresh 凭据失效 error=invalid_grant——重试无益，须重新发起 /credentials oauth）',
+    },
+    {
+        code: 'CREDENTIALS_OAUTH_FLOW_FAILED',
+        module: 'credentials',
+        description: 'oauth 流协议/传输面失败兜底——端点非预期应答、载荷坏形（缺 device_code/access_token 等）、网络传输错；重试可期',
+    },
+]);