berry-agent 0.1.0-alpha.1

package/dist/credentials/commands.js

@@ -0,0 +1,186 @@
+/**
+ * credentials — 人面命令处理器（03 §10.9 写入面复合案·静态凭证人面唯写；
+ * c-5 落码批）。
+ *
+ * 双面共享底座：TUI `/credentials`（core-plugins 注册——argv 面）与 CLI
+ * `berry-agent credentials`（cli.ts 解析产物 CredentialsSub 直入）同源本件
+ * ——动词语义/值域执法/结算文本单源，两面只差投递形（notify vs stdout）。
+ * 形态律同 /tick /memory-export（命令件先例）：argv → 人读文本；服务面守卫
+ * 错（BaseError）折文本不抛——命令面是用户面不是异常面。
+ *
+ * 铁律（03 §10.9 模型可见性铁律）：
+ *  - **值永不呈现在任何结算文本**——add/rm 只回执名与域，list 只列
+ *    namespace/名/来源/更新时间（给值唯一路径 = 注入腿 env 引用形展开）；
+ *  - 人面命令恒可列示/撤销**一切域**（host + 全部 plugin:<id>——审计与
+ *    治理面不随 namespace 分权；与 ctx.secrets 读腿的自域隔离分立两律）；
+ *  - argv 传值不落 durable——channels 命令分派纯内存直达 handler（命令
+ *    输入不进 conversation/durable 管线），CLI 同理；值经 argv 即进程内
+ *    瞬态，写库即加密落盘，无明文留痕面。
+ *
+ * 窄面注入律（词面独立律——结构兼容 persist Store 凭证方法子集四法，
+ * compat 互证归本件测试）：本件 DAG 无 host 边，宿主装配位传真身。
+ */
+import { BaseError } from '../contracts/index.js';
+import { HOST_NAMESPACE, isPluginNamespace } from './types.js';
+/** 用法文案（TUI 命令 description 位与用法错指路共用单源；oauth 动词 TUI 面承载——CLI 零装配无注册表不载） */
+export const CREDENTIALS_USAGE = [
+    '用法：/credentials add <name> <value> [--namespace <ns>] —— 录入静态凭证（缺省 host 域；值含空格用引号包裹）',
+    '　　　/credentials list —— 全域列示（namespace/名/来源/更新时间——永不呈值）',
+    '　　　/credentials rm <name> [--namespace <ns>] —— 撤销凭证（删除唯一路径）',
+    '　　　/credentials oauth <pluginId> [<name>] —— 发起插件 oauth 授权流（device-code；域随流主人）',
+].join('\n');
+/**
+ * TUI 面 argv 解析（CLI 面由 cli.ts 解析律执法——未知旗标退 2 等；本函数
+ * 只服务 TUI 通道的裸 argv：动词识别 + 位置参数 + --namespace 旗标）。
+ */
+export function parseCredentialsArgv(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === undefined || verb.startsWith('--')) {
+        return { ok: false, message: `缺子命令。\n${CREDENTIALS_USAGE}` };
+    }
+    // 旗标扫描（本命令族唯一旗标 --namespace——宽容形：位置参数与旗标可交错）
+    const literals = [];
+    let namespace;
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (tok === '--namespace') {
+            const next = rest[i + 1];
+            if (next === undefined || next === '') {
+                return { ok: false, message: `--namespace 须带值。\n${CREDENTIALS_USAGE}` };
+            }
+            namespace = next;
+            i++;
+            continue;
+        }
+        literals.push(tok);
+    }
+    if (verb === 'list') {
+        if (literals.length > 0)
+            return { ok: false, message: `list 不收位置参数。\n${CREDENTIALS_USAGE}` };
+        return { ok: true, sub: { sub: 'list' } };
+    }
+    if (verb === 'add') {
+        if (literals.length !== 2) {
+            return { ok: false, message: `add 须带 <name> <value> 两参数。\n${CREDENTIALS_USAGE}` };
+        }
+        return {
+            ok: true,
+            sub: {
+                sub: 'add',
+                name: literals[0],
+                value: literals[1],
+                ...(namespace !== undefined ? { namespace } : {}),
+            },
+        };
+    }
+    if (verb === 'rm') {
+        if (literals.length !== 1) {
+            return { ok: false, message: `rm 须带 <name> 一参数。\n${CREDENTIALS_USAGE}` };
+        }
+        return {
+            ok: true,
+            sub: { sub: 'rm', name: literals[0], ...(namespace !== undefined ? { namespace } : {}) },
+        };
+    }
+    if (verb === 'oauth') {
+        if (namespace !== undefined) {
+            // 域随流主人（token 落插件自域）——oauth 不收 --namespace
+            return { ok: false, message: `oauth 不收 --namespace（域随流主人——token 落插件自域）。\n${CREDENTIALS_USAGE}` };
+        }
+        if (literals.length < 1 || literals.length > 2) {
+            return {
+                ok: false,
+                message: `oauth 须带 <pluginId> [<name>]（name 可省 = 该插件唯一流）。\n${CREDENTIALS_USAGE}`,
+            };
+        }
+        return {
+            ok: true,
+            sub: {
+                sub: 'oauth',
+                pluginId: literals[0],
+                ...(literals.length === 2 ? { name: literals[1] } : {}),
+            },
+        };
+    }
+    return { ok: false, message: `未知子命令：${verb}（合法：add/list/rm/oauth）。\n${CREDENTIALS_USAGE}` };
+}
+/**
+ * 命令处理器（同步纯逻辑——存储三法 + 审计 seam；守卫错折文本 ok:false）。
+ */
+export function runCredentialsCommand(sub, deps) {
+    try {
+        switch (sub.sub) {
+            case 'add':
+                return runAdd(sub.name, sub.value, sub.namespace, deps);
+            case 'list':
+                return runList(deps);
+            case 'rm':
+                return runRm(sub.name, sub.namespace, deps);
+            case 'oauth':
+                // 不可达退化档（CLI 解析律不产此形、TUI 面在 core-plugins 执行腿
+                // 分流先取）——直入仍诚实回执不炸
+                return {
+                    ok: false,
+                    text: 'oauth 动词是运行时承载（需流注册表 + fetch）——TUI 内用 /credentials oauth；CLI 面不可用。',
+                };
+        }
+    }
+    catch (err) {
+        // 守卫错折文本（命令面是用户面——BaseError 码与人读原因直呈；密钥腐坏
+        // PERSIST_SECRET_UNREADABLE 等物理面错同折不炸通道）
+        if (err instanceof BaseError)
+            return { ok: false, text: `${err.code}：${err.message}` };
+        throw err;
+    }
+}
+/** namespace 解析执法（缺省 host；值域 = 'host' | 好形 plugin:<id>——判据单源 isPluginNamespace） */
+function resolveNamespace(namespace) {
+    if (namespace === undefined)
+        return HOST_NAMESPACE;
+    if (namespace !== HOST_NAMESPACE && !isPluginNamespace(namespace)) {
+        throw new BaseError('CREDENTIALS_NAMESPACE_DENIED', `namespace「${namespace}」坏形——值域 = 'host' | 'plugin:<id>'（03 §10.9 namespace 归属列值域单源）`);
+    }
+    return namespace;
+}
+/** add：录入（upsert——同名覆写整行含 meta；写 meta {source:'manual'}；值不回显） */
+function runAdd(name, value, namespace, deps) {
+    const ns = resolveNamespace(namespace);
+    if (value === '') {
+        // 空值 = 缺值形（CLI 空串经解析律已拦；TUI tokenize 可产空段——此处兜底）
+        return { ok: false, text: `值不得为空。\n${CREDENTIALS_USAGE}` };
+    }
+    const meta = { source: 'manual' };
+    deps.store.setCredential(ns, name, { apiKey: value, meta });
+    // credentials/changed 审计 seam（05 §1.1 值域单源：人面写 = action 'add' /
+    // origin 'human'；值恒不入载荷；生产装配已接线 audit_events——assembly
+    // U3 批 U3-5，缺省 no-op = 测试形）
+    deps.onCredentialChanged?.({ namespace: ns, name, action: 'add', origin: 'human' });
+    return {
+        ok: true,
+        text: `已录入凭证 ${ns}/${name}（来源 manual）——值不回显；注入用 env 引用形 '@credentials:${name}'。`,
+    };
+}
+/** rm：撤销（删除唯一路径——保留律的对面；缺席 = CREDENTIALS_NOT_FOUND 折文本） */
+function runRm(name, namespace, deps) {
+    const ns = resolveNamespace(namespace);
+    if (!deps.store.deleteCredential(ns, name)) {
+        throw new BaseError('CREDENTIALS_NOT_FOUND', `凭证 ${name} 不在 ${ns} 域——用 list 查在册名。`);
+    }
+    deps.onCredentialChanged?.({ namespace: ns, name, action: 'remove', origin: 'human' });
+    return { ok: true, text: `已撤销凭证 ${ns}/${name}。` };
+}
+/** list：全域列示（namespace/名/来源/更新时间——永不呈值；expired 位随来源列标注） */
+function runList(deps) {
+    const rows = deps.store.listCredentialProviders();
+    if (rows.length === 0) {
+        return { ok: true, text: '无凭证（数据目录凭证表空——/credentials add 录入首条）' };
+    }
+    const lines = [`共 ${rows.length} 条凭证（全域列示，永不呈值）：`];
+    for (const row of rows) {
+        const meta = (row.meta ?? {});
+        const source = meta.source ?? '未记';
+        const expired = meta.expired === true ? '（已过期——保留上次有效值）' : '';
+        lines.push(`  ${row.namespace}  ${row.provider}  来源 ${source}${expired}  更新 ${new Date(row.updatedAt).toISOString()}`);
+    }
+    return { ok: true, text: lines.join('\n') };
+}

