@foldrun/core 0.4.0 → 0.6.0

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

@@ -1,6 +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;
@@ -20,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;
@@ -77,10 +95,41 @@ export interface ExecOptions {
      *  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;
@@ -99,6 +148,9 @@ export type EventExtra = {
     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
@@ -136,11 +188,15 @@ export declare function stepCeiling(budgetUsd: number | null | undefined, spentU
  *
  * 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 earlier steps in this run cost.
+ * 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): {
+export declare function stepCeilingFor(flowShareUsd: number | null, agentBudgetUsd: number | null | undefined, agentSpentUsd: number, agent: string, sharing?: number): {
     ceilingUsd: number | null;
     note: string;
 };
@@ -189,4 +245,18 @@ 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>;
+/**
+ * The environment an Agent SDK session starts with: the step's, minus the
+ * connectors of whoever is signed in to claude.ai on this machine. Claude
+ * Code loads an account's claude.ai MCP servers (Docs, Drive, …) unless told
+ * not to, and `settingSources: []` does not reach them — they come with the
+ * login, not from a settings file. A local `foldrun run` handed every agent
+ * the person's own connectors: the hello template's agents reported that
+ * "the only tools I have are the Claude Docs ones". `strictMcpConfig` keeps
+ * the rest of the on-disk MCP configuration out; this keeps the account's.
+ */
+export declare function sdkEnv(base: Record<string, string | undefined> | undefined, extra?: Record<string, string>): Record<string, string | undefined>;