@osolmaz/pi-workflows 0.5.3 → 0.6.0

package/src/extension/index.ts

@@ -14,6 +14,7 @@ import {
 } from "../workflows/errors.js";
 import { discoverWorkflows, resolveWorkflowRef } from "../workflows/loader.js";
 import { migrateLegacyWorkflowSources } from "../workflows/migrate-sources.js";
+import { appendProgressHistory, progressRecordsFromTrace } from "../workflows/progress.js";
 import {
   createRunId,
   listRunBundles,
@@ -28,6 +29,7 @@ import type {
   WorkflowDefinitionSnapshot,
   WorkflowRunResult,
   WorkflowRunState,
+  WorkflowUpdateRecord,
 } from "../workflows/types.js";
 import {
   PiControllerHost,
@@ -36,6 +38,12 @@ import {
 } from "./controller-host.js";
 import { ConversationStepExecutor } from "./executor.js";
 import { SessionRecorder } from "./recorder.js";
+import {
+  registerWorkflowAgentStepMessageRenderer,
+  WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
+  WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
+  type WorkflowAgentStepMessageDetails,
+} from "./step-message.js";
 import { buildWidgetView } from "./widget.js";
 import { WorkflowToolParameters, type WorkflowToolInput } from "./workflow-tool.js";
 
@@ -71,6 +79,7 @@ type ActiveRun = {
   presentationPrompt: WorkflowDefinition["presentationPrompt"];
   generation: number;
   lastState: WorkflowRunState | null;
+  updateHistory: WorkflowUpdateRecord[];
   childKey?: string;
   onFinish?: (result: WorkflowSchedulerResult) => void;
   completion?: Promise<void>;
@@ -191,6 +200,10 @@ function workflowStateSummary(state: WorkflowRunState): JsonObject {
     workflowName: state.workflowName,
     status: state.status,
     steps: state.steps.length,
+    updates: (state.updates ?? []).map(({ data, ...record }) => ({
+      ...record,
+      data: data as JsonObject,
+    })),
     ...(state.currentNode !== undefined ? { currentNode: state.currentNode } : {}),
     ...(state.waitingOn !== undefined ? { waitingOn: state.waitingOn } : {}),
     ...(state.startedAt !== undefined ? { startedAt: state.startedAt } : {}),
@@ -202,6 +215,7 @@ function workflowStateSummary(state: WorkflowRunState): JsonObject {
 type WidgetSource = {
   state: WorkflowRunState;
   snapshot: WorkflowDefinitionSnapshot;
+  updateHistory?: WorkflowUpdateRecord[];
 };
 
 type WorkflowWidgetComponent = {
@@ -213,6 +227,8 @@ type WorkflowWidgetFactory = (_tui: unknown, theme: Theme) => WorkflowWidgetComp
 type WorkflowWidgetContent = string[] | WorkflowWidgetFactory;
 
 export default function piWorkflows(pi: ExtensionAPI) {
+  registerWorkflowAgentStepMessageRenderer(pi);
+
   // One runner identity per session; it names this session in run claims.
   const runnerId = randomUUID();
   let runQueueStore: SqliteControllerStore | null = null;
@@ -267,16 +283,19 @@ export default function piWorkflows(pi: ExtensionAPI) {
         leaseMs: NOTIFICATION_DELIVERY_LEASE_MS,
       })) {
         if (!alreadyDelivered.has(notification.notificationId)) {
-          pi.sendMessage({
-            customType: "pi-workflows-notification",
-            content: notification.content,
-            display: true,
-            details: {
-              notificationId: notification.notificationId,
-              runId: notification.runId,
-              kind: notification.kind,
+          pi.sendMessage(
+            {
+              customType: "pi-workflows-notification",
+              content: notification.content,
+              display: true,
+              details: {
+                notificationId: notification.notificationId,
+                runId: notification.runId,
+                kind: notification.kind,
+              },
             },
-          });
+            { triggerTurn: false },
+          );
           alreadyDelivered.add(notification.notificationId);
         }
         runQueueStore.markWorkflowNotificationDelivered({
@@ -387,6 +406,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
         runHeld(),
         width,
         theme,
+        widgetSource.updateHistory,
       );
       widgetShownScroll = view.scroll;
       widgetMaxScroll = view.maxScroll;
@@ -411,13 +431,18 @@ export default function piWorkflows(pi: ExtensionAPI) {
     ctx: ExtensionContext,
     state: WorkflowRunState,
     snapshot: WorkflowDefinitionSnapshot,
+    updateHistory?: WorkflowUpdateRecord[],
   ) => {
     if (state.steps.length !== widgetStepCount) {
       widgetStepCount = state.steps.length;
       // The workflow moved on; resume following the active node.
       widgetScroll = null;
     }
-    widgetSource = { state, snapshot };
+    widgetSource = {
+      state,
+      snapshot,
+      ...(updateHistory !== undefined ? { updateHistory: [...updateHistory] } : {}),
+    };
     renderWidget(ctx);
   };
 
@@ -596,7 +621,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     void run.recorder?.stop();
     stopWidgetTicker();
     const { state } = result;
-    updateWidget(ctx, state, run.snapshot);
+    updateWidget(ctx, state, run.snapshot, run.updateHistory);
     clearWidgetTimer();
     // A waiting run is parked at a checkpoint for a human; keep its widget up
     // until a new workflow replaces it. Terminal runs fade after a grace TTL.
@@ -734,8 +759,25 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
 
     const executor = new ConversationStepExecutor({
-      sendPrompt: ({ prompt, streaming }) => {
-        pi.sendUserMessage(prompt, streaming ? { deliverAs: "steer" } : undefined);
+      sendPrompt: ({ prompt, contract, presentation, kind, streaming }) => {
+        const details: WorkflowAgentStepMessageDetails = {
+          schema: WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA,
+          kind,
+          contract,
+          ...(presentation !== undefined ? { presentation } : {}),
+        };
+        pi.sendMessage(
+          {
+            customType: WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
+            content: prompt,
+            display: true,
+            details,
+          },
+          {
+            triggerTurn: true,
+            deliverAs: streaming ? "steer" : "followUp",
+          },
+        );
       },
       onAbort: (contract, reason) => {
         lastExpiredAttempt = {
@@ -799,9 +841,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
       onRunFinishing: async () => {
         await run.recorder?.finish();
       },
-      onEvent: (_event, state: WorkflowRunState) => {
+      onEvent: (event, state: WorkflowRunState) => {
         run.lastState = state;
-        updateWidget(ctx, state, snapshot);
+        run.updateHistory = appendProgressHistory(
+          run.updateHistory,
+          progressRecordsFromTrace([event]),
+        );
+        updateWidget(ctx, state, snapshot, run.updateHistory);
       },
     });
     const run: ActiveRun = {
@@ -814,6 +860,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       presentationPrompt: options.presentation === false ? undefined : workflow.presentationPrompt,
       generation,
       lastState: null,
+      updateHistory: [],
       ...(options.childKey !== undefined ? { childKey: options.childKey } : {}),
       ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
       ...(claimToken !== undefined ? { claimToken } : {}),
@@ -1562,13 +1609,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
     name: "workflow",
     label: "Workflow",
     description: [
-      "List, start, inspect, pause, resume, cancel, answer, or complete Pi Workflows runs.",
-      "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, everyMinutes, reportWhen, stopWhen, and optional maxChecks.",
-      "Use submit only when a workflow step contract asks for it, and pass the exact step and attempt ids.",
+      "List, start, inspect, pause, resume, cancel, answer, update, or complete Pi Workflows runs.",
+      "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, everyMinutes, stopWhen, and optional maxChecks.",
+      "Use update or submit only when a workflow step contract asks for it, and pass the exact step and attempt ids.",
       "Do not start repeated work without the user's request, and keep monitoring observation-only unless the user authorizes mutations.",
     ].join(" "),
     parameters: WorkflowToolParameters,
-    async execute(_toolCallId, params: WorkflowToolInput, _signal, _onUpdate, ctx) {
+    async execute(toolCallId, params: WorkflowToolInput, _signal, _onUpdate, ctx) {
       let control: WorkflowControlResult;
       switch (params.action) {
         case "list":
@@ -1596,6 +1643,21 @@ export default function piWorkflows(pi: ExtensionAPI) {
           });
           break;
         }
+        case "update": {
+          if (!activeRun) throw new Error("No workflow step is active.");
+          const receipt = await activeRun.engine.publishUpdate(
+            params.step,
+            params.attempt,
+            params.update,
+            toolCallId,
+          );
+          return {
+            content: [
+              { type: "text", text: "Workflow update published; the step remains active." },
+            ],
+            details: { action: "update", ...receipt },
+          };
+        }
         case "submit": {
           if (!activeRun) {
             if (

package/src/extension/step-message.ts

@@ -0,0 +1,145 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Box, Text, TruncatedText } from "@earendil-works/pi-tui";
+import { sanitizeText } from "../workflows/text.js";
+import type { AgentStepContract, AgentStepPresentation } from "../workflows/types.js";
+import type { PromptDeliveryKind } from "./executor.js";
+
+export const WORKFLOW_AGENT_STEP_MESSAGE_TYPE = "pi-workflows-agent-step";
+export const WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA = "pi-workflows.agent-step-message.v1";
+
+export type WorkflowAgentStepMessageDetails = {
+  schema: typeof WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA;
+  kind: PromptDeliveryKind;
+  contract: AgentStepContract;
+  presentation?: AgentStepPresentation;
+};
+
+type WorkflowAgentStepMessage = {
+  content: unknown;
+  details?: unknown;
+};
+
+type WorkflowAgentStepView = {
+  title: string;
+  status?: string;
+  expandedText?: string;
+};
+
+export function registerWorkflowAgentStepMessageRenderer(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer<WorkflowAgentStepMessageDetails>(
+    WORKFLOW_AGENT_STEP_MESSAGE_TYPE,
+    (message, { expanded }, theme) => {
+      const view = buildWorkflowAgentStepView(message, expanded, theme);
+      const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+      box.addChild(new TruncatedText(view.title));
+      if (view.status !== undefined) {
+        box.addChild(new TruncatedText(view.status));
+      }
+      if (view.expandedText !== undefined) {
+        box.addChild(new Text(`\n${view.expandedText}`));
+      }
+      return box;
+    },
+  );
+}
+
+/** Build renderer text without depending on Pi's session or TUI state. */
+export function buildWorkflowAgentStepView(
+  message: WorkflowAgentStepMessage,
+  expanded: boolean,
+  theme?: Pick<Theme, "fg">,
+): WorkflowAgentStepView {
+  const details = parseDetails(message.details);
+  const contract = details?.contract;
+  const kind = details?.kind ?? "step";
+  const workflowName = cleanSingleLine(contract?.workflowName ?? "Workflow");
+  const nodeId = cleanSingleLine(contract?.nodeId ?? "step");
+  const runTitle = cleanOptionalSingleLine(details?.presentation?.runTitle);
+  const statusDetail = cleanOptionalSingleLine(details?.presentation?.statusDetail);
+  const label = runTitle ?? workflowName;
+  const suffix = kind === "step" ? "" : ` · ${kind}`;
+  const glyph = kind === "step" ? "▶" : "↻";
+  const title = paint(theme, "accent", `${glyph} ${label} › ${nodeId}${suffix}`);
+
+  if (!expanded) {
+    return {
+      title,
+      ...(statusDetail !== undefined ? { status: paint(theme, "dim", statusDetail) } : {}),
+    };
+  }
+
+  const metadata = [
+    `Workflow: ${workflowName}`,
+    ...(runTitle !== undefined ? [`Run title: ${runTitle}`] : []),
+    `Run id: ${cleanSingleLine(contract?.runId ?? "unknown")}`,
+    `Node id: ${nodeId}`,
+    `Attempt id: ${cleanSingleLine(contract?.attemptId ?? "unknown")}`,
+    `Delivery: ${kind}`,
+    `Expected output: ${cleanSingleLine(contract?.expectedOutput ?? "a JSON object with your result")}`,
+  ];
+  const prompt = contentText(message.content);
+  return {
+    title,
+    ...(statusDetail !== undefined ? { status: paint(theme, "dim", statusDetail) } : {}),
+    expandedText: `${metadata.map((line) => paint(theme, "dim", line)).join("\n")}\n\n${prompt}`,
+  };
+}
+
+function parseDetails(value: unknown): WorkflowAgentStepMessageDetails | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const candidate = value as Partial<WorkflowAgentStepMessageDetails>;
+  if (candidate.schema !== WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA) return undefined;
+  if (candidate.kind !== "step" && candidate.kind !== "reminder" && candidate.kind !== "resume") {
+    return undefined;
+  }
+  const contract = candidate.contract;
+  if (
+    contract === null ||
+    typeof contract !== "object" ||
+    typeof contract.runId !== "string" ||
+    typeof contract.workflowName !== "string" ||
+    typeof contract.nodeId !== "string" ||
+    typeof contract.attemptId !== "string"
+  ) {
+    return undefined;
+  }
+  return candidate as WorkflowAgentStepMessageDetails;
+}
+
+function contentText(content: unknown): string {
+  if (typeof content === "string") return cleanMultiline(content);
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (part === null || typeof part !== "object" || !("text" in part)) return "";
+      const text = (part as { text?: unknown }).text;
+      return typeof text === "string" ? cleanMultiline(text) : "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function cleanOptionalSingleLine(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? cleanSingleLine(value) : undefined;
+}
+
+function cleanSingleLine(value: string): string {
+  return sanitizeText(value);
+}
+
+function cleanMultiline(value: string): string {
+  return value
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .split("\n")
+    .map((line) => sanitizeText(line))
+    .join("\n");
+}
+
+function paint(
+  theme: Pick<Theme, "fg"> | undefined,
+  color: "accent" | "dim",
+  text: string,
+): string {
+  return theme?.fg(color, text) ?? text;
+}

package/src/extension/widget.ts

@@ -2,11 +2,20 @@ import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { formatDuration } from "../render/format.js";
 import { nodeTypeGlyph } from "../render/node-type.js";
+import {
+  estimateProgress,
+  formatProgressLine,
+  formatRemaining,
+  prioritizeProgressEstimates,
+  progressTracksFromRecords,
+  type ProgressEstimate,
+} from "../workflows/progress.js";
 import { sanitizeText } from "../workflows/text.js";
 import type {
   WorkflowDefinitionSnapshot,
   WorkflowRunState,
   WorkflowRunStatus,
+  WorkflowUpdateRecord,
 } from "../workflows/types.js";
 
 const STATUS_GLYPHS: Record<WorkflowRunStatus, string> = {
@@ -68,6 +77,7 @@ export function buildWidgetView(
   held = false,
   width = Number.POSITIVE_INFINITY,
   theme?: WidgetTheme,
+  updateHistory?: WorkflowUpdateRecord[],
 ): WidgetView {
   const availableWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : width;
   if (availableWidth === 0) return { lines: [], scroll: 0, maxScroll: 0 };
@@ -93,13 +103,17 @@ export function buildWidgetView(
     );
   }
 
-  const budget = PI_MAX_WIDGET_LINES - 1 - footer.length;
+  const progress = progressLines(state, now, updateHistory).slice(0, 4);
+  const budget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
   const nodes = displayNodeIds(snapshot).map((nodeId) =>
     compactNodeLine(state, snapshot, nodeId, now, paused, theme),
   );
-  if (nodes.length === 0) {
+  if (nodes.length === 0 || budget <= 0) {
     return {
-      lines: fitLines([header, ...footer], availableWidth),
+      lines: fitLines(
+        [header, ...progress, ...footer].slice(0, PI_MAX_WIDGET_LINES),
+        availableWidth,
+      ),
       scroll: 0,
       maxScroll: 0,
     };
@@ -110,7 +124,12 @@ export function buildWidgetView(
   const indentation = availableWidth >= 3 ? "  " : "";
   return {
     lines: fitLines(
-      [header, ...windowed.lines.map((line) => `${indentation}${line}`), ...footer],
+      [
+        header,
+        ...windowed.lines.map((line) => `${indentation}${line}`),
+        ...progress.map((line) => `${indentation}${line}`),
+        ...footer,
+      ],
       availableWidth,
     ),
     scroll: windowed.scroll,
@@ -118,6 +137,76 @@ export function buildWidgetView(
   };
 }
 
+function progressLines(
+  state: WorkflowRunState,
+  now: Date,
+  updateHistory?: WorkflowUpdateRecord[],
+): string[] {
+  const measured =
+    updateHistory === undefined
+      ? undefined
+      : progressTracksFromRecords(updateHistory, now).map((track) => track.estimate);
+  const projected = mergeProgressEstimates(latestProgressEstimates(state, now), measured ?? []);
+  const estimates = mergeProgressEstimates(projected, monitorEstimates(state) ?? []);
+  const lines = prioritizeProgressEstimates(estimates).map((estimate) =>
+    formatProgressLine(estimate, now),
+  );
+  const schedule = (state.updates ?? []).find(
+    (record) => record.type === "monitor.schedule" && record.key === "next-check",
+  );
+  if (schedule !== undefined && typeof schedule.data.nextCheckAt === "string") {
+    const next = Date.parse(schedule.data.nextCheckAt);
+    if (Number.isFinite(next)) {
+      const age = Math.max(0, now.getTime() - Date.parse(schedule.at));
+      lines.push(
+        `Last update ${formatRemaining(age)} ago  next check ${formatRemaining(next - now.getTime())}`,
+      );
+    }
+  }
+  return lines;
+}
+
+function monitorEstimates(state: WorkflowRunState): ProgressEstimate[] | undefined {
+  const output = state.outputs.estimate;
+  if (output === null || typeof output !== "object" || Array.isArray(output)) return undefined;
+  const tracks = (output as { tracks?: unknown }).tracks;
+  if (!Array.isArray(tracks)) return undefined;
+  const estimates = tracks
+    .map((track) =>
+      track !== null && typeof track === "object" && !Array.isArray(track)
+        ? (track as { estimate?: ProgressEstimate }).estimate
+        : undefined,
+    )
+    .filter((estimate): estimate is ProgressEstimate => estimate !== undefined);
+  return estimates.length > 0 ? estimates : undefined;
+}
+
+function mergeProgressEstimates(
+  latest: ProgressEstimate[],
+  measured: ProgressEstimate[],
+): ProgressEstimate[] {
+  const measuredByKey = new Map(measured.map((estimate) => [estimate.key, estimate]));
+  const merged = latest.map((estimate) => measuredByKey.get(estimate.key) ?? estimate);
+  const latestKeys = new Set(latest.map((estimate) => estimate.key));
+  merged.push(...measured.filter((estimate) => !latestKeys.has(estimate.key)));
+  return merged;
+}
+
+function latestProgressEstimates(state: WorkflowRunState, now: Date): ProgressEstimate[] {
+  const estimates: ProgressEstimate[] = [];
+  for (const record of state.updates ?? []) {
+    if (record.type !== "progress") continue;
+    try {
+      estimates.push(
+        estimateProgress(record.key, [{ at: record.at, data: record.data as never }], now),
+      );
+    } catch {
+      // A malformed historical update must not break the workflow widget.
+    }
+  }
+  return estimates;
+}
+
 function compactFocusIndex(state: WorkflowRunState, snapshot: WorkflowDefinitionSnapshot): number {
   const nodeIds = displayNodeIds(snapshot);
   const focused = state.currentNode ?? state.waitingOn;

package/src/extension/workflow-tool.ts

@@ -37,6 +37,22 @@ export const WorkflowToolParameters: TSchema = Type.Union([
     },
     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),
@@ -56,4 +72,10 @@ export type WorkflowToolInput =
   | { 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 };

package/src/host/rpc-bridge.ts

@@ -15,26 +15,49 @@ export default function piWorkflowsRpcBridge(pi: ExtensionAPI) {
     name: "workflow",
     label: "Workflow",
     description: [
-      "Submit the output for the pending workflow step with action submit.",
+      "Publish an update or submit the output for the pending workflow step.",
       "Only call this tool when a workflow step contract in the conversation asks you to.",
-      "Pass the exact step id from the contract and your result as the output.",
+      "Pass the exact step and attempt ids from the contract.",
     ].join(" "),
-    parameters: 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) {
-      process.stderr.write(`${RPC_SUBMISSION_PREFIX}${JSON.stringify(params)}\n`);
+    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) {
+      process.stderr.write(
+        `${RPC_SUBMISSION_PREFIX}${JSON.stringify({ ...params, idempotencyKey: toolCallId })}\n`,
+      );
       return {
         content: [
           {
             type: "text",
-            text: "Submission recorded. Continue only when the workflow sends the next step.",
+            text:
+              params.action === "update"
+                ? "Workflow update recorded; continue the current step."
+                : "Submission recorded. Continue only when the workflow sends the next step.",
           },
         ],
         details: {},