@wardby/cli 0.1.0

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

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+export interface WorkflowStatusLike {
+    status: string;
+    executorId?: string;
+    applicationVersion?: string;
+}
+/**
+ * How many times the reconciler will try to adopt (resume) one orphaned
+ * workflow before declaring the run lost.
+ *
+ * DBOS gates both recovery and dequeue on `application_version`: a workflow
+ * recorded under an older version is re-`resume`d on every reconciler pass
+ * and never dequeued, so without a bound the run sits `running` forever and
+ * the reconciler re-drives it every pass. `recover()` also short-circuits an
+ * outright version mismatch (see `versionMismatchReason`); this bound is the
+ * catch-all for every other reason a resume can fail to take.
+ */
+export declare const MAX_RESUME_ATTEMPTS = 3;
+export declare const ADOPTION_EXHAUSTED_REASON = "Durable workflow could not be re-driven after 3 adoption attempts (executor/version mismatch).";
+/**
+ * Given the number of adoption attempts already made for a run, should the
+ * reconciler stop trying and declare it lost? The counter lives in the
+ * executor (in memory, per process) — this is just the bound, kept pure so
+ * it can be tested without Postgres.
+ */
+export declare function shouldGiveUpAdoption(attemptsAlreadyMade: number): boolean;
+/**
+ * Reason to give up immediately when the recorded workflow belongs to a
+ * different application version than this process runs — DBOS will never
+ * dequeue it here, so resuming it is pure churn. `undefined` when the two
+ * agree, or when either version is unknown (nothing to compare).
+ */
+export declare function versionMismatchReason(workflowVersion: string | undefined, processVersion: string | undefined): string | undefined;
+export type RecoveryDecision = {
+    action: "active";
+} | {
+    action: "resume";
+} | {
+    action: "terminal";
+} | {
+    action: "mark-failed";
+    error: string;
+} | {
+    action: "lost";
+    reason: string;
+};
+export declare function decideRecovery(status: WorkflowStatusLike | null, runIsTerminal: boolean, selfExecutorId: string): RecoveryDecision;

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

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+/**
+ * How many times the reconciler will try to adopt (resume) one orphaned
+ * workflow before declaring the run lost.
+ *
+ * DBOS gates both recovery and dequeue on `application_version`: a workflow
+ * recorded under an older version is re-`resume`d on every reconciler pass
+ * and never dequeued, so without a bound the run sits `running` forever and
+ * the reconciler re-drives it every pass. `recover()` also short-circuits an
+ * outright version mismatch (see `versionMismatchReason`); this bound is the
+ * catch-all for every other reason a resume can fail to take.
+ */
+export const MAX_RESUME_ATTEMPTS = 3;
+export const ADOPTION_EXHAUSTED_REASON = `Durable workflow could not be re-driven after ${MAX_RESUME_ATTEMPTS} adoption attempts (executor/version mismatch).`;
+/**
+ * Given the number of adoption attempts already made for a run, should the
+ * reconciler stop trying and declare it lost? The counter lives in the
+ * executor (in memory, per process) — this is just the bound, kept pure so
+ * it can be tested without Postgres.
+ */
+export function shouldGiveUpAdoption(attemptsAlreadyMade) {
+    return attemptsAlreadyMade >= MAX_RESUME_ATTEMPTS;
+}
+/**
+ * Reason to give up immediately when the recorded workflow belongs to a
+ * different application version than this process runs — DBOS will never
+ * dequeue it here, so resuming it is pure churn. `undefined` when the two
+ * agree, or when either version is unknown (nothing to compare).
+ */
+export function versionMismatchReason(workflowVersion, processVersion) {
+    if (!workflowVersion || !processVersion || workflowVersion === processVersion)
+        return undefined;
+    return `Durable workflow belongs to application version ${workflowVersion}; this process runs ${processVersion}.`;
+}
+const LIVE = new Set(["PENDING", "ENQUEUED", "DELAYED"]);
+const FINISHED = new Set(["SUCCESS", "ERROR", "CANCELLED", "MAX_RECOVERY_ATTEMPTS_EXCEEDED"]);
+export function decideRecovery(status, runIsTerminal, selfExecutorId) {
+    if (!status) {
+        return {
+            action: "lost",
+            reason: "Durable workflow record not found; the run was never started or its record was purged.",
+        };
+    }
+    if (LIVE.has(status.status)) {
+        // A live workflow this process owns is simply still running (its
+        // heartbeat lapsed under load). One owned by another executor id whose
+        // heartbeat lapsed is orphaned — that executor died — so adopt it.
+        return status.status === "PENDING" && status.executorId === selfExecutorId
+            ? { action: "active" }
+            : { action: "resume" };
+    }
+    if (FINISHED.has(status.status)) {
+        return runIsTerminal
+            ? { action: "terminal" }
+            : {
+                action: "mark-failed",
+                error: `Durable workflow finished (${status.status}) without persisting a terminal run state.`,
+            };
+    }
+    return { action: "lost", reason: `Durable workflow is in unrecognised status "${status.status}".` };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Phase 6 `Executor`: each native run is a DBOS durable workflow whose
+ * steps are the engine's LLM turns and tool calls (see StepRunner in
+ * providers/engine/types.ts). DBOS records every step result in Postgres;
+ * after a crash or redeploy `launch()` re-drives the workflows this
+ * executor id owned, and completed steps replay from the record — no
+ * repeated LLM spend for finished turns. The at-least-once window is one
+ * in-flight step: a turn that was mid-stream when the process died runs
+ * again on resume.
+ *
+ * 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.
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { ProviderRegistry } from "../index.js";
+import type { DbosConfig } from "../../config/providers.js";
+import { type RunnerDb } from "../../core/runner.js";
+import type { Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
+export declare const DBOS_BACKEND = "dbos";
+type Providers = Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory">;
+type Db = RunnerDb & Pick<PrismaClient, "run">;
+export declare class DbosExecutor implements Executor {
+    private readonly providers;
+    private readonly config;
+    private readonly db;
+    private readonly heartbeatIntervalMs;
+    private launched;
+    /** Non-optional once constructed — see the constructor's DBOS_EXECUTOR_ID guard. */
+    private readonly id;
+    /**
+     * Adoption attempts per run id, bounding `recover()`'s resume branch (see
+     * MAX_RESUME_ATTEMPTS). In memory and per process: a restart resets it,
+     * which is the right default — a restart is also the most likely thing to
+     * have fixed the version/executor mismatch that made adoption fail.
+     */
+    private readonly resumeAttempts;
+    constructor(providers: Providers, config: DbosConfig, db?: Db, heartbeatIntervalMs?: number);
+    get executorId(): string;
+    launch(): Promise<void>;
+    close(): Promise<void>;
+    start(runId: string): Promise<void>;
+    stop(runId: string, reason?: string): Promise<void>;
+    /**
+     * Answer the reconciler for a stale run. Never relaunches: `resume`
+     * re-drives the existing workflow from its last completed step, which is
+     * the same thing launch() does for this executor's own workflows.
+     */
+    recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
+    /** Workflow body. Public only so the module-level registration can reach it. */
+    runInsideWorkflow(runId: string): Promise<void>;
+}
+export {};

package/dist/providers/executor/dbos.js

@@ -0,0 +1,269 @@
+/**
+ * Phase 6 `Executor`: each native run is a DBOS durable workflow whose
+ * steps are the engine's LLM turns and tool calls (see StepRunner in
+ * providers/engine/types.ts). DBOS records every step result in Postgres;
+ * after a crash or redeploy `launch()` re-drives the workflows this
+ * executor id owned, and completed steps replay from the record — no
+ * repeated LLM spend for finished turns. The at-least-once window is one
+ * in-flight step: a turn that was mid-stream when the process died runs
+ * again on resume.
+ *
+ * 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.
+ */
+import { DBOS, Error as DbosErrors } from "@dbos-inc/dbos-sdk";
+import { executeRun, RunCancelledError } from "../../core/runner.js";
+import { markRunFailedFromExecutorError } from "../../core/dispatch.js";
+import { prisma as defaultDb } from "../../core/db.js";
+import { HEARTBEAT_INTERVAL_MS } from "../../core/timing.js";
+import { logger } from "../../core/logger.js";
+import { ADOPTION_EXHAUSTED_REASON, decideRecovery, shouldGiveUpAdoption, versionMismatchReason, } from "./dbos-status.js";
+export const DBOS_BACKEND = "dbos";
+const dbosLog = logger.child({ module: "dbos-executor" });
+/** The executor whose deps the registered workflow uses. Set by launch(). */
+let activeExecutor;
+/** Setter (rather than `activeExecutor = this` inline) to avoid aliasing `this` to a variable. */
+function setActiveExecutor(executor) {
+    activeExecutor = executor;
+}
+/**
+ * Cancellation reasons by run id, recorded by `stop()` so the workflow body
+ * can put the operator's own words on the Run row instead of DBOS's internal
+ * "workflow was cancelled" text. Module-level because `stop()` and the
+ * workflow body are not guaranteed to be on the same DbosExecutor instance
+ * (the reconciler can stop a run this process adopted). Cleared in
+ * `runInsideWorkflow`'s finally.
+ */
+const cancellationReasons = new Map();
+/**
+ * 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.
+ */
+const dbosStep = async (name, fn) => {
+    try {
+        return await DBOS.runStep(fn, { name, retriesAllowed: false });
+    }
+    catch (err) {
+        if (err instanceof DbosErrors.DBOSWorkflowCancelledError) {
+            const reason = cancellationReasons.get(err.workflowID);
+            throw new RunCancelledError(`Run cancelled: ${reason ?? "no reason given"}`);
+        }
+        throw err;
+    }
+};
+/**
+ * Registered once at module load — DBOS requires registration before
+ * launch(). The body must be deterministic between steps; everything
+ * non-deterministic in executeRun/engine is inside a runStep.
+ */
+const runWorkflow = DBOS.registerWorkflow(async (runId) => {
+    const self = activeExecutor;
+    if (!self)
+        throw new Error("DbosExecutor workflow invoked before launch().");
+    await self.runInsideWorkflow(runId);
+}, { name: "wardby.run" });
+export class DbosExecutor {
+    providers;
+    config;
+    db;
+    heartbeatIntervalMs;
+    launched = false;
+    /** Non-optional once constructed — see the constructor's DBOS_EXECUTOR_ID guard. */
+    id;
+    /**
+     * Adoption attempts per run id, bounding `recover()`'s resume branch (see
+     * MAX_RESUME_ATTEMPTS). In memory and per process: a restart resets it,
+     * which is the right default — a restart is also the most likely thing to
+     * have fixed the version/executor mismatch that made adoption fail.
+     */
+    resumeAttempts = new Map();
+    constructor(providers, config, db = defaultDb, heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS) {
+        this.providers = providers;
+        this.config = config;
+        this.db = db;
+        this.heartbeatIntervalMs = heartbeatIntervalMs;
+        if (!config.systemDatabaseUrl) {
+            throw new Error("EXECUTOR=dbos requires DBOS_SYSTEM_DATABASE_URL or DATABASE_URL.");
+        }
+        if (!config.executorId) {
+            throw new Error("EXECUTOR=dbos requires DBOS_EXECUTOR_ID, unique per running process (scheduler and MCP need different values).");
+        }
+        this.id = config.executorId;
+    }
+    get executorId() {
+        return this.id;
+    }
+    async launch() {
+        if (this.launched)
+            return;
+        // DBOS is a process-wide singleton: the executor id is fixed by whoever
+        // launched it first, and setConfig below is skipped for everyone after.
+        // Fail loudly rather than run with an id that disagrees with reality —
+        // recover()'s ownership decisions are made against DBOS.executorID.
+        if (DBOS.isInitialized() && DBOS.executorID !== this.id) {
+            throw new Error(`DBOS is already launched with executor id "${DBOS.executorID}"; ` +
+                `cannot launch a second DbosExecutor with id "${this.id}" in the same process.`);
+        }
+        setActiveExecutor(this);
+        if (!DBOS.isInitialized()) {
+            DBOS.setConfig({
+                name: "wardby",
+                systemDatabaseUrl: this.config.systemDatabaseUrl,
+                systemDatabaseSchemaName: this.config.schemaName,
+                executorID: this.id,
+                runAdminServer: false,
+                logLevel: "warn",
+            });
+            await DBOS.launch();
+        }
+        this.launched = true;
+        dbosLog.info({ executorId: DBOS.executorID }, "DBOS executor launched");
+    }
+    async close() {
+        if (!this.launched)
+            return;
+        this.launched = false;
+        if (activeExecutor === this)
+            setActiveExecutor(undefined);
+        await DBOS.shutdown({ workflowCompletionTimeoutMS: 5_000 });
+    }
+    async start(runId) {
+        if (!this.launched)
+            await this.launch();
+        await this.db.run.updateMany({
+            where: { id: runId, executionBackend: null },
+            data: { executionBackend: DBOS_BACKEND },
+        });
+        // `workflowID: runId` alone gives the idempotency this executor needs: a
+        // second `startWorkflow` call with the same id attaches to the workflow
+        // already recorded under that id instead of re-running it. In this SDK
+        // (4.27.6) `duplicationPolicy: "return-existing"` is a *queue* dedup
+        // mechanism — it throws `DBOSInvalidWorkflowTransitionError` ("requires
+        // a queueName") when passed without `queueName`/`enqueueOptions.
+        // deduplicationID`, which don't apply to this non-queued, direct-start
+        // workflow. See dist/src/dbos.js `#invokeSingletonWorkflow`.
+        const handle = await DBOS.startWorkflow(runWorkflow, { workflowID: runId })(runId);
+        try {
+            await handle.getResult();
+        }
+        catch (err) {
+            // executeRun's own catch backstop owns every terminal write for a run
+            // whose workflow body actually reached it — this only catches a
+            // workflow that failed or was cancelled *before* the body got that
+            // far, leaving the row pending/running. (A cancellation that races
+            // past a run's final step can leave the row's real, already-terminal
+            // outcome in place instead; that's expected — the reason is in the
+            // DBOS log, not here.) markRunFailedFromExecutorError's conditional
+            // update only ever touches a non-terminal row, so it never clobbers
+            // one executeRun already finished. It can also run a second time for
+            // the same failure — dispatchRun's own `.catch` around `start()` calls
+            // it too — which is harmless precisely because it is conditional and
+            // idempotent: the second call matches zero rows.
+            await markRunFailedFromExecutorError(this.db, runId, err);
+            throw err;
+        }
+    }
+    async stop(runId, reason) {
+        // Cancellation goes through DBOS, so this process has to be launched
+        // even when it never started this run (the reconciler/MCP can stop a run
+        // another instance is executing).
+        if (!this.launched)
+            await this.launch();
+        dbosLog.info({ runId, reason }, "cancelling durable run");
+        // Recorded before the cancel so the workflow's next step boundary can
+        // find it: DBOS only reports "cancelled", never why.
+        if (reason)
+            cancellationReasons.set(runId, reason);
+        await DBOS.cancelWorkflow(runId);
+    }
+    /**
+     * Answer the reconciler for a stale run. Never relaunches: `resume`
+     * re-drives the existing workflow from its last completed step, which is
+     * the same thing launch() does for this executor's own workflows.
+     */
+    async recover(handle) {
+        if (handle.backend !== DBOS_BACKEND) {
+            return { state: "lost", reason: `DbosExecutor cannot recover backend "${handle.backend}".` };
+        }
+        if (!this.launched)
+            await this.launch();
+        const status = await DBOS.getWorkflowStatus(handle.id);
+        const row = await this.db.run.findUnique({ where: { id: handle.runId }, select: { status: true } });
+        const runIsTerminal = !!row && !["pending", "running"].includes(row.status);
+        // DBOS.executorID, not this.config.executorId: launch() skips setConfig
+        // when DBOS was already initialised elsewhere in the process, so the
+        // configured id is a request, and DBOS's is the fact ownership is
+        // decided on.
+        const decision = decideRecovery(status, runIsTerminal, DBOS.executorID);
+        switch (decision.action) {
+            case "active":
+                this.resumeAttempts.delete(handle.runId);
+                return { state: "active" };
+            case "resume": {
+                // DBOS gates recovery and dequeue on application_version. A workflow
+                // recorded under a different version is never dequeued here, so
+                // resuming it would be an unbounded loop that holds the run
+                // `running` forever: give up at once and let the reconciler reap it.
+                const mismatch = versionMismatchReason(status?.applicationVersion, DBOS.applicationVersion);
+                if (mismatch) {
+                    this.resumeAttempts.delete(handle.runId);
+                    dbosLog.warn({ runId: handle.runId, workflowVersion: status?.applicationVersion }, mismatch);
+                    return { state: "lost", reason: mismatch };
+                }
+                // Belt and braces for every other reason a resume can fail to take
+                // (an id we can't dequeue for, a queue that never drains): bound the
+                // number of adoptions of one run so the reconciler stops re-driving
+                // it every pass.
+                const attempts = this.resumeAttempts.get(handle.runId) ?? 0;
+                if (shouldGiveUpAdoption(attempts)) {
+                    this.resumeAttempts.delete(handle.runId);
+                    dbosLog.warn({ runId: handle.runId, attempts }, "giving up on adopting orphaned durable run");
+                    return { state: "lost", reason: ADOPTION_EXHAUSTED_REASON };
+                }
+                this.resumeAttempts.set(handle.runId, attempts + 1);
+                dbosLog.warn({ runId: handle.runId, owner: status?.executorId, attempt: attempts + 1 }, "adopting orphaned durable run");
+                // `resumeWorkflow` *enqueues* the workflow for recovery; whichever
+                // process dequeues it runs it, which need not be this one. So
+                // "active" here means "re-driven somewhere", not "running here" —
+                // and the handle below only resolves if we are the one who got it.
+                const resumed = await DBOS.resumeWorkflow(handle.id);
+                void resumed.getResult().catch((err) => dbosLog.error({ err, runId: handle.runId }, "adopted run failed"));
+                return { state: "active" };
+            }
+            case "terminal":
+                this.resumeAttempts.delete(handle.runId);
+                return { state: "terminal" };
+            case "mark-failed":
+                this.resumeAttempts.delete(handle.runId);
+                await this.db.run.updateMany({
+                    where: { id: handle.runId, status: { in: ["pending", "running"] } },
+                    data: { status: "failed", error: decision.error, finishedAt: new Date() },
+                });
+                return { state: "terminal" };
+            case "lost":
+                this.resumeAttempts.delete(handle.runId);
+                return { state: "lost", reason: decision.reason };
+        }
+    }
+    /** Workflow body. Public only so the module-level registration can reach it. */
+    async runInsideWorkflow(runId) {
+        const beat = () => this.db.run.update({ where: { id: runId }, data: { heartbeatAt: new Date() } }).catch(() => {
+            // A missed beat only makes the reconciler look sooner; recover() answers it.
+        });
+        await beat();
+        const timer = setInterval(() => void beat(), this.heartbeatIntervalMs);
+        try {
+            await executeRun(runId, this.providers, this.db, undefined, dbosStep);
+        }
+        finally {
+            clearInterval(timer);
+            cancellationReasons.delete(runId);
+        }
+    }
+}

package/dist/providers/executor/in-process.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Phase 2's default `Executor`: runs `executeRun` in-process, providing
+ * durability via a heartbeat. If this process dies mid-run the heartbeat
+ * stops, and the reconciler (core/reconciler.ts) detects the stale
+ * heartbeat and recovers the run to `lost` rather than leaving it stuck
+ * `running` forever.
+ */
+import type { ProviderRegistry } from "../index.js";
+import { type RunnerDb } from "../../core/runner.js";
+import type { Executor } from "./types.js";
+export declare class InProcessExecutor implements Executor {
+    private readonly providers;
+    private readonly db;
+    private readonly heartbeatIntervalMs;
+    constructor(providers: Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory">, db?: RunnerDb, heartbeatIntervalMs?: number);
+    start(runId: string): Promise<void>;
+    stop(_runId: string, _reason?: string): Promise<void>;
+}

package/dist/providers/executor/in-process.js

@@ -0,0 +1,38 @@
+/**
+ * Phase 2's default `Executor`: runs `executeRun` in-process, providing
+ * durability via a heartbeat. If this process dies mid-run the heartbeat
+ * stops, and the reconciler (core/reconciler.ts) detects the stale
+ * heartbeat and recovers the run to `lost` rather than leaving it stuck
+ * `running` forever.
+ */
+import { executeRun } from "../../core/runner.js";
+import { prisma as defaultDb } from "../../core/db.js";
+import { HEARTBEAT_INTERVAL_MS } from "../../core/timing.js";
+export class InProcessExecutor {
+    providers;
+    db;
+    heartbeatIntervalMs;
+    constructor(providers, db = defaultDb, heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS) {
+        this.providers = providers;
+        this.db = db;
+        this.heartbeatIntervalMs = heartbeatIntervalMs;
+    }
+    async start(runId) {
+        const beat = () => this.db.run.update({ where: { id: runId }, data: { heartbeatAt: new Date() } }).catch(() => {
+            // A missed heartbeat write just makes the reconciler's stale-heartbeat
+            // check trigger a little sooner — never fatal to the run itself.
+        });
+        await beat();
+        const timer = setInterval(() => void beat(), this.heartbeatIntervalMs);
+        try {
+            await executeRun(runId, this.providers, this.db);
+        }
+        finally {
+            clearInterval(timer);
+        }
+    }
+    async stop(_runId, _reason) {
+        // Native engine cancellation remains cooperative until Engine accepts an
+        // AbortSignal. The task state still records the caller's request.
+    }
+}

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

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./in-process.js";
+export * from "./container.js";
+export * from "./routing.js";
+export * from "./composition.js";
+export * from "./dbos.js";
+export * from "./dbos-status.js";
+export * from "./build.js";

package/dist/providers/executor/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./in-process.js";
+export * from "./container.js";
+export * from "./routing.js";
+export * from "./composition.js";
+export * from "./dbos.js";
+export * from "./dbos-status.js";
+export * from "./build.js";

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

@@ -0,0 +1,48 @@
+import type { CodingImageSelector, Executor, ExecutionRecoveryResult, PersistedExecutionHandle } from "./types.js";
+export interface ExecutionKindResolver {
+    kindForRun(runId: string): Promise<"native" | "coding" | null>;
+}
+/** Keeps native execution unchanged while routing coding runs to isolation. */
+export declare class RoutingExecutor implements Executor {
+    private readonly resolver;
+    private readonly native;
+    private readonly coding;
+    constructor(resolver: ExecutionKindResolver, native: Executor, coding: Executor);
+    start(runId: string): Promise<void>;
+    stop(runId: string, reason?: string): Promise<void>;
+    /**
+     * Recovery is routed by the run's agent kind, exactly like start/stop: a
+     * native run's handle belongs to the native executor (e.g. a DBOS
+     * workflow handle), a coding run's to the container executor. Routing by
+     * handle backend would need this class to know every backend name.
+     */
+    recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
+    /** Lifecycle fans out to both executors; each is optional on the seam. */
+    launch(): Promise<void>;
+    close(): Promise<void>;
+    resolveCodingWorkerImage(selector: CodingImageSelector): string;
+}
+export declare class PrismaExecutionKindResolver implements ExecutionKindResolver {
+    private readonly db;
+    constructor(db: {
+        run: {
+            findUnique(input: {
+                where: {
+                    id: string;
+                };
+                select: {
+                    agent: {
+                        select: {
+                            kind: true;
+                        };
+                    };
+                };
+            }): Promise<{
+                agent: {
+                    kind: string;
+                };
+            } | null>;
+        };
+    });
+    kindForRun(runId: string): Promise<"native" | "coding" | null>;
+}

package/dist/providers/executor/routing.js

@@ -0,0 +1,70 @@
+/** Keeps native execution unchanged while routing coding runs to isolation. */
+export class RoutingExecutor {
+    resolver;
+    native;
+    coding;
+    constructor(resolver, native, coding) {
+        this.resolver = resolver;
+        this.native = native;
+        this.coding = coding;
+    }
+    async start(runId) {
+        const kind = await this.resolver.kindForRun(runId);
+        if (kind === "native")
+            return this.native.start(runId);
+        if (kind === "coding")
+            return this.coding.start(runId);
+        throw new Error("executor_run_not_found");
+    }
+    async stop(runId, reason) {
+        const kind = await this.resolver.kindForRun(runId);
+        if (kind === "native")
+            return this.native.stop(runId, reason);
+        if (kind === "coding")
+            return this.coding.stop(runId, reason);
+    }
+    /**
+     * Recovery is routed by the run's agent kind, exactly like start/stop: a
+     * native run's handle belongs to the native executor (e.g. a DBOS
+     * workflow handle), a coding run's to the container executor. Routing by
+     * handle backend would need this class to know every backend name.
+     */
+    async recover(handle) {
+        const kind = await this.resolver.kindForRun(handle.runId);
+        if (kind === "native") {
+            if (!this.native.recover)
+                return { state: "lost", reason: "native_recovery_unavailable" };
+            return this.native.recover(handle);
+        }
+        if (!this.coding.recover)
+            return { state: "lost", reason: "coding_recovery_unavailable" };
+        return this.coding.recover(handle);
+    }
+    /** Lifecycle fans out to both executors; each is optional on the seam. */
+    async launch() {
+        await this.native.launch?.();
+        await this.coding.launch?.();
+    }
+    async close() {
+        await this.coding.close?.();
+        await this.native.close?.();
+    }
+    resolveCodingWorkerImage(selector) {
+        if (!this.coding.resolveCodingWorkerImage)
+            throw new Error("coding_execution_not_configured");
+        return this.coding.resolveCodingWorkerImage(selector);
+    }
+}
+export class PrismaExecutionKindResolver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async kindForRun(runId) {
+        const run = await this.db.run.findUnique({
+            where: { id: runId },
+            select: { agent: { select: { kind: true } } },
+        });
+        return run?.agent.kind === "native" || run?.agent.kind === "coding" ? run.agent.kind : null;
+    }
+}