@osolmaz/pi-workflows 0.10.0 → 0.11.1

package/src/host/rpc-bridge.ts

@@ -1,6 +1,8 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import {
+  parseWorkflowSubmissionInput,
+  WorkflowSubmissionToolParameters,
+} from "../workflows/tool-input.js";
 
 export const RPC_SUBMISSION_PREFIX = "PI_WORKFLOWS_STEP_SUBMISSION ";
 
@@ -19,34 +21,9 @@ export default function piWorkflowsRpcBridge(pi: ExtensionAPI) {
       "Only call this tool when a workflow step contract in the conversation asks you to.",
       "Pass the exact step and attempt ids from the contract.",
     ].join(" "),
-    parameters: Type.Union([
-      Type.Object(
-        {
-          action: StringEnum(["update"] as const),
-          step: Type.String(),
-          attempt: Type.String(),
-          update: Type.Object(
-            {
-              type: Type.String(),
-              key: Type.String(),
-              data: Type.Record(Type.String(), Type.Unknown()),
-            },
-            { additionalProperties: false },
-          ),
-        },
-        { additionalProperties: false },
-      ),
-      Type.Object(
-        {
-          action: StringEnum(["submit"] as const),
-          step: Type.String({ description: "Step id from the workflow step contract" }),
-          attempt: Type.String({ description: "Attempt id from the workflow step contract" }),
-          output: Type.Unknown({ description: "Step output matching the expected shape" }),
-        },
-        { additionalProperties: false },
-      ),
-    ]),
-    async execute(toolCallId, params) {
+    parameters: WorkflowSubmissionToolParameters,
+    async execute(toolCallId, rawParams) {
+      const params = parseWorkflowSubmissionInput(rawParams);
       process.stderr.write(
         `${RPC_SUBMISSION_PREFIX}${JSON.stringify({ ...params, idempotencyKey: toolCallId })}\n`,
       );

package/src/render/graph-render.ts

@@ -216,7 +216,7 @@ function cardMetrics(view: GraphView): CardMetrics {
     measure(`${nodeTypeBadge("checkpoint")}  ${STATUS_GLYPHS[status]} ${STATUS_LABELS[status]}`);
   }
   for (const [nodeId, node] of Object.entries(snapshot.nodes)) {
-    measure(sanitizeText(nodeId));
+    measure(sanitizeText(hierarchicalNodeLabel(nodeId, node)));
     measure(nodeTypeBadge(node.nodeType, node.actionExecution));
     const labels = nodeBranchLabels(view, nodeId);
     branchRows = Math.max(branchRows, labels.length);
@@ -305,14 +305,51 @@ function renderCellText(
     const durationMs = Date.parse(attempt.finishedAt) - Date.parse(attempt.startedAt);
     elapsed = formatDuration(durationMs);
   }
+  const human = node?.humanDecision;
+  const waitingSchema =
+    state.waitingOn === nodeId &&
+    state.finalOutput !== null &&
+    typeof state.finalOutput === "object"
+      ? (state.finalOutput as { schema?: unknown }).schema
+      : undefined;
+  const waitingRequest =
+    waitingSchema === "pi-workflows.human-decision-request.v1" ||
+    waitingSchema === "pi-workflows.human-decision-request.v2"
+      ? (state.finalOutput as {
+          audience?: unknown;
+          presentationDigest?: unknown;
+          presentation?: { summary?: unknown };
+        })
+      : undefined;
+  const selected =
+    human !== undefined &&
+    state.humanDecision !== undefined &&
+    state.humanDecision.nodeId === nodeId
+      ? human.choices[state.humanDecision.response.choice]
+      : undefined;
+  const humanDetail =
+    human === undefined
+      ? undefined
+      : state.waitingOn === nodeId
+        ? `human decision · ${sanitizeText(typeof waitingRequest?.audience === "string" ? waitingRequest.audience : human.audience)}${typeof waitingRequest?.presentation?.summary === "string" ? ` · ${sanitizeText(waitingRequest.presentation.summary)}` : ""} · ${Object.values(
+            human.choices,
+          )
+            .map((choice) => sanitizeText(choice.label))
+            .join(
+              " / ",
+            )}${typeof waitingRequest?.presentationDigest === "string" ? ` · ${waitingRequest.presentationDigest.slice(7, 19)}` : ""}`
+        : selected !== undefined
+          ? `human: ${sanitizeText(selected.label)}`
+          : undefined;
   const detail =
-    atLatestStep && state.currentNode === nodeId && state.statusDetail
+    humanDetail ??
+    (atLatestStep && state.currentNode === nodeId && state.statusDetail
       ? sanitizeText(state.statusDetail)
       : node?.statusDetail
         ? sanitizeText(node.statusDetail)
         : node?.summary
           ? sanitizeText(node.summary)
-          : "";
+          : "");
   const branchLines = Array.from({ length: metrics.branchRows }, (_, index) =>
     labels[index] ? `◇ ${labels[index]}` : "",
   );

package/src/viewer/cli.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { SqliteControllerStore } from "../controllers/sqlite.js";
 import { projectControllerStoreBaseDir } from "../controllers/store.js";
-import { setupHerdrPlugin } from "../herdr/setup.js";
+import { syncHerdrPlugin } from "../herdr/setup.js";
 import { sanitizeText } from "../render/ansi.js";
 import { listRunBundles, readRunBundle, workflowRunsBaseDir } from "../workflows/store.js";
 import {
@@ -24,7 +24,8 @@ Usage:
   pi-workflows controllers [--controller-dir <dir>]
   pi-workflows controller <controller> <key> [--controller-dir <dir>]
   pi-workflows host [--project <dir>] [-- <extra pi args>]
-  pi-workflows herdr setup
+  pi-workflows herdr sync [--json]
+  pi-workflows herdr setup [--json]
 
 Commands:
   view          Open the live workflow TUI. With --once, print a snapshot.
@@ -32,13 +33,14 @@ Commands:
   controllers   List durable controller resources.
   controller    Show one resource, its effects, child workflows, and events.
   host          Run the always-on workflow host in the foreground.
-  herdr         Set up the bundled Herdr plugin.
+  herdr         Synchronize the bundled Herdr plugin. setup is an alias for sync.
 
 Options:
   --dir <runsDir>          Runs directory (default: ~/.pi/agent/workflows/runs)
   --controller-dir <dir>  Controller directory (default: project-scoped local store)
   --once                   Render once without the interactive TUI
   --project <dir>          Project directory for the host (default: cwd)
+  --json                   Print a versioned JSON result for herdr sync
 `;
 
 export type CliArgs = {
@@ -50,6 +52,7 @@ export type CliArgs = {
   dir: string;
   controllerDir: string;
   once: boolean;
+  json: boolean;
   project?: string | undefined;
   piArgs?: string[] | undefined;
 };
@@ -60,6 +63,7 @@ export function parseCliArgs(argv: string[]): CliArgs {
   let dir = workflowRunsBaseDir();
   let controllerDir = projectControllerStoreBaseDir(process.cwd());
   let once = false;
+  let json = false;
   const positionals: string[] = [];
   let project: string | undefined;
   const piArgs: string[] = [];
@@ -74,8 +78,10 @@ export function parseCliArgs(argv: string[]): CliArgs {
       project = requiredValue(args, "--project");
     } else if (arg === "--once") {
       once = true;
+    } else if (arg === "--json") {
+      json = true;
     } else if (arg === "--help" || arg === "-h") {
-      return { command: "help", dir, controllerDir, once };
+      return { command: "help", dir, controllerDir, once, json };
     } else if (arg === "--") {
       piArgs.push(...args.splice(0));
     } else if (arg.startsWith("-")) {
@@ -85,8 +91,12 @@ export function parseCliArgs(argv: string[]): CliArgs {
     }
   }
 
+  if (command !== "herdr" && json) {
+    throw new Error("--json is available only for herdr sync");
+  }
+
   if (command === "host") {
-    return { command, dir, controllerDir, once, project, piArgs };
+    return { command, dir, controllerDir, once, json, project, piArgs };
   }
 
   if (command === "controller") {
@@ -100,13 +110,14 @@ export function parseCliArgs(argv: string[]): CliArgs {
       dir,
       controllerDir,
       once,
+      json,
     };
   }
   if (command === "herdr") {
-    if (positionals.length !== 1 || positionals[0] !== "setup") {
-      throw new Error("herdr requires the setup action");
+    if (positionals.length !== 1 || (positionals[0] !== "sync" && positionals[0] !== "setup")) {
+      throw new Error("herdr requires the sync action");
     }
-    return { command, herdrAction: positionals[0], dir, controllerDir, once };
+    return { command, herdrAction: positionals[0], dir, controllerDir, once, json };
   }
   if (positionals.length > 1) {
     throw new Error(`Unexpected argument: ${positionals[1]}`);
@@ -117,6 +128,7 @@ export function parseCliArgs(argv: string[]): CliArgs {
     dir,
     controllerDir,
     once,
+    json,
   };
 }
 
@@ -240,8 +252,8 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
       return await runHost(args.project ?? process.cwd(), args.piArgs);
     }
     if (args.command === "herdr") {
-      const result = setupHerdrPlugin(packageRoot());
-      process.stdout.write(`${result.message}\n`);
+      const result = syncHerdrPlugin(packageRoot());
+      process.stdout.write(args.json ? `${JSON.stringify(result)}\n` : `${result.message}\n`);
       return 0;
     }
     if (args.command === "view") {

package/src/viewer/render.ts

@@ -2,13 +2,22 @@ import { ansi, fitWidth, sanitizeText } from "../render/ansi.js";
 import { formatDuration, runElapsedMs } from "../render/format.js";
 import { renderGraphLines } from "../render/graph-render.js";
 import { decodeValueWith } from "../workflows/artifacts.js";
+import {
+  decisionDocumentSegments,
+  decisionPresentationFingerprint,
+  humanDecisionChannelRequest,
+} from "../workflows/decision-presentation.js";
 import {
   formatProgressLine,
   progressRecordsFromTrace,
   progressTracksFromRecords,
 } from "../workflows/progress.js";
 import type { LoadedRunBundle } from "../workflows/store.js";
-import type { WorkflowRunStatus, WorkflowStepRecord } from "../workflows/types.js";
+import type {
+  HumanDecisionRequest,
+  WorkflowRunStatus,
+  WorkflowStepRecord,
+} from "../workflows/types.js";
 
 export { formatDuration, runElapsedMs };
 
@@ -132,10 +141,31 @@ function nodeStatusLine(bundle: LoadedRunBundle, nodeId: string, width: number,
     suffix = ansi.cyan(` running ${formatDuration(now.getTime() - startedAt)}${detail}`);
   } else if (state.waitingOn === nodeId) {
     glyph = ansi.yellow("⏸");
-    suffix = ansi.yellow(" waiting");
+    const human = bundle.snapshot?.nodes[nodeId]?.humanDecision;
+    const request = humanDecisionRequest(state.finalOutput);
+    const requestAudience = request?.audience ?? human?.audience;
+    suffix = ansi.yellow(
+      human === undefined
+        ? " waiting"
+        : ` waiting for human · ${sanitizeText(requestAudience ?? "operator")}${request?.schema === "pi-workflows.human-decision-request.v2" ? ` · ${sanitizeText(request.presentation.summary)}` : ""} · ${Object.values(
+            human.choices,
+          )
+            .map((choice) => sanitizeText(choice.label))
+            .join(
+              " / ",
+            )}${request?.schema === "pi-workflows.human-decision-request.v2" ? ` · ${request.presentationDigest.slice(7, 19)}` : ""}`,
+    );
   } else if (result) {
     glyph = result.outcome === "ok" ? ansi.green("✓") : ansi.red("✗");
-    suffix = ansi.dim(` ${formatDuration(result.durationMs)}`);
+    const human = bundle.snapshot?.nodes[nodeId]?.humanDecision;
+    const accepted = state.humanDecision;
+    const selected =
+      human !== undefined && accepted !== undefined && accepted.nodeId === nodeId
+        ? human.choices[accepted.response.choice]
+        : undefined;
+    suffix = ansi.dim(
+      ` ${formatDuration(result.durationMs)}${selected === undefined ? "" : ` · human: ${sanitizeText(selected.label)}`}`,
+    );
   }
   return fitWidth(`  ${glyph} ${nodeId} ${ansi.dim(`[${nodeType}]`)}${suffix}`, width);
 }
@@ -143,6 +173,20 @@ function nodeStatusLine(bundle: LoadedRunBundle, nodeId: string, width: number,
 /** Pretty-printed JSON body of the selected step for the inspector pane. */
 function inspectorLines(step: WorkflowStepRecord, width: number): string[] {
   const lines: string[] = [];
+  const request = step.error === undefined ? humanDecisionRequest(step.output) : null;
+  if (request !== null) {
+    const channelRequest = humanDecisionChannelRequest(request);
+    for (const segment of decisionDocumentSegments(channelRequest)) {
+      for (const raw of segment.text.split("\n")) {
+        lines.push(fitWidth(`  ${sanitizeText(raw)}`, width));
+      }
+      lines.push("");
+    }
+    lines.push(
+      fitWidth(ansi.dim(`  decision ${decisionPresentationFingerprint(channelRequest)}`), width),
+    );
+    return lines;
+  }
   const body = step.error !== undefined ? step.error : withArtifactPlaceholders(step.output);
   const rendered =
     typeof body === "string" && step.error !== undefined ? body : JSON.stringify(body, null, 2);
@@ -163,6 +207,15 @@ function inspectorLines(step: WorkflowStepRecord, width: number): string[] {
   return lines;
 }
 
+function humanDecisionRequest(value: unknown): HumanDecisionRequest | null {
+  if (value === null || typeof value !== "object") return null;
+  const schema = (value as { schema?: unknown }).schema;
+  return schema === "pi-workflows.human-decision-request.v1" ||
+    schema === "pi-workflows.human-decision-request.v2"
+    ? (value as HumanDecisionRequest)
+    : null;
+}
+
 /**
  * Full-run detail view: header, graph pane, step timeline, inspector.
  * `scroll` shifts the viewport down over the full body; `selectedStepIndex`

package/src/workflows/composition.ts

@@ -477,7 +477,9 @@ function wrapNode(
         message: (context) => (node as NotifyNodeDefinition).message(project(context)),
         ...(node.kind !== undefined ? { kind: node.kind } : {}),
       };
-    case "checkpoint":
+    case "checkpoint": {
+      const human = node.humanDecision;
+      const audience = human?.audience;
       return {
         ...common,
         nodeType: "checkpoint",
@@ -485,7 +487,20 @@ function wrapNode(
         ...(node.run !== undefined
           ? { run: (context: WorkflowNodeContext) => node.run?.(project(context)) }
           : {}),
+        ...(human !== undefined
+          ? {
+              humanDecision: {
+                audience:
+                  typeof audience === "function"
+                    ? (context: WorkflowNodeContext) => audience(project(context))
+                    : audience!,
+                choices: human.choices,
+                request: (context: WorkflowNodeContext) => human.request(project(context)),
+              },
+            }
+          : {}),
       } as CheckpointNodeDefinition;
+    }
     case "action":
       if ("exec" in node) {
         const shell = node as ShellActionNodeDefinition;