@wardby/cli 0.5.2 → 0.6.0

package/dist/core/runner.d.ts

@@ -16,20 +16,116 @@
  * 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 type { Prisma, PrismaClient, Run, 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 { 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 { type RepoAccessGate } from "./repo-access.js";
+declare const DelegateArgs: z.ZodObject<{
+    task: z.ZodString;
+    datastoreRef: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        key: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        key: string;
+    }, {
+        name: string;
+        key: string;
+    }>>;
+    grantParentMemoryKeys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    continuePriorRun: z.ZodOptional<z.ZodString>;
+    mergeOrder: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    task: string;
+    mergeOrder?: number | undefined;
+    datastoreRef?: {
+        name: string;
+        key: string;
+    } | undefined;
+    grantParentMemoryKeys?: string[] | undefined;
+    continuePriorRun?: string | undefined;
+}, {
+    task: string;
+    mergeOrder?: number | undefined;
+    datastoreRef?: {
+        name: string;
+        key: string;
+    } | undefined;
+    grantParentMemoryKeys?: string[] | undefined;
+    continuePriorRun?: string | undefined;
+}>;
+/** 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" | "task" | "webhook" | "$transaction" | "$queryRaw" | "agentRepository" | "runModelUsage" | "runHostCheck" | "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 +134,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 +150,28 @@ 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 };
+/**
+ * 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;
@@ -102,6 +221,220 @@ 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;
+}
+/** 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. */
+export type BuiltinToolHandler = (argsJson: 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) => 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.
+ */
+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>;
+/** 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;
+    /** 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;
+}
+/** 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>;
+/** 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>;
 /**