@osolmaz/pi-workflows 0.11.2 → 0.12.0

package/src/extension/decision-channels.ts

@@ -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")),
   );
@@ -1163,9 +1163,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 +1191,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 +1219,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"))) {

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");
+}