@wardby/cli 0.6.0 → 0.8.0

package/dist/core/runner.d.ts

@@ -17,7 +17,7 @@
  * reasons about cost, not one here plus one in the engine.
  */
 import { z } from "zod";
-import type { Prisma, PrismaClient, Run, RunTrigger } from "#prisma";
+import { Prisma, type PrismaClient, type Run, type RunTrigger } from "#prisma";
 import type { ProviderRegistry } from "../providers/index.js";
 import type { EngineProgress, EngineResult, LoadedTool } from "../providers/engine/types.js";
 import { RunOwnershipLostError, type StepRunner } from "../providers/engine/types.js";
@@ -26,64 +26,69 @@ 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>;
+/**
+ * Sub-agent dispatch uses one synthetic tool per declared child, named by the
+ * boundName it's attached
+ * under. The parent's tool call blocks until the child run reaches a
+ * terminal state, and its result comes back as this tool call's result.
+ * A run delegates at most maxDelegationsPerRun times (default one: a
+ * classifier deciding plan-vs-implement commits to exactly one child) and to
+ * each child at most once. With Agent.parallelDelegations, the delegate_to_*
+ * calls of one turn run at the same time (NativeEngine.runToolCalls); their
+ * admission (the checks below plus the child row) is still one at a time,
+ * through the run's delegation gate, and a child refused for budget while a
+ * sibling runs waits for that sibling to finish (delegation-siblings.ts).
+ *
+ * Two execution paths depending on the child's `kind`:
+ * - `native`: calls `executeRun` directly, bypassing any `Executor` — the
+ *   created Run row is never marked `executionManaged`, so the reconciler
+ *   leaves it alone even if it runs long, the same way an attended
+ *   `wardby run` foreground execution does. Fast, in-process, no durability
+ *   machinery needed for a native turn loop.
+ * - `coding`: a coding-kind child needs a real Docker container (Codex),
+ *   which `executeRun` explicitly refuses to drive itself. Goes through
+ *   `dispatchRun` (the same persistence path webhooks/trigger_agent use)
+ *   with `awaitExecution: true`, so the already-existing `RoutingExecutor`
+ *   sends it to the container backend and this call blocks until it's
+ *   terminal — reusing proven infrastructure rather than re-implementing
+ *   container dispatch. Marked `executionManaged: true` here (unlike the
+ *   native path) since a long-running container crash mid-dispatch is
+ *   exactly the case the reconciler exists for. Under the coding
+ *   concurrency cap `Executor.start` can resolve with the child merely
+ *   queued (still pending), so the call then polls the child row until it
+ *   is terminal — see `waitForCodingChild`.
+ *
+ * The `delegate_to_` prefix lives in core/tool-names.ts, which reserves it
+ * so no user tool can be created under a name this dispatch would shadow.
+ */
+export declare function delegateToolDef(boundName: string, parallel: boolean, repositories?: readonly string[]): LoadedTool;
 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">>;
+    }, z.core.$strict>>;
+    grantParentMemoryKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
     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;
-}>;
+    repository: z.ZodOptional<z.ZodString>;
+}, 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;
@@ -95,6 +100,8 @@ declare const DELEGATION_CHILD_SELECT: {
         readonly select: {
             readonly allowWebhookTaskOverride: true;
             readonly timeoutSec: true;
+            readonly repository: true;
+            readonly baseRef: true;
         };
     };
 };
@@ -125,7 +132,7 @@ export declare function nativeChildResult(run: Pick<Run, "status" | "finalText"
  * 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" | "deferredReview" | "runAttribution">;
+export type RunnerDb = Pick<PrismaClient, "agent" | "run" | "agentTool" | "agentSecret" | "agentMcpServer" | "secret" | "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"];
@@ -152,6 +159,38 @@ export declare class RunCancelledError extends Error {
 }
 /** 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
@@ -192,10 +231,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;
@@ -204,7 +245,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
@@ -243,8 +289,6 @@ export interface LoadNativeRunOptions {
  * 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;
@@ -256,6 +300,7 @@ export declare function loadNativeRun(options: LoadNativeRunOptions): Promise<{
     tools: LoadedTool[];
     toolsByName: {
         [k: string]: {
+            timeoutMs?: number | undefined;
             code: string;
             paramsZod: string;
             allowedSecrets: string[];
@@ -264,6 +309,9 @@ export declare function loadNativeRun(options: LoadNativeRunOptions): Promise<{
             allowedSharedDatastorePrefixes: Record<string, string[]>;
         };
     };
+    mcpTools?: import("./mcp-tools.js").McpToolPin[] | undefined;
+    repositoryLinks: RepositoryLink[];
+    issueProjectLinks: IssueProjectLink[];
     parallelDelegations?: boolean | undefined;
     maxDelegationsPerRun?: number | undefined;
     agentId: string;
@@ -290,11 +338,26 @@ export interface NativeRunToolsOptions {
     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;
+    /** A sandboxed run's session deadline (the gateway's); an MCP tool call never runs past it. */
+    deadlineAt?: Date;
 }
 /** 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>;
+/**
+ * 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,
@@ -304,6 +367,7 @@ export type BuiltinToolHandler = (argsJson: string) => Promise<string>;
  */
 export declare function createNativeRunTools(options: NativeRunToolsOptions): {
     toolsByName: Map<string, {
+        timeoutMs?: number | undefined;
         code: string;
         paramsZod: string;
         allowedSecrets: string[];
@@ -315,7 +379,14 @@ export declare function createNativeRunTools(options: NativeRunToolsOptions): {
     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>;
+    runSandboxTool: (name: string, argsJson: string, callId?: string) => Promise<string>;
+    toolTimeoutMs: (name: string) => number | undefined;
+    watchStop: () => {
+        signal: AbortSignal;
+        done: () => void;
+    };
+    /** Every secret value of the agent's attached MCP servers (never handed to a worker; redaction only). */
+    mcpSecretValues: () => Promise<string[]>;
 };
 /**
  * Live progress for observers (MCP get_run, the viewer). Absolute totals, so a DBOS replay
@@ -323,6 +394,8 @@ export declare function createNativeRunTools(options: NativeRunToolsOptions): {
  * 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. */
@@ -338,6 +411,19 @@ export interface NativeRunFinishContext {
 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>;
+/** How often a user tool call in progress checks whether its run was stopped. */
+export declare const TOOL_STOP_POLL_MS = 2000;
+/**
+ * Aborts `signal` once the run is no longer drivable (stop_run, a cancelled task, a parent's
+ * stop). Polls every `intervalMs`, starting one interval in, so a quick call reads nothing; a
+ * failed read changes nothing and the next tick reads again. `done()` stops the polling.
+ */
+export declare function watchRunStop(db: RunnerDb, runId: string, intervalMs?: number): {
+    signal: AbortSignal;
+    done: () => void;
+};
 /** 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>;
 /**
@@ -347,7 +433,7 @@ export declare function runDrivability(db: RunnerDb, runId: string): Promise<Run
  */
 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 type DelegationLedger = Pick<PrismaGatewayLedger, "claim" | "recordResult" | "setDelegation" | "delegation" | "waitingDelegations">;
 export interface DurableDelegationContext {
     runId: string;
     existingRun: Run;
@@ -357,6 +443,8 @@ export interface DurableDelegationContext {
     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;
@@ -406,6 +494,8 @@ export type SandboxSessionOutcome = {
     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). */
  | {
@@ -431,6 +521,12 @@ export declare function createSandboxSession(options: {
      */
     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. */