@wardby/cli 0.5.3 → 0.7.0

package/dist/core/runner.d.ts

@@ -16,20 +16,96 @@
  * down) lives inside the engine now — there is exactly one place that
  * reasons about cost, not one here plus one in the engine.
  */
-import type { PrismaClient, Run, RunTrigger } from "#prisma";
+import { z } from "zod";
+import { Prisma, type PrismaClient, type Run, type RunTrigger } from "#prisma";
 import type { ProviderRegistry } from "../providers/index.js";
-import { type StepRunner } from "../providers/engine/types.js";
+import type { EngineProgress, EngineResult, LoadedTool } from "../providers/engine/types.js";
+import { RunOwnershipLostError, type StepRunner } from "../providers/engine/types.js";
+import { type PrivilegedHost } from "../sandbox/host-functions.js";
+import type { safeFetch } from "../sandbox/safe-fetch.js";
+import { type RunDrivability, type WorkerLauncher } from "../native-worker/gateway.js";
+import { type WorkerInput } from "../native-worker/protocol.js";
+import type { PrismaGatewayLedger } from "../native-worker/ledger.js";
+import { type SecretsAccessor } from "./secrets.js";
 import type { Executor } from "../providers/executor/types.js";
 import type { ReviewHostRegistry } from "../providers/review-host/types.js";
 import type { IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+import { type RepositoryLink } from "./review-host-tools.js";
+import { type IssueProjectLink } from "./issue-tracker-tools.js";
+import { ReviewReadLedger } from "./review-reads.js";
 import { type RepoAccessGate } from "./repo-access.js";
+import { type BudgetEventView } from "./budget-events.js";
+export declare const runnerLog: import("pino").Logger<never, boolean>;
+declare const DelegateArgs: z.ZodObject<{
+    task: z.ZodString;
+    datastoreRef: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        key: z.ZodString;
+    }, z.core.$strict>>;
+    grantParentMemoryKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    continuePriorRun: z.ZodOptional<z.ZodString>;
+    mergeOrder: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** A delegate_to_* call's arguments, or the tool result refusing them. */
+export declare function parseDelegateArgs(argsJson: string): {
+    args: z.infer<typeof DelegateArgs>;
+} | {
+    refusal: string;
+};
+/**
+ * At most `limit` dispatches per run (default one: a classifier deciding plan-vs-implement
+ * commits to exactly one child), and never the same child twice, so a retry can't leave two
+ * children racing on the same task. A delegation waiting for budget holds its place.
+ */
+export declare function delegationLimitRefusal(input: {
+    priorChildAgentIds: readonly string[];
+    waitingChildAgentIds: readonly string[];
+    childAgentId: string;
+    boundName: string;
+    limit: number;
+}): string | null;
+declare const DELEGATION_CHILD_SELECT: {
+    readonly id: true;
+    readonly kind: true;
+    readonly budgetGroupId: true;
+    readonly budgetUsd: true;
+    readonly ownerId: true;
+    readonly nativeExecutionMode: true;
+    readonly codingProfile: {
+        readonly select: {
+            readonly allowWebhookTaskOverride: true;
+            readonly timeoutSec: true;
+        };
+    };
+};
+/** The child agent fields a delegation decides on. */
+export type DelegationChildAgent = Prisma.AgentGetPayload<{
+    select: typeof DELEGATION_CHILD_SELECT;
+}>;
+/**
+ * The live authorization of one delegation, and the child agent as it is now. Owners are re-read
+ * on every delegation (resource-sharing grants spec §3.4.4, N1): the child must have the parent's
+ * current owner, or that owner must still hold execute on the child. A revoked grant or a
+ * make_owner transfer stops the very next call.
+ */
+export declare function authorizeDelegation(db: RunnerDb, parentAgentId: string, edge: {
+    childAgentId: string;
+}, boundName: string, args: z.infer<typeof DelegateArgs>): Promise<{
+    refusal: string;
+} | {
+    childAgent: DelegationChildAgent;
+}>;
+/** A native child's task text: the delegated task, with any datastore reference as a note. */
+export declare function delegationTaskOverride(args: z.infer<typeof DelegateArgs>): string | undefined;
+/** The tool result a native child's terminal run reports to its parent. `note` surfaces e.g. an ignored mergeOrder. */
+export declare function nativeChildResult(run: Pick<Run, "status" | "finalText" | "costUsd" | "tokensIn" | "tokensOut" | "error">, note?: string): string;
 /**
  * The subset of the Prisma client the runner touches — mockable in tests.
  * Includes `codingRun`/`task`/`webhook`/`$transaction`/`$queryRaw` so this
  * also satisfies `dispatch.ts`'s `DispatchDb`, needed for dispatching a
  * coding-kind sub-agent from inside a running native turn loop.
  */
-export type RunnerDb = Pick<PrismaClient, "agent" | "run" | "agentTool" | "agentSecret" | "agentDatastore" | "budgetGroup" | "agentSubAgent" | "resourceGrant" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw" | "agentRepository" | "runModelUsage" | "runHostCheck" | "runHostStatus" | "hostIdentity" | "agentIssueProject" | "issuePullRequest" | "runIssueStatus" | "issueFingerprint" | "workItem">;
+export type RunnerDb = Pick<PrismaClient, "agent" | "run" | "agentTool" | "agentSecret" | "agentDatastore" | "budgetGroup" | "agentSubAgent" | "resourceGrant" | "codingRun" | "registryFetch" | "registryAuditRecord" | "task" | "webhook" | "$transaction" | "$queryRaw" | "agentRepository" | "runModelUsage" | "runHostCheck" | "runBudgetEvent" | "runHostStatus" | "hostIdentity" | "agentIssueProject" | "issuePullRequest" | "runIssueStatus" | "issueFingerprint" | "workItem" | "deferredReview" | "runAttribution">;
 /** The providers a native run needs; `executor`, `reviewHosts` and `issueTrackers` are optional capabilities. */
 export type NativeRunProviders = Pick<ProviderRegistry, "llm" | "engine" | "datastore" | "secrets" | "memory"> & {
     executor?: ProviderRegistry["executor"];
@@ -38,6 +114,13 @@ export type NativeRunProviders = Pick<ProviderRegistry, "llm" | "engine" | "data
     issueTrackers?: IssueTrackerRegistry;
     /** Repository authorization for repo_* calls; built from reviewHosts when absent. */
     repoAccess?: RepoAccessGate;
+    /**
+     * Runs sandbox-mode native runs: the engine runs in a worker this launcher starts, served by the
+     * native gateway (src/native-worker). Absent: a run whose snapshot says sandbox fails closed.
+     */
+    nativeSandbox?: WorkerLauncher;
+    /** Overrides the sandbox's outbound network call — tests only. */
+    sandboxFetch?: typeof safeFetch;
 };
 /**
  * Raised when a run's step boundary observed a cancellation (DbosExecutor's
@@ -47,12 +130,60 @@ export type NativeRunProviders = Pick<ProviderRegistry, "llm" | "engine" | "data
 export declare class RunCancelledError extends Error {
     constructor(message: string);
 }
+/** Re-exported beside RunCancelledError: thrown by a step runner when another attempt owns the run. */
+export { RunOwnershipLostError };
+/** Options for a durable executor's use of stopAwareStep (DbosExecutor); inline runs pass none. */
+export interface StopAwareStepOptions {
+    /**
+     * A failed read lets the step run, so the check adds no new way for a run to fail. The cost: in an
+     * attempt that is already superseded, a step whose read fails still runs (at most that one step,
+     * since the next read that succeeds fences it).
+     */
+    failOpen?: boolean;
+    /**
+     * Fences an attempt whose workflow the run has moved off. When the run's `executionWorkflowId`
+     * was forked from the workflow driving this attempt (a takeover recorded its fork), this attempt
+     * no longer owns the run and stops with a RunOwnershipLostError: no terminal write, no settle side
+     * effects. Only a fork *of this workflow* fences it: a null id, or an older id (a fork of a fork
+     * whose own id is not recorded yet, or failed to record), fences nothing, so a takeover's fork is
+     * never fenced out of the run it drives.
+     */
+    ownership?: {
+        /** The workflow driving this attempt, read when the step is called. */
+        workflowId: () => string | undefined;
+        /** Whether `recorded` was forked, directly or through further forks, from `own`. */
+        forkedFrom: (recorded: string, own: string) => boolean;
+    };
+}
+/**
+ * A step runner made to notice a stop. Before each step this reads the run's own row: once anything
+ * else has made it terminal (stop_run, an MCP task's cancel, a parent run's stop, the reconciler),
+ * the run stops at this boundary with a RunCancelledError. The terminal row is never rewritten
+ * (finishRunClaimed matches zero rows), so the stop keeps its reason. Inline runs need it because
+ * nothing else interrupts their steps. DbosExecutor wraps its own step runner in it too: DBOS stops
+ * only a workflow it was told to cancel, and stop() can name only the workflow the run records.
+ */
+export declare function stopAwareStep(db: Pick<RunnerDb, "run">, runId: string, inner?: StepRunner, options?: StopAwareStepOptions): StepRunner;
+/**
+ * Why a sandbox-mode native run is not executed here. The runner only ever
+ * executes native runs in the control plane; a run whose snapshot says
+ * `sandbox` reaches it only when no native sandbox executor is composed in
+ * (RoutingExecutor sends it to the native executor), and must fail closed
+ * rather than run unisolated.
+ */
+export declare const NATIVE_SANDBOX_NOT_CONFIGURED: string;
 /**
  * Slack past the child's own queue wait + container deadline before the
  * parent gives up: the executor needs a moment after a deadline kill to
  * write the terminal row, and the queue timeout only fires on a drain tick.
  */
 export declare const CODING_CHILD_WAIT_GRACE_SEC = 60;
+/**
+ * How long a parent waits for a sandbox-mode native child before stopping it. Native runs have
+ * no run timeout of their own; until the sandbox executor brings a per-run deadline, this bounds
+ * a parent left waiting on a child that never finishes.
+ */
+export declare const SANDBOX_CHILD_WAIT_SEC: number;
 export type CodingChildWaitOutcome = {
     kind: "terminal";
     run: Run;
@@ -73,10 +204,12 @@ export interface WaitForCodingChildOptions {
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
 }
+/** The leading snake_case code of an error message (`code: sentence`); messages can carry internals. */
 /**
  * What a coding sub-agent's run tells the parent run's model. A run refused
  * over its services carries the host sentence (never the raw Run.error), so
- * the parent can pass it on — for a mention, that is the requester.
+ * the parent can pass it on — for a mention, that is the requester. A failed
+ * run carries only its error code, so the parent can say why without seeing internals.
  */
 export declare function codingChildResult(run: {
     status: string;
@@ -85,7 +218,12 @@ export declare function codingChildResult(run: {
     tokensIn: number;
     tokensOut: number;
     error: string | null;
-}, codingResult?: unknown): string;
+}, codingResult?: unknown, 
+/** The child's recorded budget refusal (loadBudgetEvent), if any. */
+budgetEvent?: {
+    event: BudgetEventView;
+    agentName: string;
+} | null): string;
 /**
  * Polls a dispatched coding child until it reaches a terminal status. Needed
  * because a queued child (every concurrency slot taken) makes Executor.start
@@ -102,6 +240,247 @@ export declare function codingChildResult(run: {
 export declare function waitForCodingChild(options: WaitForCodingChildOptions): Promise<CodingChildWaitOutcome>;
 /** Persists a new pending Run for the named agent. Throws if the agent is unknown. */
 export declare function createRun(db: RunnerDb, agentName: string, trigger?: RunTrigger): Promise<Run>;
+export interface LoadNativeRunOptions {
+    runId: string;
+    existingRun: Run;
+    providers: NativeRunProviders;
+    db: RunnerDb;
+    step: StepRunner;
+    reviewHosts: ReviewHostRegistry | undefined;
+    issueTrackers: IssueTrackerRegistry | undefined;
+}
+/**
+ * The trusted load of a native run: the agent, its attached tools and their
+ * consented capabilities, the pinned catalog entry, the effective budget,
+ * sub-agent edges, and repository/issue links. Shared by in-process execution
+ * and the native sandbox gateway, which hands the worker this result.
+ *
+ * Pinned in one checkpointed step: on replay after a crash, the agent row
+ * or its budget group may have changed since first execution. The
+ * engine's control flow depends on budgetUsd and maxTurns, so they must
+ * be pinned to the values seen on first execution or the replay's step
+ * order diverges from the record.
+ */
+export declare function loadNativeRun(options: LoadNativeRunOptions): Promise<{
+    repositoryLinks: RepositoryLink[];
+    issueProjectLinks: IssueProjectLink[];
+    agent: {
+        untrustedContext?: string | undefined;
+        effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        systemPrompt: string;
+        model: string;
+        budgetUsd: number;
+        maxTurns: number;
+    };
+    tools: LoadedTool[];
+    toolsByName: {
+        [k: string]: {
+            code: string;
+            paramsZod: string;
+            allowedSecrets: string[];
+            allowedDatastorePrefixes: string[];
+            allowedHosts: string[];
+            allowedSharedDatastorePrefixes: Record<string, string[]>;
+        };
+    };
+    parallelDelegations?: boolean | undefined;
+    maxDelegationsPerRun?: number | undefined;
+    agentId: string;
+    kind: import("#prisma").AgentKind;
+    pricing: import("./run-pricing.js").PinnedPricing | undefined;
+    memoryEnabled: boolean;
+    subAgentEdges: {
+        boundName: string;
+        childAgentId: string;
+    }[];
+} | {
+    readonly unavailable: string;
+}>;
+/** A loaded native run (loadNativeRun without its model-unavailable outcome). */
+export type LoadedNativeRun = Exclude<Awaited<ReturnType<typeof loadNativeRun>>, {
+    unavailable: string;
+}>;
+export interface NativeRunToolsOptions {
+    runId: string;
+    existingRun: Run;
+    loaded: LoadedNativeRun;
+    providers: NativeRunProviders;
+    db: RunnerDb;
+    reviewHosts: ReviewHostRegistry | undefined;
+    repoAccess: RepoAccessGate | undefined;
+    issueTrackers: IssueTrackerRegistry | undefined;
+    /** What earlier requests of this run read (a sandbox run's gateway restores it per request); fresh otherwise. */
+    reviewReads?: ReviewReadLedger;
+}
+/** An attached user tool as the load step pinned it: its code, schema, and consented capabilities. */
+export type LoadedUserTool = LoadedNativeRun["toolsByName"][string];
+/**
+ * A built-in tool's handler for one call; built-ins run on the trusted side, never in a sandbox.
+ * `callId` is the model's id for the tool call, when the caller has one: a delegation keys its
+ * child on it (Run.parentCallId), so a re-executed call re-attaches instead of dispatching twice.
+ */
+export type BuiltinToolHandler = (argsJson: string, callId?: string) => Promise<string>;
+/**
+ * Every value of the secrets `names` (readable or brokered; a SigV4 secret's key and token alone
+ * too, the same set the in-process host redacts), as a redaction list. Rejects when ANY read
+ * fails: a list missing one secret would let that secret through, so a caller treats a rejection
+ * as "no list" and fails closed. A secret with no value contributes nothing.
+ */
+export declare function readRedactionValues(accessor: SecretsAccessor, names: readonly string[]): Promise<string[]>;
+/**
+ * One attempt's tool surface for a native run. `builtinHandler(name)` is the
+ * single source of truth for which names are trusted built-ins (memory,
+ * repo_*, jira_*, sub-agent/parent memory, delegate_to_*) and returns undefined
+ * for everything else, which `runUserTool` runs in the WASM sandbox. Per-attempt
+ * state (the delegation gate, siblings, issue creation counters) lives here.
+ */
+export declare function createNativeRunTools(options: NativeRunToolsOptions): {
+    toolsByName: Map<string, {
+        code: string;
+        paramsZod: string;
+        allowedSecrets: string[];
+        allowedDatastorePrefixes: string[];
+        allowedHosts: string[];
+        allowedSharedDatastorePrefixes: Record<string, string[]>;
+    }>;
+    builtinHandler: (name: string) => BuiltinToolHandler | undefined;
+    privilegedHostFor: (name: string, signal: AbortSignal, redactSecretValues?: readonly string[]) => PrivilegedHost | undefined;
+    readableSecretValues: (name: string) => Promise<string[]>;
+    runUserTool: (name: string, argsJson: string) => Promise<string>;
+    runSandboxTool: (name: string, argsJson: string, callId?: string) => Promise<string>;
+};
+/**
+ * Live progress for observers (MCP get_run, the viewer). Absolute totals, so a DBOS replay
+ * re-writing them is harmless. Written into the run's own cost columns on purpose: the run
+ * tree's shared budget (computeRunTreeSpend) then counts a running parent's spend so far, as it
+ * already does for coding runs, whose proxy ledger writes their totals live. Best-effort: a
+ * failed write only delays what observers see, and finishRun writes the final totals anyway.
+ * A cancelled run takes them too: a stop lands mid-step, and that step's spend is real, while the
+ * cancelled run's terminal write (failNativeRun) records no totals of its own.
+ */
+export declare function recordNativeRunProgress(db: RunnerDb, runId: string, progress: EngineProgress): Promise<void>;
+/** What finishing a native run needs: the run, and the integrations its trigger may have opened. */
+export interface NativeRunFinishContext {
+    runId: string;
+    db: RunnerDb;
+    providers: NativeRunProviders;
+    reviewHosts: ReviewHostRegistry | undefined;
+    repoAccess: RepoAccessGate | undefined;
+    issueTrackers: IssueTrackerRegistry | undefined;
+}
+/** The terminal write for an engine result, then its usage, host/issue status, and follow-ups. */
+export declare function finishNativeRun(ctx: NativeRunFinishContext, model: string, result: EngineResult): Promise<Run>;
+/** The backstop terminal write for a run that threw. A cancellation is not a failure: it carries the operator's own reason. */
+export declare function failNativeRun(ctx: NativeRunFinishContext, err: unknown): Promise<Run>;
+/** The terminal write for a run that cannot continue (it ends `lost` with `reason`), then the same settle path. */
+export declare function loseNativeRun(ctx: NativeRunFinishContext, reason: string): Promise<Run>;
+/** Where a run stands for the native gateway: still drivable, cancelled (its task), or otherwise ended. */
+export declare function runDrivability(db: RunnerDb, runId: string): Promise<RunDrivability>;
+/**
+ * What a sandbox worker is given: the pinned agent and tool definitions, which names are built-ins
+ * (served by the gateway), and each user tool's code and schema only — never its capabilities,
+ * secret names, or values, which stay with the gateway's privileged host.
+ */
+export declare function sandboxWorkerInput(runId: string, loaded: LoadedNativeRun, tools: Pick<ReturnType<typeof createNativeRunTools>, "builtinHandler" | "toolsByName">): WorkerInput;
+/** What the durable delegation needs from the gateway ledger (src/native-worker/ledger.ts). */
+export type DelegationLedger = Pick<PrismaGatewayLedger, "claim" | "recordResult" | "setDelegation" | "delegation" | "waitingChildAgentIds">;
+export interface DurableDelegationContext {
+    runId: string;
+    existingRun: Run;
+    loaded: LoadedNativeRun;
+    providers: NativeRunProviders;
+    db: RunnerDb;
+    issueTrackers: IssueTrackerRegistry | undefined;
+    ledger: DelegationLedger;
+    sessionId: string;
+    /** Every secret value the run can read, to redact its logs by exact value (unset or failing: nothing is logged of an error but its name and code). */
+    secretValues?: () => Promise<string[]>;
+    /** How long one call waits on the child before answering `pending` (the worker calls again). */
+    pollWindowMs?: number;
+    pollIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export type DurableDelegationOutcome = {
+    result: string;
+} | {
+    pending: true;
+};
+/** Long-poll window: well under common proxy and load-balancer idle timeouts. */
+export declare const DELEGATION_POLL_WINDOW_MS = 20000;
+/**
+ * A delegate_to_* call from a sandboxed run, served by the native gateway. The in-process branch
+ * holds its admission, budget wait, and child wait in one process's memory for the child's whole
+ * life; this one keeps them on the call's ledger row, so the worker can call again with the same
+ * callId — on any control-plane replica, before or after a restart — and continue where it was:
+ *
+ * - every child, native or coding, is a managed run dispatched through dispatchRun and the
+ *   Executor (never inline: an inline child dies with the replica, and the reconciler does not
+ *   reap unmanaged runs);
+ * - admission re-checks the per-run delegation limit under a run-scoped advisory lock inside the
+ *   child's own transaction, so parallel delegations on different replicas cannot exceed it;
+ * - a delegation the budget would refuse while sibling children still run is recorded as waiting
+ *   and re-evaluated on each call (parallelDelegations), up to the same bound as in process;
+ * - each call waits on the child row up to `pollWindowMs`, then answers `pending`.
+ *
+ * Every refusal and result uses the same helpers, and so the same messages, as in process.
+ */
+export declare function durableDelegate(ctx: DurableDelegationContext, callId: string, name: string, argsJson: string): Promise<DurableDelegationOutcome>;
+/** The integrations a native run uses, as executeRun derives them from its providers. */
+export declare function nativeRunIntegrations(providers: NativeRunProviders, db: RunnerDb): {
+    reviewHosts: Partial<Record<import("../providers/review-host/types.js").ReviewHostProvider, import("../providers/review-host/types.js").CodeReviewHost>> | undefined;
+    repoAccess: RepoAccessGate | undefined;
+    issueTrackers: Partial<Record<"jira", import("../providers/issue-tracker/types.js").IssueTracker>> | undefined;
+};
+/** How long a sandbox run's gateway session (and so its capability) stays valid. */
+export declare const SANDBOX_RUN_MAX_SEC: number;
+/** What a sandbox session pins: the worker's input (without its capability) and the trusted load. */
+export interface SandboxSessionSnapshot {
+    input: WorkerInput;
+    loaded: LoadedNativeRun;
+}
+export type SandboxSessionOutcome = {
+    kind: "started";
+    input: WorkerInput;
+    capability: string;
+    sessionId: string;
+    /** Every secret value the run's user tools may read, read on demand (never stored); rejects when any read fails. */
+    secretValues: () => Promise<string[]>;
+}
+/** The run ended before a worker was needed (already terminal, or failed at load). */
+ | {
+    kind: "ended";
+    run: Run;
+};
+/**
+ * Starts a sandbox-mode run's trusted half: loads and pins the run, marks it running, records its
+ * gateway session (capability hash, deadline, budget, snapshot), and records `native-sandbox` as
+ * its execution backend — all before any worker exists. The caller launches the worker with the
+ * returned input, which carries the gateway URL and the one-time capability.
+ */
+export declare function createSandboxSession(options: {
+    runId: string;
+    providers: NativeRunProviders;
+    db: RunnerDb;
+    ledger: Pick<PrismaGatewayLedger, "createSession">;
+    gatewayUrl: string;
+    now?: Date;
+    /**
+     * Whether the worker's network isolation exists before the worker does (Docker's internal
+     * network). False (Kubernetes): the gateway refuses calls until the launcher proves it.
+     */
+    networkReady?: boolean;
+}): Promise<SandboxSessionOutcome>;
+/**
+ * Every secret value the sandbox run's user tools `names` may read (readable or brokered): what its
+ * worker can be handed, so what the gateway checks its cause codes against and a launcher masks
+ * from the worker's output tail. Rejects when any read fails (readRedactionValues).
+ */
+export declare function userToolSecretValues(tools: Pick<ReturnType<typeof createNativeRunTools>, "readableSecretValues">, names: readonly string[]): Promise<string[]>;
+/** Run.executionBackend for a sandbox-mode run whose worker is (or was) launched. */
+export declare const NATIVE_SANDBOX_BACKEND = "native-sandbox";
+/** The stored form of a sandbox capability: never the token itself. */
+export declare function sandboxCapabilityHash(capability: string): string;
 /** Drives an existing Run (created by `createRun` or the scheduler) to a terminal state. */
 export declare function executeRun(runId: string, providers: NativeRunProviders, db?: RunnerDb, onText?: (delta: string) => void, step?: StepRunner): Promise<Run>;
 /**