feat(agent): adapter stdout JSON with full metadata (#566) (#569)

Co-authored-by: 小橘 <xiaoju@shazhou.work>
Co-committed-by: 小橘 <xiaoju@shazhou.work>

packages/workflow-util-agent/__tests__/adapter-retry.test.ts

@@ -0,0 +1,72 @@
+import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
+
+import { tryFrontmatterFastPath } from "../src/frontmatter.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    $status: { type: "string", enum: ["ready", "failed"] },
+    plan: { type: "string" },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+describe("adapter-stdout: A4 retry loop survives JSON output", () => {
+  test("A4. first extraction fails, second succeeds — final result has correct data", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    // Simulate the retry loop from createAgent (run.ts lines 163-173):
+    // First attempt: agent outputs garbage (no frontmatter)
+    const badOutput = "Here is my response without frontmatter.\nJust plain text.";
+    const firstAttempt = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    expect(firstAttempt).toBeNull();
+
+    // Second attempt (after correction message): agent outputs valid frontmatter
+    const goodOutput = `---\n$status: ready\nplan: corrected-hash\n---\nCorrected body with valid frontmatter.`;
+    const secondAttempt = await tryFrontmatterFastPath(goodOutput, schemaHash, store);
+
+    expect(secondAttempt).not.toBeNull();
+    expect(secondAttempt!.outputHash).toMatch(/^[0-9A-Z]{13}$/);
+    expect(secondAttempt!.frontmatter).toEqual({ $status: "ready", plan: "corrected-hash" });
+    expect(secondAttempt!.body).toBe("Corrected body with valid frontmatter.");
+
+    // Verify the final AdapterOutput shape would be correct
+    const adapterOutput = {
+      stepHash: "MOCK_STEP_HASH",
+      detailHash: "MOCK_DETAIL_HA",
+      role: "planner",
+      frontmatter: secondAttempt!.frontmatter,
+      body: secondAttempt!.body,
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+
+    const json = JSON.stringify(adapterOutput);
+    const parsed = JSON.parse(json);
+    expect(parsed.frontmatter).toEqual({ $status: "ready", plan: "corrected-hash" });
+    expect(parsed.body).toBe("Corrected body with valid frontmatter.");
+    expect(parsed.completedAtMs).toBeGreaterThanOrEqual(parsed.startedAtMs);
+  });
+
+  test("A4. all retries fail — extraction returns null on every attempt", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const MAX_RETRIES = 2;
+    const badOutput = "No frontmatter here";
+
+    // Simulate MAX_FRONTMATTER_RETRIES iterations all failing
+    let extracted = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    for (let retry = 0; retry < MAX_RETRIES && extracted === null; retry++) {
+      // Each retry also gets bad output
+      extracted = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    }
+
+    expect(extracted).toBeNull();
+  });
+});

packages/workflow-util-agent/__tests__/adapter-stdout.test.ts

