@foldrun/core 0.3.0 → 0.5.0

package/dist/src/step-exec.d.ts

@@ -1,5 +1,10 @@
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import type { TestEffect } from "./test-mode.ts";
+import type { OperatorEvent } from "./operator.ts";
+import { type SubagentSpec } from "./subagents.ts";
+import { type Limits } from "./limits.ts";
+import { type BrowserPodOutcome, type ClassifyContext } from "./browser-pod.ts";
 export interface ExecOutcome {
     status: "completed" | "failed";
     result: string | null;
@@ -19,6 +24,20 @@ export interface ExecOutcome {
         inputTokens: number;
         outputTokens: number;
     } | null;
+    /** Set only when some turns ran on a different model from the step's — a
+     *  sub-agent with its own `model:`. The sum of every turn, each priced at
+     *  its own model. `usage` above is one lump and cannot be repriced at the
+     *  step's model without charging the sub-agent's turns at the wrong rate;
+     *  the runner reads this instead (repriced in runner.ts). */
+    turnsCostUsd?: number;
+    /** Why the model's last turn ended, as the SDK's result message says:
+     *  end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal or
+     *  model_context_window_exceeded. Null when no result arrived. */
+    stopReason?: string | null;
+    /** Set when the step browsed through the account's browser pod from the
+     *  slim image (ExecOptions.browserPod): its reconnects, and — when the pod
+     *  was lost — why, and what the step had written by then. */
+    browserPod?: BrowserPodOutcome;
 }
 export interface ExecOptions {
     agentDir: string;
@@ -43,6 +62,9 @@ export interface ExecOptions {
      *  The runner derives it from the flow's `budget:` and what the run has
      *  already spent; absent means no ceiling on this step. */
     budgetUsd?: number | null;
+    /** Which line set the ceiling, for the error that names it — "budget: in
+     *  the flow file" or "budget: on the <agent> agent". */
+    budgetNote?: string;
     /** Price per token for the model, when the catalogue knows it, so spend
      *  can be counted turn by turn instead of learned at the end. Without it
      *  the step prices its turns from the SDK's own running total. */
@@ -58,17 +80,77 @@ export interface ExecOptions {
     /** `output: json` — the reply must carry one JSON value; extracting it is
      *  part of finishing the step, and failing to is failing the step. */
     output?: "json";
+    /** `schema:` — what that value must look like; a value that does not fit
+     *  fails the step naming the field. See json-schema.ts. */
+    schema?: Record<string, unknown> | boolean;
+    /** `max_turns:` — the most model turns before the step is stopped. The
+     *  SDK enforces it; the step reads the result's reason and says so. */
+    maxTurns?: number;
     /** false when the caller is already an isolation boundary (a run
      *  container): the SDK's bash sandbox is then redundant and would block
      *  declared network use. Default (undefined/true) keeps it on. */
     sandboxBash?: boolean;
+    /** Has a person asked for the run to stop? Polled every couple of
+     *  seconds while the model loop runs; true interrupts it. The in-process
+     *  runner answers from the run record (stopRun writes there from another
+     *  process); a container has a sandbox that is destroyed instead. */
+    stopRequested?: () => boolean;
+    /** Reads the run's inbox (operator.ts inboxReader): what a person wrote
+     *  in while the step runs, handed to the model after its next tool call.
+     *  Absent where nobody can write in (no egress proxy). */
+    inbox?: () => Promise<string | null>;
+    /** `subagents:` — colleagues the model may delegate to, each with its own
+     *  context and tools no wider than this step's (subagents.ts). Absent or
+     *  empty: no Agent tool, as before. */
+    subagents?: SubagentSpec[];
+    /** `limits:` — the most calls this step may make, per tool and in all,
+     *  resolved host-side (account, workspace, agent, step: nearest wins per
+     *  key). Counted in the PreToolUse hook below; see limits.ts. */
+    limits?: Limits;
+    /** SDK tool name → the foldrun name it counts under, for the tools whose
+     *  SDK name does not say (limits.ts toolOwners). */
+    toolOwners?: Record<string, string>;
+    /** The step runs on the slim image and browses through the account's
+     *  browser pod (browser-pod.ts). `events` is the file the web tool writes
+     *  its reconnects to; the classify context says which API operations and
+     *  web actions are writes. A lost pod stops the step, and the outcome
+     *  says what it had written, so the runner can re-run it or fail it. */
+    browserPod?: {
+        events: string;
+    } & ClassifyContext;
     emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
 }
+/** How often the stop flag is read while a step runs. */
+export declare const STOP_POLL_MS = 2000;
+/** The least a `verify:` gets when the step used up most of its `timeout:` —
+ *  capped by the timeout itself, so the step and its check together never
+ *  run past timeout + this. Under the isolated path's backstop (+60 s). */
+export declare const VERIFY_FLOOR_MS = 30000;
+/** How long a `verify:` may run: what is left of the step's `timeout:`,
+ *  with a floor. Null when the flow set no timeout — `timeout:` is the only
+ *  clock there is, and a stop still ends the check. */
+export declare function verifyBudgetMs(timeoutSec: number | undefined, elapsedMs: number): number | null;
+/** After an interrupt is asked for, how long the model loop gets to wind
+ *  down on its own before the query is aborted outright. */
+export declare const INTERRUPT_GRACE_MS = 10000;
+/** The model loop, as executeStep needs it — the SDK's `query`, or a test's
+ *  stand-in. Only the shape the loop reads. */
+export type QueryLike = AsyncIterable<unknown> & {
+    interrupt(): Promise<unknown>;
+};
+export type QueryFn = (args: {
+    prompt: string;
+    options: Record<string, unknown>;
+}) => QueryLike;
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
 export type EventExtra = {
     call?: string;
     ms?: number;
     err?: boolean;
+    effect?: TestEffect;
+    operator?: OperatorEvent;
+    subagent?: string;
+    check?: boolean;
 };
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
@@ -101,7 +183,27 @@ export declare function priceTurn(u: Record<string, number | undefined>, price:
  * over the cap however many steps it fans out to. No budget, no ceiling.
  */
 export declare function stepCeiling(budgetUsd: number | null | undefined, spentUsd: number, launching: number): number | null;
-export declare function executeStep(opts: ExecOptions): Promise<ExecOutcome>;
+/**
+ * The ceiling a step actually runs under, and which line set it.
+ *
+ * Two caps can apply to one step: the flow's `budget:` gives it an equal
+ * share of what the run has left; the agent's own `budget:` is the most that
+ * agent may spend in one run, less what its steps in this run have cost or
+ * may still cost, shared across `sharing` — this step and the agent's steps
+ * launched with it that have not started yet. Without the share, twenty
+ * fan-out copies of one agent each got the whole remainder, because none of
+ * them has recorded a cent when the next one starts.
+ * The tighter one wins, and the note says which, because "over budget" with
+ * no line to go and raise is a message that sends someone to the wrong file.
+ */
+export declare function stepCeilingFor(flowShareUsd: number | null, agentBudgetUsd: number | null | undefined, agentSpentUsd: number, agent: string, sharing?: number): {
+    ceilingUsd: number | null;
+    note: string;
+};
+export declare function executeStep(opts: ExecOptions, 
+/** The model loop. Injected so the clock and the stop can be tested
+ *  without a model; production passes nothing and gets the SDK. */
+runQuery?: QueryFn): Promise<ExecOutcome>;
 /**
  * The one JSON value a reply carries. A ```json fence wins — it is what the
  * step was asked to write — and the LAST one at that, because a model that
@@ -143,4 +245,7 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
     /** The step's own model environment, for `judge:` — it grades on the
      *  fast tier through the same credential the step rode. */
     modelEnv?: Record<string, string | undefined>;
+    /** Ends a shell check or a judge mid-way: the step's clock ran out, or a
+     *  person asked the run to stop. */
+    signal?: AbortSignal;
 }): Promise<VerifyVerdict>;