docs(spikes): OpenWorkflow and Pi SDK compatibility spikes + ADR-002/003 (W0-B)

Co-Authored-By: Claude Fable 5.1 <[email protected]>

spikes/pi/abort-resume.ts

@@ -0,0 +1,60 @@
+// Modes: abort | crash | resume. Uses a file-backed JSONL session so a second process can recover.
+import { createModels, fauxProvider } from "@earendil-works/pi-ai";
+import { AgentHarness, BACKGROUND_CONTEXT, JsonlSessionRepo } from "@earendil-works/pi-agent-core";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/harness/env/nodejs";
+import { downloadSubmit, inventoryQuery, script, submitted } from "./common.ts";
+
+const mode = process.argv[2];
+const ctx = BACKGROUND_CONTEXT;
+const faux = fauxProvider({ provider: "umt-fake" });
+const models = createModels();
+models.setProvider(faux.provider);
+faux.setResponses(mode === "resume" ? [script[2]] : script);
+
+const root = new URL("./.sessions", import.meta.url).pathname;
+const fs = new NodeExecutionEnv({ cwd: root }); // used only as FileSystem for session storage; no shell tool is exposed
+const repo = new JsonlSessionRepo({ fileSystem: fs, sessionsRoot: root });
+let session;
+if (mode === "resume") {
+  const list = await repo.list({ cwd: root }, ctx);
+  const meta = list.find((m) => m.id === "crash-demo");
+  console.log("found session", meta?.id, meta?.path);
+  session = await repo.open(meta!, ctx);
+} else {
+  session = await repo.create({ id: mode === "crash" ? "crash-demo" : `abort-${Date.now()}`, cwd: root }, ctx);
+}
+
+const { harness, open } = await AgentHarness.create({
+  session, models, model: faux.getModel(), systemPrompt: "媒体库助手",
+  tools: [inventoryQuery, downloadSubmit], toolContext: { actorId: "user:1", grants: ["download.submit"] },
+  toolExecution: "sequential",
+}, ctx);
+console.log("open operations at attach:", JSON.stringify(open));
+
+let lane = await harness.lane("main", ctx);
+for (const t of ["tool_start", "tool_end", "run_end", "operation_abort", "run_resume"] as const)
+  harness.events.on(t as any, async (e: any) => {
+    console.log(`[${e.type}]${e.recovery ? " (recovery)" : ""} ${e.toolName ?? ""} ${e.status ?? ""} ${e.result ? JSON.stringify(e.result.content[0]?.text).slice(0, 220) : ""}`);
+    if (e.type === "tool_start" && e.toolName === "download__submit") {
+      if (mode === "abort") setTimeout(async () => { console.log(">> lane.abort()"); console.log("abort result:", JSON.stringify(await lane.abort(ctx))); }, 300);
+      if (mode === "crash") setTimeout(() => { console.log(">> SIGKILL self during download.submit"); process.kill(process.pid, "SIGKILL"); }, 300);
+    }
+  });
+
+if (mode === "resume") {
+  const r = await lane.resume(ctx);
+  console.log("RESUME RESULT", JSON.stringify(r));
+} else {
+  const r = await lane.prompt("把《Dune》1080p 收进来", undefined, ctx);
+  console.log("PROMPT RESULT", JSON.stringify(r));
+}
+console.log("SUBMITTED in this process", JSON.stringify(submitted), "fake calls:", faux.state.callCount);
+const entries = (await lane.findEntries(undefined, ctx)).reverse();
+for (const e of entries as any[]) {
+  if (e.type !== "message") { console.log(" entry", e.type); continue; }
+  const m = e.message;
+  const text = m.role === "assistant" ? m.content.map((c: any) => c.type === "toolCall" ? `toolCall(${c.name})` : c.type === "text" ? c.text : `<${c.type}>`).join(" | ")
+    : Array.isArray(m.content) ? m.content.map((c: any) => c.text).join("") : m.content;
+  console.log(` ${m.role.padEnd(10)} ${m.toolName ?? ""} ${m.isError ? "[isError]" : ""} ${String(text).slice(0, 200)}`);
+}
+await harness.close(ctx);

