@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/__tests__/finalized-marker.test.ts

@@ -0,0 +1,82 @@
+// src/__tests__/finalized-marker.test.ts
+//
+// finalized-marker 专属测试。
+// 覆盖：write→read 往返 / 缺 sidecar → false / best-effort IO 错静默 / .cancelled 互斥。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { readFinalized, writeFinalized } from "../finalized-marker.ts";
+
+describe("finalized-marker", () => {
+  let tmpDir: string;
+  let sessionFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fm-test-"));
+    sessionFile = path.join(tmpDir, "2026-01-01_uuid.jsonl");
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("write → read 往返", () => {
+    it("写入后 readFinalized 返回 true", () => {
+      writeFinalized(sessionFile);
+      expect(readFinalized(sessionFile)).toBe(true);
+    });
+
+    it("sidecar 路径 = sessionFile + '.finalized'", () => {
+      writeFinalized(sessionFile);
+      expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+    });
+
+    it("sidecar 内容为空（存在性即信号）", () => {
+      writeFinalized(sessionFile);
+      const content = fs.readFileSync(`${sessionFile}.finalized`, "utf-8");
+      expect(content).toBe("");
+    });
+  });
+
+  describe("readFinalized 无 sidecar", () => {
+    it("不存在 → false", () => {
+      expect(readFinalized(sessionFile)).toBe(false);
+    });
+  });
+
+  describe("best-effort IO 错静默", () => {
+    it("writeFileSync 抛错时不抛出", () => {
+      // 目标路径不存在（不存在的父目录），writeFileSync 会抛
+      const badPath = path.join(tmpDir, "nonexistent-sub", "session.jsonl");
+      expect(() => writeFinalized(badPath)).not.toThrow();
+    });
+
+    it("写失败后 readFinalized 返回 false（sidecar 未写入）", () => {
+      const badPath = path.join(tmpDir, "nonexistent-sub", "session.jsonl");
+      writeFinalized(badPath); // 静默失败
+      expect(readFinalized(badPath)).toBe(false);
+    });
+  });
+
+  describe("与 .cancelled 互斥（BC-4）", () => {
+    it("写 finalized 时删除已有的 .cancelled", () => {
+      // 先写一个 .cancelled sidecar
+      fs.writeFileSync(`${sessionFile}.cancelled`, `{"id":"bg-1","status":"cancelled","agent":"w","startedAt":1,"endedAt":2}\n`, "utf-8");
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(true);
+
+      // 写 finalized → .cancelled 应被删除
+      writeFinalized(sessionFile);
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+      expect(readFinalized(sessionFile)).toBe(true);
+    });
+
+    it("无 .cancelled 时写 finalized 正常（不报错）", () => {
+      expect(fs.existsSync(`${sessionFile}.cancelled`)).toBe(false);
+      expect(() => writeFinalized(sessionFile)).not.toThrow();
+      expect(readFinalized(sessionFile)).toBe(true);
+    });
+  });
+});

package/src/execution/__tests__/format-schema-instruction.test.ts

