@bolloon/bolloon-agent 0.4.24 → 0.4.25

package/dist/agents/goal-store.js

@@ -0,0 +1,451 @@
+/**
+ * goal-store.ts — GoalStore: **目标事实来源** (2026-09-16 Milestone 2)
+ *
+ * 与既有模型的关系 (leo 2026-09-16: 先明确唯一关系, 不急着删旧模块):
+ *   GoalStore (本文件, `~/.bolloon/goals/<goalId>.json`)  = 目标的**唯一事实来源**
+ *   RunStore  (`~/.bolloon/runs/<runId>.json`)              = 一次执行的**唯一事实来源**
+ *   SessionStore                                            = 对话上下文来源
+ *   Task/Plan                                               = Goal 的执行辅助结构 (不承载目标状态)
+ *   旧模型保留但降级为"入口/草稿": `pi-ecosystem-goals` 的 queue.json (目标队列) 与
+ *   `goal-resume` 的 park/resume (双栖接力) 仍是生产者, 迁移留待后续批次 —— 不删。
+ *
+ * 关键规则 (协议 §「关键规则」):
+ *   - Goal 永远不能因为一次 prompt 结束就自动消失
+ *   - Run 结束 ≠ Goal 完成; 只有 successCriteria 全部满足 (且有证据) 才能 completed
+ *   - 不允许"done 但目标没达成"伪装成功
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+/** 可被 Supervisor 自动唤醒推进的状态 (其余必须等人或等外部事件) */
+export const GOAL_RUNNABLE_STATUSES = ['open', 'active', 'recovering', 'retry_wait', 'stalled'];
+export function goalsDir() {
+    return path.join(os.homedir(), '.bolloon', 'goals');
+}
+function goalPath(goalId) {
+    return path.join(goalsDir(), `${goalId}.json`);
+}
+/** 原子写 (tmp + rename): 读到的永远是完整 JSON */
+async function writeGoal(rec) {
+    await fs.mkdir(goalsDir(), { recursive: true });
+    const p = goalPath(rec.goalId);
+    const tmp = `${p}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(rec, null, 2), 'utf8');
+    await fs.rename(tmp, p);
+}
+/** 同 goal 的进程内串行化 (并发写不覆盖判据/证据) */
+const goalLocks = new Map();
+async function withGoalLock(goalId, fn) {
+    const prev = goalLocks.get(goalId) || Promise.resolve();
+    const mine = prev.catch(() => { }).then(fn);
+    const tail = mine.catch(() => { });
+    goalLocks.set(goalId, tail);
+    try {
+        return await mine;
+    }
+    finally {
+        if (goalLocks.get(goalId) === tail)
+            goalLocks.delete(goalId);
+    }
+}
+export function newGoalId() {
+    return `g-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+export async function createGoal(opts) {
+    const now = new Date().toISOString();
+    const rec = {
+        goalId: newGoalId(),
+        objective: String(opts.objective || '').slice(0, 500),
+        successCriteria: (opts.successCriteria || []).map((c) => String(c).slice(0, 200)).slice(0, 20),
+        constraints: (opts.constraints || []).map((c) => String(c).slice(0, 200)).slice(0, 20),
+        budget: opts.budget,
+        status: 'open',
+        channelId: opts.channelId,
+        agentId: opts.agentId,
+        createdBy: opts.createdBy,
+        createdAt: now,
+        updatedAt: now,
+        runs: [],
+        completedCriteria: [],
+        unresolvedItems: [],
+        evidence: [],
+    };
+    await writeGoal(rec);
+    return rec;
+}
+export async function readGoal(goalId) {
+    if (!goalId)
+        return null;
+    try {
+        return JSON.parse(await fs.readFile(goalPath(goalId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function listGoals(opts = {}) {
+    let files = [];
+    try {
+        files = await fs.readdir(goalsDir());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        const g = await readGoal(f.replace(/\.json$/, ''));
+        if (!g)
+            continue;
+        if (opts.status) {
+            const want = Array.isArray(opts.status) ? opts.status : [opts.status];
+            if (!want.includes(g.status))
+                continue;
+        }
+        out.push(g);
+    }
+    out.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return typeof opts.limit === 'number' ? out.slice(0, opts.limit) : out;
+}
+export async function updateGoal(goalId, patch) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        const next = { ...rec, ...patch, goalId: rec.goalId, updatedAt: new Date().toISOString() };
+        await writeGoal(next);
+        return next;
+    });
+}
+/**
+ * 把一次 Run 挂到 Goal 上 (Run 反查 Goal 的入口)。
+ * 幂等: 同一 runId 重复挂不会产生重复条目。
+ */
+export async function attachRun(goalId, runId, opts = {}) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        if (!rec.runs.includes(runId))
+            rec.runs.push(runId);
+        if (opts.makeCurrent !== false)
+            rec.currentRunId = runId;
+        if (rec.status === 'open')
+            rec.status = 'active';
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 标记某条判据已满足 (+可选证据) */
+export async function markCriterion(goalId, index, satisfied, evidence) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        if (index < 0 || index >= rec.successCriteria.length)
+            return rec;
+        const set = new Set(rec.completedCriteria);
+        if (satisfied)
+            set.add(index);
+        else
+            set.delete(index);
+        rec.completedCriteria = Array.from(set).sort((a, b) => a - b);
+        if (evidence)
+            rec.evidence = [...rec.evidence, String(evidence).slice(0, 300)].slice(-50);
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 记录未解决项 (失败步骤 / 待人工确认) —— 有未解决项就不许判完成 */
+export async function setUnresolved(goalId, items) {
+    return updateGoal(goalId, { unresolvedItems: items.map((i) => String(i).slice(0, 300)).slice(0, 30) });
+}
+export async function addEvidence(goalId, evidence) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        rec.evidence = [...rec.evidence, ...evidence.map((e) => String(e).slice(0, 300))].slice(-50);
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/**
+ * 完成门 (Milestone 4): **确定性**判定, 不看模型怎么说。
+ *   全部必要判据满足 + 有证据 + 无未解决项 → 才允许 completed。
+ *   未声明 successCriteria 的目标**永不**自动完成 (需要人显式确认) —— 否则"模型说完成"就变成了完成。
+ */
+export function evaluateGoalCompletion(goal) {
+    if (!goal.successCriteria.length) {
+        return { complete: false, reason: '未声明 successCriteria: 不允许自动判完成 (需人工确认)', missing: [] };
+    }
+    const missing = goal.successCriteria
+        .map((c, i) => ({ c, i }))
+        .filter(({ i }) => !goal.completedCriteria.includes(i))
+        .map(({ c, i }) => `[${i}] ${c}`);
+    if (missing.length) {
+        return { complete: false, reason: `还有 ${missing.length} 条判据未满足`, missing };
+    }
+    if (!goal.evidence.length) {
+        return { complete: false, reason: '没有证据 (evidence 为空): 不许判完成', missing: [] };
+    }
+    if (goal.unresolvedItems.length) {
+        return { complete: false, reason: `还有 ${goal.unresolvedItems.length} 项未解决`, missing: goal.unresolvedItems };
+    }
+    return { complete: true, reason: '全部判据满足 + 有证据 + 无未解决项', missing: [] };
+}
+/** 通过完成门就落 completed, 否则保持原状态并回传原因 (不静默) */
+export async function completeGoalIfEligible(goalId) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { ok: false, reason: `goal 不存在: ${goalId}`, goal: null };
+    const verdict = evaluateGoalCompletion(goal);
+    if (!verdict.complete)
+        return { ok: false, reason: verdict.reason, goal, missing: verdict.missing };
+    const next = await updateGoal(goalId, {
+        status: 'completed',
+        resolution: { reason: verdict.reason, at: new Date().toISOString() },
+    });
+    return { ok: true, reason: verdict.reason, goal: next };
+}
+/**
+ * 找一个"还在进行中"的目标 (供 prompt 入口判断"继续还是新建")。
+ * 只看 open/active, 且限定 channel+agent (不同智能体的目标不混)。
+ */
+export async function findActiveGoal(opts) {
+    const all = await listGoals({ status: ['open', 'active'] });
+    for (const g of all) {
+        if (opts.channelId && g.channelId && g.channelId !== opts.channelId)
+            continue;
+        if (opts.agentId && g.agentId && g.agentId !== opts.agentId)
+            continue;
+        return g;
+    }
+    return null;
+}
+/** 给 CLI/Web 的一行摘要 */
+export function formatGoalLine(g) {
+    const done = `${g.completedCriteria.length}/${g.successCriteria.length || 0}`;
+    return `${g.goalId}  [${g.status.padEnd(9)}] 判据 ${done.padStart(4)}  run=${(g.currentRunId || '-').slice(0, 12)}  ${g.objective.slice(0, 44)}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 2026-09-16 (M2-A): continuation —— "下一次何时、因为什么被唤醒"
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 写调度元数据 (合并式)。
+ * 这是 2-A 的落地: Goal 永远能回答"下一步是什么/还需不需要自动继续/在等什么"。
+ */
+export async function setContinuation(goalId, patch) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        rec.continuation = {
+            ...(rec.continuation || { autoContinue: true }),
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 幂等地累加自动继续尝试次数 (退避用) */
+export async function bumpContinuationAttempts(goalId) {
+    const rec = await readGoal(goalId);
+    const n = (rec?.continuation?.attempts || 0) + 1;
+    await setContinuation(goalId, { attempts: n });
+    return n;
+}
+export async function resetContinuationAttempts(goalId) {
+    await setContinuation(goalId, { attempts: 0 });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 2026-09-16 (M2-B): 执行权租约 (跨进程排他) —— 真值在 <goalId>.lease 文件, 用 O_EXCL 独占创建
+// ─────────────────────────────────────────────────────────────────────────────
+function leasePath(goalId) {
+    return path.join(goalsDir(), `${goalId}.lease`);
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
+}
+export async function readLease(goalId) {
+    try {
+        return JSON.parse(await fs.readFile(leasePath(goalId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 抢执行权 (原子: 独占创建 lease 文件)。
+ * 可回收条件 (任一):
+ *   ① leaseUntil 已过期 (TTL)
+ *   ② 持有者进程已不在 (更早回收 —— 持有者可证明已死, 不必等满 TTL)
+ * 不可回收: 持有者活着且未过期 → 明确返回 ok:false + holder (调用方据此"让路", 不是报错)
+ */
+export async function claimGoal(goalId, opts = { owner: 'unknown' }) {
+    const ttl = opts.ttlMs ?? 90_000;
+    const now = opts.now ?? Date.now();
+    await fs.mkdir(goalsDir(), { recursive: true });
+    const p = leasePath(goalId);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const claimedAt = new Date(now).toISOString();
+        const lease = {
+            owner: opts.owner,
+            leaseId: `${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`,
+            claimedAt,
+            lastHeartbeat: claimedAt,
+            leaseUntil: new Date(now + ttl).toISOString(),
+            pid: process.pid,
+            host: os.hostname(),
+        };
+        try {
+            const fh = await fs.open(p, 'wx');
+            await fh.writeFile(JSON.stringify(lease, null, 2), 'utf8');
+            await fh.close();
+            // 镜像到 Goal 文件 (只为可读; 真值在 lease 文件)
+            await updateGoal(goalId, { lease: { owner: lease.owner, leaseId: lease.leaseId, claimedAt, lastHeartbeat: claimedAt, leaseUntil: lease.leaseUntil } });
+            return { ok: true, lease };
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST') {
+                return { ok: false, reason: `lease 文件不可创建: ${String(err?.message || err).slice(0, 120)}` };
+            }
+            const holder = await readLease(goalId);
+            if (!holder) {
+                await fs.rm(p, { force: true });
+                continue;
+            } // 坏文件 → 当陈旧回收
+            const expired = Date.parse(String(holder.leaseUntil || '')) <= now;
+            const dead = holder.pid ? !pidAlive(Number(holder.pid)) : false;
+            if (expired || dead) {
+                await fs.rm(p, { force: true });
+                continue;
+            }
+            return { ok: false, reason: `lease 被占用 (owner=${holder.owner}, until=${holder.leaseUntil})`, holder };
+        }
+    }
+    return { ok: false, reason: 'lease 抢占重试后仍失败' };
+}
+/** 续租 (必须带自己的 leaseId: 被接管后旧 worker 不能再续租, 也就不能再写) */
+export async function heartbeatGoal(goalId, leaseId, ttlMs = 90_000, now = Date.now()) {
+    const cur = await readLease(goalId);
+    if (!cur)
+        return { ok: false, reason: 'lease 不存在 (可能已过期被回收)' };
+    if (cur.leaseId !== leaseId)
+        return { ok: false, reason: `lease 已被接管 (当前 owner=${cur.owner})` };
+    const next = { ...cur, lastHeartbeat: new Date(now).toISOString(), leaseUntil: new Date(now + ttlMs).toISOString() };
+    try {
+        await fs.writeFile(leasePath(goalId), JSON.stringify(next, null, 2), 'utf8');
+    }
+    catch (err) {
+        return { ok: false, reason: `续租写失败: ${String(err?.message || err).slice(0, 120)}` };
+    }
+    await updateGoal(goalId, { lease: { owner: next.owner, leaseId: next.leaseId, claimedAt: next.claimedAt, lastHeartbeat: next.lastHeartbeat, leaseUntil: next.leaseUntil } });
+    return { ok: true, lease: next };
+}
+/** 释放执行权 (只释放自己的那把) */
+export async function releaseGoal(goalId, leaseId) {
+    const cur = await readLease(goalId);
+    if (!cur) {
+        await updateGoal(goalId, { lease: undefined });
+        return { ok: true };
+    }
+    if (cur.leaseId !== leaseId)
+        return { ok: false, reason: `lease 已被接管, 未释放 (当前 owner=${cur.owner})` };
+    await fs.rm(leasePath(goalId), { force: true });
+    await updateGoal(goalId, { lease: undefined });
+    return { ok: true };
+}
+/**
+ * 扫出"现在就该跑"的 Goal (M2-B 第 1-2 步: 扫描 + 判断可否唤醒)。
+ * 规则: 状态 ∈ active/recovering; autoContinue !== false; wakeAt 未到则跳过; 有活租约则跳过。
+ * 返回附带"为什么没被选"的说明, 便于诊断 (不静默)。
+ */
+export async function listRunnableGoals(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const all = await listGoals({ limit: 100 });
+    const runnable = [];
+    const skipped = [];
+    for (const g of all) {
+        const c = g.continuation;
+        const skip = (reason) => skipped.push({ goalId: g.goalId, status: g.status, reason });
+        // 终态 / 等人 / 等外部事件 → 一律不自动唤醒 (这是 2-C 唤醒表的硬规则)
+        if (g.status === 'completed' || g.status === 'failed' || g.status === 'abandoned')
+            continue;
+        if (g.status === 'paused') {
+            skip('paused: 等用户 resume (重启也不会自动跑)');
+            continue;
+        }
+        if (g.status === 'needs_human') {
+            skip(`needs_human: 等人工 approve (${c?.wakeReason || ''})`);
+            continue;
+        }
+        if (g.status === 'awaiting_external' || c?.wakeReason === 'awaiting_external') {
+            skip(`awaiting_external: 等外部事件${c?.needsExternal ? ` (${c.needsExternal})` : ''}, 不重复发送`);
+            continue;
+        }
+        if (c?.autoContinue === false) {
+            skip(`autoContinue=false (${c.wakeReason || '等人'})`);
+            continue;
+        }
+        if (g.status === 'retry_wait' || (c?.wakeAt && Date.parse(c.wakeAt) > now)) {
+            if (c?.wakeAt && Date.parse(c.wakeAt) > now) {
+                skip(`retry_wait: 时间未到 (${c.wakeAt})`);
+                continue;
+            }
+            // retry_wait 且时间已到 → 可跑
+        }
+        const lease = await readLease(g.goalId);
+        const held = !!lease && Date.parse(String(lease.leaseUntil || '')) > now && (lease.pid ? pidAlive(Number(lease.pid)) : true);
+        if (held) {
+            skip(`lease 被 ${lease.owner} 持有至 ${lease.leaseUntil}`);
+            continue;
+        }
+        runnable.push(g);
+    }
+    // 先跑等着跑最久的 (公平性: 不让一个 Goal 霸占所有 tick)
+    runnable.sort((a, b) => Date.parse(a.updatedAt || a.createdAt) - Date.parse(b.updatedAt || b.createdAt));
+    return { runnable, skipped };
+}
+/** CLI/Web 可见的长期执行诊断 (每个 Goal 为什么在/不在跑) */
+export async function wakeReport(now = Date.now()) {
+    const goals = await listGoals({ limit: 50 });
+    const out = [];
+    for (const g of goals) {
+        const c = g.continuation;
+        const lease = await readLease(g.goalId);
+        const live = lease && Date.parse(String(lease.leaseUntil || '')) > now && (lease.pid ? pidAlive(Number(lease.pid)) : true);
+        let wake = '立即';
+        if (g.status === 'completed')
+            wake = '不再唤醒';
+        else if (g.status === 'paused' || c?.autoContinue === false)
+            wake = `等人 (${c?.wakeReason || g.status})`;
+        else if (c?.wakeAt && Date.parse(c.wakeAt) > now) {
+            const left = Math.round((Date.parse(c.wakeAt) - now) / 1000);
+            wake = `等时间 (${c.wakeAt}, 还剩 ${left}s${c.attempts ? `, 已自动继续 ${c.attempts} 次` : ''})`;
+        }
+        else if (c?.wakeReason === 'awaiting_external')
+            wake = `等外部事件${c.needsExternal ? ` (${c.needsExternal})` : ''}`;
+        else if (live)
+            wake = `已被 ${lease.owner} 认领`;
+        out.push({ goalId: g.goalId, status: g.status, wake, autoContinue: c?.autoContinue !== false, lease: live ? lease.owner : undefined });
+    }
+    return out;
+}