@osolmaz/pi-workflows 0.16.0 → 0.16.2

package/src/extension/remote-recorder-store.ts

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import type { WorkflowClient } from "../client/client.js";
+import { canonicalJson, type JsonValue } from "../state/json.js";
+import type {
+  WorkflowSessionBinding,
+  WorkflowSessionCapture,
+  WorkflowSessionEventRecord,
+} from "../workflows/types.js";
+import type { SessionRecordingStore } from "./recorder.js";
+
+type SessionCommandContext = {
+  targetSessionId: string;
+  coordinatorEpoch: string;
+};
+
+/** Sends bounded session recording batches to the single workflow host writer. */
+export class RemoteSessionRecordingStore implements SessionRecordingStore {
+  constructor(
+    private readonly client: WorkflowClient,
+    private readonly context: () => SessionCommandContext,
+  ) {}
+
+  async hasSessionBinding(runId: string): Promise<boolean> {
+    const receipt = await this.request(runId, "status");
+    if (typeof receipt.bound !== "boolean") throw new Error("Session recording status is invalid");
+    return receipt.bound;
+  }
+
+  async writeSessionBinding(
+    runId: string,
+    binding: WorkflowSessionBinding,
+    attemptId?: string,
+  ): Promise<void> {
+    await this.request(runId, "bind", {
+      binding: toJson(binding),
+      ...(attemptId === undefined ? {} : { attemptId }),
+    });
+  }
+
+  async writeSessionCapture(
+    runId: string,
+    capture: WorkflowSessionCapture,
+    attemptId?: string,
+  ): Promise<void> {
+    await this.request(runId, "capture", {
+      capture: toJson(capture),
+      ...(attemptId === undefined ? {} : { attemptId }),
+    });
+  }
+
+  async appendSessionEntry(
+    runId: string,
+    entry: Record<string, unknown>,
+    attemptId?: string,
+  ): Promise<number> {
+    const receipt = await this.request(runId, "entries", {
+      entries: [toJson(entry)],
+      ...(attemptId === undefined ? {} : { attemptId }),
+    });
+    if (!Number.isSafeInteger(receipt.entrySequence) || (receipt.entrySequence as number) <= 0) {
+      throw new Error("Session recording entry receipt is invalid");
+    }
+    return receipt.entrySequence as number;
+  }
+
+  async appendSessionEventBatch(
+    runId: string,
+    events: WorkflowSessionEventRecord[],
+    attemptId?: string,
+  ): Promise<void> {
+    await this.request(runId, "events", {
+      events: toJson(events),
+      ...(attemptId === undefined ? {} : { attemptId }),
+    });
+  }
+
+  async sessionCounts(
+    runId: string,
+    attemptId?: string,
+  ): Promise<{ eventCount: number; entryCount: number; lastEventSeq: number }> {
+    const receipt = await this.request(
+      runId,
+      "status",
+      attemptId === undefined ? {} : { attemptId },
+    );
+    const eventCount = positiveOrZero(receipt.eventCount, "eventCount");
+    const entryCount = positiveOrZero(receipt.entryCount, "entryCount");
+    const lastEventSeq = positiveOrZero(receipt.lastEventSeq, "lastEventSeq");
+    return { eventCount, entryCount, lastEventSeq };
+  }
+
+  private async request(
+    runId: string,
+    action: "status" | "bind" | "entries" | "events" | "capture",
+    extra: Record<string, JsonValue> = {},
+  ): Promise<Record<string, unknown>> {
+    const idempotencyKey = `session-record-${randomUUID()}`;
+    const response = await this.client.requestDurable({
+      operation: "session.record",
+      requestId: idempotencyKey,
+      idempotencyKey,
+      runId,
+      payload: { ...this.context(), action, ...extra },
+    });
+    if (response.outcome !== "accepted" && response.outcome !== "adopted") {
+      throw new Error(response.error ?? "Workflow host rejected the session recording batch");
+    }
+    if (!isRecord(response.receipt)) throw new Error("Session recording receipt is invalid");
+    return response.receipt;
+  }
+}
+
+function toJson(value: unknown): JsonValue {
+  return JSON.parse(canonicalJson(value)) as JsonValue;
+}
+
+function positiveOrZero(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(`Session recording ${name} is invalid`);
+  }
+  return value as number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/extension/session-events.ts