spikes/pi/common.ts

@@ -0,0 +1,83 @@
+// Shared pieces for the Pi spike: whitelisted business tools + scripted fake model.
+import { Type } from "typebox";
+import {
+  fauxAssistantMessage, fauxText, fauxThinking, fauxToolCall,
+  type FauxResponseFactory,
+} from "@earendil-works/pi-ai";
+import type { AgentHarnessTool } from "@earendil-works/pi-agent-core";
+
+// Capability id -> provider-safe tool name. Anthropic/OpenAI tool names must match ^[a-zA-Z0-9_-]{1,64}$,
+// so "inventory.query" cannot be sent verbatim; the port maps ids <-> names.
+export const toolName = (capabilityId: string) => capabilityId.replace(/\./g, "__");
+
+export const submitted: Array<{ key: string; title: string }> = [];
+
+type Ctx = { actorId: string; grants: string[] };
+
+export const inventoryQuery: AgentHarnessTool<Ctx> = {
+  name: toolName("inventory.query"),
+  label: "inventory.query",
+  description: "Query local library inventory for a title. Returns whether it exists and which versions.",
+  parameters: Type.Object({ title: Type.String(), year: Type.Optional(Type.Number()) }),
+  replay: "safe", // read-only: harness may re-execute after a crash
+  async execute(_id, params, onUpdate, toolCtx, invocation, context) {
+    onUpdate({ content: [{ type: "text", text: "searching…" }], details: {} });
+    const found = params.title === "Arrival";
+    return {
+      content: [{ type: "text", text: JSON.stringify({ title: params.title, inLibrary: found, versions: found ? ["2160p"] : [] }) }],
+      details: { actor: toolCtx.actorId, invocationId: invocation.invocationId, aborted: context.abortSignal?.aborted ?? false },
+    };
+  },
+};
+
+export const downloadSubmit: AgentHarnessTool<Ctx> = {
+  name: toolName("download.submit"),
+  label: "download.submit",
+  description: "Submit a download plan. Server validates authorization and generates the idempotency key.",
+  parameters: Type.Object({ title: Type.String(), quality: Type.String() }),
+  replay: "never", // external side effect: after crash the harness synthesizes an 'interrupted' result instead of re-running
+  executionMode: "sequential",
+  async execute(_id, params, _onUpdate, toolCtx, invocation, context) {
+    if (!toolCtx.grants.includes("download.submit")) throw new Error("not authorized: download.submit");
+    // Server-side idempotency key derived from operation semantics, not from the model.
+    const key = `dl:${params.title}:${params.quality}`;
+    const delayMs = Number(process.env.SUBMIT_DELAY_MS ?? 0);
+    if (delayMs) {
+      await new Promise<void>((resolve, reject) => {
+        const t = setTimeout(resolve, delayMs);
+        context.abortSignal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("aborted by signal")); });
+      });
+    }
+    if (!submitted.find((s) => s.key === key)) submitted.push({ key, title: params.title });
+    await invocation.setMemo("submitted", key);
+    return { content: [{ type: "text", text: JSON.stringify({ accepted: true, idempotencyKey: key, status: "submitted" }) }], details: { key } };
+  },
+};
+
+const lastToolResult = (ctx: any, name: string) =>
+  [...ctx.messages].reverse().find((m: any) => m.role === "toolResult" && m.toolName === name);
+
+// Scripted fake model: each step is a factory that looks at the transcript (tool results) and decides.
+export const script: FauxResponseFactory[] = [
+  () => fauxAssistantMessage([
+    fauxThinking("先查本地库存"),
+    fauxText("我先查一下库里有没有《Dune》。"),
+    fauxToolCall(toolName("inventory.query"), { title: "Dune", year: 2021 }),
+  ], { stopReason: "toolUse" }),
+  (ctx) => {
+    const inv = JSON.parse(lastToolResult(ctx, toolName("inventory.query")).content[0].text);
+    if (inv.inLibrary) return fauxAssistantMessage("库里已有,无需下载。");
+    return fauxAssistantMessage([
+      fauxText("库里没有,提交 1080p 下载;顺便试一下未授权的 bash。"),
+      fauxToolCall(toolName("download.submit"), { title: "Dune", quality: "1080p" }),
+      fauxToolCall("bash", { command: "rm -rf /" }),
+    ], { stopReason: "toolUse" });
+  },
+  (ctx) => {
+    const dl = lastToolResult(ctx, toolName("download.submit"));
+    const bash = lastToolResult(ctx, "bash");
+    return fauxAssistantMessage(
+      `下载已提交(仅代表已提交,不代表已入库):${dl.content[0].text};bash 结果 isError=${bash?.isError}。`,
+    );
+  },
+];

