@wardby/cli 0.1.0

package/dist/core/coding-queue.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The coding concurrency queue's driver. claimProvisioning (container.ts)
+ * refuses a slot and sets CodingRun.queuedAt when CODING_MAX_CONCURRENT
+ * coding runs already hold one; this module later:
+ *
+ *  1. fails queued runs that waited longer than CODING_QUEUE_TIMEOUT_SEC
+ *     (coding_queue_timeout), with a conditional update so concurrent
+ *     drains never double-fail a run;
+ *  2. starts the oldest queued runs, at most as many as there are free
+ *     slots, so order stays FIFO in practice. Starting is fire-and-forget,
+ *     like dispatchRun: Executor.start resolves only when the run ends.
+ *     A run that loses a slot race is simply re-queued by claimProvisioning.
+ *
+ * Called on the scheduler leader's tick and immediately in any process
+ * whose coding run just finished (ContainerExecutor onSlotReleased).
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { Executor } from "../providers/executor/types.js";
+export declare const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
+export type CodingQueueDb = Pick<PrismaClient, "run" | "codingRun" | "$transaction">;
+export interface DrainCodingQueueOptions {
+    db: CodingQueueDb;
+    executor: Executor;
+    maxConcurrent: number;
+    queueTimeoutSec: number;
+    now?: () => Date;
+}
+export interface DrainCodingQueueResult {
+    timedOut: number;
+    started: string[];
+}
+export declare function drainCodingQueue(options: DrainCodingQueueOptions): Promise<DrainCodingQueueResult>;

package/dist/core/coding-queue.js

@@ -0,0 +1,54 @@
+import { markRunFailedFromExecutorError } from "./dispatch.js";
+import { logger } from "./logger.js";
+const queueLog = logger.child({ module: "coding-queue" });
+export const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
+export async function drainCodingQueue(options) {
+    const { db, executor } = options;
+    const now = options.now?.() ?? new Date();
+    const cutoff = new Date(now.getTime() - options.queueTimeoutSec * 1000);
+    let timedOut = 0;
+    const expired = await db.codingRun.findMany({
+        where: { queuedAt: { lt: cutoff }, run: { status: "pending" } },
+        select: { runId: true },
+    });
+    for (const { runId } of expired) {
+        // Both writes commit together: a run is only ever observed with
+        // status=failed/error=coding_queue_timeout and no matching
+        // failureCategory, never one without the other.
+        const didTimeOut = await db.$transaction(async (tx) => {
+            const failed = await tx.run.updateMany({
+                where: { id: runId, status: "pending" },
+                data: { status: "failed", error: CODING_QUEUE_TIMEOUT_ERROR, finishedAt: now },
+            });
+            if (failed.count !== 1)
+                return false;
+            await tx.codingRun.update({ where: { runId }, data: { failureCategory: CODING_QUEUE_TIMEOUT_ERROR } });
+            return true;
+        });
+        if (didTimeOut)
+            timedOut += 1;
+    }
+    const active = await db.codingRun.count({
+        where: { jobBackend: { not: null }, run: { status: { in: ["pending", "running"] } } },
+    });
+    const free = options.maxConcurrent - active;
+    if (free <= 0)
+        return { timedOut, started: [] };
+    const next = await db.codingRun.findMany({
+        where: { queuedAt: { not: null }, jobBackend: null, run: { status: "pending" } },
+        // runId breaks queuedAt ties, matching claimProvisioning's queue order.
+        orderBy: [{ queuedAt: "asc" }, { runId: "asc" }],
+        take: free,
+        select: { runId: true },
+    });
+    for (const { runId } of next) {
+        // Promise.resolve().then(...) defers executor.start's call itself into
+        // the microtask queue, so even a synchronous throw from a misbehaving
+        // Executor implementation lands in this .catch instead of escaping
+        // drainCodingQueue's own call stack.
+        void Promise.resolve()
+            .then(() => executor.start(runId))
+            .catch((err) => markRunFailedFromExecutorError(db, runId, err).catch((err2) => queueLog.error({ err: err2, runId }, "failed to persist queued-run start failure")));
+    }
+    return { timedOut, started: next.map((row) => row.runId) };
+}

