@bolloon/bolloon-agent 0.4.27 → 0.4.28

package/dist/agents/execution-supervisor.js

@@ -308,6 +308,27 @@ export class ExecutionSupervisor {
             this.emit({ kind: 'retry_woke', goalId: goal.goalId, message: `到点唤醒, 第 ${(goal.continuation?.attempts || 0) + 1} 次自动继续` });
             this.log(`[supervisor] goal=${goal.goalId} retry_wait 到点 → 唤醒并清 wakeAt`);
         }
+        // ★ 2026-09-18 (M2 收口): `bolloon task` 建的目标走**同一个恢复决策函数**
+        //   (`decideTaskRecovery`) —— CLI `task --resume` 与 Supervisor 不再各判一次。
+        //   决策说"不能动钱/已经执行过"就跳过 (不重复付款、不重复执行非幂等操作)。
+        if (goal.createdBy === 'cli:task' && process.env.BOLLOON_SUPERVISOR_TASK_RESUME !== '0') {
+            try {
+                const { decideTaskRecovery, resumeTask } = await import('./task/task-runner.js');
+                const decision = await decideTaskRecovery({ goalId: goal.goalId });
+                const actionable = ['retry_payment', 'deliver', 'verify'].includes(decision.action);
+                if (!actionable) {
+                    report.skipped.push({ goalId: goal.goalId, reason: `任务恢复决策=${decision.action} (${decision.reason}) → 本周期不动` });
+                    return { goalId: goal.goalId, status: 'task_no_action' };
+                }
+                const res = await resumeTask({ goalId: goal.goalId });
+                this.log(`[supervisor] task 目标接回: goal=${goal.goalId} decision=${decision.action} → 状态 ${res.card.status}`);
+                this.emit({ kind: res.ok ? 'goal_done' : 'needs_human', goalId: goal.goalId, message: `任务接回: ${decision.action} → ${res.card.status}` });
+                return { goalId: goal.goalId, runId: res.runId, status: res.card.status, error: res.ok ? undefined : res.reason };
+            }
+            catch (err) {
+                return { goalId: goal.goalId, status: 'task_resume_failed', error: String(err?.message || err).slice(0, 160) };
+            }
+        }
         const prevRunId = goal.currentRunId;
         const prevRun = prevRunId ? await readRun(prevRunId) : null;
         const plan = prevRunId ? await buildContinuationPlan(prevRunId).catch(() => null) : null;

package/dist/agents/task/local-seller.js

