@united-workforce/cli 0.4.0 → 0.6.0

package/src/commands/thread.ts

@@ -43,6 +43,7 @@ import {
   isThreadRunning,
   readMarker,
 } from "../background/index.js";
+import { acquireSlot, DEFAULT_MAX_RUNNING, installSlotCleanup } from "../concurrency/index.js";
 import { createIncludeTag } from "../include.js";
 import { evaluate } from "../moderator/index.js";
 import {
@@ -60,6 +61,13 @@ import {
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
+import {
+  getConfigPath,
+  getNestedValue,
+  loadConfig,
+  loadWorkflowPaths,
+  parseDotPath,
+} from "./config.js";
 import {
   type ChainState,
   collectOrderedSteps,
@@ -166,6 +174,13 @@ async function resolveActiveThreadStatus(
     return "running";
   }
 
+  // Check the persisted entry status first — agent failure suspends the thread
+  // via markThreadSuspended() without producing a $SUSPEND output in CAS.
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry !== null && entry.status === "suspended") {
+    return "suspended";
+  }
+
   const chain = walkChain(uwf, head);
   const { lastOutput } = resolveEvaluateArgs(uwf, chain);
   if (readSuspendReason(lastOutput) !== null) {
@@ -225,9 +240,20 @@ function buildResumePrompt(graphPrompt: string, supplement: string | null): stri
   return `${graphPrompt}\n\n${supplement}`;
 }
 
+/**
+ * Error thrown by failStep so that callers can catch it, persist
+ * thread state (e.g. suspend), and then re-throw / exit.
+ */
+class StepFailureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StepFailureError";
+  }
+}
+
 function failStep(plog: ProcessLogger, message: string): never {
   plog.log(PL_STEP_ERROR, message, null);
-  fail(message);
+  throw new StepFailureError(message);
 }
 
 /**
@@ -344,6 +370,49 @@ async function findWorkflowInParents(startDir: string, name: string): Promise<st
   return null;
 }
 
+/**
+ * Search for a workflow by name directly in a directory (not inside .workflows/).
+ * Used for workflowPaths resolution — each path dir contains YAMLs at top level.
+ * Checks flat files (<name>.yaml/.yml) and folder layout (<name>/index.yaml/.yml).
+ */
+async function findWorkflowInPath(dir: string, name: string): Promise<string | null> {
+  // Check flat YAML files
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(dir, name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+  // Check folder-based layout (<name>/index.yaml)
+  for (const indexName of ["index.yaml", "index.yml"]) {
+    const candidate = resolvePath(dir, name, indexName);
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      /* not found */
+    }
+  }
+  return null;
+}
+
+/**
+ * Search workflowPaths directories for a workflow by name.
+ * Searches each directory in order; first match wins.
+ */
+async function findWorkflowInPaths(
+  dirs: ReadonlyArray<string>,
+  name: string,
+): Promise<string | null> {
+  for (const dir of dirs) {
+    const found = await findWorkflowInPath(dir, name);
+    if (found !== null) {
+      return found;
+    }
+  }
+  return null;
+}
+
 async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
   let text: string;
   try {
@@ -419,6 +488,13 @@ async function resolveWorkflowCasRef(
     return materializeLocalWorkflow(uwf, localPath);
   }
 
+  // Strategy 3.5: workflowPaths global directories
+  const workflowPaths = loadWorkflowPaths(uwf.storageRoot);
+  const pathsFile = await findWorkflowInPaths(workflowPaths, trimmed);
+  if (pathsFile !== null) {
+    return materializeLocalWorkflow(uwf, pathsFile);
+  }
+
   // Strategy 4: Global registry fallback
   const registry = loadWorkflowRegistry(uwf.varStore);
   const hash = resolveWorkflowHash(registry, trimmed);
@@ -992,6 +1068,15 @@ type EvaluateLastOutput = Record<string, unknown>;
 
 const STATUS_KEY = "$status";
 
+/**
+ * Strip YAML frontmatter (---...---) from a raw markdown string,
+ * returning only the body portion.
+ */
+function stripFrontmatter(raw: string): string {
+  const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return match ? raw.slice(match[0].length).trim() : raw.trim();
+}
+
 function resolveEvaluateArgs(
   uwf: UwfStore,
   chain: ChainState,
@@ -1011,6 +1096,13 @@ function resolveEvaluateArgs(
       ? (raw as Record<string, unknown>)
       : {};
 
+  // Inject _body — the markdown body (after frontmatter) from the last step's
+  // assistant output. Workflow edge prompts can reference it via {{ _body }}.
+  const content = extractLastAssistantContent(uwf, lastStep.detail);
+  if (content !== null) {
+    base._body = stripFrontmatter(content);
+  }
+
   return {
     lastRole: lastStep.role,
     lastOutput: base,
@@ -1020,10 +1112,10 @@ function resolveEvaluateArgs(
 function loadWorkflowPayload(uwf: UwfStore, workflowRef: CasRef): WorkflowPayload {
   const node = uwf.store.cas.get(workflowRef);
   if (node === null) {
-    fail(`workflow CAS node not found: ${workflowRef}`);
+    throw new Error(`workflow CAS node not found: ${workflowRef}`);
   }
   if (node.type !== uwf.schemas.workflow) {
-    fail(`node ${workflowRef} is not a Workflow`);
+    throw new Error(`node ${workflowRef} is not a Workflow`);
   }
   return node.payload as WorkflowPayload;
 }
@@ -1360,7 +1452,18 @@ export async function cmdThreadPoke(
   // Spawn the agent. The agent will create a new StepNode with prev=oldHead (it reads
   // the active thread head). After the agent returns, we rewrite that node's prev so
   // that the new head replaces the old head instead of appending after it.
-  const agentResult = spawnAgent(plog, agent, threadId, role, prompt, effectiveCwd);
+  let agentResult: AdapterOutput;
+  try {
+    agentResult = spawnAgent(plog, agent, threadId, role, prompt, effectiveCwd);
+  } catch (e) {
+    if (e instanceof StepFailureError) {
+      // Fatal agent failure in poke — persist suspended state before propagating
+      const uwfErr = await createUwfStore(storageRoot);
+      const errEntry = getThread(uwfErr.varStore, threadId) ?? entry;
+      setThread(uwfErr.varStore, threadId, markThreadSuspended(errEntry, role, e.message));
+    }
+    throw e;
+  }
   const agentStepHash = agentResult.stepHash as CasRef;
 
   plog.log(PL_AGENT_DONE, `agent returned head=${agentStepHash}`, null);
@@ -1406,6 +1509,25 @@ export function validateCount(count: number): void {
   }
 }
 
+/**
+ * Resolve the effective maxRunning limit.
+ * Priority: config file > DEFAULT_MAX_RUNNING (2).
+ */
+async function resolveMaxRunning(storageRoot: string): Promise<number> {
+  try {
+    const configPath = getConfigPath(storageRoot);
+    const config = loadConfig(configPath);
+    const path = parseDotPath("concurrency.maxRunning");
+    const value = getNestedValue(config, path);
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+      return value;
+    }
+  } catch {
+    // Config file missing or invalid — fall through to default
+  }
+  return DEFAULT_MAX_RUNNING;
+}
+
 export async function cmdThreadExec(
   storageRoot: string,
   threadId: ThreadId,
@@ -1446,6 +1568,13 @@ export async function cmdThreadExec(
     processStartTime: getProcessStartTime(process.pid),
   });
 
+  // Resolve concurrency limit: config > default
+  const effectiveMaxRunning = await resolveMaxRunning(storageRoot);
+
+  // Acquire concurrency slot (blocks if at capacity)
+  const slotHandle = await acquireSlot(storageRoot, effectiveMaxRunning);
+  const uninstallCleanup = installSlotCleanup(slotHandle);
+
   try {
     const results: StepOutput[] = [];
     for (let i = 0; i < count; i++) {
@@ -1457,10 +1586,101 @@ export async function cmdThreadExec(
     }
     return results;
   } finally {
+    uninstallCleanup();
+    await slotHandle.release();
     await deleteMarker(storageRoot, threadId);
   }
 }
 
+const JOIN_POLL_INTERVAL_MS = 1000;
+
+/**
+ * Block until a running thread finishes (marker disappears), then return the
+ * final thread state in the same `StepOutput[]` format that `cmdThreadExec`
+ * produces.
+ *
+ * - If the thread is currently running → poll until it stops, then return
+ *   its final state.
+ * - If the thread is not running → return its current state immediately.
+ *
+ * An optional `timeoutMs` aborts the wait with an error when exceeded.
+ */
+export async function cmdThreadJoin(
+  storageRoot: string,
+  threadId: ThreadId,
+  timeoutMs: number | null,
+): Promise<StepOutput[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry === null) {
+    fail(`thread not found: ${threadId}`);
+  }
+
+  // Wait for running marker to disappear
+  const deadline = timeoutMs !== null ? Date.now() + timeoutMs : null;
+
+  while ((await isThreadRunning(storageRoot, threadId)) !== null) {
+    if (deadline !== null && Date.now() >= deadline) {
+      fail(`join timed out after ${timeoutMs}ms — thread ${threadId} is still running`);
+    }
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, JOIN_POLL_INTERVAL_MS);
+    });
+  }
+
+  // Thread is no longer running — read final state.
+  // Re-open the store to get the latest state written by the worker.
+  const freshUwf = await createUwfStore(storageRoot);
+  const freshEntry = getThread(freshUwf.varStore, threadId);
+  if (freshEntry === null) {
+    fail(`thread disappeared after join: ${threadId}`);
+  }
+
+  const activeHead = freshEntry.head;
+  const workflowHash = resolveWorkflowFromHead(freshUwf, activeHead);
+  if (workflowHash === null) {
+    fail(`failed to resolve workflow from head: ${activeHead}`);
+  }
+
+  // Build the StepOutput matching exec's format
+  if (freshEntry.status === "end" || freshEntry.status === "cancelled") {
+    return [
+      {
+        workflow: workflowHash,
+        thread: threadId,
+        head: activeHead,
+        status: freshEntry.status,
+        currentRole: null,
+        suspendedRole: null,
+        suspendMessage: null,
+        done: true,
+        background: null,
+        error: null,
+      },
+    ];
+  }
+
+  // Active thread — resolve detailed status
+  const status = await resolveActiveThreadStatus(storageRoot, threadId, freshUwf, activeHead);
+  const currentRole = resolveCurrentRole(freshUwf, activeHead, workflowHash);
+  const suspendFields = resolveSuspendFieldsForShow(freshEntry, status, freshUwf, activeHead);
+
+  return [
+    {
+      workflow: workflowHash,
+      thread: threadId,
+      head: activeHead,
+      status,
+      currentRole,
+      suspendedRole: suspendFields.suspendedRole,
+      suspendMessage: suspendFields.suspendMessage,
+      done: false,
+      background: null,
+      error: null,
+    },
+  ];
+}
+
 async function resolveActiveThreadWorkflowHash(
   storageRoot: string,
   threadId: ThreadId,
@@ -1715,6 +1935,51 @@ async function cmdThreadStepOnce(
   });
 
   loadDotenv({ path: getEnvPath(storageRoot) });