package/dist/core/cron.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cron window computation for the scheduler — pure wrapper around `croner`
+ * so the due-window / DST logic is unit-testable without a live clock or DB.
+ */
+export interface DueCheckInput {
+    schedule: string;
+    timezone: string;
+    /** Start of the most recent window this agent already fired for, or null if never. */
+    lastScheduledAt: Date | null;
+    now: Date;
+}
+/**
+ * The start of the most recent due window at/before `now` that hasn't
+ * already been fired for, or `null` if not due.
+ *
+ * Only ever returns the single latest window — this is what implements
+ * "skip, don't backfill": if several windows elapsed since
+ * `lastScheduledAt` (e.g. the scheduler was down), the caller advances
+ * `lastScheduledAt` straight to this value, abandoning the earlier ones.
+ *
+ * Boundary note: croner's `previousRuns` treats its reference instant as
+ * excluded (strictly-before), so a `now` that lands on the exact
+ * millisecond of a scheduled tick reports that tick as not-yet-due until a
+ * subsequent check. Irrelevant in practice at a multi-second tick
+ * interval, but worth knowing if this is ever called with a synthetic
+ * `now` that lands exactly on a boundary.
+ */
+export declare function dueWindow(input: DueCheckInput): Date | null;
+export declare function isDue(input: DueCheckInput): boolean;
+/** Throws a descriptive error for an invalid cron expression or timezone. */
+export declare function validateCronExpression(schedule: string, timezone: string): void;

package/dist/core/cron.js

@@ -0,0 +1,43 @@
+/**
+ * Cron window computation for the scheduler — pure wrapper around `croner`
+ * so the due-window / DST logic is unit-testable without a live clock or DB.
+ */
+import { Cron } from "croner";
+/**
+ * The start of the most recent due window at/before `now` that hasn't
+ * already been fired for, or `null` if not due.
+ *
+ * Only ever returns the single latest window — this is what implements
+ * "skip, don't backfill": if several windows elapsed since
+ * `lastScheduledAt` (e.g. the scheduler was down), the caller advances
+ * `lastScheduledAt` straight to this value, abandoning the earlier ones.
+ *
+ * Boundary note: croner's `previousRuns` treats its reference instant as
+ * excluded (strictly-before), so a `now` that lands on the exact
+ * millisecond of a scheduled tick reports that tick as not-yet-due until a
+ * subsequent check. Irrelevant in practice at a multi-second tick
+ * interval, but worth knowing if this is ever called with a synthetic
+ * `now` that lands exactly on a boundary.
+ */
+export function dueWindow(input) {
+    const { schedule, timezone, lastScheduledAt, now } = input;
+    const job = new Cron(schedule, { timezone });
+    const [mostRecent] = job.previousRuns(1, now);
+    if (!mostRecent) {
+        return null;
+    }
+    if (lastScheduledAt && mostRecent.getTime() <= lastScheduledAt.getTime()) {
+        return null;
+    }
+    return mostRecent;
+}
+export function isDue(input) {
+    return dueWindow(input) !== null;
+}
+/** Throws a descriptive error for an invalid cron expression or timezone. */
+export function validateCronExpression(schedule, timezone) {
+    // The Cron constructor validates the pattern synchronously, but an
+    // invalid timezone only throws once a run is actually computed.
+    const job = new Cron(schedule, { timezone });
+    job.nextRun();
+}