@@ -0,0 +1,135 @@
+// src/__tests__/format-schema-instruction.test.ts
+//
+// 锁定 formatSchemaInstruction 契约：构造 schema enforcement 的 MANDATORY 指令。
+// 该字符串被拼入 task 末尾（runSpawn 的 fullTask = task + instruction），且 steer
+// reminder 复用同一文本。一旦漏掉 "MUST call structured-output" 关键词或 JSON
+// 序列化漂移，schema 模式会静默失效——agent 可能直接把 JSON 写进文本响应。
+//
+// 纯函数测试：不依赖 Pi 运行时、不 spawn 进程、不 mock。只 import 被测函数。
+import { describe, expect, it } from "vitest";
+
+import { formatSchemaInstruction } from "../session-runner.ts";
+
+describe("formatSchemaInstruction", () => {
+  // ── 指令文本契约 ──────────────────────────────────────────────
+
+  it("contains the structured-output tool keyword", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("structured-output");
+  });
+
+  it("emits a MANDATORY structured-output directive (not free-form JSON)", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    expect(out).toContain("MANDATORY");
+    expect(out).toContain("MUST");
+    expect(out).toContain("MUST call the `structured-output` tool");
+    expect(out).toContain("Do NOT output the JSON directly");
+  });
+
+  // ── schema 序列化 ─────────────────────────────────────────────
+
+  it("embeds the schema as pretty-printed JSON (indent=2) inside a fenced block", () => {
+    const schema: Record<string, unknown> = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    const out = formatSchemaInstruction(schema);
+    // 必须包含 JSON.stringify(schema, null, 2) 的完整结果
+    expect(out).toContain(JSON.stringify(schema, null, 2));
+    expect(out).toContain("```json");
+    expect(out).toContain("```");
+    // indent=2 的可观察证据：属性键前有恰好两个空格（object 第一层缩进）
+    expect(out).toContain('\n  "type": "object"');
+  });
+
+  it("locks the full output structure for a minimal schema", () => {
+    const out = formatSchemaInstruction({ type: "object" });
+    // 完整结构快照——任何指令措辞/顺序/缩进漂移都会被捕获。
+    // 注意第三行末尾的 em-dash（—），防止有人把它替换成普通连字符。
+    expect(out).toBe(
+      [
+        "MANDATORY: Structured Output Requirement",
+        "You MUST call the `structured-output` tool with your final answer.",
+        "Do NOT output the JSON directly in your text response — you MUST use the structured-output tool.",
+        "The schema for the structured output is:",
+        "```json",
+        '{',
+        '  "type": "object"',
+        '}',
+        "```",
+      ].join("\n"),
+    );
+  });
+
+  // ── 特殊字符转义（注入风险路径）──────────────────────────────
+
+  it("escapes double quotes inside schema string values", () => {
+    const schema: Record<string, unknown> = { prompt: 'say "hi"' };
+    const out = formatSchemaInstruction(schema);
+    // JSON.stringify 会把内层 " 转义为 \"
+    expect(out).toContain('say \\"hi\\"');
+    // 原始未转义形式（含成对字面双引号）绝不能回流进 JSON 体内
+    expect(out).not.toContain('say "hi"');
+  });
+
+  it("escapes newlines inside schema string values", () => {
+    const schema: Record<string, unknown> = { text: "line1\nline2" };
+    const out = formatSchemaInstruction(schema);
+    // 换行被序列化为字面反斜杠-n，不能是真实换行符
+    expect(out).toContain("line1\\nline2");
+    expect(out).not.toContain("line1\nline2");
+  });
+
+  it("escapes backslashes inside schema string values", () => {
+    const schema: Record<string, unknown> = { path: "C:\\Users\\x" };
+    const out = formatSchemaInstruction(schema);
+    // 单反斜杠被序列化为 \\，避免后续解析误把转义序列当指令
+    expect(out).toContain("C:\\\\Users\\\\x");
+    expect(out).not.toContain("C:\\Users\\x");
+  });
+
+  // ── 边界值 ────────────────────────────────────────────────────
+
+  it("handles empty schema object", () => {
+    const out = formatSchemaInstruction({});
+    expect(out).toContain("structured-output");
+    expect(out).toContain("{}");
+  });
+
+  it("preserves null values in schema", () => {
+    const schema: Record<string, unknown> = { default: null };
+    const out = formatSchemaInstruction(schema);
+    // JSON.stringify 对 null 保留字面 "null"（不会 omit 键，也不会变字符串）
+    expect(out).toContain('"default": null');
+  });
+
+  it("serializes nested objects and arrays", () => {
+    const schema: Record<string, unknown> = {
+      type: "object",
+      required: ["name", "age"],
+      properties: {
+        name: { type: "string" },
+        age: { type: "integer", minimum: 0 },
+      },
+    };
+    const out = formatSchemaInstruction(schema);
+    expect(out).toContain(JSON.stringify(schema, null, 2));
+    // 嵌套结构 indent 正确（第二层 4 空格）
+    expect(out).toContain('    "name": {');
+    expect(out).toContain('      "type": "string"');
+  });
+
+  // ── 确定性 ────────────────────────────────────────────────────
+
+  it("is deterministic — same schema produces identical output", () => {
+    const schema: Record<string, unknown> = { a: 1, b: [2, 3] };
+    expect(formatSchemaInstruction(schema)).toBe(formatSchemaInstruction(schema));
+  });
+
+  it("is deterministic across different object key insertion (value-equal schemas)", () => {
+    // JSON.stringify 按对象自身属性顺序序列化；同序构造的等价 schema 应产出相同指令
+    const a: Record<string, unknown> = { x: 1, y: 2 };
+    const b: Record<string, unknown> = { x: 1, y: 2 };
+    expect(formatSchemaInstruction(a)).toBe(formatSchemaInstruction(b));
+  });
+});

package/src/execution/__tests__/format.test.ts