@@ -0,0 +1,149 @@
+/**
+ * local-seller.ts — M1 的"卖方" (本地 Registry 节点)
+ *
+ * M1 只做**本地 Registry**: 卖方就是你自己本机的报价端点。
+ * 这里**不重新实现协议** —— 直接把项目真实的卖方路由
+ * (`src/web/routes-x402-info.ts: registerX402InfoRoutes`) 挂到一个极小的
+ * express 风格适配器上, 用真 HTTP 跑真 402 → 付款校验 → 签名信封。
+ *
+ * 注意: 卖方路由内部用 `os.homedir()` 找 `~/.bolloon/{identity.json, x402-info/}`,
+ *       所以调用方若做隔离测试, 需要在启动前设好 `process.env.HOME`。
+ */
+import * as http from 'http';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+function matchPath(pattern, actual) {
+    const p = pattern.split('/').filter(Boolean);
+    const a = actual.split('/').filter(Boolean);
+    if (pattern.endsWith('/') && p.length !== a.length)
+        return { hit: false, params: {} };
+    if (p.length !== a.length)
+        return { hit: false, params: {} };
+    const params = {};
+    for (let i = 0; i < p.length; i++) {
+        if (p[i].startsWith(':'))
+            params[p[i].slice(1)] = decodeURIComponent(a[i]);
+        else if (p[i] !== a[i])
+            return { hit: false, params: {} };
+    }
+    return { hit: true, params };
+}
+function makeRes() {
+    let settle;
+    const done = new Promise((r) => { settle = r; });
+    const headers = {};
+    const res = {
+        _status: 200,
+        status(n) { res._status = n; return res; },
+        set(k, v) { headers[k] = String(v); return res; },
+        json(obj) {
+            headers['content-type'] = 'application/json';
+            settle({ status: res._status, headers, body: JSON.stringify(obj ?? null) });
+            return res;
+        },
+        send(text) {
+            settle({ status: res._status, headers, body: String(text ?? '') });
+            return res;
+        },
+    };
+    return { res, done };
+}
+/** 极小的 express 风格 app (只实现卖方路由用到的 get/post/delete + res.json/status/set) */
+export function createMiniApp() {
+    const routes = [];
+    const add = (method) => (p, h) => { routes.push({ method, path: p, handler: h }); };
+    const app = { get: add('GET'), post: add('POST'), delete: add('DELETE') };
+    const dispatch = async (method, url, headers, body) => {
+        const u = new URL(url, 'http://127.0.0.1');
+        for (const r of routes) {
+            if (r.method !== method)
+                continue;
+            const m = matchPath(r.path, u.pathname);
+            if (!m.hit)
+                continue;
+            const { res, done } = makeRes();
+            let parsed = undefined;
+            if (body) {
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    parsed = undefined;
+                }
+            }
+            const req = {
+                method,
+                url,
+                headers,
+                params: m.params,
+                query: Object.fromEntries(u.searchParams.entries()),
+                body: parsed,
+                protocol: 'http',
+            };
+            try {
+                await r.handler(req, res);
+            }
+            catch (e) {
+                return { status: 500, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ error: String(e?.message || e) }) };
+            }
+            return await done;
+        }
+        return null;
+    };
+    return { app, dispatch };
+}
+/** 卖方的 DIAP 身份 (签发信封用) — 缺失就生成一个本机身份, 不静默跳过 */
+export async function ensureSellerIdentity(home = os.homedir()) {
+    const dir = path.join(home, '.bolloon');
+    const file = path.join(dir, 'identity.json');
+    if (fs.existsSync(file)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+            return { created: false, did: raw?.did };
+        }
+        catch {
+            return { created: false };
+        }
+    }
+    try {
+        const { KeyManager } = await import('@diap/sdk');
+        const kp = KeyManager.generate();
+        fs.mkdirSync(dir, { recursive: true });
+        await KeyManager.saveToFile(kp, file);
+        return { created: true, did: kp?.did };
+    }
+    catch (e) {
+        return { created: false };
+    }
+}
+/** 启动本地卖方节点: 真 HTTP + 项目真实卖方路由 */
+export async function startLocalSeller(opts = {}) {
+    const { registerX402InfoRoutes } = await import('../../web/routes-x402-info.js');
+    const { app, dispatch } = createMiniApp();
+    registerX402InfoRoutes(app);
+    const { listInfo } = await import('../x402/paid-info-store.js');
+    const server = http.createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', async () => {
+            const body = Buffer.concat(chunks).toString('utf8');
+            const out = await dispatch(req.method || 'GET', req.url || '/', req.headers, body);
+            if (!out) {
+                res.writeHead(404, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'not found' }));
+                return;
+            }
+            res.writeHead(out.status, out.headers);
+            res.end(out.body);
+        });
+    });
+    await new Promise((resolve) => server.listen(opts.port ?? 0, '127.0.0.1', () => resolve()));
+    const port = server.address()?.port;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        port,
+        itemCount: async () => (await listInfo()).length,
+        close: async () => { await new Promise((resolve) => server.close(() => resolve())); },
+    };
+}

package/dist/agents/task/report-card.js