package/dist/core/datastores.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Named datastores shared across agents: an owned resource (like Secret)
+ * attached to agents via AgentDatastore, addressed at sandbox point-of-use
+ * by a per-attachment `boundName` (sharedDatastore.get(boundName, key)) —
+ * same boundName convention as AgentSecret.
+ */
+import type { PrismaClient, Datastore as DatastoreRow } from "@prisma/client";
+import type { Datastore, DatastoreSetOptions, DatastoreValue } from "../providers/datastore/types.js";
+export type DatastoreMetadata = Pick<DatastoreRow, "id" | "name" | "ownerId" | "createdAt" | "updatedAt">;
+export interface SharedDatastoreAccessor {
+    get(boundName: string, key: string): Promise<DatastoreValue | undefined>;
+    set(boundName: string, key: string, value: DatastoreValue, opts?: DatastoreSetOptions): Promise<void>;
+    delete(boundName: string, key: string): Promise<void>;
+    list(boundName: string, prefix?: string): Promise<string[]>;
+}
+/** Creates a named datastore owned by `ownerId`. */
+export declare function createDatastore(name: string, ownerId: string, db: PrismaClient): Promise<DatastoreRow>;
+export declare function listDatastores(ownerId: string, db: PrismaClient): Promise<DatastoreMetadata[]>;
+export declare function deleteDatastore(datastoreId: string, db: PrismaClient): Promise<void>;
+/** Attaches a datastore (by id — the caller already resolved/verified ownership) to an agent under `boundName`. */
+export declare function attachDatastore(agentId: string, datastoreId: string, db: PrismaClient, boundName: string): Promise<void>;
+/** Detaches by point-of-use name — (agentId, boundName) uniquely identifies the edge. */
+export declare function detachDatastore(agentId: string, boundName: string, db: PrismaClient): Promise<void>;
+/**
+ * Resolves `boundName` to the Datastore attached to this agent under that
+ * name, then delegates to its *Shared methods. A `boundName` with no
+ * attachment behaves like a cache-miss for get/list (undefined/[]), and
+ * throws for set (a write must never silently no-op) — delete is a no-op,
+ * matching scopeDatastore's existing "disallowed delete is a no-op"
+ * convention for the private per-agent store.
+ */
+export declare function buildSharedDatastoreAccessor(agentId: string, datastore: Datastore, db: Pick<PrismaClient, "agentDatastore">): SharedDatastoreAccessor;
+/**
+ * Wraps a `SharedDatastoreAccessor` so every operation is confined to a
+ * bound name explicitly granted a prefix list, and within it, keys under one
+ * of those prefixes — mirrors scopeDatastore's OWASP LLM08 fix, per bound
+ * name instead of one flat prefix list. A boundName absent from the map
+ * denies everything, the same default-deny convention as an empty
+ * allowedDatastorePrefixes.
+ */
+export declare function scopeSharedDatastoreAccessor(accessor: SharedDatastoreAccessor, allowedPrefixes: Readonly<Record<string, readonly string[]>>): SharedDatastoreAccessor;

package/dist/core/datastores.js