@@ -0,0 +1,119 @@
+export type PublicAssistantMessageEvent =
+  | { type: "start"; partial: unknown }
+  | { type: "text_start"; contentIndex: number; partial: unknown }
+  | { type: "text_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "text_end"; contentIndex: number; content: string; partial: unknown }
+  | { type: "thinking_start"; contentIndex: number; partial: unknown }
+  | { type: "thinking_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "thinking_end"; contentIndex: number; content: string; partial: unknown }
+  | { type: "toolcall_start"; contentIndex: number; partial: unknown }
+  | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "toolcall_end"; contentIndex: number; toolCall: unknown; partial: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" | "deferred"; message: unknown }
+  | { type: "error"; reason: "aborted" | "error"; error: unknown };
+
+export type TurnStartEventLike = { turnIndex: number };
+export type TurnEndEventLike = { turnIndex: number; message: unknown };
+export type MessageStartEventLike = { message: unknown };
+export type MessageUpdateEventLike = {
+  message: unknown;
+  assistantMessageEvent: PublicAssistantMessageEvent;
+};
+export type MessageEndEventLike = { message: unknown };
+export type ToolExecutionStartEventLike = {
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+};
+export type ToolExecutionUpdateEventLike = { toolCallId: string };
+export type ToolExecutionEndEventLike = {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError: boolean;
+};
+
+export type NormalizedAssistantEvent =
+  | { type: "start" }
+  | { type: "text_start"; contentIndex: number }
+  | { type: "text_delta"; contentIndex: number; delta: string }
+  | { type: "text_end"; contentIndex: number; content: string }
+  | { type: "thinking_start"; contentIndex: number }
+  | { type: "thinking_delta"; contentIndex: number; delta: string }
+  | { type: "thinking_end"; contentIndex: number; content: string }
+  | { type: "toolcall_start"; contentIndex: number }
+  | { type: "toolcall_delta"; contentIndex: number; delta: string }
+  | { type: "toolcall_end"; contentIndex: number; toolCall: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" | "deferred" }
+  | { type: "error"; reason: "aborted" | "error" };
+
+/** Remove cumulative snapshots while preserving every semantic stream event. */
+export function normalizeAssistantEvent(
+  event: PublicAssistantMessageEvent,
+): NormalizedAssistantEvent {
+  switch (event.type) {
+    case "start":
+      return { type: event.type };
+    case "text_start":
+    case "thinking_start":
+    case "toolcall_start":
+      return { type: event.type, contentIndex: event.contentIndex };
+    case "text_delta":
+    case "thinking_delta":
+    case "toolcall_delta":
+      return { type: event.type, contentIndex: event.contentIndex, delta: event.delta };
+    case "text_end":
+    case "thinking_end":
+      return { type: event.type, contentIndex: event.contentIndex, content: event.content };
+    case "toolcall_end":
+      return {
+        type: event.type,
+        contentIndex: event.contentIndex,
+        toolCall: event.toolCall,
+      };
+    case "done":
+      return { type: event.type, reason: event.reason };
+    case "error":
+      return { type: event.type, reason: event.reason };
+    default: {
+      const exhaustive: never = event;
+      return exhaustive;
+    }
+  }
+}
+
+export function messageRole(message: unknown): string {
+  if (typeof message !== "object" || message === null || !("role" in message)) {
+    return "unknown";
+  }
+  const role = (message as { role?: unknown }).role;
+  return typeof role === "string" && role.length > 0 ? role : "unknown";
+}
+
+export function toolCallIdFromAssistantEvent(event: NormalizedAssistantEvent): string | null {
+  if (event.type !== "toolcall_end" || typeof event.toolCall !== "object" || !event.toolCall) {
+    return null;
+  }
+  const id = (event.toolCall as { id?: unknown }).id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
+export function toolStartedPayload(event: ToolExecutionStartEventLike): Record<string, unknown> {
+  return { toolName: event.toolName, args: event.args };
+}
+
+export function toolFinishedPayload(event: ToolExecutionEndEventLike): Record<string, unknown> {
+  return { toolName: event.toolName, isError: event.isError, result: event.result };
+}
+
+export function turnFinishedPayload(
+  event: TurnEndEventLike,
+  messageId: string | undefined,
+  toolCallIds: string[],
+): Record<string, unknown> {
+  return {
+    turnIndex: event.turnIndex,
+    ...(messageId === undefined ? {} : { messageId }),
+    toolCallIds,
+  };
+}

package/src/extension/session-view.ts

@@ -1,6 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { WorkflowSessionView } from "../client/view.js";
-import type { WorkflowDefinitionSnapshot, WorkflowRunState } from "../workflows/types.js";
+import type {
+  WorkflowDefinitionSnapshot,
+  WorkflowRunState,
+  WorkflowUpdateRecord,
+} from "../workflows/types.js";
 import { buildWidgetView } from "./widget.js";
 
 const WIDGET_KEY = "pi-workflows";
@@ -15,6 +19,7 @@ export class SessionWorkflowView {
   private stepCount = 0;
   private visible = false;
   private actionHint: string | undefined;
+  private lastNoticeKey: string | null = null;
 
   update(session: WorkflowSessionView, ctx: ExtensionContext): void {
     const run = session.run;
@@ -33,6 +38,7 @@ export class SessionWorkflowView {
       this.stepCount = run.state.steps.length;
     }
     this.session = session;
+    this.notifyTransition(previousRun, session, ctx);
     this.render(ctx);
   }
 
@@ -63,6 +69,7 @@ export class SessionWorkflowView {
     this.shownScroll = 0;
     this.maxScroll = 0;
     this.stepCount = 0;
+    this.lastNoticeKey = null;
     this.clearWidget(ctx);
   }
 
@@ -100,9 +107,11 @@ export class SessionWorkflowView {
         run.display.status === "paused",
         width,
         theme,
-        undefined,
+        workflowUpdates(run.updates),
         this.actionHint,
         run.display.status,
+        run.display.reason,
+        run.display.controls,
       );
       this.shownScroll = view.scroll;
       this.maxScroll = view.maxScroll;
@@ -118,10 +127,51 @@ export class SessionWorkflowView {
       } else {
         ctx.ui.setWidget(WIDGET_KEY, render());
       }
-      ctx.ui.setStatus(WIDGET_KEY, `${state.workflowName} [${run.display.status}]`);
+      const focus = state.currentNode ?? state.waitingOn;
+      ctx.ui.setStatus(
+        WIDGET_KEY,
+        `${state.workflowName} [${run.display.status}]${focus === undefined ? "" : ` ${focus}`}`,
+      );
       this.visible = true;
     });
   }
+
+  private notifyTransition(
+    previousRun: WorkflowSessionView["run"] | undefined,
+    session: WorkflowSessionView,
+    ctx: ExtensionContext,
+  ): void {
+    const run = session.run;
+    if (run === null || !isWorkflowRunState(run.state)) return;
+    const status = run.display.status;
+    const decision = session.pendingInteractions.some(
+      (value) => isRecord(value) && value.kind === "decision" && value.status === "pending",
+    );
+    const shouldNotify =
+      isTerminalStatus(status) ||
+      (status === "waiting" && (decision || previousRun?.display.status !== "waiting")) ||
+      (status === "paused" && previousRun?.display.status !== "paused");
+    if (!shouldNotify) return;
+    const key = `${run.runId}:${status}:${decision ? "decision" : "workflow"}`;
+    if (key === this.lastNoticeKey) return;
+    this.lastNoticeKey = key;
+    const reason = run.display.reason?.trim();
+    const message = decision
+      ? `Workflow ${run.state.workflowName} needs a human decision.`
+      : reason && reason.length > 0
+        ? reason
+        : `Workflow ${run.state.workflowName} ${status.replace("_", " ")}.`;
+    safelyUpdateUi(ctx, () => {
+      ctx.ui.notify(
+        message,
+        status === "failed" || status === "timed_out" || status === "ambiguous"
+          ? "error"
+          : status === "waiting" || status === "paused"
+            ? "warning"
+            : "info",
+      );
+    });
+  }
 }
 
 function isWorkflowRunState(value: unknown): value is WorkflowRunState {
@@ -135,6 +185,25 @@ function isWorkflowRunState(value: unknown): value is WorkflowRunState {
   );
 }
 
+function workflowUpdates(values: readonly unknown[]): WorkflowUpdateRecord[] {
+  return values.filter(isWorkflowUpdateRecord);
+}
+
+function isWorkflowUpdateRecord(value: unknown): value is WorkflowUpdateRecord {
+  return (
+    isRecord(value) &&
+    typeof value.updateId === "string" &&
+    typeof value.seq === "number" &&
+    typeof value.at === "string" &&
+    typeof value.runId === "string" &&
+    typeof value.nodeId === "string" &&
+    typeof value.attemptId === "string" &&
+    typeof value.type === "string" &&
+    typeof value.key === "string" &&
+    isRecord(value.data)
+  );
+}
+
 function isWorkflowDefinitionSnapshot(value: unknown): value is WorkflowDefinitionSnapshot {
   return (
     typeof value === "object" &&
@@ -145,6 +214,20 @@ function isWorkflowDefinitionSnapshot(value: unknown): value is WorkflowDefiniti
   );
 }
 
+function isTerminalStatus(status: string): boolean {
+  return (
+    status === "completed" ||
+    status === "failed" ||
+    status === "timed_out" ||
+    status === "cancelled" ||
+    status === "ambiguous"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function safelyUpdateUi(ctx: ExtensionContext, update: () => void): void {
   try {
     if (ctx.hasUI) update();

package/src/extension/step-message.ts

@@ -6,6 +6,7 @@ import type {
   AgentStepPresentation,
   AgentStepSubmission,
 } from "../workflows/types.js";
+import { WORKFLOW_STEP_MESSAGE_TYPE } from "../workflows/workflow-message-content.js";
 import {
   cleanOptionalSingleLine,
   cleanSingleLine,
@@ -15,17 +16,19 @@ import {
   type MessageCardView,
 } from "./message-card.js";
 
-export const WORKFLOW_AGENT_STEP_MESSAGE_TYPE = "pi-workflows-agent-step";
+export const WORKFLOW_AGENT_STEP_MESSAGE_TYPE = WORKFLOW_STEP_MESSAGE_TYPE;
 export const WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA = "pi-workflows.agent-step-message.v1";
 
-type PromptDeliveryKind = "step" | "reminder" | "resume";
+type PromptDeliveryReason = "initial" | "reminder" | "resumed";
 
 export type WorkflowAgentStepMessageDetails = {
   schema: typeof WORKFLOW_AGENT_STEP_MESSAGE_SCHEMA;
-  kind: PromptDeliveryKind;
+  kind: "step";
+  reason: PromptDeliveryReason;
   contract: AgentStepContract;
   presentation?: AgentStepPresentation;
-  turnIntentId?: string;
+  requestId: string;
+  workflowMessageId: string;
 };
 
 type WorkflowAgentStepMessage = {
@@ -51,14 +54,14 @@ export function buildWorkflowAgentStepView(
 ): WorkflowAgentStepView {
   const details = parseDetails(message.details);
   const contract = details?.contract;
-  const kind = details?.kind ?? "step";
+  const reason = details?.reason ?? "initial";
   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 suffix = reason === "initial" ? "" : ` · ${reason}`;
+  const glyph = reason === "initial" ? "▶" : "↻";
   const title = paintMessageCard(theme, "accent", `${glyph} ${label} › ${nodeId}${suffix}`);
 
   if (!expanded) {
@@ -80,7 +83,7 @@ export function buildWorkflowAgentStepView(
     `Run id: ${cleanSingleLine(contract?.runId ?? "unknown")}`,
     `Node id: ${nodeId}`,
     `Attempt id: ${cleanSingleLine(contract?.attemptId ?? "unknown")}`,
-    `Delivery: ${kind}`,
+    `Reason: ${reason}`,
     `Completion: ${assistant ? "assistant response" : "workflow submission"}`,
     `Expected output: ${cleanSingleLine(expectedOutput)}`,
   ];
@@ -220,7 +223,14 @@ function parseDetails(value: unknown): WorkflowAgentStepMessageDetails | undefin
   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") {
+  if (
+    candidate.kind !== "step" ||
+    (candidate.reason !== "initial" &&
+      candidate.reason !== "reminder" &&
+      candidate.reason !== "resumed") ||
+    typeof candidate.requestId !== "string" ||
+    typeof candidate.workflowMessageId !== "string"
+  ) {
     return undefined;
   }
   const contract = candidate.contract;

package/src/extension/widget.ts

@@ -38,17 +38,28 @@ const STATUS_GLYPHS: Record<WorkflowDisplayStatus, string> = {
 const PI_MAX_WIDGET_LINES = 10;
 const MAX_NODE_ERROR_CHARS = 120;
 
-export function nodeGlyph(state: WorkflowRunState, nodeId: string): string {
-  if (state.currentNode === nodeId) {
+function displayedRunningNode(
+  state: WorkflowRunState,
+  displayStatus: WorkflowDisplayStatus | undefined,
+): string | undefined {
+  return state.currentNode ?? (displayStatus === "running" ? state.waitingOn : undefined);
+}
+
+export function nodeGlyph(
+  state: WorkflowRunState,
+  nodeId: string,
+  displayStatus?: WorkflowDisplayStatus,
+): string {
+  if (displayedRunningNode(state, displayStatus) === nodeId) {
     return "◐";
   }
+  if (state.waitingOn === nodeId) {
+    return "⏸";
+  }
   const result = state.results[nodeId];
   if (!result) {
     return "·";
   }
-  if (state.waitingOn === nodeId) {
-    return "⏸";
-  }
   return result.outcome === "ok" ? "✓" : "✗";
 }
 
@@ -83,6 +94,8 @@ export function buildWidgetView(
   updateHistory?: WorkflowUpdateRecord[],
   actionHint?: string,
   displayStatus?: WorkflowDisplayStatus,
+  displayReason?: string | null,
+  controls?: readonly string[],
 ): WidgetView {
   const availableWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : width;
   if (availableWidth === 0) return { lines: [], scroll: 0, maxScroll: 0 };
@@ -100,19 +113,23 @@ export function buildWidgetView(
   const header = `${paint(theme, headerTone, glyph)} workflow ${sanitizeText(state.workflowName)}${title} ${paint(theme, headerTone, `[${statusText}]`)}`;
 
   const footer: string[] = [];
+  if (displayReason) {
+    footer.push(paint(theme, "dim", `  ${sanitizeText(displayReason)}`));
+  }
+  if (controls !== undefined && controls.length > 0) {
+    footer.push(paint(theme, "dim", `  controls: ${controls.join(", ")}`));
+  }
   if (state.error) {
     footer.push(paint(theme, "error", `  error: ${truncate(sanitizeText(state.error), 120)}`));
   }
   if (status === "waiting" && state.waitingOn) {
-    footer.push(
-      paint(theme, "warning", `  waiting on checkpoint: ${sanitizeText(state.waitingOn)}`),
-    );
+    footer.push(paint(theme, "warning", `  waiting on step: ${sanitizeText(state.waitingOn)}`));
   }
   const hint = actionHint?.trim() ? sanitizeText(actionHint) : undefined;
   const progress = progressLines(state, now, updateHistory).slice(0, 4);
   const baseBudget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
   const nodes = displayNodeIds(snapshot).map((nodeId) =>
-    compactNodeLine(state, snapshot, nodeId, now, paused, theme),
+    compactNodeLine(state, snapshot, nodeId, now, paused, status, theme),
   );
   const combineHintWithWindow =
     hint !== undefined && nodes.length > 0 && nodes.length + 1 > baseBudget;
@@ -260,15 +277,17 @@ function compactNodeLine(
   nodeId: string,
   now: Date,
   paused: boolean,
+  displayStatus: WorkflowDisplayStatus,
   theme?: WidgetTheme,
 ): string {
   const node = snapshot.nodes[nodeId];
-  const glyph = nodeGlyph(state, nodeId);
+  const runningNode = displayedRunningNode(state, displayStatus);
+  const isCurrent = runningNode === nodeId;
+  const isWaiting = state.waitingOn === nodeId && !isCurrent;
+  const glyph = nodeGlyph(state, nodeId, displayStatus);
   const typeGlyph = node ? nodeTypeGlyph(node.nodeType, node.actionExecution) : "?";
   const name = sanitizeText(nodeId);
-  const segments = nodeRuntimeSegments(state, snapshot, nodeId, now);
-  const isCurrent = state.currentNode === nodeId;
-  const isWaiting = state.waitingOn === nodeId;
+  const segments = nodeRuntimeSegments(state, snapshot, nodeId, now, isCurrent);
 
   if (isCurrent || isWaiting) {
     const tone = paused || isWaiting ? "warning" : "accent";
@@ -301,6 +320,7 @@ function nodeRuntimeSegments(
   snapshot: WorkflowDefinitionSnapshot,
   nodeId: string,
   now: Date,
+  isCurrent: boolean,
 ): string[] {
   const segments: string[] = [];
   const node = snapshot.nodes[nodeId];
@@ -312,11 +332,11 @@ function nodeRuntimeSegments(
     segments.push("assistant response");
   }
   const completedAttempts = state.steps.filter((step) => step.nodeId === nodeId).length;
-  const attempts = completedAttempts + (state.currentNode === nodeId ? 1 : 0);
+  const attempts = completedAttempts + (isCurrent ? 1 : 0);
   if (attempts > 1) {
     segments.push(`↻${attempts}`);
   }
-  if (state.currentNode === nodeId && state.currentSettingsChangeNumber !== undefined) {
+  if (isCurrent && state.currentSettingsChangeNumber !== undefined) {
     segments.push(`settings ${state.currentSettingsChangeNumber}`);
   } else {
     const latest = state.steps.findLast((step) => step.nodeId === nodeId);
@@ -326,8 +346,8 @@ function nodeRuntimeSegments(
   }
 
   const result = state.results[nodeId];
-  if (state.currentNode === nodeId) {
-    if (state.statusDetail) {
+  if (isCurrent) {
+    if (state.currentNode === nodeId && state.statusDetail) {
       segments.push(sanitizeText(state.statusDetail));
     }
     const elapsed = elapsedSince(state.currentNodeStartedAt, now);