@wardby/cli 0.5.3 → 0.7.0

package/dist/providers/executor/dbos-status.d.ts

@@ -2,6 +2,7 @@
  * Pure decision table for reconciling a stale `Run` that a DBOS workflow
  * owns. Kept free of DBOS imports so it is unit-testable without Postgres.
  */
+import { STEPS_CHANGED_REASON } from "../engine/types.js";
 export interface WorkflowStatusLike {
     status: string;
     executorId?: string;
@@ -48,3 +49,33 @@ export type RecoveryDecision = {
     reason: string;
 };
 export declare function decideRecovery(status: WorkflowStatusLike | null, runIsTerminal: boolean, selfExecutorId: string): RecoveryDecision;
+/** One recorded step of a workflow, as `DBOS.listWorkflowSteps` reports it. */
+export interface TakeoverStep {
+    functionID: number;
+    name: string;
+    output: unknown;
+}
+/** A still-drivable child of the lead being taken over. */
+export interface TakeoverChild {
+    status: string;
+    kind: "coding" | "native";
+    nativeExecutionMode: string | null;
+}
+export type TakeoverDecision = {
+    action: "fork";
+    startStep: number;
+} | {
+    action: "lost";
+    reason: string;
+};
+/** Why a forked run ends lost when its replay meets a step the new code no longer takes (defined with StepReplayMismatchError). */
+export { STEPS_CHANGED_REASON };
+/**
+ * Whether a workflow recorded under another application version can be forked under this one
+ * (design §1): only when it is waiting inside a `delegate_to_*` call of its last recorded turn and
+ * every child it may be waiting on is durable on its own (a coding run, or a sandbox-mode native
+ * run). The fork starts at the first function id with no record, so every recorded step (the
+ * turn's model reply above all) replays from its record and the delegate step re-attaches to its
+ * child. Anything else is `lost` with the mismatch reason, as before.
+ */
+export declare function decideTakeover(steps: TakeoverStep[], children: TakeoverChild[], mismatchReason: string): TakeoverDecision;

package/dist/providers/executor/dbos-status.js

@@ -2,6 +2,8 @@
  * Pure decision table for reconciling a stale `Run` that a DBOS workflow
  * owns. Kept free of DBOS imports so it is unit-testable without Postgres.
  */
+import { DELEGATE_TOOL_PREFIX } from "../../core/tool-names.js";
+import { STEPS_CHANGED_REASON } from "../engine/types.js";
 /**
  * How many times the reconciler will try to adopt (resume) one orphaned
  * workflow before declaring the run lost.
@@ -62,3 +64,65 @@ export function decideRecovery(status, runIsTerminal, selfExecutorId) {
     }
     return { action: "lost", reason: `Durable workflow is in unrecognised status "${status.status}".` };
 }
+/** Why a forked run ends lost when its replay meets a step the new code no longer takes (defined with StepReplayMismatchError). */
+export { STEPS_CHANGED_REASON };
+const LLM_STEP = /^turn:(\d+):llm$/;
+/**
+ * The tool-call names of a recorded `turn:N:llm` step. Its output is the engine's TurnResult
+ * (engine-native.ts) as DBOS deserialized it: `{ usage, text, toolCalls: [{ id, name, argsJson }],
+ * budgetExceededMidStream, error? }`. Anything else yields undefined (the shape changed: lost).
+ */
+function recordedToolCallNames(output) {
+    if (typeof output !== "object" || output === null || !("toolCalls" in output))
+        return undefined;
+    const calls = output.toolCalls;
+    if (!Array.isArray(calls))
+        return undefined;
+    const names = [];
+    for (const call of calls) {
+        if (typeof call !== "object" || call === null || !("name" in call) || typeof call.name !== "string") {
+            return undefined;
+        }
+        names.push(call.name);
+    }
+    return names;
+}
+/**
+ * Whether a workflow recorded under another application version can be forked under this one
+ * (design §1): only when it is waiting inside a `delegate_to_*` call of its last recorded turn and
+ * every child it may be waiting on is durable on its own (a coding run, or a sandbox-mode native
+ * run). The fork starts at the first function id with no record, so every recorded step (the
+ * turn's model reply above all) replays from its record and the delegate step re-attaches to its
+ * child. Anything else is `lost` with the mismatch reason, as before.
+ */
+export function decideTakeover(steps, children, mismatchReason) {
+    const lost = { action: "lost", reason: mismatchReason };
+    const sorted = [...steps].sort((a, b) => a.functionID - b.functionID);
+    const llmStep = sorted.filter((s) => LLM_STEP.test(s.name)).at(-1);
+    if (!llmStep)
+        return lost;
+    const turn = LLM_STEP.exec(llmStep.name)[1];
+    const names = recordedToolCallNames(llmStep.output);
+    if (!names)
+        return lost;
+    const recorded = new Set(sorted.map((s) => s.name));
+    const firstPending = names.findIndex((_, i) => !recorded.has(`turn:${turn}:tool:${i}`));
+    // Not waiting in a tool call at all, or waiting in one that is not a delegation (re-running it
+    // under new code would repeat its effect).
+    if (firstPending < 0 || !names[firstPending].startsWith(DELEGATE_TOOL_PREFIX))
+        return lost;
+    const durable = (child) => child.kind === "coding" || child.nativeExecutionMode === "sandbox";
+    if (!children.every(durable))
+        return lost;
+    let startStep = 0;
+    for (const step of sorted) {
+        if (step.functionID > startStep)
+            break;
+        if (step.functionID === startStep)
+            startStep += 1;
+    }
+    // A gap at or before the recorded reply would re-run the model turn: never fork into that.
+    if (startStep <= llmStep.functionID)
+        return lost;
+    return { action: "fork", startStep };
+}

package/dist/providers/executor/dbos.d.ts

@@ -11,14 +11,99 @@
  * The heartbeat is kept while the workflow runs here so the reconciler's
  * stale-heartbeat detection is unchanged; the reconciler consults
  * `recover()` (Task 6) before declaring a DBOS run lost.
+ *
+ * A stalled-but-alive owner can overlap an adopted attempt of the same run:
+ * whichever records a step second loses ownership, stops at that step
+ * without writing the run, and hands the SDK's conflict back so DBOS parks
+ * it as a duplicate execution (see dbosStep and runInsideWorkflow). After a
+ * takeover the fork has its own workflow id, so the two never share a step:
+ * the original stops the same way when it meets the takeover's cancel
+ * (dbosStepFor), and its start() handle writes nothing.
  */
+import pg from "pg";
 import type { PrismaClient } from "#prisma";
 import type { DbosConfig } from "../../config/providers.js";
+import { type StepRunner } from "../engine/types.js";
 import { type NativeRunProviders, type RunnerDb } from "../../core/runner.js";
+import { type DatabaseAuth, type PgAuthOptions } from "../../core/pg-auth.js";
 import type { Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
 export declare const DBOS_BACKEND = "dbos";
 type Providers = NativeRunProviders;
 type Db = RunnerDb & Pick<PrismaClient, "run">;
+/**
+ * DBOS.setConfig input. Under password auth this is exactly what launch() always passed, and DBOS
+ * opens its own pool from the URL. Under rds-iam DBOS gets a pool whose password is the IAM token;
+ * DBOS then runs its migrations, queries and LISTEN through that pool and never opens a URL
+ * connection (system_database.js: a custom pool skips database creation and is what every
+ * connection borrows from). The pool copies what DBOS would have set on its own: size, connect
+ * timeout and application_name. DBOS never ends a pool it was given — see endSystemPool().
+ */
+export declare function dbosLaunchConfig(config: DbosConfig, executorId: string, auth: DatabaseAuth, pgAuth?: PgAuthOptions): {
+    name: string;
+    systemDatabaseUrl: string;
+    systemDatabaseSchemaName: string;
+    executorID: string;
+    runAdminServer: false;
+    logLevel: "warn";
+    systemDatabasePool?: pg.Pool;
+};
+/**
+ * The id a takeover gives the fork of workflow `from` under application `version`. Deterministic, so
+ * a takeover that forked but never recorded the fork finishes it rather than forking again; and
+ * descendants share their ancestor's id as a prefix, which isForkOf relies on.
+ */
+export declare function forkWorkflowId(from: string, version: string): string;
+/** Whether workflow `id` was forked from `from`, directly or through further forks (forkWorkflowId). */
+export declare function isForkOf(id: string, from: string): boolean;
+/**
+ * The DBOS workflow id that drives a run: `Run.executionWorkflowId` once the
+ * run's workflow was forked under a new application version, otherwise the
+ * run id (a run's first workflow is started with its run id).
+ */
+export declare function workflowIdOf(db: Pick<PrismaClient, "run">, runId: string): Promise<string>;
+/**
+ * Bind the engine's step boundary to a DBOS checkpointed step. Never
+ * retried: a retry would re-spend.
+ *
+ * DBOS signals a cancelled workflow by throwing `DBOSWorkflowCancelledError`
+ * out of the next step boundary. Translated here into a `RunCancelledError`
+ * so executeRun's backstop records `cancelled` plus the operator's reason,
+ * rather than `failed` plus an SDK-internal message.
+ *
+ * DBOS signals that another execution of this workflow recorded the step
+ * first by throwing `DBOSWorkflowConflictError` after this attempt's step
+ * body already ran. Translated into a `RunOwnershipLostError` (carrying the
+ * discarded step's usage, if any, for the log) so executeRun's backstop stops
+ * this attempt without writing the run; runInsideWorkflow turns it back into
+ * the SDK error.
+ *
+ * DBOS signals that a replay reached a step whose recorded name differs (the
+ * run was recorded by a release whose steps differ, e.g. after a takeover
+ * fork) by throwing `DBOSUnexpectedStepError`. Translated into a
+ * `StepReplayMismatchError`, which executeRun's backstop settles as `lost`
+ * (runInsideWorkflow does it for a mismatch at the load step, which is outside
+ * that backstop).
+ */
+export declare const dbosStep: StepRunner;
+/**
+ * dbosStep for one run's workflow body. A cancellation of a workflow the run has moved off (its
+ * `executionWorkflowId` names a fork of it) is not a stop: recover() took the run over (forked it) and cancelled this,
+ * the forked-from workflow, while its owner was still alive. That attempt stops like one that lost
+ * a step's checkpoint (RunOwnershipLostError: no terminal write), so the fork, not a reasonless
+ * "cancelled" from the original, settles the run. takeOver records the fork's id before it
+ * cancels, so the original always reads the new id by the time it sees the cancel.
+ */
+export declare function dbosStepFor(db: Pick<PrismaClient, "run">, runId: string): StepRunner;
+/**
+ * dbosStepFor behind the same per-step row read as inline runs (stopAwareStep), failing open. DBOS
+ * stops a workflow it was told to cancel, but stop() can cancel only the workflow the run names, and
+ * a takeover's fork is named only once recorded: a fork already running before that (or whose
+ * record failed) would otherwise keep paying for turns under a run stop() already made terminal.
+ * The same read fences out a taken-over original as soon as the run names its fork, before the
+ * takeover's cancel lands, and even when that cancel failed: it stops as an ownership loss, without
+ * a terminal write or the settle side effects (host checks, status comments) the fork owns.
+ */
+export declare function stopAwareDbosStep(db: Pick<PrismaClient, "run">, runId: string): StepRunner;
 export declare class DbosExecutor implements Executor {
     private readonly providers;
     private readonly config;
@@ -48,6 +133,12 @@ export declare class DbosExecutor implements Executor {
      * the same thing launch() does for this executor's own workflows.
      */
     recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
+    /**
+     * A workflow recorded under another application version: fork it under this one when it is only
+     * waiting on durable children (decideTakeover), otherwise answer lost with the mismatch. The
+     * fork counts as an adoption attempt, so repeated failed takeovers of one run end lost too.
+     */
+    private takeOver;
     /** Workflow body. Public only so the module-level registration can reach it. */
     runInsideWorkflow(runId: string): Promise<void>;
 }