fix(workflow): bundle build & register workflow

- Add missing agent deps to template package.json so bun workspace
  resolution works during `bun build` (workflow-agent-cursor for develop,
  workflow-agent-hermes + workflow-execute for solve-issue)
- Create scripts/build-bundles.sh that builds both template bundles into
  dist/*.esm.js with correct --external flags for runtime-symlinked packages
- Add build:bundles script to root package.json
- Extend ensureUncagedWorkflowSymlink to also symlink workflow-util,
  workflow-execute, and workflow-register (needed by externalized bundles)
- Defer agent creation in develop bundle-entry.ts via lazy init so
  requireEnv('WORKFLOW_LLM_API_KEY') only throws at first invocation,
  not at import() time (fixes workflowAsAgent crash)
- Document that env vars must be set before the first worker spawn
  (workers are persistent and don't inherit later env changes)

Fixes #206

Co-authored-by: Cursor <cursoragent@cursor.com>

package.json

@@ -6,6 +6,7 @@
   ],
   "scripts": {
     "build": "bunx tsc --build",
+    "build:bundles": "bash scripts/build-bundles.sh",
     "check": "bunx tsc --build && biome check .",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",

packages/cli-workflow/__tests__/thread-cli.test.ts

@@ -187,6 +187,14 @@ describe("cli thread commands", () => {
     }
     expect(shown.value.includes('"threadId"')).toBe(true);
 
+    const parsed = JSON.parse(shown.value) as Record<string, unknown>;
+    expect(parsed.parentState).toBeNull();
+    const parsedSteps = parsed.steps as Array<Record<string, unknown>>;
+    for (const step of parsedSteps) {
+      expect(step).toHaveProperty("childThread");
+      expect(step.childThread).toBeNull();
+    }
+
     const removed = await cmdThreadRemove(storageRoot, threadId);
     expect(removed.ok).toBe(true);
 

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

@@ -1,4 +1,4 @@
-import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
+import { createCasStore, getContentMerklePayload, parseCasThreadNode } from "@uncaged/workflow-cas";
 import { FORK_BRANCH_ROLE, walkStateFramesNewestFirst } from "@uncaged/workflow-execute";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import { END } from "@uncaged/workflow-runtime";
@@ -6,6 +6,21 @@ import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 import { resolveThreadRecord } from "../../thread-scan.js";
 
+async function readParentStateFromStartNode(
+  cas: { get(hash: string): Promise<string | null> },
+  startHash: string,
+): Promise<string | null> {
+  const yamlText = await cas.get(startHash);
+  if (yamlText === null) {
+    return null;
+  }
+  const parsed = parseCasThreadNode(yamlText);
+  if (parsed === null || parsed.kind !== "start") {
+    return null;
+  }
+  return parsed.node.payload.parentState;
+}
+
 export async function cmdThreadShow(
   storageRoot: string,
   threadId: string,
@@ -19,7 +34,15 @@ export async function cmdThreadShow(
   const frames = await walkStateFramesNewestFirst(cas, resolved.head);
   const chronological = [...frames].reverse();
 
-  const steps: Array<{ role: string; hash: string; timestamp: number; content: string }> = [];
+  const parentState = await readParentStateFromStartNode(cas, resolved.start);
+
+  const steps: Array<{
+    role: string;
+    hash: string;
+    timestamp: number;
+    content: string;
+    childThread: string | null;
+  }> = [];
   for (const fr of chronological) {
     if (fr.payload.role === END || fr.payload.role === FORK_BRANCH_ROLE) {
       continue;
@@ -33,6 +56,7 @@ export async function cmdThreadShow(
         payloadText !== null
           ? payloadText
           : `(content not in CAS; contentHash=${fr.payload.content})`,
+      childThread: fr.payload.childThread,
     });
   }
 
@@ -41,6 +65,7 @@ export async function cmdThreadShow(
     bundleHash: resolved.bundleHash,
     head: resolved.head,
     start: resolved.start,
+    parentState,
     source: resolved.source,
     steps,
   };

packages/workflow-agent-llm/__tests__/create-llm-adapter.test.ts

@@ -10,6 +10,7 @@ function makeCtx(userContent: string): AgentContext {
       content: userContent,
       meta: {},
       timestamp: 1,
+      parentState: null,
     },
     depth: 0,
     bundleHash: "TESTHASH00001",

packages/workflow-cas/.gitignore

@@ -0,0 +1 @@
+workflow-cas

packages/workflow-dashboard/src/api.ts

@@ -147,13 +147,15 @@ export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSumma
   return fetchJson(agentBase(agent), "/workflows");
 }
 
-export function getWorkflowDescriptor(
+export async function getWorkflowDescriptor(
   agent: string,
   name: string,
 ): Promise<WorkflowDescriptor | null> {
-  return fetchJson<WorkflowDetail>(agentBase(agent), `/workflows/${encodeURIComponent(name)}`).then(
-    (res) => res.descriptor,
+  const res = await fetchJson<WorkflowDetail>(
+    agentBase(agent),
+    `/workflows/${encodeURIComponent(name)}`,
   );
+  return res.descriptor;
 }
 
 export function listThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {

packages/workflow-dashboard/src/components/record-card.tsx

@@ -56,11 +56,11 @@ function StartCard({ record }: { record: ThreadStartRecord }) {
   );
 }
 
-function RoleMessage({ record }: { record: RoleRecord }) {
+function RoleMessage({ record, highlighted }: { record: RoleRecord; highlighted: boolean }) {
   const color = roleColor(record.role);
   return (
     <div
-      className="p-3 rounded-lg border text-sm"
+      className={`p-3 rounded-lg border text-sm ${highlighted ? "wf-record-card-highlight" : ""}`}
       style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
     >
       <div className="flex items-center gap-2 mb-2">
@@ -114,12 +114,17 @@ function ResultCard({ record }: { record: WorkflowResultRecord }) {
   );
 }
 
-export function RecordCard({ record }: { record: ThreadRecord }) {
+type RecordCardProps = {
+  record: ThreadRecord;
+  highlighted: boolean;
+};
+
+export function RecordCard({ record, highlighted }: RecordCardProps) {
   switch (record.type) {
     case "thread-start":
       return <StartCard record={record} />;
     case "role":
-      return <RoleMessage record={record} />;
+      return <RoleMessage record={record} highlighted={highlighted} />;
     case "workflow-result":
       return <ResultCard record={record} />;
   }

packages/workflow-dashboard/src/components/thread-detail.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   getThread,
   getWorkflowDescriptor,
@@ -30,9 +30,10 @@ type GraphPanelProps = {
   descriptor: WorkflowDescriptor;
   workflowName: string | null;
   nodeStates: Map<string, NodeState>;
+  onNodeClick: ((roleName: string) => void) | null;
 };
 
-function GraphPanel({ descriptor, workflowName, nodeStates }: GraphPanelProps) {
+function GraphPanel({ descriptor, workflowName, nodeStates, onNodeClick }: GraphPanelProps) {
   const [open, setOpen] = useState(true);
   const edgeCount = descriptor.graph.edges.length;
   return (
@@ -64,6 +65,7 @@ function GraphPanel({ descriptor, workflowName, nodeStates }: GraphPanelProps) {
             graph={descriptor.graph}
             roles={descriptor.roles}
             nodeStates={nodeStates}
+            onNodeClick={onNodeClick}
           />
         </div>
       )}
@@ -102,6 +104,9 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
   const { status, data, error } = useFetch(() => getThread(agent, threadId), [agent, threadId]);
   const [actionStatus, setActionStatus] = useState<string | null>(null);
   const recordsEndRef = useRef<HTMLDivElement>(null);
+  const firstCardByRoleRef = useRef<Map<string, HTMLDivElement>>(new Map());
+  const highlightTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [highlightedRole, setHighlightedRole] = useState<string | null>(null);
 
   const liveActive = sse.connected && !sse.completed;
   const records = liveActive
@@ -121,6 +126,35 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
   const descriptor = descriptorFetch.status === "ok" ? descriptorFetch.data : null;
   const nodeStates = useMemo(() => computeNodeStates(records), [records]);
 
+  const firstIndexByRole = useMemo(() => {
+    const m = new Map<string, number>();
+    for (let i = 0; i < records.length; i++) {
+      const r = records[i];
+      if (r.type === "role" && !m.has(r.role)) {
+        m.set(r.role, i);
+      }
+    }
+    return m;
+  }, [records]);
+
+  const handleGraphNodeClick = useCallback((roleName: string) => {
+    const el = firstCardByRoleRef.current.get(roleName);
+    if (el == null) return;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+    setHighlightedRole(roleName);
+    highlightTimerRef.current = setTimeout(() => {
+      setHighlightedRole(null);
+      highlightTimerRef.current = null;
+    }, 1500);
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+    };
+  }, []);
+
   // biome-ignore lint/correctness/useExhaustiveDependencies: scroll when the rendered record list grows
   useEffect(() => {
     recordsEndRef.current?.scrollIntoView({ behavior: "smooth" });
@@ -194,7 +228,12 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
       )}
 
       {descriptor !== null && descriptor.graph.edges.length > 0 && (
-        <GraphPanel descriptor={descriptor} workflowName={workflowName} nodeStates={nodeStates} />
+        <GraphPanel
+          descriptor={descriptor}
+          workflowName={workflowName}
+          nodeStates={nodeStates}
+          onNodeClick={handleGraphNodeClick}
+        />
       )}
 
       {status === "loading" && !liveActive && records.length === 0 && (
@@ -205,9 +244,26 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
       )}
       {(status === "ok" || liveActive || records.length > 0) && (
         <div className="space-y-3">
-          {records.map((r, i) => (
-            <RecordCard key={`${threadId}-${i}`} record={r} />
-          ))}
+          {records.map((r, i) => {
+            const key = `${threadId}-${i}`;
+            if (r.type === "role") {
+              const isFirstForRole = firstIndexByRole.get(r.role) === i;
+              const flash = highlightedRole === r.role;
+              return (
+                <div
+                  key={key}
+                  ref={(el) => {
+                    if (!isFirstForRole) return;
+                    if (el !== null) firstCardByRoleRef.current.set(r.role, el);
+                    else firstCardByRoleRef.current.delete(r.role);
+                  }}
+                >
+                  <RecordCard record={r} highlighted={flash} />
+                </div>
+              );
+            }
+            return <RecordCard key={key} record={r} highlighted={false} />;
+          })}
           <div ref={recordsEndRef} aria-hidden />
         </div>
       )}

packages/workflow-dashboard/src/components/workflow-graph/role-node.tsx

@@ -31,7 +31,7 @@ export function RoleNode(props: NodeProps) {
 
   return (
     <div
-      className={`px-3 py-2 rounded-md border-2 text-xs font-medium ${isActive ? "wf-node-pulse" : ""}`}
+      className={`px-3 py-2 rounded-md border-2 text-xs font-medium cursor-pointer ${isActive ? "wf-node-pulse" : ""}`}
       style={{
         width: 180,
         height: 60,

packages/workflow-dashboard/src/components/workflow-graph/workflow-graph.tsx

@@ -1,4 +1,12 @@
-import { Background, type EdgeTypes, MarkerType, type NodeTypes, ReactFlow } from "@xyflow/react";
+import {
+  Background,
+  type EdgeTypes,
+  MarkerType,
+  type Node,
+  type NodeTypes,
+  type OnNodeClick,
+  ReactFlow,
+} from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
 import { useMemo } from "react";
 import type { WorkflowGraph as WorkflowGraphData } from "../../api.ts";
@@ -12,6 +20,7 @@ type Props = {
   graph: WorkflowGraphData;
   roles: Record<string, { description: string }>;
   nodeStates: Map<string, NodeState>;
+  onNodeClick: ((roleName: string) => void) | null;
 };
 
 const nodeTypes: NodeTypes = {
@@ -23,9 +32,17 @@ const edgeTypes: EdgeTypes = {
   condition: ConditionEdge,
 };
 
-export function WorkflowGraph({ graph, roles, nodeStates }: Props) {
+function handleRoleNodeClick(onRoleClick: (roleName: string) => void, node: Node): void {
+  if (node.type !== "role") return;
+  onRoleClick(node.id);
+}
+
+export function WorkflowGraph({ graph, roles, nodeStates, onNodeClick }: Props) {
   const layout = useLayout({ edges: graph.edges, roles, nodeStates });
 
+  const onNodeClickHandler: OnNodeClick | undefined =
+    onNodeClick !== null ? (_e, node) => handleRoleNodeClick(onNodeClick, node) : undefined;
+
   const styledEdges = useMemo(
     () =>
       layout.edges.map((e) => ({
@@ -46,6 +63,7 @@ export function WorkflowGraph({ graph, roles, nodeStates }: Props) {
       edges={styledEdges}
       nodeTypes={nodeTypes}
       edgeTypes={edgeTypes}
+      onNodeClick={onNodeClickHandler}
       fitView
       fitViewOptions={{ padding: 0.15 }}
       nodesDraggable={false}

packages/workflow-dashboard/src/index.css

@@ -33,3 +33,19 @@ body {
 .wf-node-pulse {
   animation: wf-node-pulse 1.6s ease-in-out infinite;
 }
+
+@keyframes wf-record-card-highlight {
+  0% {
+    border-color: var(--color-accent);
+  }
+  35% {
+    border-color: var(--color-accent);
+  }
+  100% {
+    border-color: var(--color-border);
+  }
+}
+
+.wf-record-card-highlight {
+  animation: wf-record-card-highlight 1.5s ease-out forwards;
+}

packages/workflow-execute/.gitignore

@@ -0,0 +1 @@
+workflow-execute

packages/workflow-execute/src/engine/engine.ts

@@ -499,6 +499,7 @@ export async function executeThread(
       content: input.prompt,
       meta: {},
       timestamp: nowMs,
+      parentState: options.parentStateHash,
     },
     steps: input.steps.map((out, i) => ({
       role: out.role,

packages/workflow-execute/src/workflow-as-agent.ts

@@ -59,23 +59,23 @@ export function workflowAsAgent(
 
     const registryResult = await readWorkflowRegistry(storageRoot);
     if (!registryResult.ok) {
-      return `ERROR: failed to read workflow registry: ${registryResult.error.message}`;
+      return { output: `ERROR: failed to read workflow registry: ${registryResult.error.message}`, childThread: null };
     }
 
     const maxDepth = workflowAsAgentMaxDepth(registryResult.value.config);
     if (nextDepth > maxDepth) {
-      return `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`;
+      return { output: `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`, childThread: null };
     }
 
     const entry = getRegisteredWorkflow(registryResult.value, workflowName);
     if (entry === null) {
-      return `ERROR: workflow "${workflowName}" not found in registry`;
+      return { output: `ERROR: workflow "${workflowName}" not found in registry`, childThread: null };
     }
 
     const bundlePath = join(storageRoot, "bundles", `${entry.hash}.esm.js`);
     const bundleExportsResult = await extractBundleExports(bundlePath, { storageRoot });
     if (!bundleExportsResult.ok) {
-      return `ERROR: ${bundleExportsResult.error}`;
+      return { output: `ERROR: ${bundleExportsResult.error}`, childThread: null };
     }
 
     const input = {
@@ -121,7 +121,7 @@ export function workflowAsAgent(
       return { output: summary, childThread: result.rootHash };
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
-      return `ERROR: ${message}`;
+      return { output: `ERROR: ${message}`, childThread: null };
     }
   };
 }

packages/workflow-protocol/.gitignore

@@ -0,0 +1 @@
+workflow-protocol

packages/workflow-protocol/__tests__/moderator-table.test.ts

@@ -27,6 +27,7 @@ function makeCtx(roles: (keyof TestMeta & string)[]): ModeratorContext<TestMeta>
       content: "test",
       meta: {},
       timestamp: Date.now(),
+      parentState: null,
     } as StartStep,
     steps,
   };

packages/workflow-protocol/src/types.ts

@@ -62,6 +62,7 @@ export type StartStep = {
   content: string;
   meta: Record<string, never>;
   timestamp: number;
+  parentState: string | null;
 };
 
 export type RoleStep<M extends RoleMeta> = {

packages/workflow-register/.gitignore

@@ -0,0 +1 @@
+workflow-register

packages/workflow-register/src/bundle/bundle-validator.ts

@@ -37,13 +37,7 @@ function isAllowedImportSpecifier(spec: string): boolean {
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:")) {
     return false;
   }
-  if (
-    spec === "@uncaged/workflow" ||
-    spec === "@uncaged/workflow-runtime" ||
-    spec === "@uncaged/workflow-protocol" ||
-    spec === "@uncaged/workflow-cas" ||
-    spec === "@uncaged/workflow-util"
-  ) {
+  if (spec.startsWith("@uncaged/workflow")) {
     return true;
   }
   return isBuiltin(spec);
@@ -114,7 +108,8 @@ function bindingInitializerIsCallable(init: Node): boolean {
   return (
     init.type === "FunctionExpression" ||
     init.type === "ArrowFunctionExpression" ||
-    init.type === "CallExpression"
+    init.type === "CallExpression" ||
+    init.type === "Identifier"
   );
 }
 

packages/workflow-register/src/bundle/ensure-uncaged-workflow-symlink.ts

@@ -48,6 +48,9 @@ export async function ensureUncagedWorkflowSymlink(storageRoot: string): Promise
     { name: "workflow-runtime", dir: siblingPackageDir("workflow-runtime") },
     { name: "workflow-cas", dir: siblingPackageDir("workflow-cas") },
     { name: "workflow-protocol", dir: siblingPackageDir("workflow-protocol") },
+    { name: "workflow-util", dir: siblingPackageDir("workflow-util") },
+    { name: "workflow-execute", dir: siblingPackageDir("workflow-execute") },
+    { name: "workflow-register", dir: siblingPackageDir("workflow-register") },
   ];
 
   for (const pkg of packages) {

packages/workflow-runtime/.gitignore

@@ -0,0 +1 @@
+workflow-runtime

packages/workflow-runtime/src/build-context.ts

@@ -60,6 +60,7 @@ async function threadFromStartHead<M extends RoleMeta>(
       content: prompt,
       meta: {},
       timestamp: 0,
+      parentState: p.parentState,
     },
     steps: [],
   };
@@ -120,6 +121,7 @@ async function threadFromStateHead<M extends RoleMeta>(
       content: prompt,
       meta: {},
       timestamp: firstTs,
+      parentState: sp.parentState,
     },
     steps,
   };

packages/workflow-template-develop/__tests__/develop-template.test.ts

@@ -22,6 +22,7 @@ function makeStart(): ModeratorContext<DevelopMeta>["start"] {
     content: "Implement the feature",
     meta: {},
     timestamp: 0,
+    parentState: null,
   };
 }
 

packages/workflow-template-develop/bundle-entry.ts

@@ -2,19 +2,17 @@
  * develop bundle entry — 小橘 🍊
  *
  * All roles use cursor-agent with workspace auto-extracted from context.
+ *
+ * ENV VARS: WORKFLOW_LLM_API_KEY (required), WORKFLOW_LLM_BASE_URL,
+ * WORKFLOW_LLM_MODEL, WORKFLOW_CURSOR_MODEL, WORKFLOW_CURSOR_TIMEOUT.
+ * Must be set before the first worker spawn — workers are persistent and
+ * do not pick up env changes after initial import.
  */
 import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