+
+  // Wrap agent execution in a try-catch: when the agent command crashes
+  // (non-zero exit, unparseable output, invalid CAS node, etc.), failStep throws
+  // StepFailureError. We catch it to persist suspended state before re-throwing
+  // so the CLI still exits non-zero.
+  try {
+    return await executeAndProcessAgentStep(
+      storageRoot,
+      threadId,
+      headHash,
+      workflowHash,
+      workflow,
+      role,
+      edgePrompt,
+      effectiveCwd,
+      agent,
+      plog,
+    );
+  } catch (e) {
+    if (e instanceof StepFailureError) {
+      // Fatal agent failure — persist suspended state before propagating
+      const uwfErr = await createUwfStore(storageRoot);
+      const errEntry = getThread(uwfErr.varStore, threadId) ?? createThreadIndexEntry(headHash);
+      setThread(uwfErr.varStore, threadId, markThreadSuspended(errEntry, role, e.message));
+    }
+    throw e;
+  }
+}
+
+/**
+ * Execute the agent command and process the result. Separated from cmdThreadStepOnce
+ * so that fatal failures (StepFailureError) can be caught and handled by the caller.
+ */
+async function executeAndProcessAgentStep(
+  storageRoot: string,
+  threadId: ThreadId,
+  headHash: CasRef,
+  workflowHash: CasRef,
+  workflow: WorkflowPayload,
+  role: string,
+  edgePrompt: string,
+  effectiveCwd: string,
+  agent: AgentConfig,
+  plog: ProcessLogger,
+): Promise<StepOutput> {
   const agentResult = spawnAgent(plog, agent, threadId, role, edgePrompt, effectiveCwd);
   const newHead = agentResult.stepHash as CasRef;
 
@@ -1732,22 +1997,28 @@ async function cmdThreadStepOnce(
   // next exec (until eventual success records `previousAttempts` linking the
   // failed step hashes).
   if (agentResult.isError === true) {
+    const errorMsg = agentResult.errorMessage ?? "agent reported error";
     plog.log(
       PL_AGENT_ERROR,
-      `agent reported recoverable failure stepHash=${newHead} message=${agentResult.errorMessage ?? ""}`,
+      `agent reported recoverable failure stepHash=${newHead} message=${errorMsg}`,
       null,
     );
+
+    // Persist suspended state so `thread list --status suspended` reflects the failure.
+    const priorEntry = getThread(uwfAfter.varStore, threadId) ?? createThreadIndexEntry(headHash);
+    setThread(uwfAfter.varStore, threadId, markThreadSuspended(priorEntry, role, errorMsg));
+
     return {
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
-      status: "idle",
+      status: "suspended",
       currentRole: role,
-      suspendedRole: null,
-      suspendMessage: null,
+      suspendedRole: role,
+      suspendMessage: errorMsg,
       done: false,
       background: null,
-      error: { stepHash: newHead, message: agentResult.errorMessage ?? "agent reported error" },
+      error: { stepHash: newHead, message: errorMsg },
     };
   }
 

package/src/commands/workflow.ts

@@ -10,6 +10,7 @@ import { createIncludeTag } from "../include.js";
 import {
   createUwfStore,
   discoverProjectWorkflows,
+  discoverWorkflowPathsEntries,
   findRegistryName,
   loadWorkflowRegistry,
   resolveProjectWorkflowFile,
@@ -24,8 +25,9 @@ import {
   parseWorkflowPayload,
 } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
+import { loadWorkflowPaths } from "./config.js";
 
-export type WorkflowOrigin = "local" | "global";
+export type WorkflowOrigin = "local" | "paths" | "global";
 
 export type WorkflowListEntry = {
   name: string;
@@ -126,7 +128,7 @@ export async function materializeWorkflowPayload(
  * returns silently (no stdout/stderr) and exits 0. On any error, writes a
  * single message to stderr and exits 1.
  */
-export async function cmdWorkflowValidate(filePath: string): Promise<void> {
+export async function cmdWorkflowValidate(filePath: string): Promise<string[]> {
   let text: string;
   try {
     text = await readFile(filePath, "utf8");
@@ -150,20 +152,19 @@ export async function cmdWorkflowValidate(filePath: string): Promise<void> {
 
   const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
   if (filenameError !== null) {
-    fail(filenameError);
+    return [filenameError];
   }
 
-  const semanticErrors = validateWorkflow(payload);
-  if (semanticErrors.length > 0) {
-    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
-  }
-  // success: silent return
+  return validateWorkflow(payload);
 }
 
 export async function cmdWorkflowAdd(
   storageRoot: string,
   filePath: string,
 ): Promise<WorkflowAddOutput> {
+  process.stderr.write(
+    "warning: `uwf workflow add` is deprecated. Use workflowPaths in ~/.uwf/config.yaml instead. See issue #360.\n",
+  );
   let text: string;
   try {
     text = await readFile(filePath, "utf8");
@@ -299,6 +300,14 @@ async function resolveWorkflowCasRefForShow(
     return materializeLocalWorkflowForShow(uwf, localPath);
   }
 
+  // Strategy 3.5: workflowPaths global directories
+  const workflowPaths = loadWorkflowPaths(uwf.storageRoot);
+  const pathsEntries = await discoverWorkflowPathsEntries(workflowPaths);
+  const pathsFile = resolveProjectWorkflowFile(pathsEntries, trimmed);
+  if (pathsFile !== null) {
+    return materializeLocalWorkflowForShow(uwf, pathsFile);
+  }
+
   // Strategy 4: Global registry fallback
   const registry = loadWorkflowRegistry(uwf.varStore);
   const hash = resolveWorkflowHash(registry, trimmed);
@@ -348,18 +357,30 @@ export async function cmdWorkflowList(
 ): Promise<WorkflowListEntry[]> {
   const uwf = await createUwfStore(storageRoot);
   const localEntries = await discoverProjectWorkflows(projectRoot);
+  const workflowPaths = loadWorkflowPaths(storageRoot);
+  const pathsEntries = await discoverWorkflowPathsEntries(workflowPaths);
   const registry = loadWorkflowRegistry(uwf.varStore);
 
   const result: WorkflowListEntry[] = [];
-  const localNames = new Set<string>();
+  const seenNames = new Set<string>();
 
+  // Layer 1: local .workflows/ (highest priority)
   for (const entry of localEntries) {
-    localNames.add(entry.name);
+    seenNames.add(entry.name);
     result.push({ name: entry.name, hash: "(local)", origin: "local" });
   }
 
+  // Layer 2: workflowPaths directories
+  for (const entry of pathsEntries) {
+    if (!seenNames.has(entry.name)) {
+      seenNames.add(entry.name);
+      result.push({ name: entry.name, hash: "(paths)", origin: "paths" });
+    }
+  }
+
+  // Layer 3: global registry (lowest priority)
   for (const [name, hash] of Object.entries(registry)) {
-    if (!localNames.has(name)) {
+    if (!seenNames.has(name)) {
       result.push({ name, hash, origin: "global" });
     }
   }