@@ -0,0 +1,146 @@
+/**
+ * report-card.ts — M1 薄层 ③: 报告卡
+ *
+ * M1 **唯一面向人的主出口**。用户只看到这里的东西:
+ *   任务 / 结论 / 本次使用(Skill·版本·花费·来源) / 三项校验 / 状态(4 态) / 证据指针 / 卡在哪。
+ *
+ * 两条硬门 (leo 定, 任一不满足 → M1 失败):
+ *   买到 Skill 但没有执行        → 卡片必须"需要你处理", 不许变绿
+ *   执行成功但没有报告/证据      → 卡片必须"需要你处理", 不许变绿
+ *
+ * 内部 10 态生命周期 / 8 态结算事实**只在这里被映射成 4 个人类状态**, 不外泄术语。
+ */
+/** 内部生命周期 → 人类 4 态 (术语不外泄) */
+export function humanStatusFrom(opts) {
+    if (opts.verdict === 'blocked')
+        return '需要你处理';
+    const lc = String(opts.lifecycle || '');
+    switch (lc) {
+        case 'verified':
+            return '已完成';
+        case 'settled':
+        case 'delivered':
+            return '正在执行';
+        case 'discovered':
+        case 'quoted':
+        case 'payment_required':
+        case 'paying':
+            return '正在获取能力';
+        case 'policy_denied':
+        case 'delivery_failed':
+        case 'verification_failed':
+        case 'disputed':
+        case 'failed':
+            return '需要你处理';
+        default:
+            break;
+    }
+    switch (opts.stage) {
+        case 'prepare':
+            return '准备中';
+        case 'acquire':
+            return '正在获取能力';
+        case 'execute':
+            return '正在执行';
+        default:
+            return '已完成';
+    }
+}
+/**
+ * 组装报告卡。两条硬门在这里落地 (不是靠调用方记得检查):
+ * 只要"付了没执行"或"执行了没证据", 一律 `需要你处理` + 结论降级为"证据不足"。
+ */
+export function buildReportCard(input) {
+    const checks = {
+        outputContract: input.outputContract ?? '未执行',
+        resourceVerified: input.resourceVerified ?? '未执行',
+        taskEvidence: input.evidenceComplete ? '完整' : '不完整',
+    };
+    let status = humanStatusFrom({ stage: input.stage, lifecycle: input.lifecycle, verdict: input.blocker ? 'blocked' : 'ok' });
+    let hardGate;
+    let conclusion = input.conclusion ?? (status === '已完成' ? '证据不足' : '证据不足');
+    let blocker = input.blocker;
+    if (input.paid && !input.executed) {
+        hardGate = 'bought_not_executed';
+        status = '需要你处理';
+        conclusion = '证据不足';
+        blocker = blocker || '买到了 Skill 但没有执行 —— 这一次不算完成任务 (M1 硬门)';
+    }
+    else if (input.executed && !input.evidenceComplete) {
+        hardGate = 'executed_without_evidence';
+        status = '需要你处理';
+        conclusion = '证据不足';
+        blocker = blocker || '执行了但没有留下完整证据 —— 这一次不算完成任务 (M1 硬门)';
+    }
+    else if (input.outputContract === '未通过') {
+        status = '需要你处理';
+        conclusion = '证据不足';
+        blocker = blocker || '输出不符合资源契约 —— 不计成功 (M1 硬门)';
+    }
+    if (status === '已完成' && (checks.taskEvidence !== '完整' || checks.resourceVerified !== '通过' || checks.outputContract !== '通过')) {
+        // 三项校验没全过就不许显示"已完成" (防假绿)
+        status = '需要你处理';
+        hardGate = hardGate || 'executed_without_evidence';
+        conclusion = '证据不足';
+        blocker = blocker || `三项校验未全过 (输出契约=${checks.outputContract} · 资源验证=${checks.resourceVerified} · 证据=${checks.taskEvidence})`;
+    }
+    return {
+        task: input.task,
+        conclusion,
+        conclusionDetail: input.conclusionDetail,
+        skill: input.skill,
+        cost: input.cost,
+        payment: input.payment,
+        sources: input.sources,
+        checks,
+        status,
+        executed: input.executed,
+        paid: input.paid,
+        durationMs: input.durationMs,
+        evidenceRef: input.evidenceRef,
+        blocker,
+        hardGate,
+        budgetLines: input.budgetLines,
+    };
+}
+/** CLI 文本渲染 —— M1 的唯一主出口形状 */
+export function renderReportCard(card) {
+    const L = [];
+    L.push(`任务: ${card.task}`);
+    L.push('');
+    L.push(`结论: ${card.conclusion}${card.conclusionDetail ? ` (${card.conclusionDetail})` : ''}`);
+    L.push('');
+    L.push('本次使用:');
+    if (card.skill)
+        L.push(`- Skill: ${card.skill.name}${card.skill.version ? ` @ ${card.skill.version}` : ''}`);
+    if (card.cost)
+        L.push(`- 花费: ${card.cost.amount} ${card.cost.currency} (${card.cost.network})`);
+    if (card.payment) {
+        const modeZh = card.payment.mode === 'local-dev' ? '本机联调 (local-dev)' : card.payment.mode === 'facilitator' ? 'facilitator' : card.payment.mode;
+        L.push(`- 支付方式: ${modeZh}`);
+        L.push(`- 链上已验证: ${card.payment.chainSettled ? '是' : '否'}${card.payment.chainSettled ? '' : ' (本机联调不冒充链上结算)'}`);
+    }
+    if (card.sources)
+        L.push(`- 来源: ${card.sources.length} 个${card.sources.length ? ` (${card.sources.slice(0, 3).join(', ')}${card.sources.length > 3 ? ', …' : ''})` : ''}`);
+    L.push(`- 输出契约: ${card.checks.outputContract}`);
+    L.push(`- 资源验证: ${card.checks.resourceVerified}`);
+    L.push(`- 任务证据: ${card.checks.taskEvidence}`);
+    if (typeof card.durationMs === 'number')
+        L.push(`- 耗时: ${(card.durationMs / 1000).toFixed(1)} 秒`);
+    L.push(`- 状态: ${card.status}`);
+    if (card.blocker) {
+        L.push('');
+        L.push(`卡在哪: ${card.blocker}`);
+    }
+    if (card.budgetLines && card.budgetLines.length) {
+        L.push('');
+        L.push('预算:');
+        for (const b of card.budgetLines)
+            L.push(`- ${b}`);
+    }
+    L.push('');
+    const ref = card.evidenceRef;
+    const parts = [ref.goalId ? `Goal ${ref.goalId}` : null, ref.runId ? `Run ${ref.runId}` : null, ref.transactionId ? `交易 ${ref.transactionId}` : null].filter(Boolean);
+    L.push(parts.length ? `查看完整证据: ${parts.join(' · ')}` : '查看完整证据: (无)');
+    return L.join('\n');
+}