package/dist/credentials/env-ref.js

@@ -0,0 +1,34 @@
+/**
+ * credentials — env 引用形展开器工厂（03 §10.9 注入腿；c-4 落码批）。
+ *
+ * 消费链：用户在 MCP/LSP server config env 声明 `@credentials:<name>` →
+ * 配置原文（引用形）流入 exec EnvPolicy.set → spawn 时刻 buildChildEnv 单点
+ * 调用本工厂产物展开。本工厂只做两件事：
+ *  - **host 域读**（namespace 恒 'host'——用户配置域 = 宿主域：server config
+ *    是用户手面 enabled.yaml，插件域凭证不进用户 server 配置注入面；
+ *    与 ctx.secrets.get 的插件域读腿分立两路）；
+ *  - **缺席响亮拒**（CREDENTIALS_NOT_FOUND——message 指路人面录入路径）。
+ *
+ * 不落审计：注入腿展开 = 宿主代用户配置展开，非插件越域读——无门无账
+ * （capability/used 只记插件越域命中，03 §10.9 读腿定形注同源）。
+ *
+ * 席位接线：plugin-boot 在 secretsSeatActive（与 ctx.secrets 席位门同一双
+ * 条件）时把本工厂产物供入共享根服务 'credentials-env-ref'——exec 件
+ * apply 期拾取；禁用/缺席 ⇒ 服务缺席 ⇒ 引用形 fail-loud（exec 侧执法）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { HOST_NAMESPACE } from './types.js';
+/**
+ * 建 env 引用形展开器（host 域恒定——用户配置注入面单域）。
+ * @param store 凭证存储窄面（assembly 接 persistence.store 凭证投影）
+ * @returns 展开器：名命中返回明文；缺席抛 CREDENTIALS_NOT_FOUND（指路人面）
+ */
+export function createEnvRefResolver(store) {
+    return (name) => {
+        const entry = store.getCredential(HOST_NAMESPACE, name);
+        if (entry === undefined) {
+            throw new BaseError('CREDENTIALS_NOT_FOUND', `env 引用形 @credentials:${name} 在 host 域缺席——人面录入路径 /credentials add（03 §10.9 注入腿；模型可见性铁律：值恒不出现在配置/日志/工具结果）`);
+        }
+        return entry.apiKey;
+    };
+}