+import type { AgentContext, AgentFn, AgentFnResult } from "@uncaged/workflow-runtime";
 import { createWorkflow } from "@uncaged/workflow-runtime";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
-function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (value === undefined || value === "") {
-    throw new Error(`missing required env var: ${name}`);
-  }
-  return value;
-}
-
 function optionalEnv(name: string): string | null {
   const value = process.env[name];
   if (value === undefined || value === "") {
@@ -23,23 +21,39 @@ function optionalEnv(name: string): string | null {
   return value;
 }
 
-const llmProvider = {
-  baseUrl:
-    optionalEnv("WORKFLOW_LLM_BASE_URL") ?? "https://dashscope.aliyuncs.com/compatible-mode/v1",
-  apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
-  model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
-};
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing required env var: ${name}`);
+  }
+  return value;
+}
 
-const agent = createCursorAgent({
-  model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
-  timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
-    ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
-    : 0,
-  workspace: null,
-  llmProvider,
-});
+function createLazyAgent(): AgentFn {
+  let cached: AgentFn | null = null;
+  return (ctx: AgentContext): Promise<AgentFnResult> => {
+    if (cached === null) {
+      const llmProvider = {
+        baseUrl:
+          optionalEnv("WORKFLOW_LLM_BASE_URL") ??
+          "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
+        model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
+      };
+      cached = createCursorAgent({
+        model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
+        timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
+          ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
+          : 0,
+        workspace: null,
+        llmProvider,
+      });
+    }
+    return cached(ctx);
+  };
+}
 
-const wf = createWorkflow(developWorkflowDefinition, { agent, overrides: null });
+const wf = createWorkflow(developWorkflowDefinition, { agent: createLazyAgent(), overrides: null });
 
 export const descriptor = buildDevelopDescriptor();
 export const run = wf;

packages/workflow-template-develop/package.json

@@ -12,6 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-agent-cursor": "workspace:*",
     "@uncaged/workflow-register": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"

packages/workflow-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -107,6 +107,7 @@ function makeStart(): ModeratorContext<SolveIssueMeta>["start"] {
     content: "Fix the flaky login test",
     meta: {},
     timestamp: 0,
+    parentState: null,
   };
 }
 
@@ -188,6 +189,7 @@ function makeThread(prompt: string) {
       content: prompt,
       meta: {},
       timestamp: Date.now(),
+      parentState: null,
     },
     steps: [],
   };

packages/workflow-template-solve-issue/bundle-entry.ts

@@ -3,6 +3,10 @@
  *
  * preparer + submitter → hermes agent
  * developer → workflow-as-agent (delegates to "develop" workflow)
+ *
+ * ENV VARS: WORKFLOW_HERMES_MODEL, WORKFLOW_HERMES_TIMEOUT.
+ * Must be set before the first worker spawn — workers are persistent and
+ * do not pick up env changes after initial import.
  */
 import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
 import { workflowAsAgent } from "@uncaged/workflow-execute";

packages/workflow-template-solve-issue/package.json

@@ -12,13 +12,14 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-agent-hermes": "workspace:*",
+    "@uncaged/workflow-execute": "workspace:*",
     "@uncaged/workflow-register": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@uncaged/workflow-cas": "workspace:*",
-    "@uncaged/workflow-execute": "workspace:*",
     "@uncaged/workflow-protocol": "workspace:*"
   }
 }

packages/workflow-util-agent/__tests__/build-agent-prompt.test.ts

@@ -3,12 +3,13 @@ import { type AgentContext, START } from "@uncaged/workflow-runtime";
 
 import { buildAgentPrompt } from "../src/index.js";
 
-function startTask(content: string): AgentContext["start"] {
+function startTask(content: string, parentState: string | null = null): AgentContext["start"] {
   return {
     role: START,
     content,
     meta: {},
     timestamp: 1,
+    parentState,
   };
 }
 
@@ -95,6 +96,35 @@ describe("buildAgentPrompt", () => {
     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";

packages/workflow-util-agent/src/build-agent-prompt.ts

@@ -5,6 +5,19 @@ export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
   const lines: string[] = [];
   lines.push(ctx.currentRole.systemPrompt);
   lines.push("");
+
+  if (ctx.start.parentState !== null) {
+    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.`,
+    );
+    lines.push("");
+  }
+
   lines.push("## Task");
   lines.push(ctx.start.content);
 

