minimal-agent 0.13.0 → 0.14.0

package/src/goal/goalStore.ts

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import {
+  appendFile,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { agentStateDir } from '../context/agentHome.js';
+import { GoalRuntimeError } from './errors.js';
+import type { Goal, GoalEvent, GoalScope } from './types.js';
+
+function safeSegment(value: string): string {
+  const readable = value.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 48) || 'default';
+  const hash = createHash('sha256').update(value).digest('hex').slice(0, 10);
+  return `${readable}-${hash}`;
+}
+
+export interface GoalStoreOptions {
+  stateRoot?: string;
+  lockTimeoutMs?: number;
+}
+
+export class GoalStore {
+  private readonly root: string;
+  private readonly lockTimeoutMs: number;
+
+  constructor(options: GoalStoreOptions = {}) {
+    this.root = options.stateRoot ?? join(agentStateDir(), 'goals');
+    this.lockTimeoutMs = options.lockTimeoutMs ?? 2_000;
+  }
+
+  directory(scope: GoalScope): string {
+    return join(
+      this.root,
+      safeSegment(scope.workspaceId),
+      safeSegment(scope.sessionId),
+    );
+  }
+
+  async read(scope: GoalScope): Promise<Goal | null> {
+    let snapshot: Goal | null = null;
+    try {
+      snapshot = JSON.parse(
+        await readFile(join(this.directory(scope), 'current.json'), 'utf8'),
+      ) as Goal;
+    } catch (error) {
+      if (
+        (error as NodeJS.ErrnoException).code !== 'ENOENT'
+        && !(error instanceof SyntaxError)
+      ) {
+        throw error;
+      }
+    }
+    const projected = this.project(scope, await this.readEvents(scope));
+    if (!projected) return snapshot;
+    return !snapshot || projected.revision > snapshot.revision ? projected : snapshot;
+  }
+
+  async readEvents(scope: GoalScope): Promise<GoalEvent[]> {
+    try {
+      const raw = await readFile(join(this.directory(scope), 'events.jsonl'), 'utf8');
+      const lines = raw.split('\n');
+      const events: GoalEvent[] = [];
+      for (const [index, line] of lines.entries()) {
+        if (!line.trim()) continue;
+        try {
+          const parsed = JSON.parse(line) as GoalEvent | GoalEvent[];
+          events.push(...(Array.isArray(parsed) ? parsed : [parsed]));
+        } catch (error) {
+          // appendFile 崩溃最多可能留下最后一条不完整记录。旧的完整投影仍
+          // 可用；中间损坏则必须响亮失败，不能悄悄跳过历史。
+          const isLastRecord = lines.slice(index + 1).every((item) => !item.trim());
+          if (!isLastRecord || raw.endsWith('\n')) throw error;
+        }
+      }
+      return events;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+
+  private project(scope: GoalScope, events: GoalEvent[]): Goal | null {
+    let goal: Goal | null = null;
+    let lastRevision = 0;
+    for (const event of events) {
+      if (event.type === 'goal.created') {
+        goal = {
+          goalId: event.goalId,
+          scope,
+          source: event.source,
+          status: 'active',
+          revision: event.revision ?? 1,
+          contracts: [event.contract],
+          currentContractVersion: event.contract.version,
+          attempts: [],
+          createdBy: event.createdBy,
+          acceptorHumanIds: event.acceptorHumanIds,
+          createdAt: event.at,
+          updatedAt: event.at,
+          usage: { inputTokens: 0, outputTokens: 0, elapsedMs: 0 },
+        };
+        lastRevision = goal.revision;
+        continue;
+      }
+      if (!goal || event.goalId !== goal.goalId) continue;
+      const revision = event.revision ?? lastRevision + 1;
+      if (event.type === 'goal.contract_revised') {
+        goal.contracts = [
+          ...goal.contracts.filter((item) => item.version !== event.contract.version),
+          event.contract,
+        ];
+        goal.currentContractVersion = event.contract.version;
+      } else if (event.type === 'goal.status_changed') {
+        goal.status = event.to;
+        goal.statusReason = event.reason;
+      } else if (event.type === 'goal.attempt_started') {
+        const index = goal.attempts.findIndex((item) => item.attemptId === event.attempt.attemptId);
+        if (index >= 0) goal.attempts[index] = structuredClone(event.attempt);
+        else goal.attempts.push(structuredClone(event.attempt));
+      } else if (event.type === 'goal.attempt_finished') {
+        const attempt = goal.attempts.find((item) => item.attemptId === event.attemptId);
+        if (attempt) {
+          attempt.status = event.status;
+          attempt.finishedAt = event.at;
+          attempt.artifacts = event.artifacts;
+          attempt.evidence = event.evidence;
+          attempt.blocker = event.blocker;
+        }
+      } else if (event.type === 'goal.resources_recorded') {
+        goal.usage.inputTokens += event.usage.inputTokens ?? 0;
+        goal.usage.outputTokens += event.usage.outputTokens ?? 0;
+        goal.usage.elapsedMs += event.usage.elapsedMs ?? 0;
+      }
+      goal.revision = Math.max(goal.revision, revision);
+      goal.updatedAt = Math.max(goal.updatedAt, event.at);
+      lastRevision = Math.max(lastRevision, revision);
+    }
+    return goal;
+  }
+
+  async mutate<T>(scope: GoalScope, action: () => Promise<T>): Promise<T> {
+    const dir = this.directory(scope);
+    await mkdir(dir, { recursive: true });
+    const lockPath = join(dir, '.write.lock');
+    const deadline = Date.now() + this.lockTimeoutMs;
+    let handle: Awaited<ReturnType<typeof open>> | null = null;
+    while (handle === null) {
+      try {
+        handle = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+        await handle.writeFile(`${process.pid}\n`, 'utf8');
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        if (await this.clearStaleLock(lockPath)) continue;
+        if (Date.now() >= deadline) {
+          throw new GoalRuntimeError(
+            'GOAL_STORE_LOCKED',
+            '当前 Session 的 Goal 正由另一个进程更新，请稍后重试。',
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    try {
+      return await action();
+    } finally {
+      await handle.close().catch(() => undefined);
+      await unlink(lockPath).catch(() => undefined);
+    }
+  }
+
+  private async clearStaleLock(lockPath: string): Promise<boolean> {
+    try {
+      const [raw, info] = await Promise.all([
+        readFile(lockPath, 'utf8'),
+        stat(lockPath),
+      ]);
+      const pid = Number.parseInt(raw.trim(), 10);
+      let alive = Number.isInteger(pid) && pid > 0;
+      if (alive) {
+        try {
+          process.kill(pid, 0);
+        } catch (error) {
+          alive = (error as NodeJS.ErrnoException).code !== 'ESRCH';
+        }
+      }
+      if (alive && Date.now() - info.mtimeMs < 30_000) return false;
+      await unlink(lockPath);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === 'ENOENT';
+    }
+  }
+
+  async commit(scope: GoalScope, goal: Goal, events: GoalEvent[]): Promise<void> {
+    const dir = this.directory(scope);
+    await mkdir(dir, { recursive: true });
+    if (events.length > 0) {
+      await appendFile(
+        join(dir, 'events.jsonl'),
+        // 同一次 revision 的所有事件是一条 JSONL 记录，避免崩溃后只重放
+        // 半次状态变更。readEvents 仍兼容旧版逐事件记录。
+        `${JSON.stringify(events)}\n`,
+        'utf8',
+      );
+    }
+    const current = join(dir, 'current.json');
+    const temp = `${current}.${process.pid}.${goal.revision}.tmp`;
+    await writeFile(temp, `${JSON.stringify(goal, null, 2)}\n`, 'utf8');
+    await rename(temp, current);
+  }
+}

package/src/goal/index.js

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './goalRuntime.js';
+export * from './goalStore.js';
+export * from './types.js';

package/src/goal/index.ts

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './goalRuntime.js';
+export * from './goalStore.js';
+export * from './types.js';

package/src/goal/statusMapping.js

@@ -0,0 +1,71 @@
+/**
+ * ============================================================
+ *  src/goal/statusMapping.ts —— 三套完成语义词汇的**唯一映射真值**
+ * ------------------------------------------------------------
+ *  「目标做成了没有」这件事在系统里有三套词，各自回答的问题**不同**：
+ *
+ *  | 层 | 取值 | 回答的问题 | 谁写 |
+ *  |---|---|---|---|
+ *  | 工作流 `STATUS.json` | achieved / stalled / max_iterations / budget_limited | **这一次尝试**跑成什么样 | `workflows/goal/workflow.mjs` |
+ *  | Attempt | verified / stopped / failed | 引擎经 bridge 回报的执行结局 | `runner.ts` |
+ *  | Goal | active…accepted（8 态） | **生命周期事实源** | `GoalRuntime` |
+ *
+ *  ⚠️ 三者会打架，而且是**看起来最像成功的时候**打架：
+ *  工作流写 `achieved`（硬门全过 + 独立审计通过），Goal 却只到
+ *  `ready_for_acceptance`（**还没有人验收**）。宿主只读 STATUS.json 就会
+ *  把「机器自检通过」当成「事情办完了」——这正是 Agent 不许自己宣布完成的原因。
+ *
+ *  ⚠️ **这份映射不能放 `src/web/protocol.ts`**：那个文件被
+ *  `test/webProtocolTypeOnly.test.ts` 锁死「只准 import type/export type、
+ *  零运行时副作用」，而映射表是运行时值。放进去会同时打红三处守护测试
+ *  （minimal-agent / minimal-desktop / minimal-server 各一份 protocolShared）。
+ *  这里经 package.json 的具名子路径 `minimal-agent/goal-status` 导出。
+ * ============================================================
+ */
+/** 一次尝试的结局：工作流结局 → Attempt 状态。 */
+export const OUTCOME_TO_ATTEMPT = {
+    achieved: 'verified',
+    // ⚠️ 三种未达成里，只有「卡死」与「轮数耗尽」算 failed；
+    // budget_limited 是**主动停在安全边界**，现场完好可续跑 —— 记 stopped 而不是 failed。
+    stalled: 'failed',
+    max_iterations: 'failed',
+    budget_limited: 'stopped',
+};
+/**
+ * 权威状态的人类可读说明。
+ *
+ * ⚠️ `achieved` 那条的措辞是刻意的：它**不是**「目标达成」。
+ * 机器能证明的只有「硬门全过 + 独立审计没挑出毛病」，剩下那步只能由人做。
+ */
+export const GOAL_STATUS_TEXT = {
+    active: '进行中',
+    paused: '已暂停（用户主动）',
+    blocked: '受阻，需要人介入',
+    usage_limited: '服务端配额/授权不足 —— 加预算没用，要去解决授权或等周期重置',
+    budget_limited: '用户设定的 token 预算用尽 —— 加大预算后可从断点继续',
+    ready_for_acceptance: 'Agent 自检通过，**等待人类验收**（尚未完成）',
+    accepted: '已由人类验收，完成',
+    cancelled: '已取消',
+};
+/**
+ * 宿主该信哪个：**永远是 `Goal.status`**。
+ *
+ * 这个函数存在的意义是让「该读哪个」变成一次函数调用，而不是一句注释 ——
+ * 注释拦不住下一个人直接读 STATUS.json 的顶层 status。
+ */
+export function authoritativeStatus(input) {
+    if (input.goalStatus) {
+        return {
+            status: input.goalStatus,
+            authority: 'goal-runtime',
+            // 只有 accepted 算真正完成。ready_for_acceptance 差着一次人类点头。
+            done: input.goalStatus === 'accepted',
+        };
+    }
+    // 没有 Goal Runtime（普通 /workflow 调用，没走 managedRuntime）时才退回工作流结局。
+    return {
+        status: input.workflowOutcome ?? 'unknown',
+        authority: 'workflow-attempt',
+        done: input.workflowOutcome === 'achieved',
+    };
+}

package/src/goal/statusMapping.ts

@@ -0,0 +1,95 @@
+/**
+ * ============================================================
+ *  src/goal/statusMapping.ts —— 三套完成语义词汇的**唯一映射真值**
+ * ------------------------------------------------------------
+ *  「目标做成了没有」这件事在系统里有三套词，各自回答的问题**不同**：
+ *
+ *  | 层 | 取值 | 回答的问题 | 谁写 |
+ *  |---|---|---|---|
+ *  | 工作流 `STATUS.json` | achieved / stalled / max_iterations / budget_limited | **这一次尝试**跑成什么样 | `workflows/goal/workflow.mjs` |
+ *  | Attempt | verified / stopped / failed | 引擎经 bridge 回报的执行结局 | `runner.ts` |
+ *  | Goal | active…accepted（8 态） | **生命周期事实源** | `GoalRuntime` |
+ *
+ *  ⚠️ 三者会打架，而且是**看起来最像成功的时候**打架：
+ *  工作流写 `achieved`（硬门全过 + 独立审计通过），Goal 却只到
+ *  `ready_for_acceptance`（**还没有人验收**）。宿主只读 STATUS.json 就会
+ *  把「机器自检通过」当成「事情办完了」——这正是 Agent 不许自己宣布完成的原因。
+ *
+ *  ⚠️ **这份映射不能放 `src/web/protocol.ts`**：那个文件被
+ *  `test/webProtocolTypeOnly.test.ts` 锁死「只准 import type/export type、
+ *  零运行时副作用」，而映射表是运行时值。放进去会同时打红三处守护测试
+ *  （minimal-agent / minimal-desktop / minimal-server 各一份 protocolShared）。
+ *  这里经 package.json 的具名子路径 `minimal-agent/goal-status` 导出。
+ * ============================================================
+ */
+
+import type { GoalAttemptStatus, GoalStatus } from './types.js';
+
+/** 工作流 `STATUS.json` 顶层 `status` 的取值。 */
+export type WorkflowOutcome =
+  | 'achieved'
+  | 'stalled'
+  | 'max_iterations'
+  | 'budget_limited';
+
+/** 一次尝试的结局：工作流结局 → Attempt 状态。 */
+export const OUTCOME_TO_ATTEMPT: Readonly<Record<WorkflowOutcome, GoalAttemptStatus>> = {
+  achieved: 'verified',
+  // ⚠️ 三种未达成里，只有「卡死」与「轮数耗尽」算 failed；
+  // budget_limited 是**主动停在安全边界**，现场完好可续跑 —— 记 stopped 而不是 failed。
+  stalled: 'failed',
+  max_iterations: 'failed',
+  budget_limited: 'stopped',
+};
+
+/**
+ * 权威状态的人类可读说明。
+ *
+ * ⚠️ `achieved` 那条的措辞是刻意的：它**不是**「目标达成」。
+ * 机器能证明的只有「硬门全过 + 独立审计没挑出毛病」，剩下那步只能由人做。
+ */
+export const GOAL_STATUS_TEXT: Readonly<Record<GoalStatus, string>> = {
+  active: '进行中',
+  paused: '已暂停（用户主动）',
+  blocked: '受阻，需要人介入',
+  usage_limited: '服务端配额/授权不足 —— 加预算没用，要去解决授权或等周期重置',
+  budget_limited: '用户设定的 token 预算用尽 —— 加大预算后可从断点继续',
+  ready_for_acceptance: 'Agent 自检通过，**等待人类验收**（尚未完成）',
+  accepted: '已由人类验收，完成',
+  cancelled: '已取消',
+};
+
+/**
+ * 宿主该信哪个：**永远是 `Goal.status`**。
+ *
+ * 这个函数存在的意义是让「该读哪个」变成一次函数调用，而不是一句注释 ——
+ * 注释拦不住下一个人直接读 STATUS.json 的顶层 status。
+ */
+export function authoritativeStatus(input: {
+  goalStatus?: GoalStatus | null;
+  workflowOutcome?: WorkflowOutcome | null;
+}): { status: string; authority: 'goal-runtime' | 'workflow-attempt'; done: boolean } {
+  if (input.goalStatus) {
+    return {
+      status: input.goalStatus,
+      authority: 'goal-runtime',
+      // 只有 accepted 算真正完成。ready_for_acceptance 差着一次人类点头。
+      done: input.goalStatus === 'accepted',
+    };
+  }
+  // 没有 Goal Runtime（普通 /workflow 调用，没走 managedRuntime）时才退回工作流结局。
+  return {
+    status: input.workflowOutcome ?? 'unknown',
+    authority: 'workflow-attempt',
+    done: input.workflowOutcome === 'achieved',
+  };
+}
+
+/** 工作流 Attempt 报告文件的最小协议；不包含 Goal 生命周期状态。 */
+export interface WorkflowAttemptStatusFile {
+  schemaVersion: 2;
+  status: WorkflowOutcome;
+  outcome: WorkflowOutcome;
+  attempt_outcome: WorkflowOutcome;
+  authority: 'workflow-attempt';
+}

package/src/goal/types.js

@@ -0,0 +1,7 @@
+export const TERMINAL_GOAL_STATUSES = new Set([
+    'accepted',
+    'cancelled',
+]);
+export function isGoalFinished(status) {
+    return TERMINAL_GOAL_STATUSES.has(status);
+}

package/src/goal/types.ts

@@ -0,0 +1,179 @@
+export type GoalStatus =
+  | 'active'
+  | 'paused'
+  | 'blocked'
+  | 'usage_limited'
+  | 'budget_limited'
+  | 'ready_for_acceptance'
+  | 'accepted'
+  | 'cancelled';
+
+export type GoalAttemptStatus =
+  | 'running'
+  | 'stopped'
+  | 'failed'
+  | 'verified'
+  | 'superseded';
+
+export interface GoalScope {
+  workspaceId: string;
+  sessionId: string;
+}
+
+export type GoalSource =
+  | { kind: 'standalone' }
+  | {
+      kind: 'group-task';
+      groupId: string;
+      taskId: string;
+      assigneeAgentId?: string;
+      parentTaskId?: string;
+    };
+
+export interface GoalContractInput {
+  objective: string;
+  deliverables?: string[] | null;
+  acceptanceCriteria?: string[] | null;
+  scope?: string | null;
+  sourceRefs?: string[] | null;
+  confirmedBy?: string;
+  /** 见 GoalContract.tokenBudget。`null` / 缺省 = 不限。 */
+  tokenBudget?: number | null;
+}
+
+export interface GoalContract {
+  version: number;
+  objective: string;
+  deliverables: string[];
+  acceptanceCriteria: string[];
+  scope?: string;
+  sourceRefs: string[];
+  confirmedBy: string;
+  confirmedAt: number;
+  hash: string;
+  /**
+   * 本 Goal 允许消耗的 token 上限（input + output 之和）。`null` = 不限（默认）。
+   *
+   * 语义边界，改之前先读：
+   *  - 它**只在开新一轮之前**被求值。进行中的 TAOR 循环即使超额也一路跑完到节点 ——
+   *    这是产品决策：宁可超一点预算，也不能把 agent 停在半成品状态。
+   *  - 它挂在**版本化的契约**上，而 `Goal.usage` 挂在 Goal 上（累计、不分契约版本）。
+   *    改预算 = 新契约版本，**已消耗量不重置** → 「加预算继续跑」是自然操作。
+   *  - 与 `usage_limited` 的分工：这个是**用户自己设的额度**用完了；
+   *    `usage_limited` 是**服务端配额/授权**不给了。两者都可 resume，但恢复动作不同。
+   */
+  tokenBudget?: number | null;
+}
+
+export interface GoalAttempt {
+  attemptId: string;
+  contractVersion: number;
+  workflow: string;
+  status: GoalAttemptStatus;
+  startedAt: number;
+  finishedAt?: number;
+  artifacts: string[];
+  evidence: string[];
+  blocker?: string;
+}
+
+export interface GoalResourceUsage {
+  inputTokens: number;
+  outputTokens: number;
+  elapsedMs: number;
+}
+
+export interface Goal {
+  goalId: string;
+  scope: GoalScope;
+  source: GoalSource;
+  status: GoalStatus;
+  revision: number;
+  contracts: GoalContract[];
+  currentContractVersion: number;
+  attempts: GoalAttempt[];
+  createdBy: string;
+  acceptorHumanIds: string[];
+  createdAt: number;
+  updatedAt: number;
+  usage: GoalResourceUsage;
+  statusReason?: string;
+}
+
+export type GoalEvent =
+  | {
+      type: 'goal.created';
+      eventId: string;
+      at: number;
+      goalId: string;
+      contract: GoalContract;
+      source: GoalSource;
+      createdBy: string;
+      acceptorHumanIds: string[];
+      revision?: number;
+    }
+  | {
+      type: 'goal.contract_revised';
+      eventId: string;
+      at: number;
+      goalId: string;
+      contract: GoalContract;
+      revision?: number;
+    }
+  | {
+      type: 'goal.status_changed';
+      eventId: string;
+      at: number;
+      goalId: string;
+      from: GoalStatus;
+      to: GoalStatus;
+      reason?: string;
+      actorId?: string;
+      revision?: number;
+    }
+  | {
+      type: 'goal.attempt_started';
+      eventId: string;
+      at: number;
+      goalId: string;
+      attempt: GoalAttempt;
+      revision?: number;
+    }
+  | {
+      type: 'goal.attempt_finished';
+      eventId: string;
+      at: number;
+      goalId: string;
+      attemptId: string;
+      status: GoalAttemptStatus;
+      artifacts: string[];
+      evidence: string[];
+      blocker?: string;
+      revision?: number;
+    }
+  | {
+      type: 'goal.resources_recorded';
+      eventId: string;
+      at: number;
+      goalId: string;
+      usage: Partial<GoalResourceUsage>;
+      revision?: number;
+    };
+
+export interface GoalExecutionContext {
+  goalId: string;
+  contractVersion: number;
+  attemptId: string;
+  groupId?: string;
+  taskId?: string;
+  contract: GoalContract;
+}
+
+export const TERMINAL_GOAL_STATUSES = new Set<GoalStatus>([
+  'accepted',
+  'cancelled',
+]);
+
+export function isGoalFinished(status: GoalStatus): boolean {
+  return TERMINAL_GOAL_STATUSES.has(status);
+}