@osolmaz/pi-workflows 0.5.3 → 0.6.1

package/src/host/rpc-executor.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { errorMessage } from "../workflows/errors.js";
 import type {
   AgentStepExecutor,
   AgentStepRequest,
@@ -23,6 +24,16 @@ type StepSubmission = {
   output: unknown;
 };
 
+type StepUpdate = {
+  action: "update";
+  step: string;
+  attempt: string;
+  update: { type: string; key: string; data: Record<string, unknown> };
+  idempotencyKey?: string;
+};
+
+type StepAction = StepSubmission | StepUpdate;
+
 export type RpcStepExecutorOptions = {
   cwd: string;
   registry: HostProcessRegistry;
@@ -46,7 +57,7 @@ export class RpcStepExecutor implements AgentStepExecutor {
   private child: ChildProcess | null = null;
   private childExited: { code: number | null; signal: string | null } | null = null;
   private stderrBuffer = "";
-  private submissions: StepSubmission[] = [];
+  private actions: StepAction[] = [];
   private submissionWaiters: Array<() => void> = [];
   private stdoutBuffer = "";
 
@@ -179,13 +190,13 @@ export class RpcStepExecutor implements AgentStepExecutor {
           continue;
         }
         try {
-          const parsed = JSON.parse(line.slice(RPC_SUBMISSION_PREFIX.length)) as StepSubmission;
+          const parsed = JSON.parse(line.slice(RPC_SUBMISSION_PREFIX.length)) as StepAction;
           if (
-            parsed.action === "submit" &&
+            (parsed.action === "submit" || parsed.action === "update") &&
             typeof parsed.step === "string" &&
             typeof parsed.attempt === "string"
           ) {
-            this.submissions.push(parsed);
+            this.actions.push(parsed);
           }
         } catch {
           // A malformed marker line is ignored; the step times out instead.
@@ -209,10 +220,6 @@ export class RpcStepExecutor implements AgentStepExecutor {
     if (child === null || this.childExited !== null) {
       throw new Error("Headless pi session is not running");
     }
-    const matching = this.takeMatchingSubmission(request);
-    if (matching !== undefined) {
-      return matching;
-    }
     child.stdin?.write(`${JSON.stringify({ type: "prompt", message: prompt })}\n`);
     for (;;) {
       throwIfAborted(signal);
@@ -220,9 +227,23 @@ export class RpcStepExecutor implements AgentStepExecutor {
       if (exited !== null) {
         throw new Error(`Headless pi session exited mid-step (code ${exited.code})`);
       }
-      const found = this.takeMatchingSubmission(request);
-      if (found !== undefined) {
-        return found;
+      const found = this.takeMatchingAction(request);
+      if (found?.action === "submit") return found;
+      if (found?.action === "update") {
+        if (request.publishUpdate === undefined) {
+          throw new Error("This workflow host does not support step updates");
+        }
+        try {
+          await request.publishUpdate(found.update, found.idempotencyKey);
+        } catch (error) {
+          child.stdin?.write(
+            `${JSON.stringify({
+              type: "prompt",
+              message: `Workflow update rejected: ${errorMessage(error)}. Correct the update and continue the same step.`,
+            })}\n`,
+          );
+        }
+        continue;
       }
       await new Promise<void>((resolve, reject) => {
         const waiter = () => {
@@ -239,13 +260,13 @@ export class RpcStepExecutor implements AgentStepExecutor {
     }
   }
 
-  private takeMatchingSubmission(request: AgentStepRequest): StepSubmission | undefined {
-    const index = this.submissions.findIndex(
+  private takeMatchingAction(request: AgentStepRequest): StepAction | undefined {
+    const index = this.actions.findIndex(
       (candidate) =>
         candidate.step === request.contract.nodeId &&
         candidate.attempt === request.contract.attemptId,
     );
-    return index === -1 ? undefined : (this.submissions.splice(index, 1)[0] as StepSubmission);
+    return index === -1 ? undefined : (this.actions.splice(index, 1)[0] as StepAction);
   }
 
   private sendAbortQuietly(): void {

package/src/viewer/cli.ts

@@ -138,7 +138,7 @@ async function printOnce(dir: string, runId: string | undefined): Promise<void>
   if (!match) {
     throw new Error(`Run not found: ${runId}`);
   }
-  const bundle = await readRunBundle(match.runDir);
+  const bundle = await readRunBundle(match.runDir, { includeTrace: true });
   if (!bundle) {
     throw new Error(`Run bundle unreadable: ${match.runDir}`);
   }

package/src/viewer/render.ts

@@ -2,6 +2,11 @@ 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 {
+  formatProgressLine,
+  progressRecordsFromTrace,
+  progressTracksFromRecords,
+} from "../workflows/progress.js";
 import type { LoadedRunBundle } from "../workflows/store.js";
 import type { WorkflowRunStatus, WorkflowStepRecord } from "../workflows/types.js";
 
@@ -204,6 +209,28 @@ export function renderRunDetailLines(
     }
   }
 
+  const progressRecords =
+    bundle.traceEvents === undefined
+      ? (state.updates ?? []).filter((update) => update.type === "progress")
+      : progressRecordsFromTrace(bundle.traceEvents);
+  const progress = progressTracksFromRecords(progressRecords, now);
+  if (progress.length > 0) {
+    lines.push("");
+    lines.push(ansi.bold("progress"));
+    for (const track of progress) {
+      lines.push(fitWidth(formatProgressLine(track.estimate, now), size.width));
+      const latest = track.samples.at(-1);
+      lines.push(
+        fitWidth(
+          ansi.dim(
+            `  ${track.estimate.sampleCount} samples · ${track.estimate.confidence ?? "no"} confidence · updated ${latest?.at ?? "unknown"}`,
+          ),
+          size.width,
+        ),
+      );
+    }
+  }
+
   if (steps.length > 0) {
     lines.push("");
     lines.push(ansi.bold("steps"));

package/src/viewer/tui.ts

@@ -62,7 +62,7 @@ export async function runViewer(options: ViewerOptions): Promise<void> {
   };
 
   const renderDetail = async (runDir: string, size: ViewportSize): Promise<string[]> => {
-    const bundle = await readRunBundle(runDir);
+    const bundle = await readRunBundle(runDir, { includeTrace: true });
     if (!bundle) {
       return ["Run bundle disappeared. Press q to go back."];
     }

package/src/workflows/engine.ts

@@ -23,6 +23,7 @@ import type {
   ConversationRange,
   ShellActionNodeDefinition,
   ShellActionResult,
+  WorkflowActionContext,
   WorkflowActionReceipt,
   WorkflowDefinition,
   WorkflowEngineOptions,
@@ -36,7 +37,10 @@ import type {
   WorkflowSource,
   WorkflowStepRecord,
   WorkflowTraceEventDraft,
+  WorkflowUpdateInput,
+  WorkflowUpdateReceipt,
 } from "./types.js";
+import { UpdateRateLimiter, updateReceipt, validateWorkflowUpdate } from "./updates.js";
 
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
@@ -83,6 +87,17 @@ export class WorkflowEngine {
   private readonly onRunStarted?: WorkflowEngineOptions["onRunStarted"];
   private readonly onRunFinishing?: WorkflowEngineOptions["onRunFinishing"];
   private activeAbort: AbortController | null = null;
+  private activeAttempt:
+    | {
+        runDir: string;
+        state: WorkflowRunState;
+        nodeId: string;
+        attemptId: string;
+        signal: AbortSignal;
+      }
+    | undefined;
+  private readonly updateLimiters = new Map<string, UpdateRateLimiter>();
+  private readonly updatePublications = new Map<string, Promise<WorkflowUpdateReceipt>>();
   private cancelled = false;
   private parked = false;
   private paused = false;
@@ -103,6 +118,59 @@ export class WorkflowEngine {
     return this.store.outputRoot;
   }
 
+  /** Publish a durable update for the currently active attempt without completing it. */
+  async publishUpdate(
+    step: string,
+    attempt: string,
+    input: WorkflowUpdateInput,
+    idempotencyKey?: string,
+  ): Promise<WorkflowUpdateReceipt> {
+    const active = this.activeAttempt;
+    if (
+      active === undefined ||
+      active.nodeId !== step ||
+      active.attemptId !== attempt ||
+      active.signal.aborted
+    ) {
+      throw new Error(
+        `Workflow step ${JSON.stringify(step)} attempt ${JSON.stringify(attempt)} is not active`,
+      );
+    }
+    const receiptKey =
+      idempotencyKey === undefined
+        ? undefined
+        : `${active.state.runId}:${active.attemptId}:${idempotencyKey}`;
+    if (receiptKey !== undefined) {
+      const prior = this.updatePublications.get(receiptKey);
+      if (prior !== undefined) return await prior;
+    }
+    const publication = (async () => {
+      const update = validateWorkflowUpdate(input);
+      let limiter = this.updateLimiters.get(active.state.runId);
+      if (limiter === undefined) {
+        limiter = new UpdateRateLimiter();
+        this.updateLimiters.set(active.state.runId, limiter);
+      }
+      limiter.take();
+      const { event, record } = await this.store.publishUpdate(
+        active.runDir,
+        active.state,
+        active.nodeId,
+        active.attemptId,
+        update,
+        { signal: active.signal },
+      );
+      try {
+        this.onEvent?.(event, active.state);
+      } catch {
+        // UI and logging observers never determine workflow correctness.
+      }
+      return updateReceipt(record);
+    })();
+    if (receiptKey !== undefined) this.updatePublications.set(receiptKey, publication);
+    return await publication;
+  }
+
   /** Abort the currently running node and mark the run cancelled. */
   cancel(): void {
     this.cancelled = true;
@@ -492,6 +560,7 @@ export class WorkflowEngine {
       outputs: {},
       results: {},
       steps: [],
+      updates: [],
     };
   }
 
@@ -775,6 +844,7 @@ export class WorkflowEngine {
       timer = setTimeout(() => {
         abort.abort(new TimeoutError(timeoutMs));
       }, timeoutMs);
+      this.activeAttempt = { runDir, state, nodeId, attemptId, signal: abort.signal };
       const dispatched = this.dispatchNode(
         workflow,
         state,
@@ -815,9 +885,19 @@ export class WorkflowEngine {
       if (timer !== undefined) {
         clearTimeout(timer);
       }
+      if (!abort.signal.aborted) {
+        abort.abort(new Error(`Workflow node ${nodeId} is no longer active`));
+      }
       if (this.activeAbort === abort) {
         this.activeAbort = null;
       }
+      if (this.activeAttempt?.attemptId === attemptId) {
+        this.activeAttempt = undefined;
+      }
+      const receiptPrefix = `${state.runId}:${attemptId}:`;
+      for (const key of this.updatePublications.keys()) {
+        if (key.startsWith(receiptPrefix)) this.updatePublications.delete(key);
+      }
     }
   }
 
@@ -895,7 +975,7 @@ export class WorkflowEngine {
         return { output: receipt, promptText: null };
       }
       case "action":
-        return await this.runActionNode(node, context, signal, meta);
+        return await this.runActionNode(node, context, nodeId, attemptId, signal, meta);
       case "checkpoint":
         return await runCheckpointNode(node, context);
     }
@@ -955,7 +1035,17 @@ export class WorkflowEngine {
           ...(node.expectedOutput !== undefined ? { expectedOutput: node.expectedOutput } : {}),
         },
         prompt,
+        ...(state.runTitle !== undefined || node.statusDetail !== undefined
+          ? {
+              presentation: {
+                ...(state.runTitle !== undefined ? { runTitle: state.runTitle } : {}),
+                ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
+              },
+            }
+          : {}),
         accept: async (output) => await this.acceptSubmission(node, context, output),
+        publishUpdate: async (update, idempotencyKey) =>
+          await this.publishUpdate(nodeId, attemptId, update, idempotencyKey),
       },
       signal,
     );
@@ -987,14 +1077,20 @@ export class WorkflowEngine {
   private async runActionNode(
     node: ActionNodeDefinition,
     context: WorkflowNodeContext,
+    nodeId: string,
+    attemptId: string,
     signal: AbortSignal,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
+    const actionContext: WorkflowActionContext = {
+      ...context,
+      publishUpdate: async (update) => await this.publishUpdate(nodeId, attemptId, update),
+    };
     if ("exec" in node) {
-      return await runShellActionNode(node, context, signal, meta);
+      return await runShellActionNode(node, context, actionContext, signal, meta);
     }
     meta.action = { actionType: "function" };
-    const output = await node.run(context);
+    const output = await node.run(actionContext);
     return { output, promptText: null, action: { actionType: "function" } };
   }
 
@@ -1078,13 +1174,28 @@ function shellReceipt(result: ShellActionResult): WorkflowActionReceipt {
 async function runShellActionNode(
   node: ShellActionNodeDefinition,
   context: WorkflowNodeContext,
+  actionContext: WorkflowActionContext,
   signal: AbortSignal,
   meta: NodeExecutionMeta,
 ): Promise<NodeExecution> {
   const spec = await node.exec(context);
+  const streams = new Set(node.updates?.streams ?? ["stdout"]);
   let result: ShellActionResult;
   try {
-    result = await runShellAction(spec, signal);
+    result = await runShellAction(
+      spec,
+      signal,
+      node.updates === undefined
+        ? undefined
+        : async (line) => {
+            if (!streams.has(line.stream)) return;
+            const parsed = await node.updates?.parseLine(line, actionContext);
+            if (parsed === undefined) return;
+            for (const update of Array.isArray(parsed) ? parsed : [parsed]) {
+              await actionContext.publishUpdate(update);
+            }
+          },
+    );
   } catch (error) {
     const failed = shellResultFromError(error);
     if (failed) {
@@ -1191,6 +1302,8 @@ export function appendStepContract(
     "---",
     `Workflow step contract (workflow: ${workflowName}, step: ${nodeId}, attempt: ${attemptId})`,
     "",
+    "While this step is active, you may publish non-completing updates with:",
+    `{"action": "update", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "update": {"type": "...", "key": "...", "data": {...}}}`,
     "Complete this step by calling the `workflow` tool exactly once with:",
     `{"action": "submit", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "output": <your result>}`,
     `Expected output: ${expectedOutput ?? "a JSON object with your result"}`,

package/src/workflows/index.ts

@@ -29,6 +29,28 @@ export {
   type WorkflowSearchPaths,
 } from "./loader.js";
 export { renderShellCommand, runShellAction } from "./shell.js";
+export {
+  estimateProgress,
+  formatProgressLine,
+  formatProgressReport,
+  formatRemaining,
+  prioritizeProgressEstimates,
+  progressRecordsFromTrace,
+  progressTracksFromRecords,
+  type ProgressConfidence,
+  type ProgressEstimate,
+  type ProgressSample,
+  type ProgressTrackState,
+} from "./progress.js";
+export {
+  MAX_CURRENT_UPDATES,
+  MAX_UPDATE_DATA_BYTES,
+  UPDATE_RATE_BURST,
+  UPDATE_RATE_PER_SECOND,
+  updateProjection,
+  validateProgressData,
+  validateWorkflowUpdate,
+} from "./updates.js";
 export { sanitizeText, stripAnsi } from "./text.js";
 export {
   ARTIFACT_THRESHOLD_BYTES,
@@ -51,11 +73,13 @@ export {
   readRunBundle,
   workflowRunsBaseDir,
   type LoadedRunBundle,
+  type ReadRunBundleOptions,
 } from "./store.js";
 export type {
   AgentNodeDefinition,
   AgentStepContract,
   AgentStepExecutor,
+  AgentStepPresentation,
   AgentStepRequest,
   AgentStepSubmission,
   ActionNodeDefinition,
@@ -70,6 +94,7 @@ export type {
   ShellActionExecution,
   ShellActionNodeDefinition,
   ShellActionResult,
+  WorkflowActionContext,
   WorkflowActionReceipt,
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
@@ -85,6 +110,8 @@ export type {
   WorkflowNotificationRequest,
   WorkflowNotificationSink,
   WorkflowPresentationContext,
+  WorkflowProgressData,
+  WorkflowProgressStatus,
   WorkflowRunManifest,
   WorkflowRunResult,
   WorkflowRunState,
@@ -95,4 +122,9 @@ export type {
   WorkflowStepRecord,
   WorkflowTraceEvent,
   WorkflowTraceEventDraft,
+  WorkflowUpdateInput,
+  WorkflowUpdateReceipt,
+  WorkflowUpdateRecord,
+  ShellActionUpdates,
+  ShellUpdateLine,
 } from "./types.js";