@osolmaz/pi-workflows 0.15.3 → 0.16.1

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,32 +1,57 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { SqliteControllerStore } from "../controllers/sqlite.js";
-import { workflowStatePath } from "../state/database.js";
-import { WorkflowRunStore, type LoadedWorkflowRun } from "../workflows/store.js";
+import type { WorkflowSessionView } from "../client/view.js";
+import type {
+  WorkflowDefinitionSnapshot,
+  WorkflowRunState,
+  WorkflowUpdateRecord,
+} from "../workflows/types.js";
 import { buildWidgetView } from "./widget.js";
 
 const WIDGET_KEY = "pi-workflows";
 const WIDGET_SCROLL_STEP = 3;
 
-/** Read-only projection of the host-owned run into the origin Pi session. */
+/** Client-backed projection of the host-owned run into the origin Pi session. */
 export class SessionWorkflowView {
-  private loaded: LoadedWorkflowRun | undefined;
+  private session: WorkflowSessionView | null = null;
   private scroll: number | null = null;
   private shownScroll = 0;
   private maxScroll = 0;
   private stepCount = 0;
   private visible = false;
+  private actionHint: string | undefined;
+  private lastNoticeKey: string | null = null;
 
-  refresh(ctx: ExtensionContext): void {
-    const loaded = loadSessionRun(ctx.sessionManager.getSessionId());
-    if (loaded === undefined) {
-      this.clear(ctx);
+  update(session: WorkflowSessionView, ctx: ExtensionContext): void {
+    const run = session.run;
+    if (
+      run === null ||
+      !isWorkflowRunState(run.state) ||
+      !isWorkflowDefinitionSnapshot(run.workflow)
+    ) {
+      this.session = session;
+      this.clearWidget(ctx);
       return;
     }
-    if (this.loaded?.runId !== loaded.runId || this.stepCount !== loaded.state.steps.length) {
+    const previousRun = this.session?.run;
+    if (previousRun?.runId !== run.runId || this.stepCount !== run.state.steps.length) {
       this.scroll = null;
-      this.stepCount = loaded.state.steps.length;
+      this.stepCount = run.state.steps.length;
+    }
+    this.session = session;
+    this.notifyTransition(previousRun, session, ctx);
+    this.render(ctx);
+  }
+
+  setActionHint(hint: string | undefined, ctx: ExtensionContext): void {
+    this.actionHint = hint;
+    if (this.session?.run !== null) this.render(ctx);
+  }
+
+  refresh(ctx: ExtensionContext): void {
+    if (this.session?.run === null || this.session === null) {
+      this.clearWidget(ctx);
+      return;
     }
-    this.loaded = loaded;
     this.render(ctx);
   }
 
@@ -39,42 +64,54 @@ export class SessionWorkflowView {
   }
 
   clear(ctx: ExtensionContext): void {
-    this.loaded = undefined;
+    this.session = null;
     this.scroll = null;
     this.shownScroll = 0;
     this.maxScroll = 0;
     this.stepCount = 0;
-    if (!this.visible) return;
-    this.visible = false;
-    safelyUpdateUi(ctx, () => {
-      ctx.ui.setWidget(WIDGET_KEY, undefined);
-      ctx.ui.setStatus(WIDGET_KEY, undefined);
-    });
+    this.lastNoticeKey = null;
+    this.clearWidget(ctx);
   }
 
   private scrollBy(ctx: ExtensionContext, delta: number): void {
-    if (this.loaded === undefined) return;
+    if (this.session?.run === null || this.session === null) return;
     const current = this.scroll ?? this.shownScroll;
     this.scroll = Math.max(0, Math.min(this.maxScroll, current + delta));
     this.render(ctx);
   }
 
+  private clearWidget(ctx: ExtensionContext): void {
+    if (!this.visible) return;
+    this.visible = false;
+    safelyUpdateUi(ctx, () => {
+      ctx.ui.setWidget(WIDGET_KEY, undefined);
+      ctx.ui.setStatus(WIDGET_KEY, undefined);
+    });
+  }
+
   private render(ctx: ExtensionContext): void {
-    const loaded = this.loaded;
-    if (loaded === undefined) return;
+    const run = this.session?.run;
+    if (run === null || run === undefined) return;
+    if (!isWorkflowRunState(run.state) || !isWorkflowDefinitionSnapshot(run.workflow)) return;
+    const state = run.state;
+    const snapshot = run.workflow;
     const render = (
       width = Number.POSITIVE_INFINITY,
       theme?: Parameters<typeof buildWidgetView>[6],
     ) => {
       const view = buildWidgetView(
-        loaded.state,
-        loaded.snapshot,
+        state,
+        snapshot,
         new Date(),
         this.scroll,
-        loaded.state.paused === true,
+        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;
@@ -90,42 +127,111 @@ export class SessionWorkflowView {
       } else {
         ctx.ui.setWidget(WIDGET_KEY, render());
       }
-      const label = loaded.state.paused === true ? "paused" : loaded.state.status;
-      ctx.ui.setStatus(WIDGET_KEY, `${loaded.state.workflowName} [${label}]`);
+      const focus = state.currentNode ?? state.waitingOn;
+      ctx.ui.setStatus(
+        WIDGET_KEY,
+        `${state.workflowName} [${run.display.status}]${focus === undefined ? "" : ` ${focus}`}`,
+      );
       this.visible = true;
     });
   }
-}
 
-function loadSessionRun(sessionId: string): LoadedWorkflowRun | undefined {
-  try {
-    const queue = new SqliteControllerStore(workflowStatePath(), {
-      readOnly: true,
-      global: 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",
+      );
     });
-    let runId: string | undefined;
-    try {
-      runId = queue.findSessionReservation(sessionId)?.runId;
-    } finally {
-      queue.close();
-    }
-    if (runId === undefined) return undefined;
-
-    const runs = new WorkflowRunStore(workflowStatePath(), { readOnly: true });
-    try {
-      return runs.readRun(runId) ?? undefined;
-    } finally {
-      runs.close();
-    }
-  } catch {
-    return undefined;
   }
 }
 
+function isWorkflowRunState(value: unknown): value is WorkflowRunState {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (value as { schema?: unknown }).schema === "pi-workflows.run-state.v1" &&
+    typeof (value as { workflowName?: unknown }).workflowName === "string" &&
+    Array.isArray((value as { steps?: unknown }).steps)
+  );
+}
+
+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" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (value as { schema?: unknown }).schema === "pi-workflows.definition-snapshot.v1" &&
+    typeof (value as { nodes?: unknown }).nodes === "object"
+  );
+}
+
+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();
   } catch {
-    // A session replacement can make a captured context stale between polls.
+    // A session replacement can make a captured context stale between updates.
   }
 }

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;