@united-workforce/cli 0.1.0

package/src/commands/shared.ts

@@ -0,0 +1,227 @@
+import type { Store as CasStore, JSONSchema } from "@ocas/core";
+import { getSchema } from "@ocas/core";
+import type {
+  CasRef,
+  StartNodePayload,
+  StepNodePayload,
+  ThreadId,
+} from "@united-workforce/protocol";
+import { createUwfStore, getThread, type UwfStore } from "../store.js";
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+type OrderedStepItem = {
+  hash: CasRef;
+  payload: StepNodePayload;
+  timestamp: number;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function walkChain(uwf: UwfStore, headHash: CasRef): ChainState {
+  const headNode = uwf.store.cas.get(headHash);
+  if (headNode === null) {
+    fail(`CAS node not found: ${headHash}`);
+  }
+
+  if (headNode.type === uwf.schemas.startNode) {
+    return {
+      startHash: headHash,
+      start: headNode.payload as StartNodePayload,
+      stepsNewestFirst: [],
+      headIsStart: true,
+    };
+  }
+
+  if (headNode.type !== uwf.schemas.stepNode) {
+    fail(`head ${headHash} is not a StartNode or StepNode`);
+  }
+
+  const stepsNewestFirst: StepNodePayload[] = [];
+  let hash: CasRef | null = headHash;
+
+  while (hash !== null) {
+    const node = uwf.store.cas.get(hash);
+    if (node === null) {
+      fail(`CAS node not found while walking chain: ${hash}`);
+    }
+    if (node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    stepsNewestFirst.push(payload);
+    hash = payload.prev;
+  }
+
+  const newest = stepsNewestFirst[0];
+  if (newest === undefined) {
+    fail(`empty step chain at head ${headHash}`);
+  }
+
+  const startNode = uwf.store.cas.get(newest.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    fail(`StartNode not found: ${newest.start}`);
+  }
+
+  return {
+    startHash: newest.start,
+    start: startNode.payload as StartNodePayload,
+    stepsNewestFirst,
+    headIsStart: false,
+  };
+}
+
+function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
+  const node = uwf.store.cas.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+/**
+ * Recursively expand all ocas_ref fields in a CAS node's payload,
+ * replacing hash strings with the referenced node's expanded payload.
+ */
+function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unknown {
+  const seen = visited ?? new Set<string>();
+  if (seen.has(hash)) return hash; // cycle guard
+  seen.add(hash);
+
+  const node = store.cas.get(hash);
+  if (node === null) return hash;
+
+  const schema = getSchema(store, node.type);
+  if (schema === null) return node.payload;
+
+  return expandValue(store, schema, node.payload, seen);
+}
+
+function expandCasRefField(store: CasStore, value: unknown, visited: Set<string>): unknown {
+  if (typeof value === "string") {
+    return expandDeep(store, value as CasRef, visited);
+  }
+  return value;
+}
+
+function expandAnyOfField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (!Array.isArray(schema.anyOf)) return value;
+  for (const sub of schema.anyOf as JSONSchema[]) {
+    if (sub.format === "ocas_ref" && typeof value === "string") {
+      return expandDeep(store, value as CasRef, visited);
+    }
+  }
+  return value;
+}
+
+function expandArrayField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (!schema.items || !Array.isArray(value)) return value;
+  const itemSchema = schema.items as JSONSchema;
+  return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
+}
+
+function expandObjectField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || !schema.properties) {
+    return value;
+  }
+  const props = schema.properties as Record<string, JSONSchema>;
+  const obj = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    const propSchema = props[key];
+    result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
+  }
+  return result;
+}
+
+function expandValue(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (schema.format === "ocas_ref") return expandCasRefField(store, value, visited);
+  if (Array.isArray(schema.anyOf)) return expandAnyOfField(store, schema, value, visited);
+  if (schema.type === "array") return expandArrayField(store, schema, value, visited);
+  return expandObjectField(store, schema, value, visited);
+}
+
+function collectOrderedSteps(
+  uwf: UwfStore,
+  headHash: CasRef,
+  chain: ChainState,
+): OrderedStepItem[] {
+  let hash: CasRef | null = headHash;
+  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
+  while (hash !== null) {
+    const node = uwf.store.cas.get(hash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    hashToNode.set(hash, { payload, timestamp: node.timestamp });
+    hash = payload.prev;
+  }
+
+  let cur: CasRef | null = chain.headIsStart ? null : headHash;
+  const ordered: OrderedStepItem[] = [];
+  while (cur !== null) {
+    const entry = hashToNode.get(cur);
+    if (entry === undefined) {
+      break;
+    }
+    ordered.push({ hash: cur, ...entry });
+    cur = entry.payload.prev;
+  }
+
+  ordered.reverse();
+  return ordered;
+}
+
+async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise<CasRef> {
+  const uwf = await createUwfStore(storageRoot);
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry !== null) {
+    return entry.head;
+  }
+  fail(`thread not found: ${threadId}`);
+}
+
+export {
+  type ChainState,
+  collectOrderedSteps,
+  expandAnyOfField,
+  expandArrayField,
+  expandCasRefField,
+  expandDeep,
+  expandObjectField,
+  expandOutput,
+  expandValue,
+  fail,
+  type OrderedStepItem,
+  resolveHeadHash,
+  walkChain,
+};

