@wardby/cli 0.1.0

package/dist/providers/email/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Email seam — outbound and inbound mail.
+ *
+ * Backs the sandbox `sendEmail` / `getInboundEmail` APIs.
+ * Default adapter: SmtpEmailProvider.
+ * Native adapter:  SesSnsS3EmailProvider (SES out; SNS/S3 inbound).
+ */
+export interface EmailAttachment {
+    filename: string;
+    contentType: string;
+    content: Buffer;
+}
+export interface OutboundEmail {
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    /** Sender address; the provider's configured default is used if omitted. */
+    from?: string;
+    replyTo?: string;
+    attachments?: EmailAttachment[];
+}
+export interface InboundEmail {
+    messageId: string;
+    from: string;
+    to: string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    attachments: EmailAttachment[];
+    receivedAt: Date;
+    /** True only if the provider verified DMARC (with SPF/DKIM alignment). */
+    dmarcPass: boolean;
+}
+export interface EmailProvider {
+    send(msg: OutboundEmail): Promise<{
+        messageId: string;
+    }>;
+    /** Fetch messages routed to a mailbox/address key. */
+    fetchInbound(mailbox: string, opts?: {
+        since?: Date;
+        limit?: number;
+    }): Promise<InboundEmail[]>;
+}

package/dist/providers/email/types.js

@@ -0,0 +1,8 @@
+/**
+ * Email seam — outbound and inbound mail.
+ *
+ * Backs the sandbox `sendEmail` / `getInboundEmail` APIs.
+ * Default adapter: SmtpEmailProvider.
+ * Native adapter:  SesSnsS3EmailProvider (SES out; SNS/S3 inbound).
+ */
+export {};

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

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/providers/engine/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/providers/engine/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Engine seam — the control flow *inside* a run: turns, tool calls,
+ * branching. A future LangGraph adapter is a swap at this seam, not a
+ * rewrite of the runner. Distinct from the `Executor` seam (Phase 2),
+ * which is *around* a run (how it survives a crash and resumes) — see the
+ * Phase 3 design doc's layer-boundaries section.
+ *
+ * The engine owns the entire turn loop AND the budget lifecycle
+ * (pre-flight refuse, cumulative pre-turn gate, mid-stream cutoff,
+ * graceful wind-down) — never split with the caller. Every model call
+ * must go through `ctx.providers.llm` so the guardrail holds regardless of
+ * which engine is driving: an engine that calls a provider SDK directly
+ * blinds the pre-flight refuse and mid-stream cutoff, and is not allowed.
+ */
+import type { ProviderRegistry } from "../index.js";
+/** The subset of Agent fields the engine needs — not the Prisma type, to keep this seam Prisma-agnostic. */
+export interface EngineAgent {
+    systemPrompt: string;
+    model: string;
+    budgetUsd: number;
+    maxTurns: number;
+}
+export interface LoadedTool {
+    name: string;
+    description: string;
+    /** Derived from the tool's Zod schema via zod-to-json-schema at load time. */
+    jsonSchema: Record<string, unknown>;
+}
+/**
+ * Durable step boundary. A checkpointing executor (DbosExecutor) supplies
+ * one that records each step's result, so a run resumed after a crash
+ * replays completed steps from the record instead of re-executing them
+ * (and re-spending). When absent, `fn` runs directly.
+ *
+ * Contract for engines: `fn`'s return value must be plain JSON data, and
+ * `name` must be deterministic for a given position in the run — the
+ * replay matches steps by order, so control flow between steps must depend
+ * only on earlier step results and on `agent` fields fixed at run start.
+ */
+export type StepRunner = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+/** The no-checkpoint default: run the step body directly. */
+export declare const runStepInline: StepRunner;
+export interface EngineRunContext {
+    agent: EngineAgent;
+    tools: LoadedTool[];
+    providers: Pick<ProviderRegistry, "llm">;
+    /** Host bridge: validates params (Zod-in-sandbox) then runs the tool body in the WASM sandbox. Never throws — a tool/validation failure is a JSON error result string, fed back to the model as the tool's result. */
+    runSandboxTool(name: string, argsJson: string): Promise<string>;
+    onText?: (delta: string) => void;
+    /** See StepRunner. Optional; the in-process executor leaves it unset. */
+    step?: StepRunner;
+}
+export type EngineStatus = "succeeded" | "budget_exhausted" | "refused" | "failed";
+export interface EngineResult {
+    status: EngineStatus;
+    finalText: string;
+    turns: number;
+    usage: {
+        tokensIn: number;
+        tokensOut: number;
+        costUsd: number;
+    };
+    error?: string;
+}
+export interface Engine {
+    run(ctx: EngineRunContext): Promise<EngineResult>;
+}