package/dist/credentials/index.js

@@ -0,0 +1,28 @@
+/**
+ * credentials — core:credentials 公开面（02 §4.1 #28 席；边 contracts+persist）。
+ *
+ * c-2 存储腿产物：契约词面件（types）+ 表扩容迁移（migration）。c-3 读腿
+ * 产物：错误码族（codes）+ 插件凭证面工厂（secrets——ctx.get("secrets")
+ * 消费面，host 装配序逐插件 fork provide 绑定版）。c-4 注入腿产物：env
+ * 引用形展开器工厂（env-ref——host 域，exec spawn 管道单点消费）。人面
+ * 命令/oauth 流随 c-5..c-6 落码批逐笔扩公开面（03 §10.9 件章为机制真源）。
+ * c-6 产物：oauth 流编舞 + 流注册表 + 刷新链三振（oauth.ts/refresh.ts）；
+ * ctx.secrets 第三动词 registerOAuthFlow（secrets.ts）。
+ */
+import './codes.js';
+export { HOST_NAMESPACE, pluginNamespace, isPluginNamespace, parsePluginNamespace, } from './types.js';
+export { CREDENTIALS_MIGRATION } from './migration.js';
+export { createSecretsFace, } from './secrets.js';
+// oauth 流（c-6——03 §10.9 oauth 案）：流编舞（device-code/refresh——四源
+// 注入零真网络）+ 流注册表（host-owned）+ 人面流解析
+export { runDeviceCodeFlow, refreshOAuthToken, createOAuthFlowRegistry, resolveOAuthFlow, } from './oauth.js';
+// 刷新链（c-6）：件内自持挂钟 + 保留上次有效值律三振（interval 0 = 测试
+// 手动 tick 驱动）
+export { createRefreshChain } from './refresh.js';
+// 注入腿（c-4——03 §10.9）：env 引用形展开器工厂（host 域）——plugin-boot
+// 席位接线消费（共享根服务 'credentials-env-ref' → exec spawn 管道拾取）
+export { createEnvRefResolver } from './env-ref.js';
+// 人面命令（c-5——03 §10.9 写入面复合案）：双面共享纯逻辑底座（TUI
+// /credentials 与 CLI credentials 子命令族同源——动词语义/值域执法/结算
+// 文本单源；host 侧 core-plugins 注册 + credentials-cmd CLI 入口两消费位）
+export { CREDENTIALS_USAGE, parseCredentialsArgv, runCredentialsCommand, } from './commands.js';