spikes/pi/compaction.ts

@@ -0,0 +1,21 @@
+// Manual + threshold compaction with the fake model (summary text is scripted).
+import { createModels, fauxProvider, fauxAssistantMessage } from "@earendil-works/pi-ai";
+import { AgentHarness, BACKGROUND_CONTEXT as ctx, MemorySessionRepo } from "@earendil-works/pi-agent-core";
+const faux = fauxProvider({ provider: "umt-fake", models: [{ id: "tiny", contextWindow: 3000, maxTokens: 500 }] });
+const models = createModels(); models.setProvider(faux.provider);
+const session = await new MemorySessionRepo().create({}, ctx);
+const { harness } = await AgentHarness.create({ session, models, model: faux.getModel(), systemPrompt: "助手",
+  compaction: { enabled: true, reserveTokens: 600, keepRecentTokens: 200 } }, ctx);
+for (const t of ["compaction_start", "compaction_end", "run_end"] as const)
+  harness.events.on(t as any, (e: any) => console.log(`[${e.type}] reason=${e.reason ?? ""} status=${e.status ?? ""}`));
+const lane = await harness.lane("main", ctx);
+const long = "目标:收录 Dune 1080p。约束:只用已授权能力。".repeat(Number(process.env.REPEAT ?? 60));
+faux.setResponses([fauxAssistantMessage("好的,已记录目标。" + "x".repeat(2000)), fauxAssistantMessage("## 摘要\n目标:收录 Dune 1080p;已完成:无"), fauxAssistantMessage("继续")]);
+console.log("run1:", JSON.stringify((await lane.prompt(long, undefined, ctx)) as any).slice(0, 400));
+console.log("run2:", JSON.stringify((await lane.prompt("继续", undefined, ctx)) as any).slice(0, 400));
+faux.appendResponses([fauxAssistantMessage("## 手动摘要\n目标/约束/证据/已完成/剩余")]);
+const c = await lane.compact({ customInstructions: "保留目标、约束、证据引用、已完成动作、剩余事项" }, ctx);
+console.log("manual compact:", JSON.stringify(c).slice(0, 200));
+const entries = await lane.findEntries(undefined, ctx);
+console.log("entry types:", entries.map((e: any) => e.type).join(","), "fake calls:", faux.state.callCount);
+await harness.close(ctx);

spikes/pi/fake-run.ts