package/dist/providers/engine/types.js

@@ -0,0 +1,16 @@
+/**
+ * Engine seam — the control flow *inside* a run: turns, tool calls,
+ * branching. A future LangGraph adapter is a swap at this seam, not a
+ * rewrite of the runner. Distinct from the `Executor` seam (Phase 2),
+ * which is *around* a run (how it survives a crash and resumes) — see the
+ * Phase 3 design doc's layer-boundaries section.
+ *
+ * The engine owns the entire turn loop AND the budget lifecycle
+ * (pre-flight refuse, cumulative pre-turn gate, mid-stream cutoff,
+ * graceful wind-down) — never split with the caller. Every model call
+ * must go through `ctx.providers.llm` so the guardrail holds regardless of
+ * which engine is driving: an engine that calls a provider SDK directly
+ * blinds the pre-flight refuse and mid-stream cutoff, and is not allowed.
+ */
+/** The no-checkpoint default: run the step body directly. */
+export const runStepInline = (_name, fn) => fn();

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

@@ -0,0 +1,6 @@
+import type { PrismaClient } from "@prisma/client";
+import type { ProviderRegistry } from "../index.js";
+import { type ProviderConfig } from "../../config/providers.js";
+import type { Executor } from "./types.js";
+/** Select the Executor adapter from EXECUTOR. Constructing never connects; call `launch?.()` for that. */
+export declare function buildExecutor(config: Pick<ProviderConfig, "executor">, providers: Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory">, db?: PrismaClient, env?: NodeJS.ProcessEnv): Executor;

package/dist/providers/executor/build.js

@@ -0,0 +1,15 @@
+import { loadDbosConfig } from "../../config/providers.js";
+import { prisma as defaultDb } from "../../core/db.js";
+import { InProcessExecutor } from "./in-process.js";
+import { DbosExecutor } from "./dbos.js";
+/** Select the Executor adapter from EXECUTOR. Constructing never connects; call `launch?.()` for that. */
+export function buildExecutor(config, providers, db = defaultDb, env = process.env) {
+    switch (config.executor) {
+        case "in-process":
+            return new InProcessExecutor(providers, db);
+        case "dbos":
+            return new DbosExecutor(providers, loadDbosConfig(env), db);
+        default:
+            throw new Error(`EXECUTOR "${String(config.executor)}" has no adapter (use "in-process" or "dbos").`);
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { PrismaClient } from "@prisma/client";
+import { type ProviderConfig } from "../../config/providers.js";
+import type { KubernetesApi } from "../jobs/kubernetes-api.js";
+import type { Executor } from "./types.js";
+export interface ConfiguredExecutorOptions {
+    native: Executor;
+    db: PrismaClient;
+    env?: NodeJS.ProcessEnv;
+    providerConfig?: ProviderConfig;
+    /** Tests only: replaces the kubeconfig-backed client when JOB_LAUNCHER=kubernetes. */
+    kubernetesApi?: KubernetesApi;
+}
+/** Builds container execution only when Docker or Kubernetes is explicitly selected. */
+export declare function buildConfiguredExecutor(options: ConfiguredExecutorOptions): Executor;

package/dist/providers/executor/composition.js

@@ -0,0 +1,123 @@
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { loadCodingConcurrencyConfig, loadContainerExecutorConfig, loadGitHubVcsConfig, loadKubernetesJobConfig, loadProviderConfig, } from "../../config/providers.js";
+import { drainCodingQueue } from "../../core/coding-queue.js";
+import { logger } from "../../core/logger.js";
+import { EnvironmentCredentialResolver } from "../coding-proxy/environment-credentials.js";
+import { CodingProxy } from "../coding-proxy/proxy.js";
+import { PrismaProxyLedger } from "../coding-proxy/prisma-ledger.js";
+import { DockerJobLauncher } from "../jobs/docker.js";
+import { ClientNodeKubernetesApi } from "../jobs/kubernetes-client.js";
+import { isRegistryDigest } from "../jobs/kubernetes-isolation.js";
+import { assertPlatformConfig, platformProfile } from "../jobs/kubernetes-platform.js";
+import { runKubernetesPreflight } from "../jobs/kubernetes-preflight.js";
+import { KubernetesJobLauncher } from "../jobs/kubernetes.js";
+import { buildVcsProvider } from "../vcs/index.js";
+import { ContainerExecutor, PrismaContainerExecutionStore, RunCapabilityVault } from "./container.js";
+import { PrismaExecutionKindResolver, RoutingExecutor } from "./routing.js";
+const compositionLog = logger.child({ module: "executor-composition" });
+/** Builds container execution only when Docker or Kubernetes is explicitly selected. */
+export function buildConfiguredExecutor(options) {
+    const env = options.env ?? process.env;
+    const providerConfig = options.providerConfig ?? loadProviderConfig(env);
+    if (providerConfig.jobs !== "docker" && providerConfig.jobs !== "kubernetes")
+        return options.native;
+    const github = loadGitHubVcsConfig(env);
+    const config = loadContainerExecutorConfig(env);
+    if (!config.workerImage)
+        throw new Error(`CODING_WORKER_IMAGE is required when JOB_LAUNCHER=${providerConfig.jobs}.`);
+    const proxyContainer = config.proxyContainer;
+    if (providerConfig.jobs === "docker" && !proxyContainer) {
+        throw new Error("CODING_PROXY_CONTAINER is required when JOB_LAUNCHER=docker.");
+    }
+    const workspaceRoot = resolve(github.workRoot ?? resolve(tmpdir(), "wardby-vcs"));
+    const artifactRoot = resolve(config.artifactRoot ?? resolve(tmpdir(), "wardby-coding-artifacts"));
+    const vcs = buildVcsProvider(providerConfig, { ...github, workRoot: workspaceRoot });
+    const capabilities = new RunCapabilityVault();
+    const sessions = new CodingProxy({
+        ledger: new PrismaProxyLedger(options.db),
+        credentials: new EnvironmentCredentialResolver(env),
+    });
+    let jobs;
+    if (providerConfig.jobs === "kubernetes") {
+        if (!isRegistryDigest(config.workerImage)) {
+            throw new Error("CODING_WORKER_IMAGE must be a registry digest (repo@sha256:...) when JOB_LAUNCHER=kubernetes.");
+        }
+        const kubernetes = loadKubernetesJobConfig(env);
+        // The preflight only runs on the first launch; a configuration that cannot work should
+        // fail the process at start-up, not the first coding run an hour later.
+        assertPlatformConfig(platformProfile(kubernetes.platform), {
+            runtimeClassName: kubernetes.runtimeClassName,
+            maxDiskMb: config.maxDiskMb,
+        });
+        const api = options.kubernetesApi ?? new ClientNodeKubernetesApi({ context: kubernetes.context });
+        const workerImage = config.workerImage;
+        jobs = new KubernetesJobLauncher({
+            api,
+            config: kubernetes,
+            workspaceRoot,
+            resolveCapability: (runId) => capabilities.get(runId),
+            readyTimeoutMs: kubernetes.readyTimeoutMs,
+            preflight: async () => {
+                const { proxyIp } = await runKubernetesPreflight({
+                    api,
+                    config: kubernetes,
+                    workerImage,
+                    maxDiskMb: config.maxDiskMb,
+                    timeoutMs: kubernetes.preflightTimeoutMs,
+                });
+                return { proxyIp };
+            },
+            onWarning: (message) => compositionLog.warn(message),
+        });
+    }
+    else {
+        const stateRoot = resolve(config.stateRoot ?? resolve(tmpdir(), "wardby-docker-jobs"));
+        jobs = new DockerJobLauncher({
+            stateRoot,
+            workspaceRoot,
+            proxyContainer: proxyContainer,
+            resolveCapability: (runId) => capabilities.get(runId),
+            isRunActive: async (runId, handle) => {
+                const coding = await options.db.codingRun.findUnique({
+                    where: { runId },
+                    include: { run: { select: { status: true } } },
+                });
+                return (coding?.run.status === "running" && coding.jobBackend === handle.backend && coding.jobHandle === handle.id);
+            },
+        });
+    }
+    const concurrency = loadCodingConcurrencyConfig(env);
+    // The release hook needs the composed RoutingExecutor, which only exists
+    // after the ContainerExecutor it wraps is built. The closure reads
+    // `composed` only when a run finishes, which is after this function returns.
+    const coding = new ContainerExecutor({
+        store: new PrismaContainerExecutionStore(options.db, { maxConcurrent: concurrency.maxConcurrent }),
+        jobs,
+        vcs,
+        sessions,
+        capabilities,
+        artifactRoot,
+        workerImage: config.workerImage,
+        claudeWorkerImage: config.claudeWorkerImage,
+        claudeToolRunnerImage: config.claudeToolRunnerImage,
+        additionalWorkerImages: config.additionalWorkerImages,
+        credentialRef: config.credentialRef,
+        anthropicCredentialRef: config.anthropicCredentialRef,
+        limits: { cpus: config.cpus, memoryMb: config.memoryMb, pids: config.pids, diskMb: config.diskMb },
+        maxDiskMb: config.maxDiskMb,
+        onSlotReleased: () => {
+            void drainCodingQueue({
+                db: options.db,
+                executor: composed,
+                maxConcurrent: concurrency.maxConcurrent,
+                queueTimeoutSec: concurrency.queueTimeoutSec,
+            }).catch((err) => {
+                // Never throws: the next scheduler tick drains again.
+                compositionLog.warn({ err }, "coding queue drain after a released slot failed");
+            });
+        },
+    });
+    const composed = new RoutingExecutor(new PrismaExecutionKindResolver(options.db), options.native, coding);
+    return composed;
+}

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

@@ -0,0 +1,184 @@
+import type { PrismaClient } from "@prisma/client";
+import { type CodingRunObserver } from "../../coding/observability.js";
+import { type CodingRunResult } from "../../coding/protocol.js";
+import type { ProxyProtocol } from "../coding-proxy/types.js";
+import type { JobHandle, JobResourceLimits, WorkspaceJobLauncher } from "../jobs/types.js";
+import type { VcsProvider } from "../vcs/types.js";
+import type { CodingImageSelector, ExecutionRecoveryResult, Executor, PersistedExecutionHandle } from "./types.js";
+export interface ContainerRunSnapshot {
+    runId: string;
+    status: string;
+    agentKind: string;
+    /** Human-readable agent name (e.g. "knock-knock-implement") -- surfaced in continuation status notifications. */
+    agentName: string;
+    ownerId: string | null;
+    task: string;
+    repository: string;
+    baseRef: string;
+    headRef: string;
+    provider: string;
+    model: string;
+    timeoutSec: number;
+    allowedEgress: unknown;
+    protectedPaths: unknown;
+    /** Revision-in-place: set when this run continues another run's branch/PR. See preflight(). */
+    rootCodingRunId: string | null;
+    budgetUsd: number;
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    jobHandle: JobHandle | null;
+    provisioningClaim: string | null;
+    proxySessionId: string | null;
+    result: unknown;
+    workerImage: string | null;
+    workspaceDiskMb: number | null;
+}
+/**
+ * claimed: this caller owns provisioning. unavailable: someone else does, or
+ * the run is no longer active. queued: every concurrency slot is taken, or
+ * the free ones belong to older queued runs; the run stays pending with
+ * CodingRun.queuedAt set until drainCodingQueue starts it.
+ */
+export type ProvisioningClaim = "claimed" | "unavailable" | "queued";
+export interface ContainerExecutionStore {
+    load(runId: string): Promise<ContainerRunSnapshot | null>;
+    claimProvisioning(runId: string, claimId: string): Promise<ProvisioningClaim>;
+    persistHandle(runId: string, claimId: string, handle: JobHandle): Promise<void>;
+    heartbeat(runId: string): Promise<void>;
+    complete(runId: string, status: "succeeded" | "budget_exhausted", result: CodingRunResult): Promise<void>;
+    terminate(runId: string, status: "failed" | "refused" | "lost" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<void>;
+}
+export interface CodingFailureAudit {
+    failureCategory: string;
+    diagnosticId: string;
+}
+export declare class PrismaContainerExecutionStore implements ContainerExecutionStore {
+    private readonly db;
+    private readonly options;
+    constructor(db: PrismaClient, options?: {
+        maxConcurrent?: number;
+    });
+    load(runId: string): Promise<ContainerRunSnapshot | null>;
+    claimProvisioning(runId: string, claimId: string): Promise<ProvisioningClaim>;
+    persistHandle(runId: string, claimId: string, handle: JobHandle): Promise<void>;
+    heartbeat(runId: string): Promise<void>;
+    complete(runId: string, status: "succeeded" | "budget_exhausted", result: CodingRunResult): Promise<void>;
+    terminate(runId: string, status: "failed" | "refused" | "lost" | "cancelled", error: string, audit?: CodingFailureAudit): Promise<void>;
+}
+export interface CodingSessionController {
+    createSession(input: {
+        runId: string;
+        credentialRef: string;
+        protocol: ProxyProtocol;
+        allowedModels: string[];
+        deadlineAt: Date;
+        budgetUsd: number;
+    }): Promise<{
+        id: string;
+        capability: string;
+    }>;
+    cancelSession(sessionId: string): Promise<void>;
+}
+/** Plain capabilities live only for the short provisioning window. */
+export declare class RunCapabilityVault {
+    private readonly values;
+    set(runId: string, capability: string): void;
+    get(runId: string): Promise<string>;
+    delete(runId: string): void;
+}
+export interface ContainerExecutorOptions {
+    store: ContainerExecutionStore;
+    jobs: WorkspaceJobLauncher;
+    vcs: VcsProvider;
+    sessions: CodingSessionController;
+    capabilities: RunCapabilityVault;
+    artifactRoot: string;
+    workerImage: string;
+    /** Additional toolchains beyond the "node" baseline (workerImage). Keyed by toolchain, then version. */
+    additionalWorkerImages?: Record<string, Record<string, string>>;
+    credentialRef: string;
+    claudeWorkerImage?: string;
+    claudeToolRunnerImage?: string;
+    anthropicCredentialRef?: string;
+    limits: JobResourceLimits;
+    /** Operator ceiling (MiB) on CodingRun.workspaceDiskMb; see coding_workspace_disk_exceeds_limit in jobSpec. */
+    maxDiskMb: number;
+    pollMinMs?: number;
+    pollMaxMs?: number;
+    /** How often to beat the heartbeat during a long launch; defaults to a third of the reconciler's timeout. */
+    heartbeatIntervalMs?: number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    now?: () => Date;
+    observer?: CodingRunObserver;
+    /**
+     * Called after a run this process executed reaches a terminal status,
+     * so a waiting run can take the freed concurrency slot right away rather
+     * than on the next scheduler tick. Never called for a run that was queued.
+     */
+    onSlotReleased?: () => void;
+}
+export declare class ContainerExecutor implements Executor {
+    private readonly options;
+    private readonly artifactRoot;
+    private readonly active;
+    private readonly sleep;
+    private readonly now;
+    private readonly observer;
+    private readonly startedAt;
+    constructor(options: ContainerExecutorOptions);
+    start(runId: string): Promise<void>;
+    stop(runId: string, reason?: string): Promise<void>;
+    recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
+    private execute;
+    /**
+     * Runs `work` while keeping the run's heartbeat fresh.
+     *
+     * `jobs.launch` is one long await that legitimately takes minutes on a real
+     * cluster — the pod cannot be scheduled until an autoscaler has created a node
+     * for it — and nothing inside it beats the heartbeat. Meanwhile the reconciler
+     * sweeps any run whose heartbeat is older than HEARTBEAT_TIMEOUT_MS and
+     * declares it lost, which deletes the job out from under the launch that is
+     * still running. The launch then fails on its own pod having vanished, so a
+     * single healthy run produces two failures and neither names the real cause.
+     *
+     * Measured on GKE Autopilot (2026-09-23): a scheduled run whose pod was
+     * waiting on a cold gVisor node pool was declared lost at exactly 60s, and the
+     * launch it had interrupted failed 32s later with
+     * `kubernetes_isolation_unsupported:timeout`. This never appeared on kind,
+     * where a pod is scheduled in seconds and the heartbeat gap stays well inside
+     * the timeout. The gap is what is wrong, not the timeout: a run that is
+     * provisioning IS alive, and the executor is the only thing that knows it.
+     *
+     * Failures to beat are swallowed on purpose. A missed beat costs at worst the
+     * recovery this exists to prevent, while throwing here would fail a launch
+     * that is otherwise healthy.
+     */
+    private whileHeartbeating;
+    private preflight;
+    private finishTerminal;
+    private resultFor;
+    resolveCodingWorkerImage(selector: CodingImageSelector): string;
+    private requireCurrent;
+    private jobSpec;
+    private credentialRef;
+    private writeInput;
+    private artifactPath;
+    private preflightForCleanup;
+    private abandon;
+    private cleanupTerminal;
+    private emit;
+    private terminal;
+    /**
+     * `cancelled` is passed by the one caller that knows — stop(). It is never
+     * inferred from the message: `failureCategory` substring-matches, and
+     * "cancel"/"Canceled" is routine phrasing in gRPC, Kubernetes, Docker and
+     * aborted-HTTP errors ("rpc error: code = Canceled desc = context canceled"),
+     * so inferring it would silence exactly the genuine failures this log exists
+     * to surface.
+     */
+    private failure;
+    private duration;
+}
+/** Operator-facing failure text: the message plus its cause chain, redacted. */
+export declare function describeFailure(error: unknown, depth?: number): string;