@@ -0,0 +1,105 @@
+import { boundedString } from "../sandbox/bounded-json.js";
+/** Creates a named datastore owned by `ownerId`. */
+export async function createDatastore(name, ownerId, db) {
+    boundedString(name, 1024);
+    return db.datastore.create({ data: { name, ownerId } });
+}
+export async function listDatastores(ownerId, db) {
+    const rows = await db.datastore.findMany({ where: { ownerId } });
+    return rows.map(({ id, name, ownerId: owner, createdAt, updatedAt }) => ({
+        id,
+        name,
+        ownerId: owner,
+        createdAt,
+        updatedAt,
+    }));
+}
+export async function deleteDatastore(datastoreId, db) {
+    await db.datastore.delete({ where: { id: datastoreId } });
+}
+/** Attaches a datastore (by id — the caller already resolved/verified ownership) to an agent under `boundName`. */
+export async function attachDatastore(agentId, datastoreId, db, boundName) {
+    await db.agentDatastore.create({ data: { agentId, datastoreId, boundName } });
+}
+/** Detaches by point-of-use name — (agentId, boundName) uniquely identifies the edge. */
+export async function detachDatastore(agentId, boundName, db) {
+    await db.agentDatastore.deleteMany({ where: { agentId, boundName } });
+}
+async function resolveDatastoreId(agentId, boundName, db) {
+    const attachment = await db.agentDatastore.findFirst({ where: { agentId, boundName } });
+    return attachment?.datastoreId;
+}
+/**
+ * Resolves `boundName` to the Datastore attached to this agent under that
+ * name, then delegates to its *Shared methods. A `boundName` with no
+ * attachment behaves like a cache-miss for get/list (undefined/[]), and
+ * throws for set (a write must never silently no-op) — delete is a no-op,
+ * matching scopeDatastore's existing "disallowed delete is a no-op"
+ * convention for the private per-agent store.
+ */
+export function buildSharedDatastoreAccessor(agentId, datastore, db) {
+    return {
+        async get(boundName, key) {
+            const datastoreId = await resolveDatastoreId(agentId, boundName, db);
+            if (!datastoreId)
+                return undefined;
+            return datastore.getShared(datastoreId, key);
+        },
+        async set(boundName, key, value, opts) {
+            const datastoreId = await resolveDatastoreId(agentId, boundName, db);
+            if (!datastoreId)
+                throw new Error("datastore_not_bound");
+            await datastore.setShared(datastoreId, key, value, opts);
+        },
+        async delete(boundName, key) {
+            const datastoreId = await resolveDatastoreId(agentId, boundName, db);
+            if (!datastoreId)
+                return;
+            await datastore.deleteShared(datastoreId, key);
+        },
+        async list(boundName, prefix) {
+            const datastoreId = await resolveDatastoreId(agentId, boundName, db);
+            if (!datastoreId)
+                return [];
+            return datastore.listShared(datastoreId, prefix);
+        },
+    };
+}
+/**
+ * Wraps a `SharedDatastoreAccessor` so every operation is confined to a
+ * bound name explicitly granted a prefix list, and within it, keys under one
+ * of those prefixes — mirrors scopeDatastore's OWASP LLM08 fix, per bound
+ * name instead of one flat prefix list. A boundName absent from the map
+ * denies everything, the same default-deny convention as an empty
+ * allowedDatastorePrefixes.
+ */
+export function scopeSharedDatastoreAccessor(accessor, allowedPrefixes) {
+    function isAllowed(boundName, key) {
+        const prefixes = allowedPrefixes[boundName];
+        return prefixes !== undefined && prefixes.some((prefix) => key.startsWith(prefix));
+    }
+    return {
+        async get(boundName, key) {
+            if (!isAllowed(boundName, key))
+                return undefined;
+            return accessor.get(boundName, key);
+        },
+        async set(boundName, key, value, opts) {
+            if (!isAllowed(boundName, key))
+                throw new Error("datastore_prefix_not_allowed");
+            await accessor.set(boundName, key, value, opts);
+        },
+        async delete(boundName, key) {
+            if (!isAllowed(boundName, key))
+                return;
+            await accessor.delete(boundName, key);
+        },
+        async list(boundName, prefix) {
+            const prefixes = allowedPrefixes[boundName];
+            if (!prefixes)
+                return [];
+            const keys = await accessor.list(boundName, prefix);
+            return keys.filter((key) => prefixes.some((p) => key.startsWith(p)));
+        },
+    };
+}

package/dist/core/db.d.ts

@@ -0,0 +1,2 @@
+import { PrismaClient } from "@prisma/client";
+export declare const prisma: PrismaClient<import("@prisma/client").Prisma.PrismaClientOptions, never, import("@prisma/client/runtime/library").DefaultArgs>;

package/dist/core/db.js

@@ -0,0 +1,2 @@
+import { PrismaClient } from "@prisma/client";
+export const prisma = new PrismaClient();

package/dist/core/dispatch.d.ts

