@united-workforce/cli 0.3.0 → 0.5.0

package/src/output-mappers.ts

@@ -0,0 +1,254 @@
+import type { CasRef, StartOutput, StepOutput } from "@united-workforce/protocol";
+import { extractUlidTimestamp } from "@united-workforce/util";
+import type { ThreadListItemWithStatus } from "./commands/thread.js";
+import type {
+  WorkflowAddOutput,
+  WorkflowListEntry,
+  WorkflowShowOutput,
+} from "./commands/workflow.js";
+
+/**
+ * Mappers that convert the existing rich command outputs into the
+ * schema-aligned payload shapes registered under `@uwf/output/*`.
+ *
+ * Each mapper returns plain payload data — no CAS refs, no JSON encoding,
+ * no I/O. The CLI calls one of these immediately before handing the payload
+ * to `writeEnvelope`.
+ */
+
+export type ThreadStartPayload = {
+  threadId: string;
+  workflowHash: string;
+};
+
+export function toThreadStartPayload(out: StartOutput): ThreadStartPayload {
+  return { threadId: out.thread, workflowHash: out.workflow };
+}
+
+export type ThreadStatusPayload = {
+  threadId: string;
+  workflowHash: string;
+  head: string | null;
+  status: string;
+  currentRole: string | null;
+  suspendedRole: string | null;
+  suspendMessage: string | null;
+  done: boolean;
+};
+
+export function toThreadStatusPayload(out: StepOutput): ThreadStatusPayload {
+  return {
+    threadId: out.thread,
+    workflowHash: out.workflow,
+    head: out.head ?? null,
+    status: out.status,
+    currentRole: out.currentRole,
+    suspendedRole: out.suspendedRole,
+    suspendMessage: out.suspendMessage,
+    done: out.done,
+  };
+}
+
+export type ThreadListPayload = {
+  items: Array<{
+    threadId: string;
+    workflowHash: string;
+    workflowName: string | null;
+    status: string;
+    currentRole: string | null;
+    startedAt: number | null;
+    completedAt: number | null;
+  }>;
+};
+
+export function toThreadListPayload(items: ThreadListItemWithStatus[]): ThreadListPayload {
+  return {
+    items: items.map((it) => ({
+      threadId: it.thread,
+      workflowHash: it.workflow,
+      workflowName: it.workflowName,
+      status: it.status,
+      currentRole: it.currentRole,
+      startedAt: extractUlidTimestamp(it.thread),
+      completedAt: null,
+    })),
+  };
+}
+
+export type ThreadExecPayload = {
+  threadId: string;
+  workflowHash: string;
+  steps: Array<{
+    head: string;
+    status: string;
+    currentRole: string | null;
+    done: boolean;
+    role: string | null;
+    suspendedRole: string | null;
+    suspendMessage: string | null;
+  }>;
+};
+
+export function toThreadExecPayload(results: StepOutput[]): ThreadExecPayload {
+  const first = results[0];
+  return {
+    threadId: first?.thread ?? "",
+    workflowHash: first?.workflow ?? "",
+    steps: results.map((r) => ({
+      head: r.head,
+      status: r.status,
+      currentRole: r.currentRole,
+      done: r.done,
+      role: r.currentRole ?? r.suspendedRole ?? null,
+      suspendedRole: r.suspendedRole,
+      suspendMessage: r.suspendMessage,
+    })),
+  };
+}
+
+export type StepDetailPayload = {
+  hash: string;
+  role: string;
+  agent: string;
+  status: string;
+  startedAtMs: number | null;
+  completedAtMs: number | null;
+  durationMs: number | null;
+  frontmatter: Record<string, unknown>;
+  turns: Array<{ role: string; content: string; timestamp: number | null }>;
+};
+
+export function toStepDetailPayload(stepHash: CasRef, raw: unknown): StepDetailPayload {
+  const r = (raw ?? {}) as Record<string, unknown>;
+  const turnsIn = Array.isArray(r.turns) ? (r.turns as unknown[]) : [];
+  const startedAtMs = numericOrNull(r.startedAtMs);
+  const completedAtMs = numericOrNull(r.completedAtMs);
+  const durationMs =
+    startedAtMs !== null && completedAtMs !== null && completedAtMs >= startedAtMs
+      ? completedAtMs - startedAtMs
+      : null;
+  const frontmatter =
+    r.frontmatter !== null && typeof r.frontmatter === "object" && !Array.isArray(r.frontmatter)
+      ? (r.frontmatter as Record<string, unknown>)
+      : {};
+  const status =
+    typeof frontmatter.$status === "string"
+      ? (frontmatter.$status as string)
+      : typeof r.status === "string"
+        ? (r.status as string)
+        : "";
+  return {
+    hash: stepHash,
+    role: typeof r.role === "string" ? r.role : "",
+    agent: typeof r.agent === "string" ? r.agent : "",
+    status,
+    startedAtMs,
+    completedAtMs,
+    durationMs,
+    frontmatter,
+    turns: turnsIn.map((t) => {
+      const o = (t ?? {}) as Record<string, unknown>;
+      return {
+        role: typeof o.role === "string" ? o.role : "",
+        content: typeof o.content === "string" ? o.content : "",
+        timestamp: numericOrNull(o.timestamp),
+      };
+    }),
+  };
+}
+
+function numericOrNull(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+export type StepListPayload = {
+  threadId: string;
+  items: Array<{ hash: string; role: string; durationMs: number | null }>;
+};
+
+type StepsLikeOutput = {
+  thread: string;
+  steps: Array<{
+    hash: CasRef;
+    role?: string;
+    durationMs?: number;
+  }>;
+};
+
+export function toStepListPayload(out: StepsLikeOutput): StepListPayload {
+  return {
+    threadId: out.thread,
+    items: out.steps
+      .filter((s) => typeof s.role === "string")
+      .map((s) => ({
+        hash: s.hash,
+        role: s.role ?? "",
+        durationMs: typeof s.durationMs === "number" ? s.durationMs : null,
+      })),
+  };
+}
+
+export type WorkflowDetailPayload = {
+  name: string;
+  hash: string;
+  version: number;
+  description: string;
+  roles: Record<string, { description: string; goal: string }>;
+  graph: Record<string, Record<string, { role: string; prompt: string }>>;
+};
+
+export function toWorkflowDetailPayload(out: WorkflowShowOutput): WorkflowDetailPayload {
+  const roles: Record<string, { description: string; goal: string }> = {};
+  for (const [name, def] of Object.entries(out.payload.roles)) {
+    roles[name] = { description: def.description, goal: def.goal };
+  }
+  const graph: Record<string, Record<string, { role: string; prompt: string }>> = {};
+  for (const [from, transitions] of Object.entries(out.payload.graph)) {
+    const t: Record<string, { role: string; prompt: string }> = {};
+    for (const [status, target] of Object.entries(transitions)) {
+      t[status] = { role: target.role, prompt: target.prompt };
+    }
+    graph[from] = t;
+  }
+  return {
+    name: out.name ?? out.payload.name,
+    hash: out.hash,
+    version: out.payload.version,
+    description: out.payload.description,
+    roles,
+    graph,
+  };
+}
+
+export type WorkflowListPayload = {
+  items: Array<{ name: string; hash: string; source: string; description: string }>;
+};
+
+export function toWorkflowListPayload(entries: WorkflowListEntry[]): WorkflowListPayload {
+  return {
+    items: entries.map((e) => ({
+      name: e.name,
+      hash: e.hash,
+      source: e.origin === "local" ? ".workflows" : "registry",
+      description: "",
+    })),
+  };
+}
+
+export type WorkflowAddPayload = {
+  name: string;
+  hash: string;
+};
+
+export function toWorkflowAddPayload(out: WorkflowAddOutput): WorkflowAddPayload {
+  return { name: out.name, hash: out.hash };
+}
+
+export type ValidateResultPayload = {
+  valid: boolean;
+  errors: string[];
+};
+
+export function toValidateResultPayload(errors: string[]): ValidateResultPayload {
+  return { valid: errors.length === 0, errors };
+}

package/src/schemas.ts

@@ -1,6 +1,16 @@
 import type { Hash, Store } from "@ocas/core";
-import { putSchema } from "@ocas/core";
-import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@united-workforce/protocol";
+import { bootstrap, putSchema } from "@ocas/core";
+import {
+  ERROR_OUTPUT_SCHEMA,
+  OUTPUT_SCHEMAS,
+  OUTPUT_TEMPLATES,
+  type OutputSchemaName,
+  outputSchemaVarName,
+  START_NODE_SCHEMA,
+  STEP_NODE_SCHEMA,
+  SUSPEND_OUTPUT_SCHEMA,
+  WORKFLOW_SCHEMA,
+} from "@united-workforce/protocol";
 
 export const TEXT_SCHEMA = { type: "string" as const };
 
@@ -9,18 +19,54 @@ export type UwfSchemaHashes = {
   startNode: Hash;
   stepNode: Hash;
   text: Hash;
+  errorOutput: Hash;
+  suspendOutput: Hash;
+  outputs: Record<OutputSchemaName, Hash>;
 };
 
 /**
- * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
+ * Register every uwf JSON Schema (workflow / start / step / error / suspend
+ * + the 9 CLI output envelopes) and the matching `text` Liquid templates.
  * Idempotent: safe to call on every CLI invocation.
  */
 export async function registerUwfSchemas(store: Store): Promise<UwfSchemaHashes> {
-  const [workflow, startNode, stepNode, text] = await Promise.all([
+  const [workflow, startNode, stepNode, text, errorOutput, suspendOutput] = await Promise.all([
     putSchema(store, WORKFLOW_SCHEMA),
     putSchema(store, START_NODE_SCHEMA),
     putSchema(store, STEP_NODE_SCHEMA),
     putSchema(store, TEXT_SCHEMA),
+    putSchema(store, ERROR_OUTPUT_SCHEMA),
+    putSchema(store, SUSPEND_OUTPUT_SCHEMA),
   ]);
-  return { workflow, startNode, stepNode, text };
+  const outputs = await registerOutputSchemas(store);
+  return { workflow, startNode, stepNode, text, errorOutput, suspendOutput, outputs };
+}
+
+/**
+ * Register the 9 CLI output schemas, bind `@uwf/output/<name>` to each, store
+ * each Liquid template as an `@ocas/string` CAS node, and bind
+ * `@ocas/template/text/<schemaHash>` to the template content hash.
+ *
+ * Idempotent: writes are content-addressed so repeat invocations no-op.
+ */
+async function registerOutputSchemas(store: Store): Promise<Record<OutputSchemaName, Hash>> {
+  const aliases = bootstrap(store);
+  const stringHash = aliases["@ocas/string"];
+  if (stringHash === undefined) {
+    throw new Error("@ocas/string schema not found in bootstrap result");
+  }
+
+  const result = {} as Record<OutputSchemaName, Hash>;
+  const names = Object.keys(OUTPUT_SCHEMAS) as OutputSchemaName[];
+  for (const name of names) {
+    const schemaHash = await putSchema(store, OUTPUT_SCHEMAS[name]);
+    store.var.set(outputSchemaVarName(name), schemaHash);
+
+    const template = OUTPUT_TEMPLATES[name];
+    const contentHash = store.cas.put(stringHash, template);
+    store.var.set(`@ocas/template/text/${schemaHash}`, contentHash);
+
+    result[name] = schemaHash;
+  }
+  return result;
 }

package/src/store.ts

@@ -2,7 +2,7 @@ import type { Dirent } from "node:fs";
 import { existsSync } from "node:fs";
 import { access, mkdir, readdir, readFile, rename } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve as resolvePath } from "node:path";
 
 import { bootstrap, type Hash, type Store, type VarStore } from "@ocas/core";
 import { createFsStore, createSqliteVarStore } from "@ocas/fs";
@@ -20,7 +20,7 @@ export const REGISTRY_VAR_PREFIX = "@uwf/registry/";
 /** Variable name prefix for active thread entries (`@uwf/thread/<thread-id>`). */
 export const THREAD_VAR_PREFIX = "@uwf/thread/";
 
-/** A workflow entry discovered from the project-local .workflows/ directory. */
+/** A workflow entry discovered from the project-local .workflows/ (primary) or .workflow/ (legacy) directory. */
 export type ProjectWorkflowEntry = {
   /** Workflow name (from YAML `name` field, equals filename stem). */
   name: string;
@@ -82,16 +82,11 @@ async function scanWorkflowDir(dir: string): Promise<ProjectWorkflowEntry[]> {
   return result;
 }
 
-/**
- * Scan `<projectRoot>/.workflow/` (preferred) and `.workflows/` (legacy) for workflow entries.
- * .workflow/ takes priority: if a name is found in both, .workflow/ wins.
- * Returns an empty array if neither directory exists.
- */
-export async function discoverProjectWorkflows(
-  projectRoot: string,
-): Promise<ProjectWorkflowEntry[]> {
-  const primary = await scanWorkflowDir(join(projectRoot, ".workflow"));
-  const legacy = await scanWorkflowDir(join(projectRoot, ".workflows"));
+/** Merge primary (.workflows/) and legacy (.workflow/) entries, primary wins on name collision. */
+function mergeWorkflowEntries(
+  primary: ProjectWorkflowEntry[],
+  legacy: ProjectWorkflowEntry[],
+): ProjectWorkflowEntry[] {
   const seen = new Set(primary.map((e) => e.name));
   const merged = [...primary];
   for (const entry of legacy) {
@@ -102,6 +97,63 @@ export async function discoverProjectWorkflows(
   return merged;
 }
 
+/** Check if a directory contains a .git marker (directory or file). */
+async function hasGitMarker(dir: string): Promise<boolean> {
+  try {
+    await access(join(dir, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discover project-local workflows by walking from `startDir` up through parent
+ * directories. The nearest directory that contains a `.workflows/` or `.workflow/`
+ * directory wins — once a match is found, traversal stops (entries from more
+ * distant ancestors are NOT merged in).
+ *
+ * Within the winning directory:
+ * - `.workflows/` (preferred/primary) takes priority over `.workflow/` (legacy fallback).
+ * - If both exist in that directory, `.workflows/` entries win when names collide.
+ *
+ * This matches the resolution strategy of `findWorkflowInParents` used by
+ * `uwf thread start`, so `uwf workflow list` and `uwf thread start` agree on
+ * what's discoverable from any given subdirectory.
+ *
+ * Traversal stops at the first `.git` boundary (directory or file) or the
+ * filesystem root. Returns an empty array if no `.workflows/` or `.workflow/`
+ * directory exists within that range.
+ */
+export async function discoverProjectWorkflows(startDir: string): Promise<ProjectWorkflowEntry[]> {
+  let currentDir = resolvePath(startDir);
+  const root = resolvePath("/");
+
+  while (true) {
+    const primary = await scanWorkflowDir(join(currentDir, ".workflows"));
+    const legacy = await scanWorkflowDir(join(currentDir, ".workflow"));
+
+    if (primary.length > 0 || legacy.length > 0) {
+      return mergeWorkflowEntries(primary, legacy);
+    }
+
+    // Stop at .git boundary (repo root)
+    if (await hasGitMarker(currentDir)) {
+      return [];
+    }
+
+    // Stop at filesystem root
+    if (currentDir === root) {
+      return [];
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return [];
+    }
+    currentDir = parentDir;
+  }
+}
+
 /** Default filesystem root for uwf data (`~/.uwf`). */
 export function getDefaultStorageRoot(): string {
   return join(homedir(), ".uwf");
@@ -335,35 +387,35 @@ export function setThread(varStore: VarStore, threadId: ThreadId, entry: ThreadI
   varStore.set(name, entry.head, { tags });
 }
 
-/** Load only active threads (status not in completed/cancelled). */
+/** Load only active threads (status not in end/cancelled). */
 export function loadActiveThreads(varStore: VarStore): ThreadsIndex {
   const all = loadAllThreads(varStore);
   const active: ThreadsIndex = {};
   for (const [threadId, entry] of Object.entries(all)) {
-    if (entry.status !== "completed" && entry.status !== "cancelled") {
+    if (entry.status !== "end" && entry.status !== "cancelled") {
       active[threadId as ThreadId] = entry;
     }
   }
   return active;
 }
 
-/** Load only completed/cancelled threads (history). */
+/** Load only end/cancelled threads (history). */
 export function loadHistoryThreads(varStore: VarStore): ThreadsIndex {
   const all = loadAllThreads(varStore);
   const history: ThreadsIndex = {};
   for (const [threadId, entry] of Object.entries(all)) {
-    if (entry.status === "completed" || entry.status === "cancelled") {
+    if (entry.status === "end" || entry.status === "cancelled") {
       history[threadId as ThreadId] = entry;
     }
   }
   return history;
 }
 
-/** Complete a thread by marking it completed or cancelled. */
+/** Complete a thread by marking it end or cancelled. */
 export function completeThread(
   varStore: VarStore,
   threadId: ThreadId,
-  reason: "completed" | "cancelled",
+  reason: "end" | "cancelled",
 ): void {
   const entry = getThread(varStore, threadId);
   if (entry === null) {
@@ -377,6 +429,20 @@ export function completeThread(
     completedAt: Date.now(),
   } as ThreadIndexEntry;
   setThread(varStore, threadId, completed);
+  clearThreadFailedAttempts(varStore, threadId);
+}
+
+/**
+ * Remove all `@uwf/thread-failed/<threadId>/*` variables for a thread.
+ * Called on thread completion / cancellation so retry-lineage state does not
+ * leak into the variable store after the thread is archived.
+ */
+export function clearThreadFailedAttempts(varStore: VarStore, threadId: ThreadId): void {
+  const prefix = `@uwf/thread-failed/${threadId}/`;
+  const vars = varStore.list({ namePrefix: prefix });
+  for (const v of vars) {
+    varStore.remove(v.name);
+  }
 }
 
 type LegacyHistoryEntry = {
@@ -439,7 +505,7 @@ export async function migrateHistoryIfNeeded(
     }
     const entry = parseLegacyHistoryJsonlLine(trimmed);
     if (entry !== null) {
-      const status = entry.reason === "cancelled" ? "cancelled" : "completed";
+      const status = entry.reason === "cancelled" ? "cancelled" : "end";
       const threadEntry: ThreadIndexEntry = {
         head: entry.head,
         status: status as ThreadIndexEntry["status"],
@@ -462,7 +528,7 @@ export function migrateHistoryVarsToThreadVars(varStore: VarStore): void {
   for (const v of vars) {
     const threadId = v.name.slice(LEGACY_HISTORY_VAR_PREFIX.length) as ThreadId;
     const reason = v.tags.reason;
-    const status = reason === "cancelled" ? "cancelled" : "completed";
+    const status = reason === "cancelled" ? "cancelled" : "end";
     const completedAt = Number(v.tags.completedAt ?? Date.now());
 
     const threadEntry: ThreadIndexEntry = {