@@ -0,0 +1,50 @@
+// Fake model drives AgentHarness through 2 whitelisted tools; streams events.
+import { createModels, fauxProvider } from "@earendil-works/pi-ai";
+import { AgentHarness, BACKGROUND_CONTEXT, MemorySessionRepo } from "@earendil-works/pi-agent-core";
+import { downloadSubmit, inventoryQuery, script, submitted } from "./common.ts";
+
+const faux = fauxProvider({ provider: "umt-fake" });
+const models = createModels();
+models.setProvider(faux.provider);
+faux.setResponses(script);
+
+const repo = new MemorySessionRepo();
+const session = await repo.create({ id: "spike-1" }, BACKGROUND_CONTEXT);
+const { harness } = await AgentHarness.create({
+  session, models, model: faux.getModel(),
+  systemPrompt: "你是媒体库自动化助手,只能使用提供的工具。",
+  tools: [inventoryQuery, downloadSubmit],           // explicit whitelist; no discovery
+  toolContext: { actorId: "user:1", grants: ["download.submit"] },
+  thinkingLevel: "off",
+  compaction: { enabled: true, reserveTokens: 4096, keepRecentTokens: 8000 },
+  retry: { enabled: true, maxRetries: 2, baseDelayMs: 100 },
+  toolExecution: "sequential",
+}, BACKGROUND_CONTEXT);
+
+// Server-side authorization gate in addition to the whitelist.
+harness.hooks.on("before_tool", (ev) => {
+  console.log(`  [hook before_tool] ${ev.toolName} args=${JSON.stringify(ev.args)}`);
+  return undefined;
+});
+
+const types = ["run_start", "turn_start", "message_update", "tool_start", "tool_update", "tool_end", "turn_end", "run_end", "usage", "fault", "handler_error"] as const;
+for (const t of types) harness.events.on(t as any, (e: any) => {
+  if (e.type === "message_update") {
+    if (e.event.type === "text_delta") process.stdout.write(`  [text_delta] ${JSON.stringify(e.event.delta)}\n`);
+    else if (e.event.type === "toolcall_end") console.log(`  [toolcall_end] ${e.event.toolCall.name}`);
+    return;
+  }
+  if (e.type === "tool_end") return console.log(`[tool_end] ${e.toolName} isError=${e.isError} -> ${JSON.stringify(e.result.content[0]?.text)}`);
+  if (e.type === "tool_start") return console.log(`[tool_start] ${e.toolName} ${JSON.stringify(e.args)}`);
+  if (e.type === "usage") return console.log(`[usage] in=${e.row?.usage?.input ?? "?"} totals.input=${e.totals.input} output=${e.totals.output}`);
+  if (e.type === "run_end") return console.log(`[run_end] status=${e.status}${e.error ? " error=" + JSON.stringify(e.error) : ""}`);
+  console.log(`[${e.type}]${e.lane ? " lane=" + e.lane : ""}`);
+});
+
+const lane = await harness.lane("main", BACKGROUND_CONTEXT);
+const result = await lane.prompt("把《Dune》1080p 收进来", undefined, BACKGROUND_CONTEXT);
+console.log("RESULT", JSON.stringify(result));
+console.log("SUBMITTED", JSON.stringify(submitted), "fake calls:", faux.state.callCount);
+const entries = await lane.findEntries(undefined, BACKGROUND_CONTEXT);
+console.log("TRANSCRIPT roles:", entries.map((e: any) => e.type === "message" ? e.message.role : e.type).join(","));
+await harness.close(BACKGROUND_CONTEXT);

spikes/pi/provider-config.ts