package/src/commands/step.ts

@@ -0,0 +1,343 @@
+import type { CasStore } from "@ocas/core";
+import type {
+  CasRef,
+  StartEntry,
+  StepEntry,
+  StepNodePayload,
+  ThreadForkOutput,
+  ThreadId,
+  ThreadStepsOutput,
+} from "@united-workforce/protocol";
+import { generateUlid } from "@united-workforce/util";
+import { createUwfStore, setThread } from "../store.js";
+import {
+  collectOrderedSteps,
+  expandDeep,
+  expandOutput,
+  fail,
+  resolveHeadHash,
+  walkChain,
+} from "./shared.js";
+
+type TurnToolCall = {
+  name: string;
+  args: string;
+};
+
+type TurnData = {
+  index: number;
+  role: string;
+  content: string;
+  toolCalls: TurnToolCall[] | null;
+};
+
+/**
+ * List all steps in a thread (previously: thread steps)
+ */
+export async function cmdStepList(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadStepsOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+
+  const startNode = uwf.store.cas.get(chain.startHash);
+  if (startNode === null) {
+    fail(`StartNode not found: ${chain.startHash}`);
+  }
+
+  const startEntry: StartEntry = {
+    hash: chain.startHash,
+    workflow: chain.start.workflow,
+    prompt: chain.start.prompt,
+    timestamp: startNode.timestamp,
+  };
+
+  const stepEntries: StepEntry[] = [];
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  for (const item of ordered) {
+    stepEntries.push({
+      hash: item.hash,
+      role: item.payload.role,
+      output: expandOutput(uwf, item.payload.output),
+      detail: item.payload.detail ?? null,
+      agent: item.payload.agent,
+      timestamp: item.timestamp,
+      durationMs: item.payload.completedAtMs - item.payload.startedAtMs,
+      usage: item.payload.usage ?? null,
+    });
+  }
+
+  return {
+    thread: threadId,
+    workflow: chain.start.workflow,
+    steps: [startEntry, ...stepEntries],
+  };
+}
+
+/**
+ * Show details of a specific step (previously: thread step-details)
+ */
+export async function cmdStepShow(storageRoot: string, stepHash: CasRef): Promise<unknown> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.cas.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StepNode`);
+  }
+  const payload = node.payload as StepNodePayload;
+  if (!payload.detail) {
+    fail(`step ${stepHash} has no detail`);
+  }
+  return expandDeep(uwf.store, payload.detail);
+}
+
+/**
+ * Fork a thread from a specific step (previously: thread fork)
+ */
+export async function cmdStepFork(
+  storageRoot: string,
+  stepHash: CasRef,
+): Promise<ThreadForkOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.cas.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.startNode && node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StartNode or StepNode`);
+  }
+
+  const newThreadId = generateUlid(Date.now()) as ThreadId;
+  setThread(uwf.varStore, newThreadId, {
+    head: stepHash,
+    status: "idle",
+    suspendedRole: null,
+    suspendMessage: null,
+    completedAt: null,
+  });
+
+  return {
+    thread: newThreadId,
+    forkedFrom: {
+      step: stepHash,
+    },
+  };
+}
+
+/**
+ * Load and validate step detail node from CAS store
+ */
+function loadStepDetail(store: CasStore, detailRef: CasRef): Record<string, unknown> {
+  const detailNode = store.get(detailRef);
+  if (detailNode === null) {
+    fail(`detail node not found: ${detailRef}`);
+  }
+  return detailNode.payload as Record<string, unknown>;
+}
+
+function parseTurnToolCalls(raw: unknown): TurnToolCall[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const calls: TurnToolCall[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
+    }
+    const record = entry as Record<string, unknown>;
+    const name = record.name;
+    const args = record.args;
+    if (typeof name === "string") {
+      calls.push({ name, args: typeof args === "string" ? args : "" });
+    }
+  }
+  return calls.length > 0 ? calls : null;
+}
+
+function formatTurnBody(turn: TurnData): string {
+  const parts: string[] = [];
+  parts.push(`**Turn role:** ${turn.role}`);
+
+  if (turn.toolCalls !== null) {
+    for (const call of turn.toolCalls) {
+      const argsSuffix = call.args !== "" ? ` — \`${call.args}\`` : "";
+      parts.push(`- **${call.name}**${argsSuffix}`);
+    }
+  }
+
+  if (turn.content !== "") {
+    if (parts.length > 0) {
+      parts.push("");
+    }
+    parts.push(turn.content);
+  }
+
+  return parts.join("\n");
+}
+
+function parseSingleTurn(
+  store: CasStore,
+  turnRef: unknown,
+  fallbackIndex: number,
+): TurnData | null {
+  if (typeof turnRef !== "string") {
+    return null;
+  }
+  const turnNode = store.get(turnRef as CasRef);
+  if (turnNode === null) {
+    return null;
+  }
+  const turn = turnNode.payload as Record<string, unknown>;
+  const content = typeof turn.content === "string" ? turn.content : "";
+  const toolCalls = parseTurnToolCalls(turn.toolCalls);
+  if (content === "" && toolCalls === null) {
+    return null;
+  }
+  return {
+    index: typeof turn.index === "number" ? turn.index : fallbackIndex,
+    role: typeof turn.role === "string" ? turn.role : "assistant",
+    content,
+    toolCalls,
+  };
+}
+
+/**
+ * Load all turn nodes from CAS store and extract display fields
+ */
+function loadTurnData(store: CasStore, turns: unknown): TurnData[] {
+  if (!Array.isArray(turns) || turns.length === 0) {
+    return [];
+  }
+
+  const turnData: TurnData[] = [];
+  for (const turnRef of turns) {
+    const parsed = parseSingleTurn(store, turnRef, turnData.length);
+    if (parsed !== null) {
+      turnData.push(parsed);
+    }
+  }
+  return turnData;
+}
+
+/**
+ * Select turns that fit within quota, working backwards from most recent
+ */
+function selectTurnsForQuota(turnData: TurnData[], availableQuota: number): TurnData[] {
+  const selectedTurns: TurnData[] = [];
+  let totalChars = 0;
+
+  for (let i = turnData.length - 1; i >= 0; i--) {
+    const turn = turnData[i];
+    if (turn === undefined) continue;
+
+    const turnHeader = `## Turn ${turn.index + 1}\n\n`;
+    const turnBlock = turnHeader + formatTurnBody(turn);
+    const separatorCost = selectedTurns.length > 0 ? 2 : 0;
+    const addCost = turnBlock.length + separatorCost;
+
+    if (totalChars + addCost > availableQuota && selectedTurns.length > 0) {
+      break;
+    }
+
+    selectedTurns.unshift(turn);
+    totalChars += addCost;
+  }
+
+  return selectedTurns;
+}
+
+/**
+ * Assemble final markdown output from header and selected turns
+ */
+function formatStepMarkdown(
+  stepHash: CasRef,
+  role: string,
+  agent: string,
+  turnData: TurnData[],
+  selectedTurns: TurnData[],
+): string {
+  const parts: string[] = [];
+  parts.push(`# Step ${stepHash}`);
+  parts.push("");
+  parts.push(`**Role:** ${role}`);
+  parts.push(`**Agent:** ${agent}`);
+
+  if (selectedTurns.length === 0) {
+    return parts.join("\n");
+  }
+
+  const skippedCount = turnData.length - selectedTurns.length;
+  if (skippedCount > 0) {
+    parts.push("");
+    parts.push(`_[Earlier turns omitted due to quota. Use --quota to increase.]_`);
+  }
+
+  for (const turn of selectedTurns) {
+    parts.push("");
+    parts.push(`## Turn ${turn.index + 1}`);
+    parts.push("");
+    parts.push(formatTurnBody(turn));
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Read a step's agent turns as human-readable markdown with quota enforcement
+ */
+export async function cmdStepRead(
+  storageRoot: string,
+  stepHash: CasRef,
+  quota: number,
+  showPrompt: boolean,
+): Promise<string> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.cas.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StepNode`);
+  }
+  const payload = node.payload as StepNodePayload;
+
+  // --prompt mode: show the assembled prompt that was sent to the agent
+  if (showPrompt) {
+    const promptRef = (payload as Record<string, unknown>).assembledPrompt;
+    if (typeof promptRef !== "string") {
+      return `# Step ${stepHash}\n\n_Prompt not recorded (legacy step)._`;
+    }
+    const promptNode = uwf.store.cas.get(promptRef as CasRef);
+    if (promptNode === null) {
+      return `# Step ${stepHash}\n\n_Prompt CAS node not found: ${promptRef}_`;
+    }
+    const promptText =
+      typeof promptNode.payload === "string"
+        ? promptNode.payload
+        : JSON.stringify(promptNode.payload);
+    return `# Step ${stepHash}\n\n**Role:** ${payload.role}\n**Agent:** ${payload.agent}\n\n## Prompt\n\n${promptText}`;
+  }
+
+  if (payload.detail === null) {
+    return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
+  }
+
+  const detail = loadStepDetail(uwf.store.cas, payload.detail);
+  const turnData = loadTurnData(uwf.store.cas, detail.turns);
+
+  if (turnData.length === 0) {
+    return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
+  }
+
+  const headerSection = formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
+  const BUFFER = 200;
+  const availableQuota = quota - headerSection.length - BUFFER;
+  const selectedTurns = selectTurnsForQuota(turnData, availableQuota);
+
+  return formatStepMarkdown(stepHash, payload.role, payload.agent, turnData, selectedTurns);
+}

package/src/commands/thread-time-parser.ts

@@ -0,0 +1,23 @@
+/**
+ * Parse time input: ISO date (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS) or relative (7d, 24h, 30m)
+ * Returns Unix timestamp in milliseconds.
+ */
+export function parseTimeInput(input: string, nowMs: number): number {
+  const trimmed = input.trim();
+
+  // Relative time: 7d, 24h, 30m
+  const relativeMatch = /^(\d+)(d|h|m)$/.exec(trimmed);
+  if (relativeMatch !== null) {
+    const value = Number.parseInt(relativeMatch[1], 10);
+    const unit = relativeMatch[2];
+    const multiplier = unit === "d" ? 86400000 : unit === "h" ? 3600000 : 60000;
+    return nowMs - value * multiplier;
+  }
+
+  // ISO date: try parsing
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`invalid time format: ${trimmed} (expected ISO date or relative like '7d')`);
+  }
+  return parsed;
+}