package/dist/agents/task/resource-advisor.js

@@ -0,0 +1,182 @@
+/**
+ * resource-advisor.ts — M1 薄层 ②: 资源顾问
+ *
+ * 只回答三个问题:
+ *   ① 当前任务是否缺外部能力?
+ *   ② 本地 Registry 里哪个可执行 Skill 满足契约?
+ *   ③ 为什么选它?
+ *
+ * M1 明确**不做**: 语义搜索 / 向量检索 / P2P 发现 / 竞价 / 推荐系统。
+ * 这里只有: 关键词确定性匹配 + 契约完整性检查 + 价格来源(报价)检查, 同分用名字排序 (可复现)。
+ *
+ * "本地 Registry" = 已装技能目录 (`defaultSkillPaths` + `~/.bolloon/skills`)
+ *                × 本机 x402 报价 (`listInfo`), 两者按约定关联 (见 linkListing)。
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { defaultSkillPaths, loadSkillsDir } from '../skill-loader.js';
+import { listInfo } from '../x402/paid-info-store.js';
+import { parseResourceContract } from '../x402/resource-contract.js';
+/** 中文按 bigram、英文/数字按词切; 去停用词。确定性, 无随机。 */
+export function tokenizeTask(task) {
+    const text = String(task || '').toLowerCase();
+    const out = [];
+    for (const m of text.matchAll(/[a-z0-9][a-z0-9._-]+/g))
+        out.push(m[0]);
+    const cjk = text.replace(/[^\u4e00-\u9fff]+/g, ' ');
+    for (const seg of cjk.split(/\s+/)) {
+        if (!seg)
+            continue;
+        if (seg.length <= 2) {
+            out.push(seg);
+            continue;
+        }
+        for (let i = 0; i + 2 <= seg.length; i++)
+            out.push(seg.slice(i, i + 2));
+    }
+    const stop = new Set(['这个', '那个', '一个', '是否', '请问', '帮我', 'the', 'and', 'for', 'with', 'task']);
+    return Array.from(new Set(out.filter((t) => t.length >= 2 && !stop.has(t))));
+}
+/** 关键词命中打分: 只在名字 / 描述 / triggers / capability 文本里找, 命中即记 why。 */
+export function scoreSkill(args) {
+    const fields = [
+        ['name', args.name || ''],
+        ['description', args.description || ''],
+        ['triggers', (args.triggers || []).join(' ')],
+        ['capability', args.capability || ''],
+        ['guarantees', (args.guarantees || []).join(' ')],
+    ];
+    const lowered = fields.map(([k, v]) => [k, v.toLowerCase()]);
+    const why = [];
+    let score = 0;
+    for (const tok of args.tokens) {
+        for (const [field, text] of lowered) {
+            if (!text)
+                continue;
+            if (text.includes(tok)) {
+                const w = field === 'name' ? 3 : field === 'capability' ? 2 : 1;
+                score += w;
+                why.push(`命中 ${field}: "${tok}" (+${w})`);
+                break;
+            }
+        }
+    }
+    return { score, why };
+}
+/**
+ * 报价 ↔ 技能 的关联约定 (M1 确定性规则, 不做模糊匹配):
+ *   ① item.id === skill 名  ② item.source.note 含 `skill=<name>`  ③ item.title 含技能名
+ */
+export function linkListing(skillName, items) {
+    const lower = skillName.toLowerCase();
+    const hit = items.find((i) => {
+        if (String(i.id).toLowerCase() === lower)
+            return true;
+        const note = String(i.source?.note || '').toLowerCase();
+        if (note.includes(`skill=${lower}`))
+            return true;
+        return String(i.title || '').toLowerCase().includes(lower);
+    });
+    if (!hit)
+        return undefined;
+    return {
+        itemId: hit.id,
+        title: String(hit.title || hit.id),
+        amount: String(hit.price?.amount ?? '0'),
+        currency: String(hit.price?.currency ?? 'USDC'),
+        network: String(hit.price?.network ?? 'base-sepolia'),
+        payTo: String(hit.price?.payTo ?? ''),
+        skillName: String(hit.source?.note || '').includes('skill=') ? skillName : undefined,
+    };
+}
+/**
+ * 顾问主函数: 扫本地 Registry → 过滤"有契约且可执行"的候选 → 确定性打分排序。
+ * 不猜: 一个候选都没有 → needed:false 并说明原因。
+ */
+export async function adviseResource(opts) {
+    const home = opts.home ?? os.homedir();
+    const cwd = opts.cwd ?? process.cwd();
+    const notes = [];
+    const paths = (opts.skillPaths ?? [...defaultSkillPaths(home, cwd), path.join(home, '.bolloon', 'skills')]);
+    const merged = [];
+    for (const p of paths)
+        if (!merged.includes(p))
+            merged.push(p);
+    const skillDirs = [];
+    for (const p of merged) {
+        let metas = [];
+        try {
+            metas = await loadSkillsDir(p);
+        }
+        catch (e) {
+            notes.push(`技能目录不可读 (跳过): ${p} — ${String(e?.message || e).slice(0, 80)}`);
+            continue;
+        }
+        for (const meta of metas) {
+            const fm = (meta.frontmatter || {});
+            const parsed = parseResourceContract(fm, { skillName: String(meta.name), skillVersion: String(fm.version || '') });
+            if (!parsed.ok || !parsed.contract)
+                continue; // 非法契约直接不算候选
+            const c = parsed.contract;
+            if (!c.execution?.entrypoint)
+                continue; // 不可执行 → 不是 M1 要的资源
+            if (!c.inputSchema || !c.outputSchema)
+                continue; // 无输入/输出契约 → 不买
+            skillDirs.push({
+                name: String(meta.name),
+                version: String(fm.version || (c.version ?? '')),
+                dir: path.dirname(String(meta.sourcePath)),
+                description: String(meta.description || ''),
+                triggers: (meta.triggers || []),
+                contract: parsed.contract,
+            });
+        }
+    }
+    if (skillDirs.length === 0) {
+        return { needed: false, reason: `本地 Registry 里没有"可执行且契约完整"的 Skill (已扫 ${merged.length} 个目录)`, candidates: [], notes };
+    }
+    const items = await listInfo(home);
+    const tokens = tokenizeTask(opts.task);
+    const candidates = skillDirs.map((s) => {
+        const c = s.contract;
+        const scored = scoreSkill({
+            tokens,
+            name: s.name,
+            description: s.description,
+            triggers: s.triggers,
+            capability: c.capability,
+            guarantees: c.guarantees,
+        });
+        return {
+            name: s.name,
+            version: s.version,
+            dir: s.dir,
+            contract: s.contract,
+            score: scored.score,
+            why: scored.why,
+            listing: linkListing(s.name, items),
+        };
+    });
+    // 确定性排序: 分数降序 → 名字升序
+    candidates.sort((a, b) => (b.score - a.score) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const minScore = opts.minScore ?? 1;
+    const top = candidates[0];
+    if (!top || top.score < minScore) {
+        return {
+            needed: false,
+            reason: `任务关键词与本地可执行 Skill 都不匹配 (最高分 ${top?.score ?? 0} < ${minScore}) — 不买不该买的东西`,
+            candidates,
+            notes,
+        };
+    }
+    if (!top.listing) {
+        notes.push(`候选 Skill "${top.name}" 没有本机报价 (listInfo 里没有对应 item) → M1 买不到, 会如实告诉你`);
+    }
+    return {
+        needed: true,
+        reason: `本地 Registry 命中 "${top.name}" (分数 ${top.score}: ${top.why.slice(0, 3).join(' / ') || '名字匹配'})`,
+        candidates,
+        chosen: top,
+        notes,
+    };
+}

package/dist/agents/task/task-budget.js

@@ -0,0 +1,103 @@
+/**
+ * task-budget.ts — M1 预算闸 (leo 2026-09-18 冻结规则 ③)
+ *
+ *   单任务 0.05 USDC / 单次购买 0.02 USDC / 单日测试 0.10 USDC, **所有层取最小值**。
+ *   用户只在开始时给一次; 执行过程中**不许被 Agent 自动扩大** (assertNoExpansion 是那条红线)。
+ *
+ * 与 policy 的关系: `economic-policy.ts` 的 `单笔 $1 / 每日 $10` 是系统级闸门,
+ * 这里是**任务级**的第二道闸, 两层都过才放行 (trade.ts 的 taskBudget 参数即为此闸)。
+ */
+/** M1 硬上限 (leo 定) */
+export const M1_BUDGET_LIMITS = { task: 0.05, perPurchase: 0.02, daily: 0.10 };
+function num(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const n = typeof v === 'number' ? v : Number(String(v));
+    if (!Number.isFinite(n))
+        return undefined;
+    return n;
+}
+/**
+ * 解析任务预算。缺省 → M1 默认值; 给多了 → **取 min 并显式记录被收紧** (不静默改成别的数)。
+ * 非法输入 → ok:false (不猜)。
+ */
+export function resolveTaskBudget(opts = {}) {
+    const lim = opts.limits ?? M1_BUDGET_LIMITS;
+    const reqTask = num(opts.taskBudget);
+    const reqPer = num(opts.perPurchase);
+    const reqDaily = num(opts.daily);
+    for (const [k, v] of [['taskBudget', opts.taskBudget], ['perPurchase', opts.perPurchase], ['daily', opts.daily]]) {
+        if (v !== undefined && v !== null && String(v) !== '' && num(v) === undefined) {
+            return { ok: false, error: `${k} 不是合法数字: ${String(v)}` };
+        }
+        const n = num(v);
+        if (n !== undefined && n <= 0)
+            return { ok: false, error: `${k} 必须为正数: ${String(v)}` };
+    }
+    const taskBudget = Math.min(reqTask ?? lim.task, lim.task);
+    const perPurchase = Math.min(reqPer ?? lim.perPurchase, lim.perPurchase, taskBudget);
+    const daily = Math.min(reqDaily ?? lim.daily, lim.daily);
+    const why = [];
+    why.push(`任务预算 ${taskBudget} USDC (M1 硬上限 ${lim.task}${reqTask !== undefined ? `, 你给的 ${reqTask}` : ''})`);
+    why.push(`单次购买上限 ${perPurchase} USDC (M1 硬上限 ${lim.perPurchase}${reqPer !== undefined ? `, 你给的 ${reqPer}` : ''})`);
+    why.push(`当日预算 ${daily} USDC (M1 硬上限 ${lim.daily}${reqDaily !== undefined ? `, 你给的 ${reqDaily}` : ''})`);
+    const clamped = {
+        task: reqTask !== undefined && reqTask > lim.task,
+        perPurchase: reqPer !== undefined && reqPer > Math.min(lim.perPurchase, taskBudget),
+        daily: reqDaily !== undefined && reqDaily > lim.daily,
+    };
+    if (clamped.task)
+        why.push(`⚠️ 你给的任务预算 ${reqTask} 超过 M1 上限 ${lim.task} → 实际按 ${taskBudget} 执行 (不是 Agent 改的, 是 M1 规则)`);
+    if (clamped.perPurchase)
+        why.push(`⚠️ 你给的购买上限 ${reqPer} 被收紧到 ${perPurchase}`);
+    if (clamped.daily)
+        why.push(`⚠️ 你给的当日预算 ${reqDaily} 被收紧到 ${daily}`);
+    return { ok: true, plan: { taskBudget, perPurchase, daily, requested: { task: reqTask, perPurchase: reqPer, daily: reqDaily }, clamped, why } };
+}
+/** 逐层检查一次购买; 哪一层拦住就说清哪一层 (绝不合并成"预算不足"这种糊话)。 */
+export function checkPurchaseAllowed(opts) {
+    const amount = num(opts.amount);
+    if (amount === undefined)
+        return { allowed: false, layer: undefined, reason: `金额不是合法数字: ${String(opts.amount)}` };
+    const spentInTask = opts.spentInTask ?? 0;
+    const spentToday = opts.spentToday ?? 0;
+    const remainingTask = round6(opts.plan.taskBudget - spentInTask);
+    const remainingDaily = round6(opts.plan.daily - spentToday);
+    if (amount > opts.plan.perPurchase) {
+        const capSource = opts.plan.perPurchase < opts.plan.requested.perPurchase
+            ? `来自任务预算 ${opts.plan.taskBudget}`
+            : opts.plan.clamped.perPurchase ? '被 M1 上限收紧后的值' : '你给的上限';
+        return { allowed: false, layer: 'perPurchase', reason: `单次购买上限 ${opts.plan.perPurchase} USDC (${capSource}); 这次要 ${amount} USDC`, remainingTask, remainingDaily };
+    }
+    if (amount > remainingTask) {
+        return { allowed: false, layer: 'taskBudget', reason: `任务预算只剩 ${remainingTask} USDC; 这次要 ${amount} USDC`, remainingTask, remainingDaily };
+    }
+    if (amount > remainingDaily) {
+        return { allowed: false, layer: 'daily', reason: `今日预算只剩 ${remainingDaily} USDC; 这次要 ${amount} USDC`, remainingTask, remainingDaily };
+    }
+    return { allowed: true, remainingTask, remainingDaily };
+}
+function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+/** 购买前的"价格与预算影响"预览 (M1 验收第 5 项: 付款前必须看得到) */
+export function previewPurchaseImpact(plan, amount, spentToday = 0) {
+    const a = num(amount);
+    if (a === undefined)
+        return [`金额非法: ${String(amount)}`];
+    const pctTask = plan.taskBudget > 0 ? Math.round((a / plan.taskBudget) * 100) : 100;
+    return [
+        `价格 ${a} USDC · 占任务预算 ${pctTask}%`,
+        `购买后: 任务剩余 ${round6(plan.taskBudget - a)} USDC · 今日剩余 ${round6(plan.daily - spentToday - a)} USDC`,
+    ];
+}
+/** 执行中不许扩大预算 (M1 红线: 用户只给一次) */
+export function assertNoExpansion(prev, next) {
+    if (next.taskBudget > prev.taskBudget + 1e-9)
+        return { ok: false, reason: `任务预算被扩大: ${prev.taskBudget} → ${next.taskBudget} (M1 不允许)` };
+    if (next.perPurchase > prev.perPurchase + 1e-9)
+        return { ok: false, reason: `单次上限被扩大: ${prev.perPurchase} → ${next.perPurchase} (M1 不允许)` };
+    if (next.daily > prev.daily + 1e-9)
+        return { ok: false, reason: `当日预算被扩大: ${prev.daily} → ${next.daily} (M1 不允许)` };
+    return { ok: true };
+}