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

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

packages/cli-workflow/src/__tests__/adapter-json-roundtrip.test.ts

@@ -0,0 +1,174 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { registerUwfSchemas } from "../schemas.js";
+import { saveThreadsIndex } from "../store.js";
+
+// ── schemas ──────────────────────────────────────────────────────────────────
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const, enum: ["done", "failed"] },
+    result: { type: "string" as const },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+// ── fixture ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-roundtrip-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("C1: adapter JSON round-trip integration", () => {
+  test("mock agent outputs JSON, CLI parses it and updates thread head in CAS", async () => {
+    // 1. Set up CAS store with workflow, start node, and output schema
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = createFsStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+
+    const outputSchemaHash = await putSchema(store, OUTPUT_SCHEMA);
+
+    const workflowHash = await store.put(schemas.workflow, {
+      name: "test-roundtrip",
+      description: "roundtrip integration test",
+      roles: {
+        worker: {
+          description: "Worker role",
+          goal: "Do work",
+          capabilities: [],
+          procedure: "work",
+          output: "result",
+          frontmatter: outputSchemaHash,
+        },
+      },
+      graph: {
+        $START: { _: { role: "worker", prompt: "Do the work", location: null } },
+        worker: { done: { role: "$END", prompt: "completed", location: null } },
+      },
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Test round-trip task",
+    });
+
+    const threadId = "01ROUNDTRIPTEST0000000000" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: startHash });
+
+    // 2. Pre-create CAS nodes that the mock agent would produce
+    const outputHash = await store.put(outputSchemaHash, {
+      $status: "done",
+      result: "test-ok",
+    });
+
+    // Use text schema for detail (simple placeholder)
+    const detailHash = await store.put(schemas.text, "mock detail");
+
+    const startedAtMs = 1716600000000;
+    const completedAtMs = 1716600001500;
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-mock",
+      edgePrompt: "Do the work",
+      startedAtMs,
+      completedAtMs,
+      cwd: tmpDir,
+    });
+
+    // 3. Create a minimal mock agent shell script that just outputs JSON
+    //    The step node is already in CAS — the agent just needs to print the JSON line
+    const mockAgentPath = join(tmpDir, "mock-agent.sh");
+    const adapterJson = JSON.stringify({
+      stepHash,
+      detailHash,
+      role: "worker",
+      frontmatter: { $status: "done", result: "test-ok" },
+      body: "",
+      startedAtMs,
+      completedAtMs,
+    });
+    await writeFile(mockAgentPath, `#!/bin/sh\necho '${adapterJson}'\n`, { mode: 0o755 });
+
+    // 4. Write config.yaml
+    const configPath = join(tmpDir, "config.yaml");
+    await writeFile(
+      configPath,
+      `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+    );
+
+    // 5. Run CLI with agent override pointing to our mock
+    const cliPath = join(import.meta.dirname, "..", "cli.js");
+    let stdout: string;
+    let stderr: string;
+    let exitCode: number;
+
+    try {
+      stdout = execFileSync(
+        "bun",
+        ["run", cliPath, "thread", "exec", threadId, "--agent", mockAgentPath],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          env: { ...process.env, WORKFLOW_STORAGE_ROOT: tmpDir },
+          cwd: tmpDir,
+          timeout: 30000,
+        },
+      );
+      stderr = "";
+      exitCode = 0;
+    } catch (e: unknown) {
+      const err = e as NodeJS.ErrnoException & {
+        stdout?: string;
+        stderr?: string;
+        status?: number;
+      };
+      stdout = err.stdout ?? "";
+      stderr = err.stderr ?? "";
+      exitCode = err.status ?? 1;
+    }
+
+    // 6. Verify
+    if (exitCode !== 0) {
+      throw new Error(`CLI exited with code ${exitCode}\nstdout: ${stdout}\nstderr: ${stderr}`);
+    }
+
+    // Parse CLI output
+    const cliOutput = JSON.parse(stdout.trim());
+    expect(cliOutput).toHaveProperty("thread", threadId);
+    expect(cliOutput).toHaveProperty("head", stepHash);
+    expect(cliOutput.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
+
+    // Verify the CAS step node exists and has correct metadata
+    const storeAfter = createFsStore(casDir);
+    const stepNode = storeAfter.get(cliOutput.head as CasRef);
+    expect(stepNode).not.toBeNull();
+
+    const payload = stepNode!.payload as StepNodePayload;
+    expect(payload.role).toBe("worker");
+    expect(payload.agent).toBe("uwf-mock");
+    expect(payload.startedAtMs).toBe(1716600000000);
+    expect(payload.completedAtMs).toBe(1716600001500);
+    expect(payload.output).toBe(outputHash);
+    expect(payload.detail).toBe(detailHash);
+  });
+});

packages/cli-workflow/src/__tests__/spawn-agent-json.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "vitest";
+
+/**
+ * B-group tests: validate JSON parsing logic used by spawnAgent.
+ *
+ * We test the parsing logic inline since spawnAgent is a private function.
+ * These tests verify the contract: last line of stdout must be valid JSON
+ * with a valid stepHash CasRef.
+ */
+
+const CASREF_PATTERN = /^[0-9A-HJ-NP-TV-Z]{13}$/;
+
+function isCasRef(s: string): boolean {
+  return CASREF_PATTERN.test(s);
+}
+
+type AdapterOutput = {
+  stepHash: string;
+  detailHash: string;
+  role: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  startedAtMs: number;
+  completedAtMs: number;
+};
+
+function parseAgentStdout(stdout: string): AdapterOutput {
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    throw new Error(`agent stdout last line is not valid JSON: ${line || "(empty)"}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (
+    typeof obj !== "object" ||
+    obj === null ||
+    typeof obj.stepHash !== "string" ||
+    !isCasRef(obj.stepHash as string)
+  ) {
+    throw new Error(`agent stdout JSON missing valid stepHash: ${line}`);
+  }
+  return obj as unknown as AdapterOutput;
+}
+
+const VALID_OUTPUT: AdapterOutput = {
+  stepHash: "0123456789ABC",
+  detailHash: "DEFGH12345678",
+  role: "planner",
+  frontmatter: { $status: "ready", plan: "somehash" },
+  body: "Plan body",
+  startedAtMs: 1000,
+  completedAtMs: 2000,
+};
+
+describe("spawnAgent JSON parsing", () => {
+  test("B1. parses valid JSON from agent stdout", () => {
+    const stdout = JSON.stringify(VALID_OUTPUT) + "\n";
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+    expect(result.detailHash).toBe("DEFGH12345678");
+    expect(result.role).toBe("planner");
+    expect(result.frontmatter).toEqual({ $status: "ready", plan: "somehash" });
+    expect(result.body).toBe("Plan body");
+    expect(result.startedAtMs).toBe(1000);
+    expect(result.completedAtMs).toBe(2000);
+  });
+
+  test("B2. extracts stepHash for head pointer", () => {
+    const stdout = JSON.stringify(VALID_OUTPUT) + "\n";
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+    expect(isCasRef(result.stepHash)).toBe(true);
+  });
+
+  test("B3. handles debug lines before JSON", () => {
+    const debugLines = "[debug] loading context...\n[debug] running agent...\n";
+    const stdout = debugLines + JSON.stringify(VALID_OUTPUT) + "\n";
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+  });
+
+  test("B4. rejects non-JSON last line", () => {
+    const stdout = "not-json-at-all\n";
+    expect(() => parseAgentStdout(stdout)).toThrow("not valid JSON");
+  });
+
+  test("B5. rejects JSON missing stepHash", () => {
+    const incomplete = { detailHash: "DEFGH12345678", role: "planner" };
+    const stdout = JSON.stringify(incomplete) + "\n";
+    expect(() => parseAgentStdout(stdout)).toThrow("missing valid stepHash");
+  });
+
+  test("B6. rejects JSON with invalid stepHash", () => {
+    const bad = { ...VALID_OUTPUT, stepHash: "not-a-hash" };
+    const stdout = JSON.stringify(bad) + "\n";
+    expect(() => parseAgentStdout(stdout)).toThrow("missing valid stepHash");
+  });
+});