@@ -0,0 +1,320 @@
+// src/__tests__/format.test.ts
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { describe, expect, it } from "vitest";
+
+import {
+  formatElapsedSeconds,
+  formatTokens,
+  padToVisible,
+  sanitizeLabel,
+  segFillColored,
+  shortId,
+  spinnerGlyph,
+  statusGlyph,
+  truncLine,
+  wrapText,
+} from "../../interface/format.ts";
+
+// ============================================================
+// formatTokens
+// ============================================================
+describe("formatTokens", () => {
+  it("shows plain value below 1000", () => {
+    expect(formatTokens(0)).toBe("0");
+    expect(formatTokens(820)).toBe("820");
+    expect(formatTokens(999)).toBe("999");
+  });
+
+  it("shows N.Nk between 1000 and 9999", () => {
+    expect(formatTokens(1000)).toBe("1.0k");
+    expect(formatTokens(8200)).toBe("8.2k");
+    expect(formatTokens(9999)).toBe("10.0k");
+  });
+
+  it("shows rounded Nk at 10000+", () => {
+    expect(formatTokens(10000)).toBe("10k");
+    expect(formatTokens(23000)).toBe("23k");
+    expect(formatTokens(99999)).toBe("100k");
+  });
+});
+
+// ============================================================
+// formatElapsedSeconds
+// ============================================================
+describe("formatElapsedSeconds", () => {
+  it("shows Xs below 60", () => {
+    expect(formatElapsedSeconds(0)).toBe("0s");
+    expect(formatElapsedSeconds(12)).toBe("12s");
+    expect(formatElapsedSeconds(59)).toBe("59s");
+  });
+
+  it("shows Xm Ys between 60 and 3599", () => {
+    expect(formatElapsedSeconds(60)).toBe("1m0s");
+    expect(formatElapsedSeconds(72)).toBe("1m12s");
+    expect(formatElapsedSeconds(3599)).toBe("59m59s");
+  });
+
+  it("shows Xh Ym at 3600+", () => {
+    expect(formatElapsedSeconds(3600)).toBe("1h0m");
+    expect(formatElapsedSeconds(3661)).toBe("1h1m");
+    expect(formatElapsedSeconds(7325)).toBe("2h2m");
+  });
+});
+
+// ============================================================
+// statusGlyph
+// ============================================================
+describe("statusGlyph", () => {
+  it("running → no icon, accent color", () => {
+    expect(statusGlyph("running")).toEqual({ icon: undefined, color: "accent" });
+  });
+
+  it("done → checkmark, success", () => {
+    expect(statusGlyph("done")).toEqual({ icon: "✓", color: "success" });
+  });
+
+  it("failed → cross, error", () => {
+    expect(statusGlyph("failed")).toEqual({ icon: "✗", color: "error" });
+  });
+
+  it("cancelled → square, muted", () => {
+    expect(statusGlyph("cancelled")).toEqual({ icon: "■", color: "muted" });
+  });
+});
+
+// ============================================================
+// spinnerGlyph
+// ============================================================
+describe("spinnerGlyph", () => {
+  it("returns a frame for valid seed", () => {
+    expect(spinnerGlyph(0)).toBe("⠋");
+    expect(spinnerGlyph(1)).toBe("⠙");
+    expect(spinnerGlyph(9)).toBe("⠏");
+  });
+
+  it("wraps around (mod 10)", () => {
+    expect(spinnerGlyph(10)).toBe("⠋");
+    expect(spinnerGlyph(15)).toBe("⠴"); // index 5
+  });
+
+  it("falls back to frame 0 on NaN", () => {
+    expect(spinnerGlyph(NaN)).toBe("⠋");
+  });
+
+  it("handles negative seeds via abs", () => {
+    expect(spinnerGlyph(-1)).toBe("⠙"); // abs(-1) % 10 = 1 → ⠙
+    expect(spinnerGlyph(-10)).toBe("⠋");
+  });
+
+  it("falls back to frame 0 on Infinity", () => {
+    expect(spinnerGlyph(Infinity)).toBe("⠋");
+  });
+});
+
+// ============================================================
+// sanitizeLabel
+// ============================================================
+describe("sanitizeLabel", () => {
+  it("replaces CRLF/LF with single space", () => {
+    expect(sanitizeLabel("line1\r\nline2\nline3")).toBe("line1 line2 line3");
+  });
+
+  it("replaces tabs with 2 spaces", () => {
+    expect(sanitizeLabel("a\tb")).toBe("a  b");
+  });
+
+  it("collapses multiple consecutive newlines into one space", () => {
+    // /[\r\n]+/g treats \r\n\r\n as one match → single space
+    expect(sanitizeLabel("a\r\n\r\nb")).toBe("a b");
+  });
+
+  it("leaves clean text unchanged", () => {
+    expect(sanitizeLabel("read foo.ts")).toBe("read foo.ts");
+  });
+});
+
+// ============================================================
+// padToVisible
+// ============================================================
+describe("padToVisible", () => {
+  it("pads short text to width with trailing spaces", () => {
+    expect(padToVisible("ab", 5)).toBe("ab   ");
+  });
+
+  it("returns unchanged when already at width", () => {
+    expect(padToVisible("hello", 5)).toBe("hello");
+  });
+
+  it("returns unchanged when wider than width", () => {
+    expect(padToVisible("hello world", 5)).toBe("hello world");
+  });
+
+  it("handles CJK width (2 columns per char)", () => {
+    // 你好 = 4 visible columns
+    expect(padToVisible("你好", 6)).toBe("你好  ");
+  });
+});
+
+// ============================================================
+// segFillColored
+// ============================================================
+describe("segFillColored", () => {
+  it("returns empty string for width <= 0", () => {
+    expect(segFillColored("title", "-", 0)).toBe("");
+    expect(segFillColored("title", "-", -1)).toBe("");
+  });
+
+  it("pure fill when no title", () => {
+    expect(segFillColored(undefined, "-", 5)).toBe("-----");
+  });
+
+  it("title + fill to width", () => {
+    expect(segFillColored("Hi", "-", 5)).toBe("Hi---");
+  });
+
+  it("truncates title when wider than width", () => {
+    const result = segFillColored("Hello World", "-", 5);
+    // title visible width 11 > 5 → truncated to 5 (with ellipsis = 4 chars + …)
+    expect(result.length).toBeLessThanOrEqual(10); // visible width 5 but may include ANSI
+  });
+
+  it("preserves ANSI in title and fill separately (no nesting color loss)", () => {
+    const redTitle = "\x1b[31mHi\x1b[0m";
+    const blueFill = "\x1b[34m-\x1b[0m";
+    const result = segFillColored(redTitle, blueFill, 5);
+    // title visible width = 2 ("Hi"), fill count = 3
+    expect(result).toContain(redTitle);
+    expect(result).toContain(blueFill);
+    // fill repeated 3 times
+    expect(result).toBe(redTitle + blueFill + blueFill + blueFill);
+  });
+});
+
+// ============================================================
+// truncLine
+// ============================================================
+describe("truncLine", () => {
+  it("returns text unchanged when within width", () => {
+    expect(truncLine("hello", 10)).toBe("hello");
+    expect(truncLine("hello", 5)).toBe("hello");
+  });
+
+  it("returns empty string for width <= 0", () => {
+    expect(truncLine("hello", 0)).toBe("");
+  });
+
+  it("truncates with ellipsis when exceeding width", () => {
+    const result = truncLine("hello world", 8);
+    // 纯文本截断不发 \x1b[0m（全局重置会破坏外层背景色）
+    expect(result.endsWith("…")).toBe(true);
+    expect(result).not.toContain("\x1b[0m");
+    // visible width should be 8 (7 chars + ellipsis)
+  });
+
+  it("handles CJK characters (2 columns each)", () => {
+    // 你好世界 = 8 visible columns; truncate to 5 → 2 chars (4 cols) + …
+    const result = truncLine("你好世界", 5);
+    expect(result.endsWith("…")).toBe(true);
+    expect(result).not.toContain("\x1b[0m");
+  });
+
+  it("handles emoji correctly", () => {
+    const result = truncLine("😀😁😂🤣😃", 3);
+    expect(result.endsWith("…")).toBe(true);
+    expect(result).not.toContain("\x1b[0m");
+  });
+
+  it("reapplies active ANSI styles before ellipsis (no background break)", () => {
+    // red text that exceeds width → ellipsis should have red re-applied
+    const input = "\x1b[31mhello world this is long\x1b[0m";
+    const result = truncLine(input, 10);
+    expect(result.endsWith("…\x1b[0m")).toBe(true);
+    // The ellipsis should be preceded by the active red style (re-applied)
+    // Check that the last grapheme sequence includes the red SGR before …
+    expect(result).toMatch(/\x1b\[31m…\x1b\[0m$/);
+  });
+
+  it("clears style stack on reset code", () => {
+    // text with reset in the middle → after reset, no style re-applied
+    const input = "\x1b[31mab\x1b[0mcdefghijk";
+    const result = truncLine(input, 6);
+    // reset 后 activeStyles 为空 → 截断不发 \x1b[0m
+    expect(result.endsWith("…")).toBe(true);
+  });
+
+  it("flattens newlines to spaces (single-line rendering safety)", () => {
+    // 多行 prompt / turn.text 含 \n，单行渲染时 \n 会意外换行破坏行对齐。
+    // truncLine 作为单行渲染入口必须剥离 \n（用空格替代保留词边界）。
+    const multiLine = "只读任务：分析核心逻辑。\n项目根：/Users/test\n输出：报告";
+    const result = truncLine(multiLine, 80);
+    expect(result).not.toContain("\n");
+    expect(result).toContain("只读任务");
+    expect(result).toContain("项目根");
+  });
+
+  it("flattens \r\n sequences", () => {
+    const crlf = "line1\r\nline2\r\nline3";
+    const result = truncLine(crlf, 80);
+    expect(result).not.toContain("\r");
+    expect(result).not.toContain("\n");
+  });
+});
+
+// ============================================================
+// wrapText
+// ============================================================
+describe("wrapText", () => {
+  it("returns text as-is when shorter than width", () => {
+    expect(wrapText("hello", 80)).toEqual(["hello"]);
+  });
+
+  it("wraps long text into multiple lines (no truncation)", () => {
+    const text = "abcdefghij"; // 10 chars
+    const lines = wrapText(text, 4);
+    // 每行最多 4 列，10 字符 → 3 行（4+4+2），不截断不省略号
+    expect(lines.join("")).toBe("abcdefghij");
+    for (const l of lines.slice(0, -1)) {
+      expect(visibleWidth(l)).toBeLessThanOrEqual(4);
+    }
+  });
+
+  it("preserves original newlines as paragraph breaks", () => {
+    const text = "第一行\n第二行";
+    const lines = wrapText(text, 80);
+    expect(lines).toEqual(["第一行", "第二行"]);
+  });
+
+  it("wraps CJK text correctly (2 columns each)", () => {
+    // 你好世界你好世界 = 8 CJK chars = 16 columns, wrap to 4 columns
+    const text = "你好世界你好世界";
+    const lines = wrapText(text, 4);
+    // 每行最多 4 列 = 2 CJK chars, 共 4 行
+    expect(lines).toHaveLength(4);
+    expect(lines.join("")).toBe(text);
+  });
+
+  it("handles width <= 0 by returning original", () => {
+    expect(wrapText("hello", 0)).toEqual(["hello"]);
+  });
+
+  it("preserves empty lines from blank paragraphs", () => {
+    const text = "a\n\nb";
+    expect(wrapText(text, 80)).toEqual(["a", "", "b"]);
+  });
+});
+
+// ============================================================
+// shortId
+// ============================================================
+describe("shortId", () => {
+  it("returns sync id unchanged (run-N already short)", () => {
+    expect(shortId("run-1")).toBe("run-1");
+    expect(shortId("run-42")).toBe("run-42");
+  });
+
+  it("strips timestamp from background id (bg-tag-seq-<ts> → bg-tag-seq)", () => {
+    // 真实格式：bg-${6位hex tag}-${seq}-${Date.now()}（subagent-service.ts:422）
+    expect(shortId("bg-f6f731-10-1719500000000")).toBe("bg-f6f731-10");
+    expect(shortId("bg-abc123-99-1719500123456")).toBe("bg-abc123-99");
+  });
+});

package/src/execution/__tests__/helpers/mock-extension-api.ts

@@ -0,0 +1,30 @@
+/**
+ * 创建一个结构兼容的 ExtensionAPI mock，供 sdk-contract / 注册契约测试用。
+ *
+ * ExtensionAPI 有 ~30 个必需方法（on/registerTool/registerCommand/...），逐个手写
+ * 不现实。本 helper 用 Proxy 把所有未显式 override 的方法/属性短路为 no-op 函数，
+ * 让对象**结构兼容** ExtensionAPI——避免 `as unknown as ExtensionAPI` 双重断言
+ * （taste/no-unsafe-cast 规则禁止）。测试只需 override 关心的方法：
+ *
+ *   const pi = mockExtensionApi({
+ *     registerCommand: (name) => { capturedName = name; },
+ *   });
+ *
+ * Proxy 的 trap 对所有属性访问返回 override 值或 no-op 函数，运行时安全
+ * （注册 handler 只调用被 override 的方法，其余方法测试不触及）。
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export function mockExtensionApi(
+  overrides: Record<string, unknown> = {},
+): ExtensionAPI {
+  const noop = (): void => { /* test mock: method not invoked by this test */ };
+  // Proxy<T> 泛型参数决定返回类型——直接声明为 ExtensionAPI，
+  // TS 接受（Proxy handler 对 target 的类型不约束 T）。
+  return new Proxy<ExtensionAPI>(overrides as ExtensionAPI, {
+    get(target, prop: string | symbol): unknown {
+      if (prop in target) return target[prop as keyof ExtensionAPI];
+      return noop;
+    },
+  });
+}