@@ -0,0 +1,81 @@
+import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "@prisma/client";
+import type { Executor } from "../providers/executor/types.js";
+export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw">;
+type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$queryRaw">;
+type DispatchAgent = Prisma.AgentGetPayload<{
+    include: {
+        codingProfile: true;
+    };
+}>;
+export interface DispatchRunOptions {
+    db: DispatchDb;
+    executor: Executor;
+    agentId: string;
+    trigger?: RunTrigger;
+    codingTask?: string;
+    codingBaseRef?: string;
+    /**
+     * Revision-in-place: the id of a prior CodingRun whose branch/PR this
+     * dispatch should push a new
+     * commit onto instead of opening a fresh branch. Resolved and verified
+     * here against the database (same repository, and it actually reached a
+     * PR-opening outcome) -- never trusted as a raw branch name, and
+     * deliberately not restricted to the same agent (cross-role continuation,
+     * e.g. plan -> implement on one PR, is allowed by design). Mutually
+     * exclusive with `codingBaseRef`. Coding agents only.
+     */
+    continuesCodingRunId?: string;
+    now?: Date;
+    lockAgent?: boolean;
+    task?: {
+        principalId: string;
+        ttlMs: number;
+    };
+    beforePersist?: (tx: DispatchTx, agent: DispatchAgent) => Promise<boolean>;
+    /** Sub-agent dispatch (see AgentSubAgent): links this run into a run tree. */
+    parentRunId?: string;
+    grantedParentMemoryKeys?: string[];
+    /**
+     * Per-run task text for a NATIVE agent (appended to its systemPrompt at
+     * load time — see runner.ts). The native equivalent of `codingTask`;
+     * mutually exclusive with it, since a native run has no CodingRun.
+     */
+    taskOverride?: string;
+    /**
+     * Overrides `agent.budgetUsd` for this run's coding budget reservation —
+     * used by sub-agent dispatch to apply the run-tree's tightened effective
+     * budget (see src/core/budget-groups.ts) instead of the agent's raw
+     * per-run ceiling, the same composability already applied to native runs.
+     * Ignored for native agents, which compute their own effective budget
+     * inside executeRun's load step.
+     */
+    budgetUsdOverride?: number;
+    /**
+     * Default (false/undefined): fire-and-forget, matching every existing
+     * caller (webhook ingress, trigger_agent, the scheduler) — none of them
+     * want to block on a potentially long-running coding container. Set true
+     * only when the caller genuinely wants to await the run's terminal state,
+     * e.g. a sub-agent dispatch tool blocking the parent's own turn.
+     */
+    awaitExecution?: boolean;
+}
+export interface DispatchRunResult {
+    run: Run;
+    task?: Task;
+}
+/**
+ * Record an executor-level failure on a run that never reached a terminal
+ * state itself. Deliberately idempotent: the same failure can arrive twice —
+ * DbosExecutor.start() calls this when the workflow handle rejects, and
+ * dispatchRun's `.catch` around that same `start()` call calls it again — and
+ * the conditional `updateMany` makes the second call match zero rows rather
+ * than overwrite whatever landed in between.
+ */
+export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run">, runId: string, err: unknown): Promise<void>;
+/**
+ * Persists every detached run input in one transaction, then invokes the
+ * executor only after commit. A null result means the caller's transactional
+ * claim was no longer valid (for example, a schedule was already claimed).
+ */
+export declare function dispatchRun(options: DispatchRunOptions): Promise<DispatchRunResult | null>;
+export {};

package/dist/core/dispatch.js

