@foldrun/core 0.3.0 → 0.5.0

package/dist/src/store.d.ts

@@ -1,4 +1,7 @@
+import type { BrowserPodOutcome } from "./browser-pod.ts";
 import { singleWorkspace } from "./paths.ts";
+import type { TestEffect } from "./test-mode.ts";
+import type { OperatorEvent } from "./operator.ts";
 /**
  * The frontmatter of one markdown file, as the runtime reads it. Exported
  * for the CLI: `foldrun probe` used to import gray-matter itself, which is
@@ -53,9 +56,10 @@ export declare function workspaceDir(tenant: string, workspace: string): string;
  * The account root — where `library/`, account secrets and the account-wide
  * AGENTS.md live.
  *
- * On a laptop there is no account, so it is the workspace's parent: `my-desk/`
- * sits beside `library/` and an `AGENTS.md` covering everything there. Same
- * rule libraryDir uses, so the two never disagree about where "up" is.
+ * On a laptop it is wherever `singleAccountRoot` says: the workspace's parent
+ * for a flat `my-desk/`, and the account root two levels up for a workspace
+ * inside `my-account/workspaces/`. Same rule libraryDir uses, so the two never
+ * disagree about where "up" is.
  */
 export declare function accountDir(tenant: string): string;
 /**
@@ -110,6 +114,10 @@ export declare function assertCanonicalCase(rel: string): void;
 export declare const PLATFORM_FILES: string[];
 /** True for anything the platform, not the author or the agent, writes. */
 export declare function isPlatformPath(rel: string): boolean;