@@ -0,0 +1,69 @@
+// Real provider types (Anthropic Messages + OpenAI-compatible Chat Completions) pointed at a LOCAL capture server.
+// No external network: the capture server records method/path/headers/body and returns HTTP 400.
+import http from "node:http";
+import { createModels, createProvider, getSupportedThinkingLevels, type Model } from "@earendil-works/pi-ai";
+import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
+import { AgentHarness, BACKGROUND_CONTEXT, MemorySessionRepo } from "@earendil-works/pi-agent-core";
+import { inventoryQuery } from "./common.ts";
+
+const captured: any[] = [];
+const server = http.createServer((req, res) => {
+  let body = ""; req.on("data", (c) => (body += c)); req.on("end", () => {
+    captured.push({ method: req.method, url: req.url, auth: req.headers["authorization"] ?? req.headers["x-api-key"], body: JSON.parse(body || "{}") });
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: { type: "invalid_request_error", message: "capture server: refusing on purpose" } }));
+  });
+});
+await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+const base = `http://127.0.0.1:${(server.address() as any).port}`;
+
+// Secret comes from our own secret store; resolve() is called at request time. No env var lookup.
+const secret = (name: string) => ({ name, resolve: async () => ({ auth: { apiKey: `sk-test-${name}` } }) });
+
+const anthropicCompatible: Model<"anthropic-messages"> = {
+  id: "claude-sonnet-4-5", name: "Anthropic-compatible upstream", api: "anthropic-messages", provider: "upstream-anthropic",
+  baseUrl: base, reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 200000, maxTokens: 8192,
+};
+const openaiCompatible: Model<"openai-completions"> = {
+  id: "qwen3-235b", name: "OpenAI-compatible upstream", api: "openai-completions", provider: "upstream-openai",
+  baseUrl: `${base}/v1`, reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 131072, maxTokens: 8192, compat: { supportsDeveloperRole: false, thinkingFormat: "qwen" },
+};
+
+const models = createModels();
+models.setProvider(createProvider({ id: "upstream-anthropic", auth: { apiKey: secret("anthropic") }, models: [anthropicCompatible], api: anthropicMessagesApi() }));
+models.setProvider(createProvider({ id: "upstream-openai", auth: { apiKey: secret("openai") }, models: [openaiCompatible], api: openAICompletionsApi() }));
+
+// Built-in provider catalog is available too (no request made):
+const builtin = anthropicProvider();
+const cat = createModels(); cat.setProvider(builtin);
+console.log("builtin anthropic models (first 5):", cat.getModels("anthropic").slice(0, 5).map((m) => m.id).join(", "));
+console.log("builtin anthropic auth configured without env?", JSON.stringify(await cat.checkAuth("anthropic")));
+console.log("supported thinking levels, custom anthropic model:", getSupportedThinkingLevels(anthropicCompatible).join(","));
+console.log("supported thinking levels, custom openai model:", getSupportedThinkingLevels(openaiCompatible).join(","));
+
+for (const model of [anthropicCompatible, openaiCompatible] as Model<any>[]) {
+  const repo = new MemorySessionRepo();
+  const session = await repo.create({}, BACKGROUND_CONTEXT);
+  const { harness } = await AgentHarness.create({
+    session, models, model, systemPrompt: "媒体库助手", tools: [inventoryQuery], toolContext: { actorId: "u", grants: [] },
+    thinkingLevel: "high",
+    compaction: { enabled: true, reserveTokens: 8000, keepRecentTokens: 12000 },
+    retry: { enabled: false, maxRetries: 0, baseDelayMs: 0 },
+    streamOptions: { timeoutMs: 5000, maxRetries: 0, headers: { "x-umt-run": "spike" } },
+  }, BACKGROUND_CONTEXT);
+  harness.hooks.on("before_request", (ev) => { console.log(`[before_request] ${ev.model.provider}/${ev.model.id} step=${ev.step} attempt=${ev.attempt}`); return undefined; });
+  const lane = await harness.lane("main", BACKGROUND_CONTEXT);
+  const r = await lane.prompt("库里有 Dune 吗", undefined, BACKGROUND_CONTEXT);
+  console.log(`[${model.provider}] run:`, JSON.stringify(r.ok ? { status: r.value.status, error: (r.value as any).error } : r.error).slice(0, 300));
+  await harness.close(BACKGROUND_CONTEXT);
+}
+for (const c of captured) {
+  const b = c.body;
+  console.log(`CAPTURED ${c.method} ${c.url} auth=${c.auth}`);
+  console.log(`   model=${b.model} max_tokens=${b.max_tokens ?? b.max_completion_tokens} thinking=${JSON.stringify(b.thinking ?? b.enable_thinking ?? b.reasoning_effort)} tools=${JSON.stringify((b.tools ?? []).map((t: any) => t.name ?? t.function?.name))} stream=${b.stream}`);
+}
+server.close();