@@ -0,0 +1,184 @@
+import { CODING_PROTOCOL_VERSION, CodingTaskInputSchema, normalizeGitHubRepository, publicCodingRunResult, } from "../coding/protocol.js";
+import { assertCodingProviderModel } from "../coding/provider.js";
+import { logger } from "./logger.js";
+const dispatchLog = logger.child({ module: "dispatch" });
+function isSerializationConflict(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const candidate = err;
+    return candidate.code === "P2034" || (candidate.code === "P2010" && candidate.meta?.code === "40001");
+}
+/**
+ * Record an executor-level failure on a run that never reached a terminal
+ * state itself. Deliberately idempotent: the same failure can arrive twice —
+ * DbosExecutor.start() calls this when the workflow handle rejects, and
+ * dispatchRun's `.catch` around that same `start()` call calls it again — and
+ * the conditional `updateMany` makes the second call match zero rows rather
+ * than overwrite whatever landed in between.
+ */
+export async function markRunFailedFromExecutorError(db, runId, err) {
+    await db.run.updateMany({
+        where: { id: runId, status: { in: ["pending", "running"] } },
+        data: {
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            finishedAt: new Date(),
+        },
+    });
+}
+/**
+ * Persists every detached run input in one transaction, then invokes the
+ * executor only after commit. A null result means the caller's transactional
+ * claim was no longer valid (for example, a schedule was already claimed).
+ */
+export async function dispatchRun(options) {
+    const now = options.now ?? new Date();
+    const persistOnce = () => options.db.$transaction(async (tx) => {
+        if (options.lockAgent) {
+            const locked = await tx.$queryRaw `
+        SELECT "id" FROM "Agent" WHERE "id" = ${options.agentId} FOR UPDATE SKIP LOCKED
+      `;
+            if (locked.length === 0)
+                return null;
+        }
+        const agent = await tx.agent.findUnique({
+            where: { id: options.agentId },
+            include: { codingProfile: true },
+        });
+        if (!agent)
+            throw new Error(`Unknown agent "${options.agentId}".`);
+        if (options.beforePersist && !(await options.beforePersist(tx, agent)))
+            return null;
+        if (options.taskOverride !== undefined && agent.kind !== "native") {
+            throw new Error("taskOverride can only be supplied for a native agent.");
+        }
+        const run = await tx.run.create({
+            data: {
+                agentId: agent.id,
+                trigger: options.trigger ?? "manual",
+                executionManaged: true,
+                parentRunId: options.parentRunId,
+                grantedParentMemoryKeys: options.grantedParentMemoryKeys ?? [],
+                taskOverride: options.taskOverride,
+            },
+        });
+        if (agent.kind === "coding") {
+            if (!agent.codingProfile)
+                throw new Error(`Coding agent "${agent.id}" has no coding profile.`);
+            assertCodingProviderModel(agent.codingProfile.provider, agent.model);
+            const task = options.codingTask ?? agent.codingProfile.defaultTask;
+            if (!task)
+                throw new Error(`Coding agent "${agent.id}" requires a task.`);
+            const budgetUsd = options.budgetUsdOverride ?? Number(agent.budgetUsd);
+            let baseRef = options.codingBaseRef ?? agent.codingProfile.baseRef;
+            let headRef = `wardby/run-${run.id}`;
+            let continuationOf;
+            let rootCodingRunId;
+            if (options.continuesCodingRunId !== undefined) {
+                if (options.codingBaseRef !== undefined) {
+                    throw new Error("continuesCodingRunId cannot be combined with codingBaseRef.");
+                }
+                const candidate = await tx.codingRun.findUnique({ where: { runId: options.continuesCodingRunId } });
+                if (!candidate)
+                    throw new Error("Cannot continue an unknown coding run.");
+                const root = candidate.rootCodingRunId
+                    ? await tx.codingRun.findUnique({ where: { runId: candidate.rootCodingRunId } })
+                    : candidate;
+                if (!root)
+                    throw new Error("Cannot continue an unknown coding run.");
+                if (normalizeGitHubRepository(root.repository) !== normalizeGitHubRepository(agent.codingProfile.repository)) {
+                    throw new Error("Cannot continue a coding run from a different repository.");
+                }
+                const rootResult = publicCodingRunResult(root.result);
+                if (rootResult?.outcome !== "pull_request_opened" && rootResult?.outcome !== "pull_request_updated") {
+                    throw new Error("Cannot continue a coding run that never opened a pull request.");
+                }
+                baseRef = root.baseRef;
+                headRef = root.headRef;
+                continuationOf = { runId: root.runId };
+                rootCodingRunId = root.runId;
+            }
+            const input = CodingTaskInputSchema.parse({
+                schemaVersion: CODING_PROTOCOL_VERSION,
+                runId: run.id,
+                repository: agent.codingProfile.repository,
+                baseRef,
+                headRef,
+                task,
+                model: agent.model,
+                budgetUsd,
+                deadlineAt: new Date(now.getTime() + agent.codingProfile.timeoutSec * 1000).toISOString(),
+                continuationOf,
+            });
+            const workerImage = options.executor.resolveCodingWorkerImage?.({
+                provider: agent.codingProfile.provider,
+                toolchain: agent.codingProfile.toolchain,
+                toolchainVersion: agent.codingProfile.toolchainVersion,
+                workerImageRef: agent.codingProfile.workerImageRef,
+            });
+            await tx.codingRun.create({
+                data: {
+                    runId: run.id,
+                    task: input.task,
+                    repository: input.repository,
+                    baseRef: input.baseRef,
+                    headRef: input.headRef,
+                    provider: agent.codingProfile.provider,
+                    model: input.model,
+                    timeoutSec: agent.codingProfile.timeoutSec,
+                    allowedEgress: agent.codingProfile.allowedEgress,
+                    protectedPaths: agent.codingProfile.protectedPaths,
+                    workerImage,
+                    budgetReservedUsd: budgetUsd,
+                    rootCodingRunId,
+                    workspaceDiskMb: agent.codingProfile.workspaceDiskMb,
+                },
+            });
+        }
+        else if (options.codingTask !== undefined ||
+            options.codingBaseRef !== undefined ||
+            options.continuesCodingRunId !== undefined) {
+            throw new Error("Coding overrides cannot be supplied for a native agent.");
+        }
+        const task = options.task
+            ? await tx.task.create({
+                data: {
+                    kind: "run",
+                    runId: run.id,
+                    principalId: options.task.principalId,
+                    status: "working",
+                    ttlAt: new Date(now.getTime() + options.task.ttlMs),
+                },
+            })
+            : undefined;
+        return { run, task };
+    }, { isolationLevel: "Serializable" });
+    let persisted = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            persisted = await persistOnce();
+            break;
+        }
+        catch (err) {
+            if (!isSerializationConflict(err) || attempt === 2)
+                throw err;
+        }
+    }
+    if (!persisted)
+        return null;
+    const runStart = async () => {
+        try {
+            await options.executor.start(persisted.run.id);
+        }
+        catch (err) {
+            await markRunFailedFromExecutorError(options.db, persisted.run.id, err).catch((err2) => dispatchLog.error({ err: err2, runId: persisted.run.id }, "failed to persist executor start failure"));
+        }
+    };
+    if (options.awaitExecution) {
+        await runStart();
+    }
+    else {
+        void runStart();
+    }
+    return persisted;
+}

