chore: reorganize repo — legacy packages to legacy-packages/, templates to examples/

- Move 15 old workflow-* packages to legacy-packages/ (inactive, preserved for reference) - Rename templates/ → examples/ for clarity - Rewrite docs/architecture.md to reflect current uwf architecture - Active packages remain in packages/: cli-uwf, uwf-agent-hermes, uwf-agent-kit, uwf-moderator, uwf-protocol, workflow-util 小橘 🍊（NEKO Team）
2026-05-19 07:19:40 +00:00
parent 2a3a40b9d9
commit d63d58ccb5
373 changed files with 393 additions and 203 deletions
@@ -0,0 +1,81 @@
+# @uncaged/workflow-util-agent
+
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.4
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.3
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.2
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- fix: include create-agent-adapter.ts in published src
+  - @uncaged/workflow-cas@0.5.0-alpha.1
+  - @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.0
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+
+## 0.4.5
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.4.5
+- @uncaged/workflow-runtime@0.4.5
+
+## 0.4.4
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.4.4
+- @uncaged/workflow-runtime@0.4.4
+
+## 0.4.3
+
+### Patch Changes
+
+- Include src/ in published packages so bun runtime can resolve the 'bun' exports condition.
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.3
+  - @uncaged/workflow-runtime@0.4.3
+
+## 0.4.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution: use workspace:^ so published packages resolve to compatible versions instead of exact (non-existent) versions.
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.2
+  - @uncaged/workflow-runtime@0.4.2
+
+## 0.4.0
+
+### Minor Changes
+
+- Fix package exports for published packages and adopt changesets for version management.
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.0
+  - @uncaged/workflow-runtime@0.4.0
@@ -0,0 +1,34 @@
+# @uncaged/workflow-util-agent
+
+Shared helpers for CLI-backed workflow agents: assemble prompts from thread context and spawn subprocesses with timeouts.
+
+Used by `@uncaged/workflow-agent-cursor` and `@uncaged/workflow-agent-hermes`. Depends on `@uncaged/workflow` for CAS reads (`getContentMerklePayload`) and `Result` typing.
+
+## Install
+
+```bash
+bun add @uncaged/workflow-util-agent @uncaged/workflow
+```
+
+In this monorepo: `workspace:*` for both packages.
+
+## Usage
+
+```typescript
+import { buildAgentPrompt, spawnCli } from "@uncaged/workflow-util-agent";
+
+const prompt = await buildAgentPrompt(agentContext);
+const result = await spawnCli("my-cli", ["--json"], { cwd: "/tmp", timeoutMs: 60_000 });
+if (!result.ok) { /* handle SpawnCliError */ }
+const stdout = result.value;
+```
+
+## API overview
+
+| Export | Description |
+|--------|-------------|
+| `buildAgentPrompt(ctx)` | System prompt + task + prior step summaries + latest body from CAS; appends `uncaged-workflow thread <id>` tool hint |
+| `spawnCli(cmd, args, { cwd, timeoutMs })` | `Promise<Result<string, SpawnCliError>>`; captures stdout, non-zero exit and spawn failures as `err` |
+| `SpawnCliConfig` | `cwd: string \| null`, `timeoutMs: number \| null` |
+| `SpawnCliError` | `non_zero_exit` \| `timeout` \| `spawn_failed` |
+| `SpawnCliResult` | Alias for `Result<string, SpawnCliError>` |
@@ -0,0 +1,168 @@
+import { describe, expect, test } from "bun:test";
+import { type AgentContext, START } from "@uncaged/workflow-runtime";
+
+import { buildAgentPrompt } from "../src/index.js";
+
+function startTask(content: string, parentState: string | null = null): AgentContext["start"] {
+  return {
+    role: START,
+    content,
+    meta: {},
+    timestamp: 1,
+    parentState,
+  };
+}
+
+describe("buildAgentPrompt", () => {
+  test("includes system prompt and full task; omits tools when there are no steps", async () => {
+    const ctx: AgentContext = {
+      start: startTask("fix the bug"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      steps: [],
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: START, systemPrompt: "You are an agent." },
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain("You are an agent.");
+    expect(text).toContain("## Task");
+    expect(text).toContain("fix the bug");
+    expect(text).not.toContain("## Tools");
+  });
+
+  test("single step shows hash and meta, and includes tools", async () => {
+    const onlyHash = "01HASHSINGLESTEP0000000001";
+    const ctx: AgentContext = {
+      start: startTask("user task"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: "coder", systemPrompt: "Be helpful." },
+      steps: [
+        {
+          role: "coder",
+          contentHash: onlyHash,
+          meta: { files: ["a.ts"] },
+          refs: [onlyHash],
+          timestamp: 2,
+        },
+      ],
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain("## Task");
+    expect(text).toContain("user task");
+    expect(text).toContain("## Step: coder");
+    expect(text).toContain(`ContentHash: ${onlyHash}`);
+    expect(text).toContain('Meta: {"files":["a.ts"]}');
+    expect(text).toContain("## Tools");
+    expect(text).toContain("uncaged-workflow thread 01TEST000000000000000000TR");
+  });
+
+  test("two or more steps: previous steps are meta-only; latest step includes hash", async () => {
+    const plannerHash = "01HASHPLANNER0000000000001";
+    const coderHash = "01HASHCODER0000000000000001";
+    const ctx: AgentContext = {
+      start: startTask("first message full: task content here"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: "coder", systemPrompt: "System." },
+      steps: [
+        {
+          role: "planner",
+          contentHash: plannerHash,
+          meta: { plan: "short" },
+          refs: [plannerHash],
+          timestamp: 2,
+        },
+        {
+          role: "coder",
+          contentHash: coderHash,
+          meta: { done: true },
+          refs: [coderHash],
+          timestamp: 3,
+        },
+      ],
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain("first message full: task content here");
+    expect(text).toContain("## Previous Steps");
+    expect(text).toContain("### Step 1: planner");
+    expect(text).toContain('Summary: {"plan":"short"}');
+    expect(text).toContain("## Latest Step: coder");
+    expect(text).toContain(`ContentHash: ${coderHash}`);
+    expect(text).toContain('Meta: {"done":true}');
+    expect(text).toContain("## Tools");
+    expect(text).toContain("uncaged-workflow thread 01TEST000000000000000000TR");
+  });
+
+  test("parentState null omits Parent Context section", async () => {
+    const ctx: AgentContext = {
+      start: startTask("top-level task"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      steps: [],
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: START, systemPrompt: "You are an agent." },
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).not.toContain("## Parent Context");
+  });
+
+  test("parentState non-null includes Parent Context section with hash", async () => {
+    const parentHash = "01PARENTSTATE0000000000001";
+    const ctx: AgentContext = {
+      start: startTask("child task", parentHash),
+      depth: 1,
+      bundleHash: "TESTHASH00001",
+      steps: [],
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: START, systemPrompt: "You are an agent." },
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain("## Parent Context");
+    expect(text).toContain(parentHash);
+    expect(text).toContain(`uncaged-workflow cas get ${parentHash}`);
+  });
+
+  test("middle steps show meta summary only and latest shows hash", async () => {
+    const ha = "01HASHA00000000000000000001";
+    const hb = "01HASHB00000000000000000001";
+    const hc = "01HASHC00000000000000000001";
+    const ctx: AgentContext = {
+      start: startTask("start"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: "c", systemPrompt: "S" },
+      steps: [
+        {
+          role: "a",
+          contentHash: ha,
+          meta: { n: 1 },
+          refs: [ha],
+          timestamp: 2,
+        },
+        {
+          role: "b",
+          contentHash: hb,
+          meta: { n: 2 },
+          refs: [hb],
+          timestamp: 3,
+        },
+        {
+          role: "c",
+          contentHash: hc,
+          meta: { n: 3 },
+          refs: [hc],
+          timestamp: 4,
+        },
+      ],
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain('Summary: {"n":1}');
+    expect(text).toContain('Summary: {"n":2}');
+    expect(text).toContain(`ContentHash: ${hc}`);
+    expect(text).toContain("## Latest Step: c");
+  });
+});
@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import * as z from "zod/v4";
+
+import { buildOutputFormatInstruction } from "../src/build-output-format-instruction.js";
+
+describe("buildOutputFormatInstruction", () => {
+  test("always includes the frontmatter example block", () => {
+    const schema = z.object({ status: z.string() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("## Deliverable Format");
+    expect(result).toContain("status:");
+    expect(result).toContain("confidence:");
+    expect(result).toContain("artifacts:");
+    expect(result).toContain("scope:");
+  });
+
+  test("always includes scope reminder", () => {
+    const schema = z.object({ status: z.string() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("Focus exclusively on YOUR role's deliverable");
+    expect(result).toContain("Do not perform actions outside your role's scope");
+  });
+
+  test("lists fields from a flat ZodObject schema", () => {
+    const schema = z.object({
+      title: z.string(),
+      phases: z.array(z.string()),
+      reason: z.union([z.string(), z.null()]),
+    });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`title`");
+    expect(result).toContain("`phases`");
+    expect(result).toContain("`reason`");
+  });
+
+  test("lists union of fields from a discriminated union schema", () => {
+    const schema = z.discriminatedUnion("status", [
+      z.object({ status: z.literal("planned"), phases: z.array(z.string()) }),
+      z.object({ status: z.literal("aborted"), reason: z.string() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`status`");
+    expect(result).toContain("`phases`");
+    expect(result).toContain("`reason`");
+  });
+
+  test("lists fields from a plain ZodUnion schema", () => {
+    const schema = z.union([
+      z.object({ kind: z.literal("a"), valueA: z.string() }),
+      z.object({ kind: z.literal("b"), valueB: z.number() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("`kind`");
+    expect(result).toContain("`valueA`");
+    expect(result).toContain("`valueB`");
+  });
+
+  test("falls back gracefully for a non-object schema (no field list crash)", () => {
+    const schema = z.string();
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("## Deliverable Format");
+    expect(result).toContain("schema fields will be extracted automatically");
+  });
+
+  test("marks frontmatter as the primary deliverable", () => {
+    const schema = z.object({ done: z.boolean() });
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("primary deliverable");
+  });
+
+  test("no field is listed more than once for a union with overlapping keys", () => {
+    const schema = z.union([
+      z.object({ status: z.literal("a"), shared: z.string() }),
+      z.object({ status: z.literal("b"), shared: z.string() }),
+    ]);
+    const result = buildOutputFormatInstruction(schema);
+    const matches = [...result.matchAll(/`shared`/g)];
+    expect(matches.length).toBe(1);
+  });
+});
@@ -0,0 +1,238 @@
+import { describe, expect, test, vi } from "vitest";
+
+const mock = vi.fn;
+
+import type { CasStore } from "@uncaged/workflow-cas";
+import type { ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+import { createAgentAdapter } from "../src/index.js";
+
+// ── Minimal test fixtures ─────────────────────────────────────────────────────
+
+function makeCtx(): ThreadContext {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    bundleHash: "TESTHASH00001",
+    start: {
+      role: "START" as const,
+      content: "test task",
+      meta: {},
+      timestamp: 1,
+      parentState: null,
+    },
+    steps: [],
+  };
+}
+
+function makeCas(): CasStore & { store: Map<string, string> } {
+  const store = new Map<string, string>();
+  let seq = 0;
+  return {
+    store,
+    async put(content: string) {
+      const hash = `HASH${String(++seq).padStart(9, "0")}`;
+      store.set(hash, content);
+      return hash;
+    },
+    async get(hash: string) {
+      return store.get(hash) ?? null;
+    },
+    async delete(hash: string) {
+      store.delete(hash);
+    },
+    async list() {
+      return [...store.keys()];
+    },
+  };
+}
+
+// ── Frontmatter-compatible schema ─────────────────────────────────────────────
+
+// Schema that maps directly to AgentFrontmatter fields so happy path works.
+const FrontmatterSchema = z.object({
+  status: z.union([
+    z.literal("done"),
+    z.literal("needs_input"),
+    z.literal("in_progress"),
+    z.literal("failed"),
+    z.null(),
+  ]),
+  next: z.union([z.string(), z.null()]),
+  confidence: z.union([z.number(), z.null()]),
+  artifacts: z.array(z.string()),
+  scope: z.union([z.literal("role"), z.literal("thread")]),
+});
+
+type FrontmatterMeta = z.infer<typeof FrontmatterSchema>;
+
+// ── Happy path ────────────────────────────────────────────────────────────────
+
+describe("createAgentAdapter — happy path (valid frontmatter satisfies schema)", () => {
+  test("returns meta from frontmatter without calling runtime.extract", async () => {
+    const cas = makeCas();
+    const extractMock = mock(async () => {
+      throw new Error("runtime.extract must not be called in happy path");
+    });
+    const runtime: WorkflowRuntime = { cas, extract: extractMock as WorkflowRuntime["extract"] };
+
+    const rawOutput = [
+      "---",
+      "status: done",
+      "next: reviewer",
+      "confidence: 0.9",
+      "artifacts: [src/foo.ts]",
+      "scope: role",
+      "---",
+      "",
+      "## Summary",
+      "Work is complete.",
+    ].join("\n");
+
+    const agentFn = mock(async (_ctx: ThreadContext, _opts: null) => rawOutput);
+    const extractOpts = mock(async () => null);
+
+    const adapter = createAgentAdapter<null>(agentFn, extractOpts);
+    const roleFn = adapter<FrontmatterMeta>("test prompt", FrontmatterSchema);
+    const result = await roleFn(makeCtx(), runtime);
+
+    // Meta must come from frontmatter
+    expect(result.meta.status).toBe("done");
+    expect(result.meta.next).toBe("reviewer");
+    expect(result.meta.confidence).toBe(0.9);
+    expect(result.meta.artifacts).toEqual(["src/foo.ts"]);
+    expect(result.meta.scope).toBe("role");
+    expect(result.childThread).toBeNull();
+
+    // LLM extract must NOT have been called
+    expect(extractMock).not.toHaveBeenCalled();
+
+    // CAS should store the body (without frontmatter) as the CAS node payload
+    const storedContent = [...cas.store.values()][0] ?? "";
+    expect(storedContent).toContain("## Summary");
+    expect(storedContent).toContain("Work is complete.");
+    // The frontmatter block itself must not appear in the stored payload
+    expect(storedContent).not.toContain("status: done\n");
+  });
+
+  test("body stored in CAS does not include the frontmatter block", async () => {
+    const cas = makeCas();
+    const runtime: WorkflowRuntime = {
+      cas,
+      extract: mock(async () => {
+        throw new Error("must not be called");
+      }) as WorkflowRuntime["extract"],
+    };
+
+    const rawOutput =
+      "---\nstatus: done\nnext: null\nconfidence: null\nscope: role\n---\n\nThe actual work content here.";
+
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    await roleFn(makeCtx(), runtime);
+
+    // CAS node wraps content as `payload: <body>`; check the payload contains only body
+    const stored = [...cas.store.values()][0] ?? "";
+    expect(stored).toContain("The actual work content here.");
+    // The frontmatter block must be stripped
+    expect(stored).not.toContain("status: done");
+  });
+});
+
+// ── Fallback path ─────────────────────────────────────────────────────────────
+
+describe("createAgentAdapter — fallback path (no frontmatter)", () => {
+  test("calls runtime.extract when output has no frontmatter block", async () => {
+    const cas = makeCas();
+    const expectedMeta: FrontmatterMeta = {
+      status: "done",
+      next: null,
+      confidence: null,
+      artifacts: [],
+      scope: "role",
+    };
+
+    const extractFn = mock(async (_schema: unknown, _hash: string) => ({
+      meta: expectedMeta as Record<string, unknown>,
+      contentPayload: "plain text output",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    const rawOutput = "This is plain markdown without any frontmatter.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    const result = await roleFn(makeCtx(), runtime);
+
+    // runtime.extract must have been called once
+    expect(extractFn).toHaveBeenCalledTimes(1);
+    expect(result.meta).toEqual(expectedMeta);
+    expect(result.childThread).toBeNull();
+
+    // CAS should store the full raw output (as CAS node payload)
+    const stored = [...cas.store.values()][0] ?? "";
+    expect(stored).toContain(rawOutput);
+  });
+
+  test("falls back to runtime.extract when frontmatter is structurally invalid", async () => {
+    const cas = makeCas();
+    const expectedMeta: FrontmatterMeta = {
+      status: null,
+      next: null,
+      confidence: null,
+      artifacts: [],
+      scope: "role",
+    };
+    const extractFn = mock(async () => ({
+      meta: expectedMeta as Record<string, unknown>,
+      contentPayload: "",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    // confidence out of range — validateFrontmatter will reject
+    const rawOutput = "---\nstatus: done\nconfidence: 1.5\nscope: role\n---\n\nBody.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<FrontmatterMeta>("prompt", FrontmatterSchema);
+    await roleFn(makeCtx(), runtime);
+
+    expect(extractFn).toHaveBeenCalledTimes(1);
+  });
+
+  test("falls back when frontmatter fields do not satisfy schema", async () => {
+    const cas = makeCas();
+
+    // Schema requires a mandatory non-null string field that frontmatter cannot provide
+    const StrictSchema = z.object({
+      requiredField: z.string(),
+    });
+
+    const extractFn = mock(async () => ({
+      meta: { requiredField: "from-llm" } as Record<string, unknown>,
+      contentPayload: "",
+      refs: [],
+    }));
+    const runtime: WorkflowRuntime = { cas, extract: extractFn as WorkflowRuntime["extract"] };
+
+    const rawOutput = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const adapter = createAgentAdapter<null>(
+      mock(async () => rawOutput),
+      mock(async () => null),
+    );
+    const roleFn = adapter<{ requiredField: string }>("prompt", StrictSchema);
+    await roleFn(makeCtx(), runtime);
+
+    // frontmatter has no `requiredField`, so schema parse fails → fallback
+    expect(extractFn).toHaveBeenCalledTimes(1);
+  });
+});
@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+
+import { spawnCli } from "../src/index.js";
+
+const noTimeout = { cwd: null, timeoutMs: null } as const;
+
+describe("spawnCli", () => {
+  test("resolves ok stdout on zero exit", async () => {
+    const run = await spawnCli("echo", ["spawn-cli-ok"], { ...noTimeout });
+    expect(run.ok).toBe(true);
+    if (run.ok) {
+      expect(run.value.trim()).toBe("spawn-cli-ok");
+    }
+  });
+
+  test("resolves err on non-zero exit", async () => {
+    const run = await spawnCli("false", [], { ...noTimeout });
+    expect(run.ok).toBe(false);
+    if (!run.ok) {
+      expect(run.error.kind).toBe("non_zero_exit");
+    }
+  });
+
+  test("resolves err on timeout", async () => {
+    const run = await spawnCli("sleep", ["10"], { cwd: null, timeoutMs: 80 });
+    expect(run.ok).toBe(false);
+    if (!run.ok) {
+      expect(run.error.kind).toBe("timeout");
+    }
+  });
+
+  test("resolves err when spawn fails", async () => {
+    const run = await spawnCli("definitely-missing-executable-7f2a9c1b", [], { ...noTimeout });
+    expect(run.ok).toBe(false);
+    if (!run.ok) {
+      expect(run.error.kind).toBe("spawn_failed");
+    }
+  });
+});
@@ -0,0 +1,30 @@
+{
+  "name": "@uncaged/workflow-util-agent",
+  "version": "0.5.0-alpha.4",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/workflow-runtime": "workspace:^",
+    "@uncaged/workflow-cas": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,13 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@uncaged/workflow-runtime':
+        specifier: workspace:*
+        version: link:../workflow-runtime
@@ -0,0 +1,78 @@
+import type { AgentContext, ThreadContext } from "@uncaged/workflow-runtime";
+
+/**
+ * Builds a user-message string from thread context: task, previous steps, and tool hints.
+ * Does NOT include a system prompt — that is passed separately via the adapter.
+ *
+ * Ordering: Task → Previous Steps → Parent Context → Tools
+ * The "Deliverable" section lives in the system prompt (injected by createAgentAdapter).
+ */
+export async function buildThreadInput(ctx: ThreadContext): Promise<string> {
+  const lines: string[] = [];
+
+  // 1. Task — what to do
+  lines.push("## Task");
+  lines.push(ctx.start.content);
+
+  const { steps } = ctx;
+
+  // 2. Context — previous steps
+  if (steps.length === 1) {
+    const s = steps[0];
+    lines.push("");
+    lines.push(`## Step: ${s.role}`);
+    lines.push("");
+    lines.push(`ContentHash: ${s.contentHash}`);
+    lines.push(`Meta: ${JSON.stringify(s.meta)}`);
+  } else if (steps.length > 1) {
+    lines.push("");
+    lines.push("## Previous Steps");
+    for (let i = 0; i < steps.length - 1; i++) {
+      const s = steps[i];
+      lines.push("");
+      lines.push(`### Step ${i + 1}: ${s.role}`);
+      lines.push(`Summary: ${JSON.stringify(s.meta)}`);
+    }
+    const last = steps[steps.length - 1];
+    lines.push("");
+    lines.push(`## Latest Step: ${last.role}`);
+    lines.push("");
+    lines.push(`ContentHash: ${last.contentHash}`);
+    lines.push(`Meta: ${JSON.stringify(last.meta)}`);
+  }
+
+  // 3. Parent context — available when this workflow was spawned by another
+  if (ctx.start.parentState !== null) {
+    lines.push("");
+    lines.push("## Parent Context");
+    lines.push(
+      "This workflow was spawned by a parent workflow. The parent's state at spawn time is available at hash: " +
+        ctx.start.parentState,
+    );
+    lines.push(
+      `Use \`uncaged-workflow cas get ${ctx.start.parentState}\` to inspect the parent's context and trace back through its steps.`,
+    );
+  }
+
+  if (steps.length === 0 && ctx.start.parentState === null) {
+    return lines.join("\n");
+  }
+
+  // 4. Tools — available commands
+  lines.push("");
+  lines.push("## Tools");
+  lines.push(
+    `Use \`uncaged-workflow thread ${ctx.threadId}\` to read full details of any previous step.`,
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * @deprecated Use {@link buildThreadInput} instead. This wrapper prepends the system prompt
+ * from `ctx.currentRole` for backward compatibility with existing agents.
+ */
+export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
+  const threadInput = await buildThreadInput(ctx);
+  return `${ctx.currentRole.systemPrompt}\n\n${threadInput}`;
+}
@@ -0,0 +1,79 @@
+import type * as z from "zod/v4";
+
+type ZodSchema = z.ZodType;
+
+/**
+ * Extract the top-level field names from a Zod schema.
+ *
+ * Handles:
+ * - ZodObject → its `.shape` keys
+ * - ZodDiscriminatedUnion / ZodUnion → union of all variant shapes
+ *
+ * Returns an empty array for schemas that have no inspectable shape
+ * (e.g. primitives, ZodAny).
+ */
+function extractSchemaFields(schema: ZodSchema): string[] {
+  const def = schema.def as {
+    type: string;
+    shape?: Record<string, ZodSchema>;
+    options?: ZodSchema[];
+  };
+
+  if (def.type === "object" && def.shape !== undefined) {
+    return Object.keys(def.shape);
+  }
+
+  if ((def.type === "discriminated_union" || def.type === "union") && Array.isArray(def.options)) {
+    const fieldSet = new Set<string>();
+    for (const option of def.options) {
+      for (const field of extractSchemaFields(option as ZodSchema)) {
+        fieldSet.add(field);
+      }
+    }
+    return [...fieldSet];
+  }
+
+  return [];
+}
+
+/**
+ * Build a concise output format instruction block for an agent role.
+ *
+ * The instruction describes the expected frontmatter markdown format and lists
+ * the meta fields derived from `schema`. It is injected at the top of the
+ * system prompt so the deliverable format is the first thing the agent sees.
+ *
+ * Focus on YOUR role's deliverable. Do not perform actions outside your role's scope.
+ */
+export function buildOutputFormatInstruction(schema: ZodSchema): string {
+  const fields = extractSchemaFields(schema);
+
+  const fieldList =
+    fields.length > 0
+      ? fields.map((f) => `  - \`${f}\``).join("\n")
+      : "  (schema fields will be extracted automatically)";
+
+  return `## Deliverable Format
+
+Your response MUST begin with a YAML frontmatter block followed by your markdown work:
+
+\`\`\`
+---
+status: done          # done | needs_input | in_progress | failed
+next: <role-name>     # suggested next role, or omit
+confidence: 0.9       # 0.0–1.0, your self-assessed confidence
+artifacts:            # list of file paths or CAS hashes you produced
+  - path/to/file.ts
+scope: role           # role | thread
+---
+
+... your markdown work here ...
+\`\`\`
+
+The frontmatter is the **primary deliverable** — the engine reads it directly.
+Your meta output must satisfy these fields:
+
+${fieldList}
+
+Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope.`;
+}
@@ -0,0 +1,109 @@
+import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
+import type {
+  AdapterFn,
+  AgentFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import {
+  createLogger,
+  parseFrontmatterMarkdown,
+  validateFrontmatter,
+} from "@uncaged/workflow-util";
+import type * as z from "zod/v4";
+import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+
+const log = createLogger({ sink: { kind: "stderr" } });
+
+export type ExtractOptionsFn<Opt> = (
+  ctx: ThreadContext,
+  prompt: string,
+  runtime: WorkflowRuntime,
+) => Promise<Opt>;
+
+/**
+ * Try to satisfy `schema` from frontmatter fields alone.
+ *
+ * Returns the parsed value on success, or `null` when the frontmatter does not
+ * cover all required fields of the schema.  Never throws.
+ */
+function tryFrontmatterMeta<T>(
+  raw: string,
+  schema: z.ZodType<T>,
+): { meta: T; body: string } | null {
+  const { frontmatter, body } = parseFrontmatterMarkdown(raw);
+
+  if (frontmatter === null) {
+    return null;
+  }
+
+  const validationErrors = validateFrontmatter(frontmatter);
+  if (validationErrors.length > 0) {
+    log(
+      "4KNMR2PX",
+      `frontmatter validation errors: ${validationErrors.map((e) => e.message).join("; ")}`,
+    );
+    return null;
+  }
+
+  // Coerce frontmatter into the plain object shape the schema expects.
+  const candidate: Record<string, unknown> = {
+    status: frontmatter.status,
+    next: frontmatter.next,
+    confidence: frontmatter.confidence,
+    artifacts: frontmatter.artifacts,
+    scope: frontmatter.scope,
+  };
+
+  const result = schema.safeParse(candidate);
+  if (!result.success) {
+    log("7BQST3VW", "frontmatter does not satisfy schema; falling back to extract");
+    return null;
+  }
+
+  return { meta: result.data, body };
+}
+
+/**
+ * Bridges {@link AgentFn} to {@link AdapterFn}.
+ *
+ * Happy path (zero LLM cost):
+ *   1. extract(ctx, prompt, runtime) → Opt
+ *   2. agent(ctx, options) → raw string
+ *   3. Parse raw as frontmatter markdown
+ *   4. If frontmatter is valid AND satisfies `schema` → use as meta directly
+ *      CAS stores the body (without frontmatter block)
+ *
+ * Fallback (safety net):
+ *   4b. Store full raw in CAS
+ *   5b. runtime.extract(schema, contentHash) → typed meta via LLM
+ */
+export function createAgentAdapter<Opt>(
+  agent: AgentFn<Opt>,
+  extract: ExtractOptionsFn<Opt>,
+): AdapterFn {
+  return <T>(prompt: string, schema: z.ZodType<T>) => {
+    const augmentedPrompt = `${buildOutputFormatInstruction(schema)}\n\n${prompt}`;
+    return async (ctx: ThreadContext, runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const options = await extract(ctx, augmentedPrompt, runtime);
+      const raw = await agent(ctx, options);
+
+      const frontmatterResult = tryFrontmatterMeta(raw, schema);
+
+      if (frontmatterResult !== null) {
+        log("3VXPW8QR", "frontmatter satisfied schema — skipping LLM extract");
+        await putContentNodeWithRefs(runtime.cas, frontmatterResult.body, []);
+        return { meta: frontmatterResult.meta, childThread: null };
+      }
+
+      log("8MTNJ5YK", "no valid frontmatter — falling back to runtime.extract");
+      const contentHash = await putContentNodeWithRefs(runtime.cas, raw, []);
+      const extracted = await runtime.extract(
+        schema as z.ZodType<Record<string, unknown>>,
+        contentHash,
+      );
+      return { meta: extracted.meta as T, childThread: null };
+    };
+  };
+}
@@ -0,0 +1,5 @@
+export { buildAgentPrompt, buildThreadInput } from "./build-agent-prompt.js";
+export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+export { createAgentAdapter } from "./create-agent-adapter.js";
+export type { SpawnCliError } from "./spawn-cli.js";
+export { spawnCli } from "./spawn-cli.js";
@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+
+import { err, ok, type Result } from "@uncaged/workflow-runtime";
+
+export type SpawnCliError =
+  | { kind: "non_zero_exit"; exitCode: number | null; stdout: string; stderr: string }
+  | { kind: "timeout" }
+  | { kind: "spawn_failed"; message: string };
+
+export type SpawnCliConfig = {
+  cwd: string | null;
+  timeoutMs: number | null;
+};
+
+export type SpawnCliResult = Result<string, SpawnCliError>;
+
+export function spawnCli(
+  command: string,
+  args: string[],
+  options: SpawnCliConfig,
+): Promise<SpawnCliResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd === null ? undefined : options.cwd,
+      env: process.env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    let timedOut = false;
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    if (options.timeoutMs !== null) {
+      timeoutId = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+      }, options.timeoutMs);
+    }
+
+    child.on("error", (cause) => {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+      const message = cause instanceof Error ? cause.message : String(cause);
+      resolve(err({ kind: "spawn_failed", message }));
+    });
+
+    child.on("close", (code) => {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+      if (timedOut) {
+        resolve(err({ kind: "timeout" }));
+        return;
+      }
+      if (code === 0) {
+        resolve(ok(stdout));
+        return;
+      }
+      resolve(err({ kind: "non_zero_exit", exitCode: code, stdout, stderr }));
+    });
+  });
+}
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../workflow-runtime" }, { "path": "../workflow-cas" }]
+}