@osolmaz/pi-workflows 0.13.4 → 0.15.0

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

@@ -1,171 +0,0 @@
-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

@@ -1,166 +0,0 @@
-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");
-}