package/dist/core/engine-native.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The native multi-turn engine — the default (and, in Phase 3, only)
+ * `Engine` implementation. Owns the whole turn loop and the whole budget
+ * lifecycle: pre-flight refuse, cumulative pre-turn gate, mid-stream
+ * cutoff, graceful wind-down. See providers/engine/types.ts for why this
+ * lives behind a seam (a future LangGraph engine swaps in here) and why
+ * the budget guardrail must stay above whichever engine is running.
+ */
+import type { Engine, EngineResult, EngineRunContext } from "../providers/engine/types.js";
+export declare class NativeEngine implements Engine {
+    run(ctx: EngineRunContext): Promise<EngineResult>;
+    /**
+     * One final turn with tools disabled, checked against *remaining*
+     * budget and mid-stream-capped so it cannot overshoot. If remaining
+     * budget can't even afford this turn's estimated input, hard-stop
+     * without it — either way the terminal status is `budget_exhausted`.
+     */
+    private windDown;
+    private finish;
+    /**
+     * Streams one model turn, applying the mid-stream cutoff against the
+     * *cumulative* running total (this extends Phase 1's single-turn
+     * AbortController logic across the whole loop). Per-delta output-token
+     * counting mirrors runner.ts's O(delta)-per-event approach — see its
+     * comment for why summing per-delta counts beats re-tokenizing the
+     * whole accumulated output on every event.
+     */
+    private runOneTurn;
+}