@zhushanwen/subagent-core 0.2.0

package/src/execution/engine/common/errors.ts

@@ -0,0 +1,183 @@
+// src/execution/engine/common/errors.ts
+//
+// 引擎层错误 SSOT（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md §3.3.3 错误规格全表（11 条）。
+//
+// 为什么集中一处：错误文案契约（code + 恢复指引）被三层消费——公共降级层
+// （prompt_too_large / nested_spawn_rejected / engine_timeout）、后续 wave 的路由与
+// 探针（engine_not_found / engine_probe_failed / model_not_available）、引擎适配器
+// （engine_run_failed / engine_session_not_resumable）。散落各处会漂移成同一错误
+// 多种文案，GUI 无法按 code 分流。
+//
+// 与 registry.ts 的 EngineNotFoundError 的关系：那是 P1 随注册表落地的
+// engine_not_found 错误类（getEngine 抛出），本文件不复制其类定义、只对齐 code
+// 字面量——后续 wave 统一收敛时以本表为 SSOT。
+
+// ============================================================
+// 错误码全集（§3.3.3 表 code 列，顺序与设计文档一致）
+// ============================================================
+
+export const ENGINE_ERROR_CODES = [
+  "engine_not_found",
+  "engine_probe_failed",
+  "engine_credential_missing",
+  "nested_spawn_rejected",
+  "schema_emulation_failed",
+  "engine_timeout",
+  "engine_capability_unsupported",
+  "engine_session_not_resumable",
+  "model_not_available",
+  "prompt_too_large",
+  "engine_run_failed",
+] as const;
+
+export type EngineErrorCode = (typeof ENGINE_ERROR_CODES)[number];
+
+/** unknown → EngineErrorCode 收窄（外部输入携带错误码时的运行时 guard）。 */
+export function isEngineErrorCode(value: unknown): value is EngineErrorCode {
+  return typeof value === "string" && (ENGINE_ERROR_CODES as readonly string[]).includes(value);
+}
+
+// ============================================================
+// 错误类（code + 恢复指引的结构化载体）
+// ============================================================
+
+/**
+ * 引擎层结构化错误。message 恒为 `<code>: <detail>` 前缀格式（AgentOutcome.error
+ * 的错误码前缀约定，§3.3.5）；recovery 指向恢复动作（全局规则：错误信息必须可操作）。
+ */
+export class EngineError extends Error {
+  readonly code: EngineErrorCode;
+  /** 恢复指引：指向具体下一步（命令 / 配置路径 / 替代方案），非安慰性文案。 */
+  readonly recovery: string;
+
+  constructor(code: EngineErrorCode, detail: string, recovery: string) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineError";
+    this.code = code;
+    this.recovery = recovery;
+  }
+
+  /** 结构化投影（InteractResult.code/message 与 GUI 警告条共用形态）。 */
+  toStructured(): { code: EngineErrorCode; message: string; recovery: string } {
+    return { code: this.code, message: this.message, recovery: this.recovery };
+  }
+}
+
+// ============================================================
+// 默认恢复指引模板（§3.3.3 恢复指引列的静态部分）
+// ============================================================
+
+/**
+ * 11 条错误的默认恢复指引。Record<EngineErrorCode, string> 使 TS 强制全集覆盖——
+ * 新增错误码漏写模板会在此处编译失败，而不是运行时空指引。
+ * 含动态参数的恢复指引（版本命令 / 模型清单 / 字节数）用下方具名构造器，不走此表。
+ */
+export const DEFAULT_RECOVERY_HINTS: Record<EngineErrorCode, string> = {
+  engine_not_found:
+    "Check the engine id in the agent .md frontmatter (engine: field) against the registered engine list, " +
+    "fix the typo, or install/register the engine first.",
+  engine_probe_failed:
+    "Confirm the engine version (e.g. `<engine> --version`), then re-run the engine probe. " +
+    "For contract drift, see docs/research/agent-engine-*.md for the expected output format.",
+  engine_credential_missing:
+    "Configure the engine credentials (see the engine credential section of docs/research/agent-engine-*.md), " +
+    "then retry — the preparer cannot synthesize credentials it has no source for.",
+  nested_spawn_rejected:
+    "Subagents must not spawn further subagents (unbounded recursion guard). " +
+    "Do the work directly inside the current task instead of delegating.",
+  schema_emulation_failed:
+    "The model output failed JSON extraction or schema validation. Retry once with a strengthened prompt " +
+    "(buildSchemaEmulationSegment output + the error tail); if it still fails, relax the schema or switch to a " +
+    "schema-native engine (engine: pi).",
+  engine_timeout:
+    "The engine was killed by the host timeout chain. Inspect the captured stdout tail, then re-run with a larger " +
+    "timeout, a narrower task, or `engine: pi`.",
+  engine_capability_unsupported:
+    "This engine declares the capability unsupported. Use a single-shot call instead of interactive steering, " +
+    "or dispatch with `engine: pi` which supports it.",
+  engine_session_not_resumable:
+    "Idle-process reuse does not survive a main-session reload. Use a cold resume path " +
+    "(engine --resume / --session with the recorded session reference), or start a new subagent.",
+  model_not_available:
+    "The requested model is not resolvable in this engine's provider system. Pick a model from the engine's " +
+    "available model list — the host never swaps engines implicitly on model mismatch.",
+  prompt_too_large:
+    "Shorten the task text, move the persona to the file channel, or use an engine with a stdin prompt channel.",
+  engine_run_failed:
+    "The engine process failed at runtime (parse failure / non-zero exit / contract drift). " +
+    "Check the captured stdout tail and exit code, confirm the engine version, re-run the probe, or retry with `engine: pi`.",
+};
+
+// ============================================================
+// P2 消费的具名构造器（动态参数进 detail/recovery）
+// ============================================================
+
+/** 错误回显长度上限（截断长输出，避免错误消息爆炸——对齐 structured-output echo 上限量级）。 */
+const DETAIL_ECHO_MAX_CHARS = 200;
+
+/** truncate(text, max)：尾部截断 + 省略号标记（模板共用）。 */
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+
+/**
+ * prompt_too_large（persona-router 的 argv 预算拦截消费）：仅 argv 投递的引擎在
+ * prepare 期报——禁止 spawn 后撞 E2BIG 才失败（§3.3.3 第 10 行）。
+ */
+export function promptTooLargeError(actualBytes: number, limitBytes: number): EngineError {
+  return new EngineError(
+    "prompt_too_large",
+    `estimated argv size ${actualBytes} bytes exceeds the ${limitBytes}-byte budget`,
+    DEFAULT_RECOVERY_HINTS.prompt_too_large,
+  );
+}
+
+/** nested_spawn_rejected（nesting-guard 消费）：文案说明防护规则 + 指向 task 内自行完成。 */
+export function nestedSpawnRejectedError(): EngineError {
+  return new EngineError(
+    "nested_spawn_rejected",
+    "this process is already a subagent (XYZ_AGENT_SUBAGENT=1)",
+    DEFAULT_RECOVERY_HINTS.nested_spawn_rejected,
+  );
+}
+
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+export const STDOUT_TAIL_ECHO_CHARS = 2000;
+
+/**
+ * engine_timeout 的 outcome.error 文案（kill-chain 的 synthesizeTimeoutOutcome 消费）：
+ * 含 stdout 尾部 2000 字 + 「可用 engine: pi 重跑」建议（§3.3.3 第 6 行）。
+ */
+export function engineTimeoutDetail(stdoutTail: string): string {
+  return (
+    `host timeout chain exhausted (SIGTERM -> grace -> SIGKILL). ` +
+    `Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.engine_timeout}`
+  );
+}
+
+/**
+ * engine_run_failed 的 outcome.error 文案：含 stdout 尾部 2000 字 + exit code +
+ * 恢复指引（版本确认 + 探针重跑 / engine: pi 重跑，§3.3.3 第 11 行）。
+ */
+export function engineRunFailedDetail(reason: string, exitCode: number | null, stdoutTail: string): string {
+  const exit = exitCode === null ? "killed by signal" : `exit code ${exitCode}`;
+  return (
+    `engine failed at runtime: ${reason} (${exit}). ` +
+    `Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.engine_run_failed}`
+  );
+}
+
+/**
+ * schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）：
+ * 与 structured-output 的重试语义对齐（重试一次 → 报错含原始输出尾部）。
+ */
+export function schemaEmulationFailedDetail(error: string, tail: string): string {
+  return (
+    `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. ` +
+    `Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.schema_emulation_failed}`
+  );
+}

