@foldrun/core 0.4.0 → 0.6.0

package/dist/src/store.d.ts

@@ -1,5 +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
@@ -54,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;
 /**
@@ -111,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. */
@@ -132,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
@@ -168,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.
@@ -190,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. */
@@ -212,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};
@@ -242,9 +277,15 @@ 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. */
@@ -256,6 +297,32 @@ export interface AgentInfo {
     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;
@@ -287,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. */
@@ -381,6 +453,9 @@ export interface FlowStep {
     /** `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;
@@ -426,7 +501,10 @@ export interface FlowInfo {
      *  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;
@@ -470,6 +548,13 @@ export interface FlowInfo {
      *  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. */
@@ -488,6 +573,15 @@ export interface FlowInfo {
      *  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"];
@@ -529,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
@@ -563,6 +657,13 @@ export declare function unquote(raw: string): string;
  * 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
@@ -593,40 +694,24 @@ 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
@@ -784,12 +869,50 @@ export interface RunEvent {
      *  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 attempt, 1-based: `attempts` on the step at the time. */
+    /** 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;
-    status: "completed" | "failed";
+    /** 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;
@@ -800,6 +923,11 @@ export interface StepAttempt {
     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
@@ -808,6 +936,11 @@ export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "co
 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
@@ -850,6 +983,31 @@ 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;
+    /** Which model credential the step ran on, by its variable — "API key
+     *  (ANTHROPIC_API_KEY)", "Claude login token (CLAUDE_CODE_OAUTH_TOKEN)",
+     *  "provider: …" — or "none set" (model-credential.ts). */
+    credential?: string;
+    /** 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
@@ -876,6 +1034,7 @@ export interface StepRecord {
     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. */
@@ -1001,6 +1160,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. */
@@ -1214,6 +1387,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.