@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/src/extension/widget.ts

@@ -297,8 +297,36 @@ function nodeRuntimeSegments(
   }
 
   if (state.waitingOn === nodeId) {
-    const summary = snapshot.nodes[nodeId]?.summary;
-    segments.push(summary ? sanitizeText(summary) : "waiting");
+    const human = snapshot.nodes[nodeId]?.humanDecision;
+    if (human !== undefined) {
+      const request =
+        state.finalOutput !== null && typeof state.finalOutput === "object"
+          ? (state.finalOutput as {
+              schema?: unknown;
+              audience?: unknown;
+              presentationDigest?: unknown;
+              presentation?: { summary?: unknown };
+            })
+          : undefined;
+      const requestAudience =
+        (request?.schema === "pi-workflows.human-decision-request.v1" ||
+          request?.schema === "pi-workflows.human-decision-request.v2") &&
+        typeof request.audience === "string"
+          ? request.audience
+          : human.audience;
+      segments.push(
+        `human decision · ${sanitizeText(requestAudience)}${typeof request?.presentation?.summary === "string" ? ` · ${sanitizeText(request.presentation.summary)}` : ""} · ${Object.values(
+          human.choices,
+        )
+          .map((choice) => sanitizeText(choice.label))
+          .join(
+            " / ",
+          )}${typeof request?.presentationDigest === "string" ? ` · ${request.presentationDigest.slice(7, 19)}` : ""}`,
+      );
+    } else {
+      const summary = snapshot.nodes[nodeId]?.summary;
+      segments.push(summary ? sanitizeText(summary) : "waiting");
+    }
     return segments;
   }
 
@@ -313,6 +341,15 @@ function nodeRuntimeSegments(
     );
     return segments;
   }
+  const human = snapshot.nodes[nodeId]?.humanDecision;
+  if (
+    human !== undefined &&
+    state.humanDecision !== undefined &&
+    state.humanDecision.nodeId === nodeId
+  ) {
+    const selected = human.choices[state.humanDecision.response.choice];
+    if (selected !== undefined) segments.push(`human: ${sanitizeText(selected.label)}`);
+  }
   if (Number.isFinite(result.durationMs)) {
     segments.push(formatDuration(result.durationMs));
   }

package/src/extension/workflow-tool.ts

@@ -1,81 +1,5 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { Type, type TSchema } from "typebox";
-
-const noExtraProperties = { additionalProperties: false } as const;
-
-export const WorkflowToolParameters: TSchema = Type.Union([
-  Type.Object(
-    {
-      action: StringEnum(["list"] as const),
-      offset: Type.Optional(Type.Integer({ minimum: 0, description: "Workflow list offset" })),
-    },
-    noExtraProperties,
-  ),
-  Type.Object(
-    {
-      action: StringEnum(["start"] as const),
-      workflow: Type.String({ description: "Discovered workflow name or workflow file path" }),
-      input: Type.Optional(Type.Unknown({ description: "Structured workflow input" })),
-    },
-    noExtraProperties,
-  ),
-  Type.Object(
-    {
-      action: StringEnum(["status"] as const),
-      runId: Type.Optional(Type.String({ description: "Run id; omit for the active run" })),
-    },
-    noExtraProperties,
-  ),
-  Type.Object({ action: StringEnum(["pause"] as const) }, noExtraProperties),
-  Type.Object({ action: StringEnum(["resume"] as const) }, noExtraProperties),
-  Type.Object({ action: StringEnum(["cancel"] as const) }, noExtraProperties),
-  Type.Object(
-    {
-      action: StringEnum(["answer"] as const),
-      input: Type.Unknown({ description: "Checkpoint answer" }),
-      runId: Type.Optional(Type.String({ description: "Waiting run id" })),
-    },
-    noExtraProperties,
-  ),
-  Type.Object(
-    {
-      action: StringEnum(["update"] as const),
-      step: Type.String({ description: "Active step id" }),
-      attempt: Type.String({ description: "Active attempt id" }),
-      update: Type.Object(
-        {
-          type: Type.String(),
-          key: Type.String(),
-          data: Type.Record(Type.String(), Type.Unknown()),
-        },
-        noExtraProperties,
-      ),
-    },
-    noExtraProperties,
-  ),
-  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" }),
-    },
-    noExtraProperties,
-  ),
-]);
-
-export type WorkflowToolInput =
-  | { action: "list"; offset?: number }
-  | { action: "start"; workflow: string; input?: unknown }
-  | { action: "status"; runId?: string }
-  | { action: "pause" }
-  | { action: "resume" }
-  | { action: "cancel" }
-  | { action: "answer"; input: unknown; runId?: string }
-  | {
-      action: "update";
-      step: string;
-      attempt: string;
-      update: { type: string; key: string; data: Record<string, unknown> };
-    }
-  | { action: "submit"; step: string; attempt: string; output: unknown };
+export {
+  parseWorkflowToolInput,
+  WorkflowToolParameters,
+  type WorkflowToolInput,
+} from "../workflows/tool-input.js";

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,25 +305,63 @@ 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]}` : "",
   );
   const count = atLatestStep && state.currentNode === nodeId ? Math.max(attempts, 1) : attempts;
   const timing =
     attempt || count > 0 ? `${count} attempt${count === 1 ? "" : "s"} · ${elapsed}` : "not visited";
-  const text = `${nodeId} [${nodeType}] ${timing}`;
+  const displayNodeId = hierarchicalNodeLabel(nodeId, node);
+  const text = `${displayNodeId} [${nodeType}] ${timing}`;
   return {
     cell,
     text,
-    nodeId: sanitizeText(nodeId),
+    nodeId: sanitizeText(displayNodeId),
     nodeType,
     typeBadge: node ? nodeTypeBadge(node.nodeType, node.actionExecution) : "? unknown",
     status,
@@ -337,6 +375,17 @@ function renderCellText(
   };
 }
 
+function hierarchicalNodeLabel(
+  nodeId: string,
+  node: WorkflowDefinitionSnapshot["nodes"][string] | undefined,
+): string {
+  if (node?.mountPath === undefined || node.localNodeId === undefined) return nodeId;
+  const path = node.mountPath.join(" › ");
+  if (node.includeTransition === "entry") return `${path} · enter`;
+  if (node.includeTransition === "exit") return `${path} · ${node.localNodeId} exit`;
+  return `${path} › ${node.localNodeId}`;
+}
+
 type RankGeometry = {
   cells: RenderedCell[];
   centers: number[];

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/catalog.ts

@@ -83,6 +83,13 @@ export class BuiltinWorkflowCatalog {
     return this.byName.get(name);
   }
 
+  sourceForDefinition(definition: WorkflowDefinition): WorkflowSource | undefined {
+    const entry = this.list().find((candidate) => candidate.definition === definition);
+    return entry === undefined
+      ? undefined
+      : { kind: "builtin", id: entry.id, revision: entry.revision };
+  }
+
   resolve(
     source: WorkflowSource,
     runId = `builtin:${source.kind === "builtin" ? source.id : "unknown"}`,