@osolmaz/pi-workflows 0.11.2 → 0.12.1

package/src/extension/decision-channels.ts

@@ -14,7 +14,7 @@ import {
 } from "../workflows/decision-presentation.js";
 import { HumanDecisionStore, createHumanDecisionAttemptId } from "../workflows/human-decision.js";
 import type {
-  AcceptedHumanDecision,
+  ResolvedHumanDecision,
   HumanDecisionAnswerSource,
   HumanDecisionCancellationRecord,
   HumanDecisionChannelRequest,
@@ -47,7 +47,7 @@ export type HumanDecisionDeliveryResult = {
   errorCode?: string;
 };
 
-export type SettledHumanDecision = AcceptedHumanDecision | HumanDecisionCancellationRecord;
+export type SettledHumanDecision = ResolvedHumanDecision | HumanDecisionCancellationRecord;
 
 export interface HumanDecisionChannel {
   readonly id: string;
@@ -105,13 +105,13 @@ export async function loadDecisionChannelConfig(
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw error;
   }
-  await requirePrivateFile(channelPath, "Pi Workflows channel profile");
+  await requirePrivateFile(channelPath, "pi-workflows channel profile");
   const channels = parseChannelConfig(channelsRaw);
   const profileNames = Object.keys(channels.telegramProfiles ?? {});
   if (profileNames.length === 0) return { channels, credentials: {}, configDir };
 
   const credentialPath = path.join(configDir, "credentials.json");
-  await requirePrivateFile(credentialPath, "Pi Workflows credential profile");
+  await requirePrivateFile(credentialPath, "pi-workflows credential profile");
   const credentialConfig = parseCredentialConfig(
     JSON.parse(await fsp.readFile(credentialPath, "utf8")),
   );
@@ -162,7 +162,7 @@ export class PiDecisionChannel implements HumanDecisionChannel {
       await this.options.store.recordDelivery(
         request,
         this.id,
-        v2DeliveryRecord(request, this.id, attemptId, "intent", "intent", createdAt),
+        deliveryRecord(request, this.id, attemptId, "intent", "intent", createdAt),
       );
       const entries = Object.entries(request.choices);
       const selectedChoice = await this.options.ui.custom<string | undefined>(
@@ -241,7 +241,7 @@ export class PiDecisionChannel implements HumanDecisionChannel {
         await this.options.store.recordDelivery(
           request,
           this.id,
-          v2DeliveryRecord(
+          deliveryRecord(
             request,
             this.id,
             `${attemptId}-cancelled`,
@@ -267,7 +267,7 @@ export class PiDecisionChannel implements HumanDecisionChannel {
           await this.options.store.recordDelivery(
             request,
             this.id,
-            v2DeliveryRecord(
+            deliveryRecord(
               request,
               this.id,
               `${attemptId}-cancelled`,
@@ -291,7 +291,7 @@ export class PiDecisionChannel implements HumanDecisionChannel {
       await this.options.store.recordDelivery(
         request,
         this.id,
-        v2DeliveryRecord(
+        deliveryRecord(
           request,
           this.id,
           `${attemptId}-confirmed`,
@@ -684,7 +684,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
     await this.store.recordDelivery(
       request,
       channelPath,
-      v2DeliveryRecord(request, this.id, attemptId, "intent", "intent", createdAt, {
+      deliveryRecord(request, this.id, attemptId, "intent", "intent", createdAt, {
         partCount: parts.length,
       }),
     );
@@ -704,7 +704,6 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
         );
         const confirmed = prior.some(
           (record) =>
-            record.schema === "pi-workflows.human-decision-delivery.v2" &&
             record.phase === "part" &&
             record.state === "confirmed" &&
             record.recipientIndex === recipientIndex &&
@@ -724,7 +723,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
           await this.store.recordDelivery(
             request,
             channelPath,
-            v2DeliveryRecord(
+            deliveryRecord(
               request,
               this.id,
               `${attemptId}-r${recipientIndex}-p${partIndex}-unknown`,
@@ -740,15 +739,12 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
         await this.store.recordDelivery(
           request,
           channelPath,
-          v2DeliveryRecord(
-            request,
-            this.id,
-            `${partAttemptId}-intent`,
-            "part",
-            "intent",
-            createdAt,
-            { recipientIndex, partIndex, partCount: parts.length, contentDigest },
-          ),
+          deliveryRecord(request, this.id, `${partAttemptId}-intent`, "part", "intent", createdAt, {
+            recipientIndex,
+            partIndex,
+            partCount: parts.length,
+            contentDigest,
+          }),
         );
         try {
           const result = await this.call("sendMessage", {
@@ -769,7 +765,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
           await this.store.recordDelivery(
             request,
             channelPath,
-            v2DeliveryRecord(
+            deliveryRecord(
               request,
               this.id,
               `${partAttemptId}-confirmed`,
@@ -785,7 +781,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
           await this.store.recordDelivery(
             request,
             channelPath,
-            v2DeliveryRecord(
+            deliveryRecord(
               request,
               this.id,
               `${partAttemptId}-${state}`,
@@ -804,7 +800,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
           await this.store.recordDelivery(
             request,
             channelPath,
-            v2DeliveryRecord(
+            deliveryRecord(
               request,
               this.id,
               `${attemptId}-${state}`,
@@ -821,7 +817,7 @@ export class TelegramDecisionChannel implements HumanDecisionChannel {
     await this.store.recordDelivery(
       request,
       channelPath,
-      v2DeliveryRecord(
+      deliveryRecord(
         request,
         this.id,
         `${attemptId}-confirmed`,
@@ -1163,9 +1159,9 @@ export async function writeDecisionChannelProfile(options: {
 }
 
 function parseChannelConfig(value: unknown): DecisionChannelConfig {
-  const config = record(value, "Pi Workflows channel config");
+  const config = record(value, "pi-workflows channel config");
   if (config.schema !== "pi-workflows.channels.v1") {
-    throw new Error("Pi Workflows channel config schema is invalid");
+    throw new Error("pi-workflows channel config schema is invalid");
   }
   const telegramProfiles: NonNullable<DecisionChannelConfig["telegramProfiles"]> = {};
   if (config.telegramProfiles !== undefined) {
@@ -1191,7 +1187,7 @@ function parseChannelConfig(value: unknown): DecisionChannelConfig {
       };
     }
   }
-  const audiencesRaw = record(config.audiences, "Pi Workflows audiences");
+  const audiencesRaw = record(config.audiences, "pi-workflows audiences");
   const audiences: DecisionChannelConfig["audiences"] = {};
   for (const [name, raw] of Object.entries(audiencesRaw)) {
     requireSimpleId(name, "Decision audience");
@@ -1219,9 +1215,9 @@ function parseChannelConfig(value: unknown): DecisionChannelConfig {
 }
 
 function parseCredentialConfig(value: unknown): DecisionCredentialConfig {
-  const config = record(value, "Pi Workflows credential config");
+  const config = record(value, "pi-workflows credential config");
   if (config.schema !== "pi-workflows.credentials.v1") {
-    throw new Error("Pi Workflows credential config schema is invalid");
+    throw new Error("pi-workflows credential config schema is invalid");
   }
   const telegram: DecisionCredentialConfig["telegram"] = {};
   for (const [name, raw] of Object.entries(record(config.telegram, "Telegram credentials"))) {
@@ -1234,29 +1230,26 @@ function parseCredentialConfig(value: unknown): DecisionCredentialConfig {
   return { schema: "pi-workflows.credentials.v1", telegram };
 }
 
-type DeliveryV2 = Extract<
-  HumanDecisionDeliveryRecord,
-  { schema: "pi-workflows.human-decision-delivery.v2" }
->;
+type DeliveryRecord = HumanDecisionDeliveryRecord;
 
-type DeliveryV2Extra = Partial<
+type DeliveryRecordExtra = Partial<
   Pick<
-    DeliveryV2,
+    DeliveryRecord,
     "recipientIndex" | "partIndex" | "partCount" | "contentDigest" | "messageCount" | "errorCode"
   >
 >;
 
-function v2DeliveryRecord(
+function deliveryRecord(
   request: HumanDecisionChannelRequest,
   channel: string,
   attemptId: string,
-  phase: DeliveryV2["phase"],
-  state: DeliveryV2["state"],
+  phase: DeliveryRecord["phase"],
+  state: DeliveryRecord["state"],
   createdAt: string,
-  extra: DeliveryV2Extra = {},
-): DeliveryV2 {
+  extra: DeliveryRecordExtra = {},
+): DeliveryRecord {
   return {
-    schema: "pi-workflows.human-decision-delivery.v2",
+    schema: "pi-workflows.human-decision-delivery.v1",
     attemptId,
     decisionId: request.decisionId,
     requestDigest: request.requestDigest,
@@ -1271,37 +1264,14 @@ function v2DeliveryRecord(
 }
 
 function isCompleteDelivery(record: HumanDecisionDeliveryRecord): boolean {
-  return (
-    record.state === "confirmed" &&
-    (record.schema === "pi-workflows.human-decision-delivery.v1" || record.phase === "complete")
-  );
+  return record.state === "confirmed" && record.phase === "complete";
 }
 
 function hasUnsettledDeliveryIntent(records: HumanDecisionDeliveryRecord[]): boolean {
-  const hasLegacyIntent = records.some(
-    (record) =>
-      record.schema === "pi-workflows.human-decision-delivery.v1" && record.state === "intent",
-  );
-  if (
-    hasLegacyIntent &&
-    !records.some(
-      (record) =>
-        record.schema === "pi-workflows.human-decision-delivery.v1" && record.state !== "intent",
-    )
-  ) {
-    return true;
-  }
   return records.some((record) => {
-    if (
-      record.schema !== "pi-workflows.human-decision-delivery.v2" ||
-      record.phase !== "part" ||
-      record.state !== "intent"
-    ) {
-      return false;
-    }
+    if (record.phase !== "part" || record.state !== "intent") return false;
     return !records.some(
       (other) =>
-        other.schema === "pi-workflows.human-decision-delivery.v2" &&
         other.phase === "part" &&
         other.state !== "intent" &&
         other.recipientIndex === record.recipientIndex &&

package/src/extension/deferred-turn-coordinator.ts

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import type {
+  SqliteControllerStore,
+  WorkflowTurnIntentRecord,
+  WorkflowTurnIntentResolution,
+} from "../controllers/sqlite.js";
+import { deferredTurnMessageId } from "./deferred-turn.js";
+
+export type BranchIntentResolution = {
+  resolution: WorkflowTurnIntentResolution;
+  messageId: string;
+};
+
+type NaturalDelivery = {
+  runId: string;
+  targetSessionId: string;
+  resolution: Exclude<WorkflowTurnIntentResolution, "fallback">;
+  send: (turnIntentId?: string) => void;
+};
+
+type FallbackDelivery = {
+  targetSessionId: string;
+  send: (intent: WorkflowTurnIntentRecord) => void;
+};
+
+export class DeferredTurnCoordinator {
+  private readonly store: () => SqliteControllerStore | null;
+  private readonly branchResolution: (intentId: string) => BranchIntentResolution | null;
+  private readonly leaseMs: number;
+  private readonly deferredNatural = new Map<string, NaturalDelivery>();
+
+  constructor(options: {
+    store: () => SqliteControllerStore | null;
+    branchResolution: (intentId: string) => BranchIntentResolution | null;
+    leaseMs: number;
+  }) {
+    this.store = options.store;
+    this.branchResolution = options.branchResolution;
+    this.leaseMs = options.leaseMs;
+  }
+
+  sendNatural(delivery: NaturalDelivery, idle: boolean): "sent" | "deferred" | "suppressed" {
+    const store = this.store();
+    const intent = store?.findPendingWorkflowTurnIntent({
+      runId: delivery.runId,
+      targetSessionId: delivery.targetSessionId,
+    });
+    if (store === null || store === undefined || intent === undefined) {
+      delivery.send();
+      return "sent";
+    }
+    if (!idle) {
+      this.deferredNatural.set(intent.intentId, delivery);
+      return "deferred";
+    }
+    const result = this.deliverNatural(intent.intentId, delivery);
+    if (result === "deferred") this.deferredNatural.set(intent.intentId, delivery);
+    return result;
+  }
+
+  flushNatural(idle: boolean): number {
+    if (!idle) return 0;
+    let sent = 0;
+    for (const [intentId, delivery] of this.deferredNatural) {
+      const result = this.deliverNatural(intentId, delivery);
+      if (result !== "deferred") {
+        this.deferredNatural.delete(intentId);
+      }
+      if (result === "sent") sent += 1;
+    }
+    return sent;
+  }
+
+  deliverFallbacks(delivery: FallbackDelivery, idle: boolean): number {
+    const store = this.store();
+    if (!idle || store === null) return 0;
+    const claimToken = randomUUID();
+    const intents = store.claimEligibleWorkflowTurnIntents({
+      targetSessionId: delivery.targetSessionId,
+      claimToken,
+      leaseMs: this.leaseMs,
+    });
+    let sent = 0;
+    for (const [index, intent] of intents.entries()) {
+      const branch = this.branchResolution(intent.intentId);
+      if (branch !== null) {
+        store.resolveWorkflowTurnIntent({
+          intentId: intent.intentId,
+          targetSessionId: delivery.targetSessionId,
+          claimToken,
+          resolution: branch.resolution,
+          messageId: branch.messageId,
+        });
+        continue;
+      }
+      try {
+        delivery.send(intent);
+        store.resolveWorkflowTurnIntent({
+          intentId: intent.intentId,
+          targetSessionId: delivery.targetSessionId,
+          claimToken,
+          resolution: "fallback",
+          messageId: deferredTurnMessageId(intent.intentId, "fallback"),
+        });
+        sent += 1;
+      } catch (error) {
+        for (const pending of intents.slice(index)) {
+          store.releaseWorkflowTurnIntentClaim({
+            intentId: pending.intentId,
+            targetSessionId: delivery.targetSessionId,
+            claimToken,
+          });
+        }
+        throw error;
+      }
+    }
+    return sent;
+  }
+
+  clearDeferred(): void {
+    this.deferredNatural.clear();
+  }
+
+  private deliverNatural(
+    intentId: string,
+    delivery: NaturalDelivery,
+  ): "sent" | "deferred" | "suppressed" {
+    const store = this.store();
+    if (store === null) return "deferred";
+    const claimToken = randomUUID();
+    const intent = store.claimWorkflowTurnIntent({
+      intentId,
+      targetSessionId: delivery.targetSessionId,
+      claimToken,
+      leaseMs: this.leaseMs,
+    });
+    if (intent === undefined) {
+      const current = store.getWorkflowTurnIntent(intentId);
+      return current?.resolvedAt === null ? "deferred" : "suppressed";
+    }
+    const branch = this.branchResolution(intent.intentId);
+    if (branch !== null) {
+      store.resolveWorkflowTurnIntent({
+        intentId: intent.intentId,
+        targetSessionId: delivery.targetSessionId,
+        claimToken,
+        resolution: branch.resolution,
+        messageId: branch.messageId,
+      });
+      return "suppressed";
+    }
+    try {
+      delivery.send(intent.intentId);
+      store.resolveWorkflowTurnIntent({
+        intentId: intent.intentId,
+        targetSessionId: delivery.targetSessionId,
+        claimToken,
+        resolution: delivery.resolution,
+        messageId: deferredTurnMessageId(intent.intentId, delivery.resolution),
+      });
+      return "sent";
+    } catch (error) {
+      store.releaseWorkflowTurnIntentClaim({
+        intentId: intent.intentId,
+        targetSessionId: delivery.targetSessionId,
+        claimToken,
+      });
+      throw error;
+    }
+  }
+}

package/src/extension/deferred-turn.ts

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import type {
+  WorkflowTurnIntentCause,
+  WorkflowTurnIntentFacts,
+  WorkflowTurnIntentRecord,
+  WorkflowTurnIntentResolution,
+} from "../controllers/sqlite.js";
+
+export const DEFERRED_TURN_MESSAGE_TYPE = "pi-workflows-deferred-turn";
+export const DEFERRED_TURN_MESSAGE_SCHEMA = "pi-workflows.deferred-turn-message.v1";
+const FACTS_SCHEMA = "pi-workflows.deferred-turn-facts.v1";
+const MAX_REASON_CHARS = 8_192;
+
+export type DeferredTurnSource = {
+  runId: string;
+  workflowName: string;
+  targetSessionId: string;
+  cause: WorkflowTurnIntentCause;
+  sourceEventId: string;
+  observedState: string;
+  nodeId?: string | null;
+  attemptId?: string | null;
+  reason?: string | null;
+  handoff?: boolean;
+};
+
+export type DeferredTurnDescriptor = {
+  intentId: string;
+  sourceEventId: string;
+  runId: string;
+  workflowRef: string;
+  targetSessionId: string;
+  cause: WorkflowTurnIntentCause;
+  nodeId: string | null;
+  attemptId: string | null;
+  fallbackFacts: WorkflowTurnIntentFacts;
+};
+
+export type DeferredTurnMessageDetails = {
+  schema: typeof DEFERRED_TURN_MESSAGE_SCHEMA;
+  turnIntentId: string;
+  runId: string;
+  cause: WorkflowTurnIntentCause;
+};
+
+export function deferredTurnSourceEventId(options: {
+  runId: string;
+  cause: WorkflowTurnIntentCause;
+  nodeId?: string | null;
+  attemptId?: string | null;
+  source?: string;
+}): string {
+  const parts = [
+    options.runId,
+    options.source ?? "run",
+    options.nodeId ?? "$run",
+    options.attemptId ?? "$none",
+    options.cause,
+  ];
+  return `turn-source:${digest(parts)}`;
+}
+
+export function createDeferredTurnDescriptor(source: DeferredTurnSource): DeferredTurnDescriptor {
+  const nodeId = source.nodeId ?? null;
+  const attemptId = source.attemptId ?? null;
+  const fallbackFacts = createDeferredTurnFacts(source);
+  return {
+    intentId: `deferred-turn:${digest([
+      source.targetSessionId,
+      source.runId,
+      source.sourceEventId,
+      nodeId ?? "$run",
+      attemptId ?? "$none",
+      source.cause,
+    ])}`,
+    sourceEventId: source.sourceEventId,
+    runId: source.runId,
+    workflowRef: source.workflowName,
+    targetSessionId: source.targetSessionId,
+    cause: source.cause,
+    nodeId,
+    attemptId,
+    fallbackFacts,
+  };
+}
+
+export function createDeferredTurnFacts(source: DeferredTurnSource): WorkflowTurnIntentFacts {
+  return {
+    schema: FACTS_SCHEMA,
+    workflowName: source.workflowName,
+    runId: source.runId,
+    observedState: source.observedState,
+    cause: source.cause,
+    nodeId: source.nodeId ?? null,
+    attemptId: source.attemptId ?? null,
+    reason: boundedReason(source.reason),
+    handoff: source.handoff ?? false,
+  };
+}
+
+export function deferredTurnMessageId(
+  intentId: string,
+  resolution: WorkflowTurnIntentResolution,
+): string {
+  return `turn-message:${digest([intentId, resolution])}`;
+}
+
+export function deferredTurnMessageDetails(
+  intent: WorkflowTurnIntentRecord,
+): DeferredTurnMessageDetails {
+  return {
+    schema: DEFERRED_TURN_MESSAGE_SCHEMA,
+    turnIntentId: intent.intentId,
+    runId: intent.runId,
+    cause: intent.cause,
+  };
+}
+
+export function buildDeferredTurnContent(intent: WorkflowTurnIntentRecord): string {
+  const facts = intent.fallbackFacts;
+  const source = [
+    facts.nodeId === null ? null : `node ${facts.nodeId}`,
+    facts.attemptId === null ? null : `attempt ${facts.attemptId}`,
+  ]
+    .filter((part): part is string => part !== null)
+    .join(", ");
+  const reason =
+    facts.reason === null
+      ? ""
+      : ` Reason: ${facts.reason}${/[.!?]$/.test(facts.reason) ? "" : "."}`;
+  const sourceText = source.length === 0 ? "" : ` Source: ${source}.`;
+  if (facts.cause === "launchFailed") {
+    return [
+      `Workflow ${facts.workflowName} failed to start (run ${facts.runId}).`,
+      `${sourceText}${reason}`.trim(),
+      "Inspect the durable workflow state before you explain the outcome or start a corrected workflow.",
+    ]
+      .filter((part) => part.length > 0)
+      .join(" ");
+  }
+  if (facts.handoff) {
+    return [
+      `Workflow ${facts.workflowName} was handed to another runner (run ${facts.runId}).`,
+      `Observed state: ${facts.observedState}.${sourceText}${reason}`,
+      "Inspect the durable workflow state before you explain the outcome or take any authorized corrective action.",
+    ].join(" ");
+  }
+  return [
+    `Workflow ${facts.workflowName} ended with state ${facts.observedState} (run ${facts.runId}).`,
+    `${sourceText}${reason}`.trim(),
+    "Inspect the durable workflow state before you explain the outcome or take any authorized corrective action.",
+  ]
+    .filter((part) => part.length > 0)
+    .join(" ");
+}
+
+function boundedReason(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) return null;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return null;
+  return trimmed.length <= MAX_REASON_CHARS ? trimmed : trimmed.slice(0, MAX_REASON_CHARS);
+}
+
+function digest(parts: readonly string[]): string {
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}