+/** What a deploy keeps whatever it ships — the rule above saveWorkspace's
+ *  body. planDeploy reports removals through the same test, so a plan never
+ *  lists a file the save would keep. */
+export declare function keptOnDeploy(rel: string, shipped: ReadonlySet<string>): boolean;
 export declare function saveWorkspace(tenant: string, workspace: string, files: DeployFile[], 
 /** Attribution for the revision this save records. A deploy passes the
  *  commit, which becomes the revision's id. */
@@ -131,19 +139,25 @@ export interface McpSpec {
     url?: string;
     headers: Record<string, string>;
 }
-export type ToolDef = {
+/** `outward: true` in a tool's frontmatter: this one sends, posts, buys,
+ *  publishes or uploads. It changes nothing at run time — `check` uses it to
+ *  insist the step that grants it has a verify or a gate. */
+export type OutwardMark = {
+    outward?: boolean;
+};
+export type ToolDef = ({
     kind: "http";
     name: string;
     spec: ApiSpec;
-} | {
+} & OutwardMark) | ({
     kind: "script";
     name: string;
     spec: Record<string, unknown>;
-} | {
+} & OutwardMark) | ({
     kind: "mcp";
     name: string;
     spec: McpSpec;
-};
+} & OutwardMark);
 /**
  * The program inside a single-file script tool: the first fenced block whose
  * language tag names a runnable language. By tag, not by position — a body
@@ -167,6 +181,13 @@ export declare function fencedCodeBlock(body: string): {
     start: number;
     end: number;
 } | null;
+/**
+ * `outward: true` — this tool changes something that is not ours: it sends,
+ * posts, buys, publishes, uploads. The runtime does not treat it differently;
+ * `check` does, because the step that uses one is the step where a silent
+ * failure costs something that cannot be taken back. See `lintFlow`.
+ */
+export declare function toolIsOutward(data: Record<string, unknown>): boolean;
 export declare function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null;
 /**
  * Tools in a directory, in both shapes.
@@ -189,6 +210,19 @@ export declare function parseToolDef(data: Record<string, unknown>, fallbackName
  *
  * Flat files keep working unchanged — the shape is a migration, not a break.
  */
+/**
+ * A folder tool's `requirements.txt` and `package.json`, as a `runtime:`
+ * block. Requirement lines only: comments and blanks are left out, and so
+ * are options — whole option lines (`-r`, `--index-url`, `-e`) and the ones
+ * a requirement carries (`--hash=…`). Options never reach the installer,
+ * which takes them from the same argv as its operands; their NAMES are kept
+ * in `ignored`, never their values (an index URL can carry a password), so
+ * the build log can say what was not applied. Anything else that is not a
+ * requirement is refused later by parseRuntime with a log line, the same as
+ * it would be in tool.md. `dependencies` only — a tool's dev dependencies
+ * are its author's, not its runtime's.
+ */
+export declare function folderRuntime(folder: string): Record<string, unknown> | null;
 declare function readToolDir(dir: string, scope?: "workspace" | "account"): Record<string, ToolDef>;
 /** Definitions that exist on disk but could not be read, for the scopes an
  *  agent draws on. Empty when everything parsed. */
@@ -211,7 +245,9 @@ export interface ApiSpec {
     openapi?: string;
     /** Which of the document's operations to expose — operationIds or
      *  `"METHOD /path"` strings. Absent: every operation, capped at 60.
-     *  Present: only these, and the generic `call_<api>` tool is withheld. */
+     *  Present: only these, and the generic `call_<api>` tool is withheld —
+     *  always. If none of them resolve (document missing, moved, or an
+     *  operation renamed) the API gets no tools that run: it fails closed. */
     operations?: string[];
     /** Calls per second this API may see from one step: `count` is the burst
      *  the bucket holds, `perSec` the refill rate. `"5/s"` → {5, 5};
@@ -241,14 +277,52 @@ export interface AgentInfo {
     /** Names still written under the removed `use:` key. Nothing is granted
      *  for them; `foldrun check` and the run log say what to write instead. */
     legacyUse: string[];
+    /** Retired built-in names still in `tools:` (files, bash) — granted, but
+     *  `check` says what to write instead. */
+    retiredTools: string[];
     /** Colleagues this agent may consult mid-run (`agents:`) — each becomes a
      *  consult_<name> tool. The team's edges, as the author drew them. */
     consults: string[];
+    /** Colleagues this agent may DELEGATE to (`subagents:`) — each runs with
+     *  its own context and its own tools, no wider than this agent's. */
+    subagents: string[];
     /** The `skills:` allowlist, or null when the field is absent — which is
      *  not the same thing: absent inherits every skill in scope, an empty
      *  list withholds all of them. */
     skills: string[] | null;
     secrets: string[];
+    /** `budget:` — the most this agent may spend in ONE run, in USD, across
+     *  every step it takes in it; null is no cap. Per run and nothing else:
+     *  an agent has no calendar, the workspace and the account do. */
+    budget: number | null;
+    /** What is wrong with the `budget:` line, or null. */
+    budgetProblem: string | null;
+    /** `timezone:` — the calendar this agent works to, nearest-wins over its
+     *  flow's, its workspace's and the account's. Null inherits. */
+    timezone: string | null;
+    /** What is wrong with the `timezone:` line, or null. */
+    timezoneProblem: string | null;
+    languageProblem: string | null;
+    /** region:/currency:/units:/calendar: values that cannot be read. */
+    localeProblems: string[];
+    /** `web:` values that cannot work. The run says
+     *  so in its trail and carries on; check and deploy say so first. */
+    webProblems: string[];
+    /** `web:` that works but should change — the old `session:` key, a pinned
+     *  user agent behind the runner image's Chrome (when this process knows
+     *  that Chrome: FOLDRUN_RUNNER_ENGINES). Warnings, never refusals. */
+    webWarnings: string[];
+    /** `schedule:` written on an agent, which nothing runs — only a flow has
+     *  a clock. The message, or null when there is no such line. */
+    scheduleProblem: string | null;
+    /** `limits:` — the agent's own per-step call limits, as readable. */
+    limits: Record<string, number>;
+    /** What is wrong with the `limits:` block's shape; key-vs-grant problems
+     *  need the tool lists, and `check` adds them (limits.ts limitKeyProblems). */
+    limitProblems: string[];
+    /** Tools this agent declares inline rather than in `tools:` — `apis:`,
+     *  `scripts:` and `mcpServers:` names — which a limit may also name. */
+    inlineTools: string[];
 }
 export declare const MODEL_TIERS: Record<string, string>;
 export type Tier = keyof typeof MODEL_TIERS;
@@ -280,6 +354,11 @@ export declare function parseApis(raw: unknown): ApiSpec[];
 export interface FlowStep {
     agent: string;
     instruction: string;
+    /** The instruction was written over more than one line and the parser
+     *  joined them. It runs, but `foldrun check` says so: a wrapped
+     *  instruction is one editor keystroke away from being a paragraph of
+     *  prose the parser has to guess about. */
+    wrapped?: boolean;
     group: number;
     optional: boolean;
     /** Set when the step targets another flow (`[[flow:name]]`) instead of an agent. */
@@ -291,11 +370,14 @@ export interface FlowStep {
     effort?: string;
     /** Pause for a human before running this step. */
     approve?: boolean;
-    /** Run only if the previous results contain this text (case-insensitive).
-     *  Independent: every matching `when:` step in a group runs. */
+    /** Run only if the previous group's result has a line beginning with
+     *  this marker (case-insensitive). The previous group is the nearest
+     *  earlier one that produced a result. Independent: every matching
+     *  `when:` step in a group runs. */
     when?: string;
     /** Exclusive routing: of a group's `case:` steps, only the FIRST whose
-     *  text appears in the previous results runs; the rest are routed past. */
+     *  marker leads a line of the previous group's result runs; the rest are
+     *  routed past. */
     case?: string;
     /** The route of last resort: runs only when none of its group's `case:`
      *  steps matched. */
@@ -357,9 +439,32 @@ export interface FlowStep {
      *  cannot, and hands the value to the next group losslessly — the narrow
      *  move the grammar ADR allowed instead of variables. */
     output?: "json";
+    /** `schema:` — the JSON Schema an `output: json` value must satisfy,
+     *  written inline (one-line JSON, or a YAML block under the key) and
+     *  checked where the reply is; a value that does not fit fails the step
+     *  with the field named. */
+    schema?: Record<string, unknown> | boolean;
+    /** `schema: <path>` — the same, in a file under the workspace, read when
+     *  the step runs. */
+    schemaPath?: string;
+    /** `parallel:` — how many of an `each:` step's instances run at once.
+     *  Unset is all of them, which is what fan-out always did. */
+    parallel?: number;
+    /** `max_turns:` — the most model turns this step may take before it is
+     *  stopped, beside `budget:` (money) and `timeout:` (time). */
+    maxTurns?: number;
+    /** `limits: {web.search: 10}` — this step's call limits, over the agent's
+     *  (nearest wins per key). See limits.ts. */
+    limits?: Record<string, number>;
     /** 1-indexed line in the flow file. Diagnostics without a line make you
      *  search; every real linter emits file:line. */
     line?: number;
+    /** What is wrong with an option's VALUE, in the author's words — `timeout:
+     *  abc`, `retry: 9`, `each: columns`. The parser keeps the step (a run
+     *  still has a shape) and the lint reports each of these as an error, so
+     *  `foldrun check` fails on a value that would otherwise be read as
+     *  something the author never wrote: `timeout: 15m` used to be one second. */
+    problems?: string[];
 }
 export interface FlowInfo {
     name: string;
@@ -390,11 +495,16 @@ export interface FlowInfo {
      *  that crosses it is the last one that runs. Null: no cap of its own
      *  (the workspace's monthly `budget:` still applies). */
     budget: number | null;
+    /** What is wrong with the `budget:` line, or null. */
+    budgetProblem: string | null;
     /** `trigger: flow` — start when this other flow of the workspace finishes,
      *  with `on:` saying which endings count. The finished run's summary and
      *  result become this run's task. */
     after: string | null;
-    on: "completed" | "failed" | "any";
+    /** `blocked` is a completed run whose verdict is BLOCKED — the work
+     *  refused itself. `completed` no longer includes those: a follow-up to a
+     *  publish that did not happen should not run as if it had. */
+    on: "completed" | "failed" | "blocked" | "any";
     /** `trigger: once` — an ISO 8601 instant; fires the first tick at or after
      *  it, once, then never again. */
     at: string | null;
@@ -412,6 +522,66 @@ export interface FlowInfo {
     /** `trigger: storage` — a path prefix under storage/; a file landing
      *  there starts the flow with the path as its task. */
     path: string | null;
+    /** `idempotency:` — the name of the field that identifies a delivery, so
+     *  the same one twice starts one run. A header on the request
+     *  ("x-github-delivery"), or "body:<key>" for a top-level field of a JSON
+     *  body. A name, never an expression: the value is read from the delivery,
+     *  not computed from it. Null: every delivery is its own event. */
+    idempotency: string | null;
+    /** `debounce:` — seconds of quiet before a fired trigger becomes a run.
+     *  A burst of deliveries, storage writes or watched changes collapses into
+     *  one run once they stop. The task is the LAST event's, since that is the
+     *  state the flow is reacting to. Null: every event starts a run. */
+    debounce: number | null;
+    /** `throttle:` — the least time between two runs of this flow. A trigger
+     *  arriving inside the window is dropped, and the trace of the run that
+     *  held the window says how many. Null: no floor. */
+    throttle: number | null;
+    /** `catchup:` — what a scheduled flow does about a fire it missed while
+     *  the platform was not running. "last" is the behaviour that always
+     *  applied: one make-up run for however many were missed. "none" skips
+     *  them, for a flow whose moment has passed by the time anyone notices.
+     *  Null reads as "last". */
+    catchup: "last" | "none" | null;
+    /** `disable_after:` — consecutive failed runs after which the platform
+     *  stops firing this flow's schedule and says so. A nightly desk that has
+     *  failed all week is not going to fix itself, and every one of those runs
+     *  costs money and sends mail. Null: never quarantined. */
+    disableAfter: number | null;
+    /** `pause_when:` — a marker (DONE, NOTHING LEFT) that, leading a line of
+     *  any step's reply in the flow's latest run, pauses its schedule: the
+     *  work is finished, so firing again would only spend money saying so.
+     *  Derived from that run, like disable_after, so a run that finds work
+     *  again (a person clicking Run after adding some) lifts it by itself.
+     *  Null: never paused. */
+    pauseWhen: string | null;
+    /** `sla:` — seconds a run of this flow is expected to take. A run still
+     *  going well past it is reported once, as a notification, and keeps
+     *  running: this is a smoke alarm, not a timeout. Null: no expectation. */
+    sla: number | null;
+    /** `approvers:` — the email addresses that may decide this flow's gates,
+     *  or the single word "admins" for anyone at admin or above. Empty means
+     *  the account's existing rule: any member who can run the workspace.
+     *  Nobody may approve their own run's gate whatever this says. */
+    approvers: string[] | null;
+    /** `approve_within:` — how long a gate waits for a person before the run
+     *  is rejected and fails. A gate with no expiry holds its run, and its
+     *  place in the account's concurrency, for as long as nobody looks.
+     *  Null: it waits indefinitely, which stays the default. */
+    approveWithin: number | null;
+    /** `live: true` — this flow's runs are real even where the platform would
+     *  default them to test: in a preview workspace, and as an eval's subject.
+     *  Only ever an opt-out of the safe default, never the other way round. */
+    live: boolean;
+    /** `description:` — one line on what this flow is for, shown in listings
+     *  and the trace. Read here so a documented, scaffolded field means
+     *  something rather than sitting in every file unread. */
+    description: string | null;
+    /** Flow-level frontmatter values the parser could not read — a bad
+     *  `overlap:`/`priority:`/`catchup:`/`on:`/`signature:`, or a step line
+     *  whose `[[target]]` is malformed. Errors, the way a bad step option is,
+     *  rather than a silent default. */
+    frontProblems: string[];
     steps: FlowStep[];
 }
 export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
@@ -422,9 +592,25 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
+/** The most fan-out instances `parallel:` may run at once — the fan-out's
+ *  own hard cap, since more slots than items is no cap. */
+export declare const PARALLEL_CAP = 20;
+/** The most turns `max_turns:` may allow. A turn is one model reply, tool
+ *  calls included; a step that needs more than this is not one step. */
+export declare const MAX_TURNS_CAP = 500;
 /** "90s", "30m", "4h", "3d" — or a bare number of seconds. Clamped to 30
  *  days: a wait is a pause in a flow, not a second scheduler. */
 export declare function parseWait(value: string): number | undefined;
+/** The one duration grammar every key shares — `wait:`, `timeout:`, the
+ *  flow's `throttle:`/`debounce:`/`sla:` — as whole seconds, at least 1.
+ *  Undefined for anything that is not one: the caller says what the key
+ *  was, because "not a duration" is only useful with the line it names. */
+export declare function parseDuration(value: string): number | undefined;
+/** `timeout:` — the same units `wait:` takes, and no ceiling: the platform
+ *  sets no clock of its own, so the author's number stands as written.
+ *  `timeout: 15m` was `Math.max(1, Number("15m") || 0)` — one second — and
+ *  every step wearing it was cut off before its first tool call returned. */
+export declare function parseTimeout(value: string): number | undefined;
 /** An ISO 8601 instant (YAML may already have parsed it into a Date), or
  *  null for anything that is not one — a `once` flow with an unreadable
  *  `at:` never fires, and `foldrun check` says so. */
@@ -437,7 +623,7 @@ export declare function parseInstant(raw: unknown): string | null;
  * removed a leading OR a trailing quote independently, so a value that
  * merely *ended* with one lost it — and
  *
- *   verify: test "$(cat ../../storage/draft/published.run)" = "$FOLDRUN_RUN_ID"
+ *   verify: test "$(cat workspace/storage/draft/published.run)" = "$FOLDRUN_RUN_ID"
  *
  * reached bash unbalanced, which exited 2 with "unexpected EOF" on every
  * run. The step could never pass, whatever the agent did, and nothing said
@@ -449,7 +635,55 @@ export declare function parseInstant(raw: unknown): string | null;
  * they are two pairs, not one wrapper.
  */
 export declare function unquote(raw: string): string;
+/**
+ * Does this text carry the marker a `when:` is looking for?
+ *
+ * At the START OF A LINE, not anywhere in the prose. A plain substring
+ * search is the obvious implementation and it is wrong in a way that is
+ * very hard to see: an agent writing
+ *
+ *   There are no BLOCKED items this week.
+ *
+ * opened a `when: BLOCKED` gate, because the word is right there. Saying a
+ * marker is absent necessarily names it, so the more carefully an agent
+ * explains itself the more likely it is to trip its own condition. It bit
+ * one desk on its first run and sat latent in another.
+ *
+ * A verdict is written as a headline — the line leads with it — so leading
+ * position is what distinguishes "this is my verdict" from "here is a word
+ * I am using in a sentence". Markdown decoration in front of it is fine: a
+ * heading, a bullet or bold is still a line that leads with the marker.
+ *
+ * The marker must also END at a boundary, so BLOCKED does not match
+ * BLOCKEDBY.
+ */
+/**
+ * The path of a `when: rows of <path>` condition, or null when the condition
+ * is a marker. `rows of` is the phrase `each:` uses for the same file, so a
+ * flow reads a CSV one way in both. The whole phrase is required: a bare
+ * `when: ROWS` stays the marker it always was.
+ */
+export declare function whenRowsPath(when: string): string | null;
+export declare function markerPresent(text: string | null | undefined, marker: string): boolean;
 export declare function parseFlow(file: string, raw: string): FlowInfo;
+/** A schema written out: JSON, or YAML (parsed as frontmatter is, by the
+ *  same engine). The result must be an object — a schema is a document,
+ *  and `schema: 3` or `schema: [a, b]` describes nothing. */
+export declare function parseSchemaText(text: string): {
+    schema: Record<string, unknown> | boolean;
+} | {
+    problem: string;
+};
+/** May this person decide a gate of this flow? `approvers:` is an allowlist
+ *  of addresses plus the word "admins"; an empty list defers to whatever
+ *  permission the caller already needed to reach the route.
+ *
+ *  Self-approval is refused separately (see approvals.ts): who STARTED a run
+ *  is a property of the run, not of the flow file. */
+export declare function mayApprove(flow: Pick<FlowInfo, "approvers"> | null | undefined, who: {
+    email?: string | null;
+    role?: string | null;
+}): boolean;
 /** A live run of this flow — the fact overlap: decisions are made on. */
 export declare function flowHasLiveRun(tenant: string, workspace: string, flowName: string): boolean;
 /**
@@ -460,41 +694,29 @@ export declare function flowHasLiveRun(tenant: string, workspace: string, flowNa
  * and the diff is exactly the lines that changed. A flow with no
  * frontmatter gains the smallest one that can carry the trigger.
  */
-export declare function setFlowTrigger(raw: string, opts: {
+declare function setFlowTriggerLF(raw: string, opts: {
     trigger: FlowTrigger;
     schedule?: string;
     timezone?: string;
 }): string;
-/**
- * Rewrite one step's option lines — the board's step editor. Surgical, like
- * every flow rewrite: only the managed option lines of block `index` change;
- * the step line, its unmanaged options (approve stays the `!` marker's
- * business), other steps, comments and frontmatter survive verbatim.
- * `null` clears an option; values are clamped exactly as parseFlow reads
- * them, so what the editor writes is what the runner will do.
- */
-/**
- * Rewrite one step's instruction, and nothing else.
- *
- * The step line carries four things — the group number, the optional/approve
- * marker, the wikilink, and the instruction — and only the last is being
- * edited. Rebuilding the line from the parsed step would silently normalise
- * the other three (a "2?" becoming "2.", an en dash becoming an em dash), so
- * the prefix is taken verbatim from the file and only the tail replaced. A
- * flow's markdown stays the author's.
- */
-export declare function updateFlowStepInstruction(raw: string, index: number, instruction: string): string;
-export declare function updateFlowStep(raw: string, index: number, options: Partial<Record<"model" | "effort" | "retry" | "timeout" | "verify" | "when" | "case" | "else" | "loop" | "until" | "each" | "max", string | number | null>>): string;
-export declare function reorderFlowSteps(raw: string, groups: number[][]): string;
+declare function updateFlowStepLF(raw: string, index: number, options: Partial<Record<"model" | "effort" | "retry" | "timeout" | "verify" | "when" | "case" | "else" | "loop" | "until" | "each" | "max" | "limits", string | number | null>>): string;
 /** Append a step as its own group at the end of the flow. */
-export declare function addFlowStep(raw: string, step: {
+declare function addFlowStepLF(raw: string, step: {
     target: string;
     subflow?: boolean;
     instruction?: string;
 }): string;
-/** Drop one step, by its index in the flow's parsed steps. */
-export declare function removeFlowStep(raw: string, index: number): string;
+export declare const setFlowTrigger: (raw: string, opts: Parameters<typeof setFlowTriggerLF>[1]) => string;
+export declare const updateFlowStepInstruction: (raw: string, index: number, instruction: string) => string;
+export declare const updateFlowStep: (raw: string, index: number, options: Parameters<typeof updateFlowStepLF>[2]) => string;
+export declare const reorderFlowSteps: (raw: string, groups: number[][]) => string;
+export declare const addFlowStep: (raw: string, step: Parameters<typeof addFlowStepLF>[1]) => string;
+export declare const removeFlowStep: (raw: string, index: number) => string;
 export declare function listFlows(tenant: string, workspace: string): FlowInfo[];
+/** One flow of a workspace by name, or null. The same read listFlows makes,
+ *  named so callers that want a single flow — the approval rules, the
+ *  runner's budget stamp — do not each re-implement the directory walk. */
+export declare function readFlow(tenant: string, workspace: string, flowName: string): FlowInfo | null;
 export interface WorkspaceSummary {
     name: string;
     description: string;
@@ -642,10 +864,83 @@ export interface RunEvent {
     call?: string;
     ms?: number;
     err?: boolean;
+    /** Set on a test run's event that reports what the platform did instead
+     *  of the real thing — a refused send, a redirected email, a diverted
+     *  state write, a withheld secret. The run page lists these; the text is
+     *  still the trace's line. See test-mode.ts. */
+    effect?: TestEffect;
+    /** Set when a person was involved mid-step: a question the agent asked
+     *  (ask_person), its answer, or a message a person sent in (operator.ts). */
+    operator?: OperatorEvent;
+    /** Set on a tool event a SUB-AGENT made (`subagents:`): its name. The
+     *  trace labels the call with it; cost stays the step's. */
+    subagent?: string;
+    /** Set on an error a failed check wrote — `verify:` (its headline and its
+     *  detail), `output: json`, a schema. What the runner reads to decline a
+     *  retry of an outward step whose tools already ran. */
+    check?: boolean;
 }
+/** A question an agent asked a person while its step ran (tools: [ask]). */
+export interface StepQuestion {
+    id: string;
+    question: string;
+    options?: string[];
+    askedAt: string;
+    answer?: string;
+    answeredAt?: string;
+    by?: string | null;
+    /** true when the wait ran out with no answer. */
+    unanswered?: boolean;
+}
+/** A message a person sent into a running step, and when the agent got it. */
+export interface StepMessage {
+    text: string;
+    by?: string | null;
+    at: string;
+    deliveredAt: string;
+}
+/** One attempt of a step — see StepRecord.tries. */
+export interface StepAttempt {
+    /** Which try, 1-based, in the order they ran: a retry is the next try,
+     *  and so is the full re-run after a slim go the browser pod was lost
+     *  under. Equal to the step's attempt (`attempts` at the time) unless
+     *  `attempt` says otherwise. */
+    n: number;
+    /** The step's attempt this try belongs to, written only when it is not
+     *  `n` — after a lost slim go, its full re-run is try 2 of attempt 1. */
+    attempt?: number;
+    /** `lost`: a slim go the account's browser pod went away under, which
+     *  the step ran again on the full image within the same attempt — a row
+     *  of its own (image slim), before the full go's. */
+    status: "completed" | "failed" | "lost";
+    costUsd: number | null;
+    tokens: {
+        input: number;
+        output: number;
+    } | null;
+    computeSecs: number | null;
+    startedAt: string;
+    finishedAt: string;
+    /** The last error event this attempt wrote, when it failed. */
+    error?: string;
+    /** The runner image this attempt ended on, and — when it browsed through
+     *  the account's pod from slim — what happened to the pod: reconnects,
+     *  the re-run on full, or why it was not re-run. */
+    image?: "full" | "slim";
+    browserPod?: string;
+}
+/** The step's totals across its attempts, from the rows. Null where no
+ *  attempt reported the figure — an in-process step rents no sandbox, and
+ *  billing reads null as zero, not as "unknown, charge something". */
+export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs">;
 export interface StepRecord {
     agent: string;
     instruction: string;
+    /** Questions the agent asked a person mid-step (tools: [ask]), newest
+     *  last. One without an answer (and not `unanswered`) is still open. */
+    questions?: StepQuestion[];
+    /** Messages a person sent into the running step, as delivered. */
+    messages?: StepMessage[];
     group: number;
     optional: boolean;
     /** Carried from the flow — see FlowStep. Both are resolved at run
@@ -662,6 +957,17 @@ export interface StepRecord {
     verify?: string;
     /** Attempts made so far, for the run trace. */
     attempts?: number;
+    /**
+     * One row per attempt, oldest first: what each cost and how it ended.
+     * `costUsd`, `tokens` and `computeSecs` on the step are the SUM of these
+     * rows — a retried step spent every attempt's money, and the run's spend,
+     * the flow's `budget:` and the platform's bill all read the step's
+     * figure, so the figure is the total. Before this the step carried only
+     * the last attempt's cost and a `retry: 2` step could spend three shares
+     * of the budget while reporting one. A loop cycle that re-runs the step
+     * appends here too, so its earlier cycles are not lost from the bill.
+     */
+    tries?: StepAttempt[];
     /** The sandbox this step is executing in, while it is: which executor,
      *  its handle (a pod name), and how many of its output lines the driver
      *  has already applied to this record. What a driver that inherits the
@@ -677,6 +983,27 @@ export interface StepRecord {
     /** A size class a retry moved the step up to (an evicted or OOM-killed
      *  attempt), overriding the agent's own `size:` for the attempts after. */
     sizeUp?: "large" | "heavy";
+    /** Which runner image the step's sandbox ran: `full` (browsers in it) or
+     *  `slim`, why, and `pod` when a browsing step ran slim and browsed
+     *  through the account's browser pod. The last attempt's; absent where
+     *  the executor has one image (docker, in-process). */
+    image?: {
+        variant: "full" | "slim";
+        why?: string;
+        pod?: boolean;
+    } | null;
+    /** Slim browsing through the account's pod (browser-pod.ts): reconnect
+     *  tries and how many got through; when the pod was lost, why and what
+     *  the step had written by then; and what happened — `fallback` (the
+     *  step had only read and ran again on the full image) or `failure` (it
+     *  had written, so it was not re-run). */
+    browserPod?: (BrowserPodOutcome & {
+        fallback?: string;
+        failure?: string;
+    }) | null;
+    /** The slim go a lost browser pod ended, set aside while the step re-runs
+     *  on full; recordAttempt makes it a `lost` row of `tries` and clears it. */
+    podLostTry?: Omit<StepAttempt, "n" | "attempt" | "startedAt"> | null;
     /** When the step actually started and finished executing — not when the
      *  run reached it. A step's events approximate this (first and last), but
      *  a model can think for minutes before its first tool call, and a step
@@ -699,6 +1026,11 @@ export interface StepRecord {
     max?: number;
     /** Carried from the flow — see FlowStep. */
     output?: "json";
+    schema?: Record<string, unknown> | boolean;
+    schemaPath?: string;
+    parallel?: number;
+    maxTurns?: number;
+    limits?: Record<string, number>;
     /** The parsed JSON an `output: json` step returned. Kept beside the prose
      *  result rather than instead of it: the reply is still what a person
      *  reads on the run page, and the data is what the next step computes on. */
@@ -824,6 +1156,20 @@ export interface RunRecord {
      * simply gets its first line — which is still better than a status.
      */
     summary?: string | null;
+    /**
+     * What the run's work concluded, when its summary leads with one of the
+     * four verdict words every desk ends on: GOOD, BAD, QUIET, BLOCKED.
+     *
+     * `status` says whether the machine ran — a step crashed, a budget ran
+     * out. The verdict says what the agents found when it did. They are
+     * different facts: a publisher that checks, sees the wrong change in
+     * front of it and refuses to push has run perfectly, and its run is
+     * `completed`. Until this field, that run was a green tick beside a line
+     * reading BLOCKED (run-mu4sdg8z-1otr, 2026-09-17) — the one outcome a
+     * person most needed to see, drawn as success. Null: the summary does
+     * not lead with a verdict, and the run reads exactly as it always did.
+     */
+    verdict?: Verdict | null;
     /** The flow's per-run `budget:` at the time this run started, so the cap
      *  a run was held to is on its record rather than read from a file that
      *  may since have changed. Null: none. */
@@ -832,6 +1178,26 @@ export interface RunRecord {
      *  the agents decided was worth remembering, listed so a person can review
      *  the lesson without diffing the folder. */
     memoryWrites?: string[];
+    /** Who asked for this run, when a person did: their email address. A
+     *  schedule, a webhook and a chained flow have no one, and leave it unset.
+     *  Kept so a gate can refuse the one approval nobody should be able to
+     *  give — your own. */
+    startedBy?: string | null;
+    /** When this run's gate stops waiting, stamped the moment it parks from
+     *  the flow's `approve_within:`. A gate nobody answers by then is rejected
+     *  and the run fails, rather than holding a concurrency slot forever. */
+    approveBy?: string | null;
+    /** A test run: every step runs for real, against the real files and the
+     *  real read APIs, but nothing outward happens — sends are refused or
+     *  sunk at the egress proxy, send-capable secrets never enter the
+     *  sandbox, and state/ and storage/ writes land under this run's own
+     *  directory. On the record, not in an env var, so a script cannot turn
+     *  it off; carried onto every rerun of this run. See test-mode.ts. */
+    test?: boolean;
+    /** Digests of the emailed approval links that have already decided a
+     *  step of this run — never the tokens. A link is good once; the second
+     *  click is a 409, not a second approval. Written by approvals.ts. */
+    approvalLinksUsed?: string[];
     steps: StepRecord[];
 }
 export declare function runFilePath(tenant: string, workspace: string, runId: string): string;
@@ -878,7 +1244,81 @@ export declare function writeRun(tenant: string, workspace: string, run: RunReco
 export interface RunWithWorkspace extends RunRecord {
     workspace: string;
 }
+/**
+ * Every run in the account, newest first, off the per-workspace index.
+ *
+ * A finished run comes back as the index knows it: id, flow, status,
+ * summary, times, and each step's agent, group, status, cost, tokens,
+ * seconds, skip reason and last error — with `instruction` empty, `events`
+ * holding only that error, and `result` null. That is what every list and
+ * every rollup reads (runCost, runFailure, runDurationSecs, the usage
+ * window, the graph's stats). A run that is still live — queued, running,
+ * or parked at a gate — is read whole, because the gate's question and its
+ * events are what the approvals list shows. Anything wanting a finished
+ * run's reply or trace opens it with readRun.
+ *
+ * This used to parse every run file of every workspace on every call, and
+ * the dashboard calls it every twenty seconds per open tab.
+ */
 export declare function listAllRuns(tenant: string): RunWithWorkspace[];
+/** What a list knows about one step. */
+export interface RunSummaryStep {
+    agent: string;
+    group: number;
+    status: StepRecord["status"];
+    costUsd: number | null;
+    tokens?: {
+        input: number;
+        output: number;
+    } | null;
+    computeSecs?: number | null;
+    skipReason?: string;
+    /** The last error event, for a failed step — what runFailure reads. */
+    error?: string;
+    item?: string;
+    waitFor?: "event";
+    ask?: string;
+    /** The step's instruction, kept for a parked step so the approvals banner can show the question without the record. */
+    instruction?: string;
+    /** When a parked step last spoke — the moment the banner sorts by. */
+    waitingSince?: string;
+    startedAt?: string;
+    finishedAt?: string;
+}
+/** What a list knows about one run. */
+export interface RunSummary {
+    id: string;
+    flow: string;
+    status: RunRecord["status"];
+    summary: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    stopRequested?: boolean;
+    test?: boolean;
+    budgetUsd?: number | null;
+    tags?: string[];
+    startedBy?: string | null;
+    parkedAt?: string | null;
+    /** A step is parked for a person — what the approvals banner counts. */
+    awaitingApproval: boolean;
+    steps: RunSummaryStep[];
+}
+/** One run's row. */
+export declare function summarizeRun(run: RunRecord): RunSummary;
+/** A RunRecord with the shape a list reads and nothing else — see listAllRuns. */
+export declare function runFromSummary(s: RunSummary): RunRecord;
+/**
+ * The workspace's runs as the index knows them, newest first — the call a
+ * list makes. Reconciled against the directory on every read: rows for
+ * records that are gone are dropped, records with no row or a moved mtime
+ * are re-read, and the index is rewritten if anything changed. A missing
+ * or unreadable index is a full scan that leaves one behind.
+ */
+export declare function listRunSummaries(tenant: string, workspace: string): RunSummary[];
+/** Every workspace's runs as summaries, tagged with the workspace. */
+export declare function listAllRunSummaries(tenant: string): (RunSummary & {
+    workspace: string;
+})[];
 /**
  * The status a person should see. "failed" and "someone stopped it" are
  * different facts — the record keeps them apart (stopRequested), and the
@@ -943,6 +1383,18 @@ export declare function runFailure(run: RunRecord): {
  * runFailure, which puts the reason for a failure on the list for the same
  * reason — the sentence was in the record all along.
  */
+export declare const VERDICTS: readonly ["GOOD", "BAD", "QUIET", "BLOCKED"];
+export type Verdict = (typeof VERDICTS)[number];
+/**
+ * The verdict a headline leads with, or null. Leading, whole-word and
+ * upper-case only — "GOOD — 6 links applied", "**BLOCKED**: nothing
+ * pushed", "BAD: 3 pages dropped". A summary that merely contains the word
+ * ("no BLOCKED items") has no verdict, for the reason markerPresent gives.
+ */
+export declare function verdictOf(summary: string | null | undefined): Verdict | null;
+/** A run's verdict: recorded when it finished, else read from its summary,
+ *  so runs from before the field existed show one too. */
+export declare function runVerdict(run: Pick<RunRecord, "verdict" | "summary">): Verdict | null;
 export declare function runSummary(run: RunRecord): string | null;
 /**
  * What one step concluded, in a line.
@@ -997,6 +1449,8 @@ export interface AgentStep {
  *  step-io-model, which is the pure copy the client can import. */
 export declare function deniedPaths(step: Pick<StepRecord, "events">): number;
 export declare function listAgentSteps(tenant: string, workspace: string, agent: string): AgentStep[];
+/** Every run of the workspace, whole, newest first. Parses every record;
+ *  a list that needs only what a list needs reads listRunSummaries. */
 export declare function listRuns(tenant: string, workspace: string): RunRecord[];
 /**
  * `provider:` — which endpoint the model calls run against, and the two