@foldrun/core 0.2.0 → 0.4.0

package/dist/src/store.d.ts

@@ -1,4 +1,5 @@
 import { singleWorkspace } from "./paths.ts";
+import type { TestEffect } from "./test-mode.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
@@ -249,6 +250,12 @@ export interface AgentInfo {
      *  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;
 }
 export declare const MODEL_TIERS: Record<string, string>;
 export type Tier = keyof typeof MODEL_TIERS;
@@ -291,11 +298,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 +367,29 @@ 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;
     /** 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;
@@ -378,12 +408,20 @@ export interface FlowInfo {
      *  overlap) — a default that changed underfoot would surprise every flow
      *  that legitimately runs in parallel. */
     overlap: "skip" | "queue" | null;
+    /** Where this flow's runs stand in the queue against everyone else's:
+     *  "high" is claimed before the round-robin, "low" after it. Adds to the
+     *  account's own priority; the account's cap still bounds how many run
+     *  at once, so a high lane never starves the rest outright. Unset is
+     *  normal — first come, fair across accounts. */
+    priority: "high" | "normal" | "low" | null;
     /** The most one run of this flow may spend, in USD. A literal, never an
      *  expression — the cap is readable off the file, which is the property
      *  the whole grammar exists to keep. Checked between groups: the group
      *  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. */
@@ -406,6 +444,50 @@ 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;
+    /** `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;
     steps: FlowStep[];
 }
 export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
@@ -416,9 +498,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. */
@@ -443,7 +541,48 @@ 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.
+ */
+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;
 /**
@@ -489,6 +628,10 @@ export declare function addFlowStep(raw: string, step: {
 /** Drop one step, by its index in the flow's parsed steps. */
 export declare function 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;
@@ -565,6 +708,9 @@ export interface ChangeMeta {
     message?: string;
 }
 export declare function writeWorkspaceFile(tenant: string, workspace: string, rel: string, content: string, meta?: ChangeMeta): void;
+/** Tell the platform, and never let its listener fail a write. */
+declare function workspaceChanged(tenant: string, workspace: string, why: "write" | "deploy" | "push" | "delete"): void;
+export { workspaceChanged as notifyWorkspaceChanged };
 export declare function syncBundleFor(file: string, change?: "Creation" | "Update"): void;
 /**
  * Rename one editable file. Both ends pass the same gate as a write — a
@@ -633,7 +779,32 @@ 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;
 }
+/** One attempt of a step — see StepRecord.tries. */
+export interface StepAttempt {
+    /** Which attempt, 1-based: `attempts` on the step at the time. */
+    n: number;
+    status: "completed" | "failed";
+    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 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;
@@ -653,6 +824,32 @@ 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
+     *  run — after a deploy rolled the last one, or it crashed — needs to
+     *  re-attach and carry on rather than run the step again. Cleared when
+     *  the step settles. */
+    sandbox?: {
+        kind: string;
+        ref: string;
+        consumed: number;
+        since: string;
+    } | null;
+    /** 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";
     /** 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
@@ -675,6 +872,10 @@ export interface StepRecord {
     max?: number;
     /** Carried from the flow — see FlowStep. */
     output?: "json";
+    schema?: Record<string, unknown> | boolean;
+    schemaPath?: string;
+    parallel?: number;
+    maxTurns?: 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. */
@@ -808,6 +1009,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;
@@ -854,7 +1075,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
@@ -973,6 +1268,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