@mebular/fleet 0.0.0-stage → 0.1.0

package/src/runtime/node.ts

@@ -0,0 +1,250 @@
+// Fleet 节点（M2）：任务板 + 发起端。写入任务（created 事件）→ 投递 → 收集结果事件 → 观察收敛。
+
+import { randomUUID } from 'node:crypto';
+import type { FleetEndpoint, FleetTrace, TaskBudget, TaskDispatch } from '../protocol/envelope.js';
+import type { TaskEvent } from '../protocol/events.js';
+import { reduceTaskEvents, type TaskState } from '../model.js';
+import type { LocalQuota, QuotaDecision } from '../quota.js';
+import type { TaskEventStore } from '../store/file-store.js';
+import type { MebularMessageStore } from '../store/message-store.js';
+import type { TaskTransport } from '../transport/types.js';
+import { dagCompletion, deriveEdges, type DagCompletion } from '../collab/dag.js';
+import { NegotiationTracker, validateNegotiationMessage, type NegotiationMessage } from '../collab/negotiation.js';
+import { admitCreated, admissibleTaskIds } from '../collab/tree.js';
+
+export interface FleetNodeOptions {
+  device: string;
+  /** 发起端 Agent 名（默认 `board`） */
+  agent?: string;
+  store: TaskEventStore;
+  transport: TaskTransport;
+  quota: LocalQuota;
+  /**
+   * 1d-b：有限协商（可选）。`respond=true` 时，发起端对未终态任务的协商消息
+   * **自动接受**（确定性策略）——使 `clarify/counter → accept → 执行` 的 E2E 可自动推进。
+   */
+  negotiation?: {
+    store: MebularMessageStore<NegotiationMessage>;
+    maxRounds: number;
+    /** 发起端策略：`accept`（默认）接受；`counter` 反提案（与 worker 交替直到超限） */
+    policy?: 'accept' | 'counter';
+  };
+}
+
+export interface SubmitRequest {
+  intent: string;
+  to: FleetEndpoint;
+  payloadRef?: string;
+  expiresAt?: number;
+  /** 因果链（默认空；用于 DAG 派生：`causedBy` 指向父任务） */
+  trace?: FleetTrace;
+  /** 重复投递该 created 事件（同 eventId、不同 msgId）以验证幂等（默认 1） */
+  deliveries?: number;
+  /** **W1**：root 子树预算（缺省=默认上界）；子任务应 ≤ 父剩余（入口不变式判定） */
+  budget?: TaskBudget;
+  /** **W1**：root 派发策略（缺省 `children-ok`） */
+  dispatch?: TaskDispatch;
+}
+
+export interface SubmitResult {
+  taskId: string | null;
+  decision: QuotaDecision;
+}
+
+export class FleetNode {
+  readonly endpoint: FleetEndpoint;
+  private readonly store: TaskEventStore;
+  private readonly transport: TaskTransport;
+  private readonly quota: LocalQuota;
+  private readonly negotiation: FleetNodeOptions['negotiation'] | null;
+
+  constructor(options: FleetNodeOptions) {
+    this.endpoint = { device: options.device, agent: options.agent ?? 'board' };
+    this.store = options.store;
+    this.transport = options.transport;
+    this.quota = options.quota;
+    this.negotiation = options.negotiation ?? null;
+  }
+
+  /**
+   * 1d-b：对未终态任务应用发起端协商策略——未接受且未超限时**接受**
+   * （确定性；`messageId` 幂等去重保证只发一次）。
+   */
+  async applyNegotiationPolicy(): Promise<number> {
+    if (!this.negotiation) return 0;
+    const policy = this.negotiation.policy ?? 'accept';
+    const all = await this.negotiation.store.all();
+    let responded = 0;
+    for (const state of await this.states()) {
+      if (state.terminal) continue;
+      const tracker = new NegotiationTracker(state.taskId, { maxRounds: this.negotiation.maxRounds });
+      for (const message of all) {
+        if (message.taskId === state.taskId && validateNegotiationMessage(message).ok) tracker.apply(message);
+      }
+      const status = tracker.status();
+      if (status.accepted || status.rejected || status.exceeded) continue;
+      const messages = tracker.messages();
+      const last = messages[messages.length - 1];
+      // 只在对端（worker）发言后回应，避免自我循环
+      if (last === undefined || last.from.device === this.endpoint.device) continue;
+      const reply: NegotiationMessage =
+        policy === 'accept'
+          ? { v: 1, messageId: `${state.taskId}#accept@${this.endpoint.device}`, taskId: state.taskId, round: status.rounds, from: this.endpoint, kind: 'accept', text: 'accepted' }
+          : { v: 1, messageId: `${state.taskId}#neg#${status.rounds + 1}@${this.endpoint.device}`, taskId: state.taskId, round: status.rounds + 1, from: this.endpoint, kind: 'counter', text: 'counter' };
+      if (await this.negotiation.store.append(reply)) responded += 1;
+    }
+    return responded;
+  }
+
+  /**
+   * 1d-a：等待从 `rootTaskId` 可达的**全部节点终态**（dagCompletion）。
+   * 返回完成判定（含可达/待决节点），便于断言与汇总。
+   */
+  async waitForDagCompletion(
+    rootTaskId: string,
+    options: { timeoutMs: number; pollMs?: number },
+  ): Promise<DagCompletion> {
+    const pollMs = options.pollMs ?? 10;
+    const deadline = Date.now() + options.timeoutMs;
+    let completion: DagCompletion = dagCompletion([], () => false, rootTaskId);
+    for (;;) {
+      await this.pollOnce();
+      await this.applyNegotiationPolicy();
+      const states = await this.states();
+      const terminal = new Set(states.filter((s) => s.terminal).map((s) => s.taskId));
+      completion = dagCompletion(deriveEdges(states), (id) => terminal.has(id), rootTaskId);
+      if (completion.complete || Date.now() >= deadline) return completion;
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+  }
+
+  /** 1d-a：审查 DAG 汇总——从 root 可达且终态的节点结果按 taskId 确定序拼接。 */
+  async summarizeDag(rootTaskId: string): Promise<{ root: string; reachable: string[]; pending: string[]; summary: string }> {
+    const states = await this.states();
+    const terminal = new Set(states.filter((s) => s.terminal).map((s) => s.taskId));
+    const completion = dagCompletion(deriveEdges(states), (id) => terminal.has(id), rootTaskId);
+    const byId = new Map(states.map((s) => [s.taskId, s]));
+    const summary = completion.reachable
+      .filter((id) => terminal.has(id))
+      .map((id) => `${id}=${byId.get(id)?.resultRef ?? ''}`)
+      .join('|');
+    return { root: completion.root, reachable: completion.reachable, pending: completion.pending, summary };
+  }
+
+  private async emit(event: TaskEvent, to: FleetEndpoint, deliveries = 1): Promise<void> {
+    await this.store.append(event);
+    for (let i = 0; i < deliveries; i++) {
+      await this.transport.publish({ msgId: randomUUID(), from: this.endpoint, to, event });
+    }
+  }
+
+  /** 提交任务：本地配额判定 → 写 `created` 事件 → 投递（可重复投递）。 */
+  async submit(request: SubmitRequest): Promise<SubmitResult> {
+    const decision = this.quota.decide(this.endpoint.device);
+    if (decision === 'rejected') return { taskId: null, decision };
+
+    const taskId = `task-${this.endpoint.device}-${randomUUID().slice(0, 8)}`;
+    const event: TaskEvent = {
+      v: 1,
+      eventId: `${taskId}#created`,
+      taskId,
+      type: 'created',
+      actor: this.endpoint,
+      at: Date.now(),
+      toStatus: 'queued',
+      trace: request.trace ?? { chain: [] },
+      to: request.to,
+      intent: request.intent,
+    };
+    if (request.payloadRef !== undefined) event.payloadRef = request.payloadRef;
+    if (request.expiresAt !== undefined) event.expiresAt = request.expiresAt;
+    if (request.budget !== undefined) event.budget = request.budget;
+    if (request.dispatch !== undefined) event.dispatch = request.dispatch;
+    await this.emit(event, request.to, request.deliveries ?? 1);
+    return { taskId, decision };
+  }
+
+  /** 处理收件箱：把收到的状态事件幂等并入本地存储。返回本次新并入的事件数。 */
+  async pollOnce(): Promise<number> {
+    const messages = await this.transport.drain(this.endpoint);
+    let applied = 0;
+    let states = await this.states();
+    for (const message of messages) {
+      const event = message.event;
+      // W1 入口拒收：越预算/越链长/root-only 的 created 不入库（纯函数、全端一致）
+      if (event.type === 'created') {
+        const verdict = admitCreated(event, states, reduceTaskEvents);
+        if (!verdict.ok) continue;
+      }
+      if (await this.store.append(event)) {
+        applied += 1;
+        const reduced = reduceTaskEvents(await this.store.byTask(event.taskId));
+        if (reduced !== null) states = states.filter((s) => s.taskId !== reduced.taskId).concat(reduced);
+      }
+    }
+    return applied;
+  }
+
+  /** 权威任务视图（已剔除违反树不变式的任务）；供 DAG/汇总与验收读取。 */
+  async statesView(): Promise<TaskState[]> {
+    return this.states();
+  }
+
+  /** 当前所有任务的权威状态（按 taskId 排序）。 */
+  async states(): Promise<TaskState[]> {
+    const events = await this.store.all();
+    const byTask = new Map<string, TaskEvent[]>();
+    for (const event of events) {
+      const list = byTask.get(event.taskId);
+      if (list) list.push(event);
+      else byTask.set(event.taskId, [event]);
+    }
+    const out: TaskState[] = [];
+    for (const taskId of [...byTask.keys()].sort()) {
+      const state = reduceTaskEvents(byTask.get(taskId)!);
+      if (state) out.push(state);
+    }
+    // W1：权威视图剔除违反树不变式的任务（经记忆同步到达的无效 created 亦生效）
+    const admissible = admissibleTaskIds(out);
+    return out.filter((s) => admissible.has(s.taskId));
+  }
+
+  async stateOf(taskId: string): Promise<TaskState | null> {
+    return reduceTaskEvents(await this.store.byTask(taskId));
+  }
+
+  /** 轮询直到给定任务全部终态（或超时）。返回是否全部终态。 */
+  async waitForTerminal(
+    taskIds: readonly string[],
+    options: { timeoutMs: number; pollMs?: number },
+  ): Promise<boolean> {
+    const pollMs = options.pollMs ?? 10;
+    const deadline = Date.now() + options.timeoutMs;
+    const pending = new Set(taskIds);
+    while (Date.now() < deadline) {
+      await this.pollOnce();
+      await this.applyNegotiationPolicy();
+      const states = await this.states();
+      for (const state of states) if (state.terminal) pending.delete(state.taskId);
+      if (pending.size === 0) return true;
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return pending.size === 0;
+  }
+
+  /** 清空收件箱（把当前待处理消息并入存储）。便于测试可控推进。 */
+  async settle(): Promise<number> {
+    let total = 0;
+    let n = await this.pollOnce();
+    while (n > 0) {
+      total += n;
+      n = await this.pollOnce();
+    }
+    return total;
+  }
+
+  async close(): Promise<void> {
+    await this.transport.close();
+    await this.store.close();
+  }
+}

package/src/runtime/openchamber-http.ts

@@ -0,0 +1,137 @@
+// OpenChamber 适配器（M4）：**中立 HTTP 客户端 seam**。
+//
+// 本文件对 provider **毫不知情**：只接受「一个 HTTPS/HTTP 端点 + 一个 bearer-ish token（内联或从文件读）
+// + 超时 + 可选 agent/model」，POST 一个 JSON 请求并读取 `{ ok, result:{ text, sessionId? }, error? }`。
+// 当前 provider #1 是 oc-hermes-bridge daemon 的 `POST /agent/run-once`（由调用方/脚本提供 endpoint 与
+// token 路径）；将来换成独立 provider 或 OpenChamber 官方 API，**不改本文件、也不改 fleet 代码**。
+//
+// 安全：只发本机端点、token 不硬编码、不打印、不落盘、不出现在错误信息里；超时/连接失败 → 归一错误。
+
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+
+import type { OpenChamberPromptInput, OpenChamberSessionSeam } from './openchamber.js';
+
+export interface HttpOpenChamberSeamOptions {
+  /** 完整端点 URL（provider 决定路径）；缺省读 env `MEBULAR_FLEET_OPENCHAMBER_ENDPOINT` */
+  endpoint?: string;
+  /** 内联 token；缺省 `MEBULAR_FLEET_OPENCHAMBER_TOKEN` */
+  token?: string;
+  /** 从文件读 token；缺省 `MEBULAR_FLEET_OPENCHAMBER_TOKEN_FILE` */
+  tokenFile?: string;
+  /** 文件为 JSON 时取该点分路径；缺省 `MEBULAR_FLEET_OPENCHAMBER_TOKEN_JSON_PATH` 或 `token` */
+  tokenJsonPath?: string;
+  /** 鉴权头名（provider 决定，默认 `X-Bridge-Token`）；缺省 `MEBULAR_FLEET_OPENCHAMBER_AUTH_HEADER` */
+  authHeader?: string;
+  /** 等待上限（默认 600000ms，且不超过 600s） */
+  timeoutMs?: number;
+}
+
+interface BridgeReply {
+  ok: boolean;
+  result?: { text?: string; sessionId?: string; ms?: number };
+  error?: string;
+}
+
+function env(name: string): string | undefined {
+  const value = process.env[name];
+  return value === undefined || value === '' ? undefined : value;
+}
+
+/** 读取 token：文件是 JSON 则按 `jsonPath` 取值，否则取整文件文本。 */
+function readTokenFromFile(file: string, jsonPath: string): string | null {
+  try {
+    const raw = readFileSync(file, 'utf-8').trim();
+    if (raw.startsWith('{')) {
+      let node: unknown = JSON.parse(raw);
+      for (const key of jsonPath.split('.')) {
+        if (typeof node !== 'object' || node === null) return null;
+        node = (node as Record<string, unknown>)[key];
+      }
+      return typeof node === 'string' && node.length > 0 ? node : null;
+    }
+    return raw.length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 本机 HTTP POST JSON；连接失败/超时/非 JSON → null 或 `{ok:false}`；错误不夹带 token。 */
+function postJson(endpoint: string, token: string, authHeader: string, body: string, timeoutMs: number): Promise<BridgeReply | null> {
+  return new Promise((resolve) => {
+    let url: URL;
+    try {
+      url = new URL(endpoint);
+    } catch {
+      resolve(null);
+      return;
+    }
+    const req = http.request(
+      {
+        host: url.hostname,
+        port: url.port,
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+          [authHeader]: token,
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data) as BridgeReply);
+          } catch {
+            resolve({ ok: false, error: `provider returned non-JSON (status ${res.statusCode ?? '?'})` });
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve(null)); // 不回传底层细节（避免泄露端点/凭据）
+    req.setTimeout(Math.max(1, timeoutMs), () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+/** 中立 HTTP seam（provider 只决定 endpoint/token/字段）。 */
+export class HttpOpenChamberSeam implements OpenChamberSessionSeam {
+  constructor(private readonly options: HttpOpenChamberSeamOptions = {}) {}
+
+  private resolveToken(): string | null {
+    const inline = this.options.token ?? env('MEBULAR_FLEET_OPENCHAMBER_TOKEN');
+    if (inline !== undefined) return inline;
+    const file = this.options.tokenFile ?? env('MEBULAR_FLEET_OPENCHAMBER_TOKEN_FILE');
+    if (file === undefined) return null;
+    const jsonPath = this.options.tokenJsonPath ?? env('MEBULAR_FLEET_OPENCHAMBER_TOKEN_JSON_PATH') ?? 'token';
+    return readTokenFromFile(file, jsonPath);
+  }
+
+  async prompt(input: OpenChamberPromptInput): Promise<{ text: string; sessionId?: string; error?: string }> {
+    const endpoint = this.options.endpoint ?? env('MEBULAR_FLEET_OPENCHAMBER_ENDPOINT');
+    if (endpoint === undefined) return { text: '', error: 'openchamber endpoint not configured' };
+    const token = this.resolveToken();
+    if (token === null) return { text: '', error: 'openchamber token unavailable' };
+
+    const timeoutMs = Math.max(1, Math.min(input.timeoutMs ?? this.options.timeoutMs ?? 600_000, 600_000));
+    const payload: Record<string, unknown> = { prompt: input.prompt, timeoutSec: Math.ceil(timeoutMs / 1000) };
+    if (input.agent !== undefined) payload.agent = input.agent;
+    if (input.model !== undefined) payload.model = input.model;
+
+    const authHeader = this.options.authHeader ?? env('MEBULAR_FLEET_OPENCHAMBER_AUTH_HEADER') ?? 'X-Bridge-Token';
+    const reply = await postJson(endpoint, token, authHeader, JSON.stringify(payload), timeoutMs);
+    if (reply === null) return { text: '', error: 'openchamber provider unavailable or timed out' };
+    if (reply.ok !== true) return { text: '', error: reply.error ?? 'openchamber provider error' };
+    const result = reply.result ?? {};
+    return {
+      text: typeof result.text === 'string' ? result.text : '',
+      ...(typeof result.sessionId === 'string' ? { sessionId: result.sessionId } : {}),
+    };
+  }
+}

package/src/runtime/openchamber.ts

@@ -0,0 +1,66 @@
+// OpenChamber Agent 适配器（M4）：**中立接口 + 执行器**。
+//
+// fleet 对 provider 毫不知情：`OpenChamberAgent` 只依赖注入的 `OpenChamberSessionSeam`（prompt →
+// {text, sessionId?, error?}），选项仅 `timeoutMs/maxOutputBytes/cwd/model/agent`。具体 provider
+// 由调用方注入（字段与错误码见 `packages/fleet/OPENCHAMBER-SEAM.md`）。
+// 当前 provider #1 是 oc-hermes-bridge daemon 的 `POST /agent/run-once`（见 `openchamber-http.ts`
+// 的中立 HTTP seam）；将来换成独立 provider 或 OpenChamber 官方 API，**不改本文件**。
+
+import type { TaskState } from '../model.js';
+import type { ExecutionOutcome, TaskExecutor } from './executor.js';
+import { truncateOutput } from './agent.js';
+
+/** 一次会话提示的输入。 */
+export interface OpenChamberPromptInput {
+  prompt: string;
+  cwd?: string;
+  model?: string;
+  agent?: string;
+  /** 期望的最长等待（seam 实现负责超时并在超时后抛错/返回失败） */
+  timeoutMs?: number;
+}
+
+/** OpenChamber 会话 seam：把「运行一次提示」抽象出来，交由 OpenChamber 侧实现。 */
+export interface OpenChamberSessionSeam {
+  /**
+   * 运行一次 OpenChamber 会话提示，返回最终文本与（可选）会话 id。
+   * 超时/失败应以异常或 `{ error }` 表达；实现方不得在此打印/落盘任何凭据。
+   */
+  prompt(input: OpenChamberPromptInput): Promise<{ text: string; sessionId?: string; error?: string }>;
+}
+
+export interface OpenChamberAgentOptions {
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  cwd?: string;
+  model?: string;
+  agent?: string;
+}
+
+/** 基于注入 seam 的 OpenChamber 执行器（默认不接任何真实通道）。 */
+export class OpenChamberAgent implements TaskExecutor {
+  constructor(
+    private readonly seam: OpenChamberSessionSeam,
+    private readonly options: OpenChamberAgentOptions = {},
+  ) {}
+
+  async execute(task: TaskState): Promise<ExecutionOutcome> {
+    const input: OpenChamberPromptInput = { prompt: task.intent };
+    if (this.options.cwd !== undefined) input.cwd = this.options.cwd;
+    if (this.options.model !== undefined) input.model = this.options.model;
+    if (this.options.agent !== undefined) input.agent = this.options.agent;
+    if (this.options.timeoutMs !== undefined) input.timeoutMs = this.options.timeoutMs;
+    try {
+      const result = await this.seam.prompt(input);
+      if (result.error !== undefined) return { ok: false, reason: `OPENCHAMBER_ERROR: ${result.error}` };
+      const truncated = truncateOutput(result.text.trim(), this.options.maxOutputBytes ?? 65_536);
+      return {
+        ok: true,
+        ...(result.sessionId !== undefined ? { reason: `session:${result.sessionId}` } : {}),
+        resultRef: truncated.text,
+      };
+    } catch (error) {
+      return { ok: false, reason: `OPENCHAMBER_ERROR: ${(error as Error).message}` };
+    }
+  }
+}

package/src/runtime/planner.ts

@@ -0,0 +1,36 @@
+// 任务派生计划（1d-a 审查 DAG）：worker 执行任务后可按**确定性计划**派生**子任务**。
+//
+// 计划是纯数据/纯函数，便于夹具驱动与确定性 E2E；子任务以既有 `created` 事件承载，
+// `trace.causedBy` 指向父任务、`chain` 为祖先链（禁环由创建守卫保证）。
+
+import type { FleetEndpoint } from '../protocol/envelope.js';
+import type { TaskState } from '../model.js';
+
+/** 计划中的一个子任务。 */
+export interface PlannedChild {
+  intent: string;
+  /** 目标端（缺省 = 父任务的 to） */
+  to?: FleetEndpoint;
+  /** 显式 taskId（缺省 = `<parent>~c<index>`，确定）；**负例**可用它构造环以触发守卫 */
+  taskId?: string;
+  payloadRef?: string;
+}
+
+/** 计划器：由父任务与执行结果派生直接子任务。 */
+export interface TaskPlanner {
+  plan(state: TaskState, outcome: { ok: boolean; resultRef?: string }): PlannedChild[];
+}
+
+/** 确定性子任务 id（无显式 taskId 时使用）。 */
+export function childTaskId(parent: string, index: number): string {
+  return `${parent}~c${index}`;
+}
+
+/** 由 `intent → 子任务[]` 映射构造计划器（缺省 = 无子任务）。 */
+export function mapPlanner(plan: Readonly<Record<string, PlannedChild[]>>): TaskPlanner {
+  return {
+    plan(state) {
+      return (plan[state.intent] ?? []).map((child) => ({ ...child }));
+    },
+  };
+}