@@ -0,0 +1,105 @@
+import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
+
+import { tryFrontmatterFastPath } from "../src/frontmatter.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    $status: { type: "string", enum: ["ready", "failed"] },
+    plan: { type: "string" },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+const FRONTMATTER_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { anyOf: [{ type: "string" }, { type: "null" }] },
+    next: { anyOf: [{ type: "string" }, { type: "null" }] },
+    confidence: { anyOf: [{ type: "number" }, { type: "null" }] },
+    artifacts: { type: "array", items: { type: "string" } },
+    scope: { type: "string" },
+  },
+  required: ["status", "next", "confidence", "artifacts", "scope"],
+  additionalProperties: false,
+};
+
+describe("adapter-stdout: FrontmatterFastPathResult includes frontmatter", () => {
+  test("A2. frontmatter field contains the parsed YAML frontmatter object", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const raw = `---\n$status: ready\nplan: abc123\n---\nSome body text`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.frontmatter).toEqual({ $status: "ready", plan: "abc123" });
+  });
+
+  test("A3. body field contains the markdown body after frontmatter", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const raw = `---\n$status: ready\nplan: hash123\n---\nHere is the body.\n\nWith multiple paragraphs.`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.body).toBe("Here is the body.\n\nWith multiple paragraphs.");
+  });
+
+  test("A1. result contains outputHash as valid CasRef", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, FRONTMATTER_SCHEMA);
+
+    const raw = `---\nstatus: done\nnext: null\nconfidence: 0.9\nartifacts: []\nscope: test\n---\nBody`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.outputHash).toMatch(/^[0-9A-Z]{13}$/);
+    expect(result!.frontmatter).toBeDefined();
+    expect(result!.body).toBe("Body");
+  });
+});
+
+describe("adapter-stdout: AdapterOutput JSON shape", () => {
+  test("A5. JSON.stringify produces valid parseable JSON with all fields", () => {
+    const output = {
+      stepHash: "0123456789ABC",
+      detailHash: "DEFGH12345678",
+      role: "planner",
+      frontmatter: { $status: "ready", plan: "somehash" },
+      body: "Plan body text",
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+
+    const json = JSON.stringify(output);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.stepHash).toBe("0123456789ABC");
+    expect(parsed.detailHash).toBe("DEFGH12345678");
+    expect(parsed.role).toBe("planner");
+    expect(parsed.frontmatter).toEqual({ $status: "ready", plan: "somehash" });
+    expect(parsed.body).toBe("Plan body text");
+    expect(parsed.startedAtMs).toBe(1000);
+    expect(parsed.completedAtMs).toBe(2000);
+  });
+
+  test("completedAtMs >= startedAtMs", () => {
+    const output = {
+      stepHash: "0123456789ABC",
+      detailHash: "DEFGH12345678",
+      role: "planner",
+      frontmatter: {},
+      body: "",
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+
+    expect(output.completedAtMs).toBeGreaterThanOrEqual(output.startedAtMs);
+  });
+});

packages/workflow-util-agent/src/frontmatter.ts

@@ -20,6 +20,7 @@ type StandardKey = (typeof STANDARD_KEYS)[number];
 export type FrontmatterFastPathResult = {
   body: string;
   outputHash: CasRef;
+  frontmatter: Record<string, unknown>;
 };
 
 function extractYamlBlock(raw: string): string | null {
@@ -176,5 +177,5 @@ export async function tryFrontmatterFastPath(
     return null;
   }
 
-  return { body, outputHash };
+  return { body, outputHash, frontmatter: candidate };
 }

packages/workflow-util-agent/src/index.ts

@@ -15,6 +15,7 @@ export { createAgent, parseArgv } from "./run.js";
 export { getCachedSessionId, getCachePath, setCachedSessionId } from "./session-cache.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
 export type {
+  AdapterOutput,
   AgentContext,
   AgentContinueFn,
   AgentOptions,

packages/workflow-util-agent/src/run.ts

@@ -6,7 +6,7 @@ import { buildContextWithMeta } from "./context.js";
 import { tryFrontmatterFastPath } from "./frontmatter.js";
 import type { AgentStore } from "./storage.js";
 import { getEnvPath, resolveStorageRoot } from "./storage.js";
-import type { AgentOptions } from "./types.js";
+import type { AdapterOutput, AgentOptions } from "./types.js";
 
 const MAX_FRONTMATTER_RETRIES = 2;
 
@@ -85,14 +85,24 @@ async function writeStepNode(options: {
   return hash;
 }
 
+type ExtractedOutput = {
+  outputHash: CasRef;
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
 async function tryExtractOutput(
   rawOutput: string,
   outputSchema: CasRef,
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
-): Promise<CasRef | null> {
+): Promise<ExtractedOutput | null> {
   const fastPath = await tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store);
   if (fastPath !== null) {
-    return fastPath.outputHash;
+    return {
+      outputHash: fastPath.outputHash,
+      frontmatter: fastPath.frontmatter,
+      body: fastPath.body,
+    };
   }
   return null;
 }
@@ -148,9 +158,9 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
     const primaryDetailHash = agentResult.detailHash;
 
     // Try to extract frontmatter; retry via continue if it fails
-    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+    let extracted = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
 
-    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && outputHash === null; retry++) {
+    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && extracted === null; retry++) {
       const correctionMessage =
         "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
         "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
@@ -159,10 +169,10 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       agentResult = await runWithMessage("agent continue failed", () =>
         options.continue(agentResult.sessionId, correctionMessage, ctx.meta.store),
       );
-      outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+      extracted = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
     }
 
-    if (outputHash === null) {
+    if (extracted === null) {
       fail(
         "Agent output does not contain valid YAML frontmatter matching the role schema " +
           `after ${MAX_FRONTMATTER_RETRIES} retries.\n` +
@@ -172,13 +182,22 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
     const completedAtMs = Date.now();
     const stepHash = await persistStep({
       ctx,
-      outputHash,
+      outputHash: extracted.outputHash,
       detailHash: primaryDetailHash,
       agentName: agentLabel(options.name),
       startedAtMs,
       completedAtMs,
     });
 
-    process.stdout.write(`${stepHash}\n`);
+    const adapterOutput: AdapterOutput = {
+      stepHash,
+      detailHash: primaryDetailHash,
+      role,
+      frontmatter: extracted.frontmatter,
+      body: extracted.body,
+      startedAtMs,
+      completedAtMs,
+    };
+    process.stdout.write(`${JSON.stringify(adapterOutput)}\n`);
   };
 }

packages/workflow-util-agent/src/types.ts

@@ -37,6 +37,16 @@ export type AgentContinueFn = (
 
 export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
 
+export type AdapterOutput = {
+  stepHash: string;
+  detailHash: string;
+  role: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  startedAtMs: number;
+  completedAtMs: number;
+};
+
 export type AgentOptions = {
   name: string;
   run: AgentRunFn;