packages/workflow-util/.gitignore

@@ -0,0 +1 @@
+workflow-util

scripts/build-bundles.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Packages externalized from bundles — resolved at runtime via symlinks
+# created by ensureUncagedWorkflowSymlink in workflow-register.
+EXTERNAL=(
+  --external @uncaged/workflow-runtime
+  --external @uncaged/workflow-protocol
+  --external @uncaged/workflow-cas
+  --external @uncaged/workflow-util
+  --external @uncaged/workflow-execute
+  --external @uncaged/workflow-register
+)
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+mkdir -p dist
+
+echo "Building develop bundle..."
+bun build packages/workflow-template-develop/bundle-entry.ts \
+  --bundle --format esm --target bun \
+  "${EXTERNAL[@]}" \
+  --outfile dist/develop.esm.js
+
+echo "Building solve-issue bundle..."
+bun build packages/workflow-template-solve-issue/bundle-entry.ts \
+  --bundle --format esm --target bun \
+  "${EXTERNAL[@]}" \
+  --outfile dist/solve-issue.esm.js
+
+echo "Done. Bundles written to dist/"
+
+# Register bundles if --register flag is passed
+if [[ "${1:-}" == "--register" ]]; then
+  STORAGE_ROOT="${UNCAGED_WORKFLOW_STORAGE_ROOT:-${WORKFLOW_STORAGE_ROOT:-$HOME/.uncaged/workflow}}"
+  echo "Registering bundles..."
+  for bundle in develop solve-issue; do
+    cp "dist/${bundle}.esm.js" "$STORAGE_ROOT/${bundle}.esm.js"
+    uncaged-workflow workflow add "$bundle" "$STORAGE_ROOT/${bundle}.esm.js"
+  done
+  echo "Bundles registered."
+fi