package/dist/credentials/migration.js

@@ -0,0 +1,18 @@
+export const CREDENTIALS_MIGRATION = {
+    version: 7,
+    name: 'credentials-namespace',
+    sql: `
+    CREATE TABLE credentials_v7 (
+      namespace  TEXT    NOT NULL DEFAULT 'host',        -- 归属列（'host' | 'plugin:<id>'——词面单源 src/credentials/types.ts）
+      provider   TEXT    NOT NULL,                       -- 作用名（读腿 get(name) 的 name——物理列名承 v1）
+      api_key    TEXT    NOT NULL,                       -- v1:<base64(iv|tag|ct)>（secret-box 加密产物）
+      meta       TEXT,                                   -- JSON 附加元数据（source/expired 键约定见 types.ts）
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (namespace, provider)
+    ) STRICT;
+    INSERT INTO credentials_v7 (namespace, provider, api_key, meta, updated_at)
+      SELECT 'host', provider, api_key, meta, updated_at FROM credentials;
+    DROP TABLE credentials;
+    ALTER TABLE credentials_v7 RENAME TO credentials;
+  `,
+};

package/dist/credentials/oauth.js

@@ -0,0 +1,266 @@
+/**
+ * credentials — oauth 授权流件（03 §10.9 oauth bullet；c-6 落码批）。
+ *
+ * 三段承载：
+ *  1. **device-code 流编舞**（RFC 8628——回调受理位挂账 U5 后，v1 只此流）：
+ *     `runDeviceCodeFlow` 纯舞步——发起（POST deviceAuthUrl form）→ present
+ *     用户（user_code/verification_uri 人读呈现）→ 按 interval 轮询 token
+ *     端点 → authorization_pending 续轮 / slow_down 提速降频（interval+5s）/
+ *     access_denied → DENIED / expired_token·超窗 → EXPIRED / 200 → tokens。
+ *     fetch/clock/present/sleep 四源全注入（测试零真网络铁律——loop 只认
+ *     StreamFn 同律：本件无 web 边，fetchFn 由宿主装配位注入）。
+ *  2. **刷新腿** `refreshOAuthToken`：grant_type=refresh_token 换新——
+ *     invalid_grant → EXPIRED（授权态坏，重试无益）；其余非 200 → 兜底码。
+ *  3. **流注册表**（host-owned——createJobRegistry 同形先例）：按
+ *     (pluginId, name) 分键、同插件同名后写胜出（注册动词换装正道——
+ *     channels 后写胜出同律，零新撞名码）、跨插件结构性不撞（分域）。
+ *     invoke = 宿主回调窗包裹（enterHostCallback 开 → 插件 handler →
+ *     finally 合窗——窗内 ctx.secrets.set 可达，c-3 受理窗机制的消费位）。
+ *
+ * 受理全景（03 §10.9 写入面复合案 oauth 案）：用户人面 `/credentials oauth
+ * <pluginId> [<name>]` 发起 → 宿主解析流 → 开窗回调插件 handler（io 携
+ * runDeviceCode 舞步 + present 呈现面）→ 插件窗内 `ctx.secrets.set` 写
+ * 自域（token 经 io 返回值只在内存过手——宿主不落 token，永不持值面）。
+ *
+ * 回调受理位（redirect URI 形）挂账 U5 路由受限开放后定形——本批只钉
+ * 挂点归属（sdk.register-route 门制复用），不落形。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 注册表工厂（纯内存——零 IO，装载代内生命周期） */
+export function createOAuthFlowRegistry() {
+    // 双层分键：外层 pluginId（跨插件结构性不撞）→ 内层流名（后写胜出）
+    const flows = new Map();
+    return {
+        register(pluginId, spec, openWriteWindow) {
+            let byName = flows.get(pluginId);
+            if (byName === undefined) {
+                byName = new Map();
+                flows.set(pluginId, byName);
+            }
+            byName.set(spec.def.name, {
+                pluginId,
+                def: spec.def,
+                // 宿主回调窗包裹：开窗 → handler → finally 合窗（异常路径同样收口——
+                // c-3 窗计数幂等恢复律；窗内该插件 ctx.secrets.set 可达）
+                invoke: async (io) => {
+                    const exit = openWriteWindow();
+                    try {
+                        await spec.handler(io);
+                    }
+                    finally {
+                        exit();
+                    }
+                },
+            });
+        },
+        get(pluginId, name) {
+            return flows.get(pluginId)?.get(name);
+        },
+        flowsOf(pluginId) {
+            return [...(flows.get(pluginId)?.values() ?? [])];
+        },
+        list() {
+            return [...flows.values()].flatMap((byName) => [...byName.values()]);
+        },
+        unregisterForPlugin(pluginId) {
+            return flows.delete(pluginId);
+        },
+    };
+}
+/**
+ * 人面流解析（`/credentials oauth <pluginId> [<name>]` 的解析腿）：
+ * name 给定 = 精确解析；缺省 = 该插件唯一流自动选中（0/多流各成指路文案）。
+ * 返回流或人读 message（不抛——命令面是用户面，文案单源在本函数）。
+ */
+export function resolveOAuthFlow(registry, pluginId, name) {
+    const listFlows = (rows) => rows.length === 0
+        ? `（无——该插件未注册任何 oauth 流；装载期 ctx.secrets.registerOAuthFlow 注册）`
+        : rows.map((f) => `plugin:${f.pluginId}/${f.def.name}`).join('、');
+    if (name !== undefined) {
+        const flow = registry.get(pluginId, name);
+        if (flow === undefined) {
+            return {
+                flow: undefined,
+                message: `oauth 流 ${name} 不在插件 ${pluginId} 名下（在册流：${listFlows(registry.flowsOf(pluginId))}）。`,
+            };
+        }
+        return { flow };
+    }
+    const flows = registry.flowsOf(pluginId);
+    if (flows.length === 0) {
+        return { flow: undefined, message: `插件 ${pluginId} 未注册任何 oauth 流。` };
+    }
+    if (flows.length > 1) {
+        return { flow: undefined, message: `插件 ${pluginId} 在册多流，须指名其一：${listFlows(flows)}。` };
+    }
+    return { flow: flows[0] };
+}
+/** form 编码单源（URLSearchParams——百分号转义与空格 %20 形由标准库保证） */
+function formUrlEncode(fields) {
+    return new URLSearchParams(fields).toString();
+}
+/** JSON 安全解析（非 JSON → null——调用面折 FLOW_FAILED 兜底码） */
+function safeJsonParse(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 端点载荷字符串键提取（坏形/缺席 → undefined——调用面判形折错） */
+function strField(parsed, key) {
+    return parsed !== null && typeof parsed[key] === 'string' ? parsed[key] : undefined;
+}
+/** 端点载荷数值键提取（同上——expires_in/interval 等） */
+function numField(parsed, key) {
+    return parsed !== null && typeof parsed[key] === 'number' ? parsed[key] : undefined;
+}
+/**
+ * device-code 流编舞（纯舞步——存储/窗/注册表全不在场，消费位 =
+ * 人面动词的 io.runDeviceCode 实现）。
+ */
+export async function runDeviceCodeFlow(def, io) {
+    // 1. 发起设备授权（POST form：client_id + scope——scope 空数组/缺省不带）
+    let device;
+    try {
+        const body = formUrlEncode({
+            client_id: def.clientId,
+            ...(def.scopes !== undefined && def.scopes.length > 0 ? { scope: def.scopes.join(' ') } : {}),
+        });
+        const res = await io.fetchFn(def.deviceAuthUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `设备授权端点非 200（${res.status}）：${text.slice(0, 200)}`);
+        }
+        const parsed = safeJsonParse(text);
+        const deviceCode = strField(parsed, 'device_code');
+        const userCode = strField(parsed, 'user_code');
+        const verificationUri = strField(parsed, 'verification_uri');
+        const expiresIn = numField(parsed, 'expires_in');
+        if (deviceCode === undefined ||
+            userCode === undefined ||
+            verificationUri === undefined ||
+            expiresIn === undefined) {
+            throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `设备授权端点载荷坏形（device_code/user_code/verification_uri/expires_in 四键须齐——现得 ${text.slice(0, 200)}）`);
+        }
+        device = {
+            deviceCode,
+            userCode,
+            verificationUri,
+            expiresIn,
+            interval: numField(parsed, 'interval'),
+        };
+    }
+    catch (err) {
+        if (err instanceof BaseError)
+            throw err;
+        // 传输面错（网络拒/丢包等）——兜底码包装
+        throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `设备授权端点传输失败：${errText(err)}`);
+    }
+    // 2. present 用户（呈现面由宿主注入——TUI notify 直达）
+    io.present([
+        `oauth 授权流「${def.name}」已发起——请在浏览器完成授权：`,
+        `  打开：${device.verificationUri}`,
+        `  输入代码：${device.userCode}`,
+        `  （${Math.ceil(device.expiresIn / 60)} 分钟内有效）`,
+    ].join('\n'));
+    // 3. 轮询 token 端点（authorization_pending 续轮；slow_down 提 interval+5s）
+    const deadline = io.now() + device.expiresIn * 1000;
+    let intervalMs = (device.interval ?? 5) * 1000; // RFC 缺省 5s
+    for (;;) {
+        if (io.now() >= deadline) {
+            throw new BaseError('CREDENTIALS_OAUTH_EXPIRED', '设备码轮询窗已过期（expires_in 到限）——请重新发起 /credentials oauth。');
+        }
+        const res = await io.fetchFn(def.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: formUrlEncode({
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: device.deviceCode,
+                client_id: def.clientId,
+            }),
+        });
+        const text = await res.text();
+        const parsed = safeJsonParse(text);
+        if (res.ok) {
+            const accessToken = strField(parsed, 'access_token');
+            if (accessToken === undefined) {
+                throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `token 端点 200 但缺 access_token（${text.slice(0, 200)}）`);
+            }
+            const refreshToken = strField(parsed, 'refresh_token');
+            const expiresIn = numField(parsed, 'expires_in');
+            return {
+                accessToken,
+                ...(refreshToken !== undefined ? { refreshToken } : {}),
+                ...(expiresIn !== undefined ? { expiresAt: io.now() + expiresIn * 1000 } : {}),
+            };
+        }
+        // RFC 8628 §3.5 错误分流
+        const error = strField(parsed, 'error');
+        if (error === 'authorization_pending') {
+            // 授权未完成——续轮
+        }
+        else if (error === 'slow_down') {
+            intervalMs += 5000; // 提速降频（RFC：至少 +5s）
+        }
+        else if (error === 'access_denied') {
+            throw new BaseError('CREDENTIALS_OAUTH_DENIED', '用户在授权页拒绝了本次授权（access_denied）。');
+        }
+        else if (error === 'expired_token') {
+            throw new BaseError('CREDENTIALS_OAUTH_EXPIRED', '设备码已过期（expired_token）——请重新发起 /credentials oauth。');
+        }
+        else {
+            throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `token 端点非预期应答（${res.status}${error === undefined ? '' : ` error=${error}`}）：${text.slice(0, 200)}`);
+        }
+        await io.sleep(intervalMs);
+    }
+}
+/**
+ * refresh 换新（grant_type=refresh_token——刷新链巡检腿消费）。
+ * invalid_grant → EXPIRED（refresh 凭据失效/被撤销——授权态坏，重试无益，
+ * 唯一出路 = 重新发起授权流）；其余非 200 → 兜底码（传输/端点抖动，重试可期）。
+ */
+export async function refreshOAuthToken(def, refreshToken, io) {
+    let res;
+    try {
+        res = await io.fetchFn(def.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: formUrlEncode({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: def.clientId }),
+        });
+    }
+    catch (err) {
+        throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `token 端点传输失败：${errText(err)}`);
+    }
+    const text = await res.text();
+    const parsed = safeJsonParse(text);
+    if (res.ok) {
+        const accessToken = strField(parsed, 'access_token');
+        if (accessToken === undefined) {
+            throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `refresh 应答 200 但缺 access_token（${text.slice(0, 200)}）`);
+        }
+        // RFC 6749 §6：新 refresh_token 可选——不下发即复用旧值（链不动刷新行）
+        const refreshToken = strField(parsed, 'refresh_token');
+        const expiresIn = numField(parsed, 'expires_in');
+        return {
+            accessToken,
+            ...(refreshToken !== undefined ? { refreshToken } : {}),
+            ...(expiresIn !== undefined ? { expiresAt: io.now() + expiresIn * 1000 } : {}),
+        };
+    }
+    const error = strField(parsed, 'error');
+    if (error === 'invalid_grant') {
+        throw new BaseError('CREDENTIALS_OAUTH_EXPIRED', `refresh 凭据失效（invalid_grant——被撤销或过期）——重新发起授权流 /credentials oauth ${def.name}。`);
+    }
+    throw new BaseError('CREDENTIALS_OAUTH_FLOW_FAILED', `refresh 应答非预期（${res.status}${error === undefined ? '' : ` error=${error}`}）：${text.slice(0, 200)}`);
+}
+/** 非 BaseError 错误折文案（兜底包装位共用——不出对象字面量防泄漏） */
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}