package/src/execution/engine/common/event-journal.ts

@@ -0,0 +1,254 @@
+// src/execution/engine/common/event-journal.ts
+//
+// 宿主 event journal（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D6（第②级归属宿主——host 统一落盘
+// 则全引擎免费获得、格式唯一）+ §3.3.6 event journal 格式（JSONL 中立 v1）。
+//
+// 为什么 host 落盘而非各 adapter 缓存：adapter 各自缓存会演变出六种格式；host 消费
+// onEvent 统一落盘，read 第②级（journal 重放）与探针 golden 语料共用同一份产物。
+//
+// 写入纪律（§3.3.6）：onEvent 回调内追加写（有界缓冲 + 批量 flush），run 终态后
+// flush 并 fsync 一次。journal 不随池删（D5），生命周期跟随 record。
+//
+// 失败语义：journal 是降级链第②级（尽力而为的数据源）——写失败不炸主流程：
+// warn 一次 + 置 failed，后续 append 丢弃、close 立即返回（不静默：warn 有留痕）。
+
+import { appendFile, mkdir, open } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { getLogger } from "../../../core/logger.ts";
+
+import type { AgentEvent } from "../../types.ts";
+
+const logger = getLogger("subagents");
+
+// ============================================================
+// 中立行格式（§3.3.6 v1）
+// ============================================================
+
+/** journal 单行（JSONL）。seq 是 host 侧单调递增序号——重放顺序权威。 */
+export interface JournalLine {
+  v: 1;
+  /** host 落盘时刻（Date.now()，ms）。 */
+  ts: number;
+  /** = RunContext.taskId = record.id（journal 文件名与池引用计数 key）。 */
+  taskId: string;
+  engineId: string;
+  seq: number;
+  /** AgentEvent 原样（onEvent 回调对象的 JSON.stringify 直接产物，无二次变换）。 */
+  event: AgentEvent;
+}
+
+// ============================================================
+// JournalWriter
+// ============================================================
+
+/** flush 触发的缓冲阈值：行数与字节数任一到达即批量落盘（有界缓冲）。 */
+const FLUSH_THRESHOLD_LINES = 64;
+// eslint-disable-next-line no-magic-numbers -- 32KB = 32 * 1024 bytes 缓冲字节换算常数
+const FLUSH_THRESHOLD_BYTES = 32 * 1024;
+
+/** FileHandle 的结构子集（close 期 fsync 用；注入 fake 可测）。 */
+export interface FileHandleLike {
+  sync(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** writer 的文件系统依赖面（结构接口：测试注入 fake，免 vi.mock 整个 fs 模块）。 */
+export interface JournalFsDeps {
+  mkdir(path: string, opts: { recursive: boolean }): Promise<unknown>;
+  appendFile(path: string, data: string): Promise<void>;
+  open(path: string, flags: string): Promise<FileHandleLike>;
+}
+
+const defaultFs: JournalFsDeps = {
+  mkdir: (p, o) => mkdir(p, o),
+  appendFile: (p, d) => appendFile(p, d, "utf8"),
+  open: (p, f) => open(p, f),
+};
+
+/** JournalWriter 构造参数。 */
+export interface JournalWriterOpts {
+  /** journal 文件绝对路径（经 paths.ts resolveJournalPath 派生，禁自拼）。 */
+  path: string;
+  taskId: string;
+  engineId: string;
+}
+
+/**
+ * 追加写 writer：append 同步入队（onEvent 是同步回调，不阻塞事件流），批量异步
+ * flush；close = flush 全部 + fsync 一次（§3.3.6 写入纪律）。
+ *
+ * 文件惰性创建：首个 flush 才 mkdir + appendFile——无事件的任务不产生空 journal。
+ */
+export class JournalWriter {
+  private readonly opts: JournalWriterOpts;
+  private readonly fs: JournalFsDeps;
+  private readonly warn: (msg: string) => void;
+
+  private buffer: string[] = [];
+  private bufferedBytes = 0;
+  private seq = 0;
+  /** 串行化异步写（promise 链），防交错 append。 */
+  private chain: Promise<void> = Promise.resolve();
+  private failed = false;
+  private closed = false;
+  /** 是否成功落过盘——close 的 fsync 只对已存在的文件做（无事件任务不产生空文件）。 */
+  private wrote = false;
+
+  constructor(opts: JournalWriterOpts, fs: JournalFsDeps = defaultFs, warn: (msg: string) => void = defaultWarn) {
+    this.opts = opts;
+    this.fs = fs;
+    this.warn = warn;
+  }
+
+  /** 追加一个事件（同步入队；缓冲达阈值自动排队 flush）。closed/failed 后丢弃。 */
+  append(event: AgentEvent): void {
+    if (this.failed || this.closed) return;
+    const line: JournalLine = {
+      v: 1,
+      ts: Date.now(),
+      taskId: this.opts.taskId,
+      engineId: this.opts.engineId,
+      seq: this.seq++,
+      event,
+    };
+    const serialized = JSON.stringify(line);
+    this.buffer.push(serialized);
+    this.bufferedBytes += serialized.length;
+    if (this.buffer.length >= FLUSH_THRESHOLD_LINES || this.bufferedBytes >= FLUSH_THRESHOLD_BYTES) {
+      void this.flush();
+    }
+  }
+
+  /** 把缓冲写入磁盘（串行排队；等待此前所有排队写完成）。 */
+  flush(): Promise<void> {
+    if (this.failed || this.buffer.length === 0) return this.chain;
+    const chunk = `${this.buffer.join("\n")}\n`;
+    this.buffer = [];
+    this.bufferedBytes = 0;
+    this.chain = this.chain.then(() => this.writeChunk(chunk));
+    return this.chain;
+  }
+
+  /** run 终态后调用：flush 全部 + fsync 一次 + 关闭（幂等）。 */
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.flush();
+    if (this.failed || !this.wrote) return;
+    // fsync 一次（§3.3.6）：进程崩溃后已 flush 的行不丢——record 读第②级的一致性依据
+    this.chain = this.chain.then(async () => {
+      const fh = await this.fs.open(this.opts.path, "r");
+      try {
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+    });
+    await this.chain;
+  }
+
+  /** 是否已写失败（降级诊断用；failed 后 journal 不可作为②级数据源）。 */
+  get isFailed(): boolean {
+    return this.failed;
+  }
+
+  /**
+   * 重定向落盘路径（对齐点③：journal 路径权威 = 引擎声明的池 key）。
+   * 仅在尚未落盘（wrote=false）时允许——已 flush 过的文件搬家会制造两份半截 journal，
+   * 重放语义破坏；已落盘时 warn 拒绝（不静默）。事件在重定向前到达的场景由调用方
+   * 契约保证（RunContext.onPoolResolved 注释：引擎须在首个事件 emit 前回调）。
+   */
+  retarget(path: string): void {
+    if (this.closed || this.failed) return;
+    if (this.wrote) {
+      this.warn(
+        `[event-journal] retarget ignored for task ${this.opts.taskId}: journal already flushed to ` +
+          `${this.opts.path} (events must not precede onPoolResolved)`,
+      );
+      return;
+    }
+    this.opts.path = path;
+  }
+
+  /** 当前落盘路径（handle.journalPath 回填数据源）。 */
+  get path(): string {
+    return this.opts.path;
+  }
+
+  private async writeChunk(chunk: string): Promise<void> {
+    try {
+      await this.fs.mkdir(dirname(this.opts.path), { recursive: true });
+      await this.fs.appendFile(this.opts.path, chunk);
+      this.wrote = true;
+    } catch (err) {
+      // 尽力而为语义：一次写失败即永久放弃（重试追写会产生乱序行），warn 留痕不静默
+      this.failed = true;
+      this.buffer = [];
+      this.warn(
+        `[event-journal] write failed, journal for task ${this.opts.taskId} is unavailable ` +
+          `(read falls back to lower tiers): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+function defaultWarn(msg: string): void {
+  logger.warn(msg);
+}
+
+// ============================================================
+// 重放
+// ============================================================
+
+/**
+ * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。
+ *
+ * - 文件不存在 → []（降级链语义：②级不可达不算错误，调用方落 ③级）；
+ * - 损坏行跳过（追加写产物末行可能截断；跳过优于整体失败——设计 C5「三级都不 throw」）；
+ * - 按 seq 稳定排序后返回（重放顺序权威是 seq，不依赖文件行序的隐式保证，§3.3.6）。
+ */
+export function replayJournal(path: string): AgentEvent[] {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const lines: JournalLine[] = [];
+  for (const row of raw.split("\n")) {
+    const trimmed = row.trim();
+    if (trimmed === "") continue;
+    const parsed = parseLine(trimmed);
+    if (parsed !== undefined) lines.push(parsed);
+  }
+  lines.sort((a, b) => a.seq - b.seq);
+  return lines.map((l) => l.event);
+}
+
+/** 单行 parse + 结构 guard（v=1 + event 形状最小判别：object 且 type 为 string）。 */
+function parseLine(trimmed: string): JournalLine | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined;
+  const rec = parsed as Record<string, unknown>;
+  const event = rec.event;
+  if (rec.v !== 1 || typeof rec.ts !== "number" || typeof rec.seq !== "number") return undefined;
+  if (typeof event !== "object" || event === null || typeof (event as Record<string, unknown>).type !== "string") {
+    return undefined;
+  }
+  return {
+    v: 1,
+    ts: rec.ts,
+    taskId: typeof rec.taskId === "string" ? rec.taskId : "",
+    engineId: typeof rec.engineId === "string" ? rec.engineId : "",
+    seq: rec.seq,
+    event: event as AgentEvent,
+  };
+}

package/src/execution/engine/common/journal-replay.ts

@@ -0,0 +1,62 @@
+// src/execution/engine/common/journal-replay.ts
+//
+// read 第②级（宿主 event journal 重放）的公共实现（P4，对齐点①接线）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D6 + §3.3.6「重放等价性」——
+// journal 重放与 live 通路共用同一 reducer（updateFromEvent 范式），不引入第二套
+// 解析器；conformance C5 断言重放 turns 与 live 一致。
+//
+// 为什么放 common：zcode/pi 的 read() ②级降级是同一段逻辑（replayJournal 拿事件流 →
+// live reducer 累积 turns → 投影 SessionView）——放引擎各自实现会漂移出两份形状。
+
+import { createRecord, updateFromEvent } from "../../execution-record.ts";
+import type { AgentEvent } from "../../types.ts";
+import type { EngineHandle, SessionView } from "../types.ts";
+import { replayJournal } from "./event-journal.ts";
+import { aggregateUsage, toReplayedTurn } from "./session-view-projection.ts";
+
+/**
+ * journal → SessionView（read 第②级）。
+ * 返回 undefined = ②级不可达（journal 路径缺省 / 文件不存在 / 无事件），调用方落 ③级。
+ * coarse 引擎（zcode）journal 只含合成事件，重放退化为摘要级——D6 已声明的保真度
+ * 下限，非缺陷。
+ */
+export function replayJournalToSessionView(
+  handle: EngineHandle,
+  engineId: string,
+): SessionView | undefined {
+  const journalPath = handle.data.journalPath;
+  if (journalPath === undefined) return undefined;
+  const events = replayJournal(journalPath);
+  if (events.length === 0) return undefined;
+  return eventsToSessionView(events, engineId, sessionIdFromHandle(handle));
+}
+
+/** 事件流 → SessionView（live reducer 累积 turns——重放等价性的实现体）。 */
+export function eventsToSessionView(
+  events: readonly AgentEvent[],
+  engineId: string,
+  sessionId?: string,
+): SessionView {
+  const record = createRecord("journal-replay", {
+    agent: "journal-replay",
+    model: "",
+    mode: "background",
+    task: "",
+    slug: "",
+    startedAt: 0,
+  });
+  for (const ev of events) updateFromEvent(record, ev);
+  return {
+    engineId,
+    ...(sessionId !== undefined ? { sessionId } : {}),
+    turns: record.turns.map(toReplayedTurn),
+    usage: aggregateUsage(record.turns),
+    source: "journal",
+  };
+}
+
+/** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
+function sessionIdFromHandle(handle: EngineHandle): string | undefined {
+  const v = handle.data.sessionRef["sessionId"];
+  return typeof v === "string" ? v : undefined;
+}