packages/cli-workflow/src/commands/thread.ts

@@ -23,6 +23,7 @@ import {
   generateUlid,
   type ProcessLogger,
 } from "@uncaged/workflow-util";
+import type { AdapterOutput } from "@uncaged/workflow-util-agent";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-util-agent";
 import { config as loadDotenv } from "dotenv";
 import { parse } from "yaml";
@@ -788,7 +789,7 @@ function spawnAgent(
   role: string,
   edgePrompt: string,
   cwd: string,
-): CasRef {
+): AdapterOutput {
   const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
   let stdout: string;
   try {
@@ -811,10 +812,22 @@ function spawnAgent(
   }
 
   const line = stdout.trim().split("\n").pop()?.trim() ?? "";
-  if (!isCasRef(line)) {
-    failStep(plog, `agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    failStep(plog, `agent stdout last line is not valid JSON: ${line || "(empty)"}`);
   }
-  return line;
+  const obj = parsed as Record<string, unknown>;
+  if (
+    typeof obj !== "object" ||
+    obj === null ||
+    typeof obj.stepHash !== "string" ||
+    !isCasRef(obj.stepHash as string)
+  ) {
+    failStep(plog, `agent stdout JSON missing valid stepHash: ${line}`);
+  }
+  return obj as unknown as AdapterOutput;
 }
 
 async function archiveThread(
@@ -1019,7 +1032,8 @@ async function cmdThreadStepOnce(
   });
 
   loadDotenv({ path: getEnvPath(storageRoot) });
-  const newHead = spawnAgent(plog, agent, threadId, role, edgePrompt, effectiveCwd);
+  const agentResult = spawnAgent(plog, agent, threadId, role, edgePrompt, effectiveCwd);
+  const newHead = agentResult.stepHash as CasRef;
 
   plog.log(PL_AGENT_DONE, `agent returned head=${newHead}`, null);