@foldrun/core 0.2.0

package/dist/src/store.d.ts

@@ -0,0 +1,1052 @@
+import { singleWorkspace } from "./paths.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
+ * this package's dependency, not the CLI's — on an installed CLI the import
+ * failed, the catch swallowed it, and the workspace's provider block was
+ * silently ignored, so the probe went to Anthropic and reported a model
+ * that "may not exist". Reading through here, the CLI cannot drift from
+ * the runtime, and there is nothing to fail to import.
+ */
+export declare function readFrontmatter(file: string): Record<string, unknown>;
+import { type WireFormat, type AuthShape } from "./providers.ts";
+/**
+ * Single-workspace mode. When set, the workspace IS this directory — no
+ * tenant, no projects/ nesting. That's the difference between a framework you
+ * run on a folder and a platform that hosts many, and it's the only thing the
+ * core needs to know about which one it's in.
+ */
+export { singleWorkspace };
+export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "state"];
+export declare const STORAGE_DIR = "storage";
+/** What this directory was called before. Read-only: nothing writes here any
+ *  more, but installs created before the rename have bytes under it, and a
+ *  workspace whose files vanished on upgrade is a data-loss bug however
+ *  cosmetic the cause. `adoptLegacyFilesDir` moves one across, once. */
+export declare const LEGACY_FILES_DIR = "files";
+/**
+ * Move a pre-rename `files/` directory to `storage/`, once, in place.
+ *
+ * Called on the paths that resolve the store and the run mirror, so an
+ * existing install upgrades the first time either is touched rather than
+ * needing a migration step someone has to remember to run. A no-op when
+ * `storage/` already exists (the normal case after the first call) or when
+ * there is nothing to move (a fresh install).
+ */
+export declare function adoptLegacyFilesDir(parent: string): void;
+/**
+ * Rewrite a pre-rename `mdagent_version:` in an AGENTS.md to `foldrun_version:`,
+ * once, in place.
+ *
+ * The reader used to accept both spellings, which meant the old name lived on
+ * forever in files nobody would ever edit. Migrating on touch retires it: the
+ * first read of an account or workspace converts the file, and after that
+ * there is one name in the codebase and one name on disk.
+ *
+ * Only the key is touched — same line, same value, same everything else — so
+ * a file with comments or unusual formatting comes through unchanged.
+ */
+export declare function adoptLegacyVersionKey(dir: string): void;
+export declare function assertSafeName(name: string, kind: string): void;
+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.
+ */
+export declare function accountDir(tenant: string): string;
+/**
+ * Create the account's AGENTS.md if it is missing. Returns what it wrote.
+ *
+ * Called from every path that brings a workspace into being, because there is
+ * no separate "create an account" step — the account root accumulates
+ * (`library/`, `secrets.json`) as things need it, and its AGENTS.md is one
+ * more of those things.
+ *
+ * Never overwrites, and treats the legacy `project.md` as already-present: the
+ * whole file is hand-authored config, and a deploy is not permission to touch
+ * a scope the deploy did not ship. `dir` is explicit for `foldrun init`, which
+ * writes a workspace to an arbitrary path before anything is pinned to it and
+ * so cannot ask accountDir where "up" is.
+ */
+export declare function ensureAccountFiles(tenant: string, dir?: string): string[];
+export interface DeployFile {
+    path: string;
+    content: string;
+}
+/**
+ * The format version this build understands.
+ *
+ * A workspace declares what it targets with `foldrun_version` in AGENTS.md.
+ * Without it, the first breaking change to the flow grammar or frontmatter
+ * silently changes what everyone's existing files mean — the one failure a
+ * format cannot recover from, because there is no error to notice.
+ *
+ * Missing is treated as "current": nobody's existing workspace breaks by
+ * having been written before this existed.
+ */
+export declare const FORMAT_VERSION = "0.1";
+export interface VersionCheck {
+    declared: string | null;
+    supported: string;
+    /** Set when the workspace targets something this build cannot promise. */
+    warning: string | null;
+}
+export declare function checkFormatVersion(declared: unknown): VersionCheck;
+export declare function assertCanonicalCase(rel: string): void;
+/**
+ * What the platform owns inside a workspace directory, in one place.
+ *
+ * Three separate mechanisms need this exact list and drifted apart while it
+ * lived in each of them: deploys must preserve these files, and the run
+ * executors (docker and k8s) must not copy them into a sandbox. A platform
+ * file added to one list and not the others is either silently wiped by the
+ * next deploy or silently handed to every container — both invisible until
+ * someone is bitten.
+ */
+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;
+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. */
+meta?: ChangeMeta & {
+    commit?: string | null;
+}): {
+    preserved: number;
+};
+export declare function buildMemoryIndex(dir: string, prefix?: string): string | null;
+export declare function workspaceMemoryIndex(tenant: string, workspace: string): string | null;
+export declare function knowledgeIndex(dir: string, prefix?: string): string | null;
+export declare function workspaceKnowledgeIndex(tenant: string, workspace: string): string | null;
+export interface McpSpec {
+    name: string;
+    description: string;
+    command?: string;
+    args: string[];
+    env: Record<string, string>;
+    url?: string;
+    headers: Record<string, string>;
+}
+export type ToolDef = {
+    kind: "http";
+    name: string;
+    spec: ApiSpec;
+} | {
+    kind: "script";
+    name: string;
+    spec: Record<string, unknown>;
+} | {
+    kind: "mcp";
+    name: string;
+    spec: McpSpec;
+};
+/**
+ * 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
+ * legitimately opens with a \`\`\`yaml example of the tools: line, and running
+ * the documentation would be a memorable bug. Untagged fences never qualify:
+ * "which block is the program" must be answerable by reading, not guessing.
+ */
+export declare function fencedCode(body: string): {
+    code: string;
+    ext: string;
+} | null;
+/**
+ * The same block, with where it sits — for the migration that lifts a
+ * single-file tool's program out into a file beside it. Extracting the code
+ * and then removing it from the body are the same question asked twice, and
+ * a second copy of the language table is how they would come to disagree.
+ */
+export declare function fencedCodeBlock(body: string): {
+    code: string;
+    ext: string;
+    start: number;
+    end: number;
+} | null;
+export declare function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null;
+/**
+ * Tools in a directory, in both shapes.
+ *
+ *   tools/email.md            flat — a definition and nothing else
+ *   tools/bounce-verify/      folder — tool.md plus the code it runs
+ *     tool.md
+ *     run.mjs
+ *
+ * The folder is the shape to write. A script tool is a definition and an
+ * executable that cannot be separated — point `run:` at the wrong scope and
+ * the tool silently resolves to nothing — so keeping them in one directory
+ * is what stops the two from ever disagreeing. It is also how skills already
+ * work, which is the pattern people have seen.
+ *
+ * A folder tool's `run:` is relative to its own folder, and rewritten here
+ * to the scope-qualified path the runner resolves. That is the point of the
+ * shape: the definition never names the scope it lives in, so the same
+ * folder works copied into a workspace or installed at the account.
+ *
+ * Flat files keep working unchanged — the shape is a migration, not a break.
+ */
+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. */
+export declare function brokenToolReport(tenant: string, workspace: string): string[];
+export declare function workspaceTools(tenant: string, workspace: string): Record<string, ToolDef>;
+export { readToolDir };
+export declare function agentScripts(tenant: string, workspace: string, agent: string): string[];
+export interface ApiSpec {
+    name: string;
+    base: string;
+    description: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    methods: string[];
+    /** Seconds a call may take, when the tool.md says so. Unset: no clock. */
+    timeout?: number;
+    /** An OpenAPI 3.x document describing the API: a path relative to the
+     *  workspace root (`tools/hubspot/openapi.json`, JSON or YAML) or an
+     *  https URL. Each operation becomes its own typed tool. */
+    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. */
+    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};
+     *  `"100/m"` → {100, 1.67}. A call over the limit waits, never fails. */
+    rate?: {
+        count: number;
+        perSec: number;
+    };
+    /** The operations the `openapi:` document yielded, filled in by
+     *  attachOperations (openapi.ts) before the step is assembled. parseApis
+     *  leaves it unset. Plain JSON: this crosses into the run container. */
+    resolvedOperations?: import("./openapi.ts").OperationSpec[];
+}
+export interface AgentInfo {
+    name: string;
+    description: string;
+    model: string;
+    /** The other half of model selection. listAgents has always returned it;
+     *  the interface did not say so, so every consumer had to re-read the file
+     *  to show it. */
+    effort: string | null;
+    tools: string[];
+    apis: ApiSpec[];
+    /** The author's own tools named in `tools:` — the subset that is not a
+     *  built-in. Same list as `tools`, minus what the runtime provides. */
+    ownTools: string[];
+    /** 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[];
+    /** 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[];
+    /** 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[];
+}
+export declare const MODEL_TIERS: Record<string, string>;
+export type Tier = keyof typeof MODEL_TIERS;
+/** Which tier a word names, or null if it names none. Exported because the
+ *  provider block keys a remap table by tier and should accept every word
+ *  `model:` does — one vocabulary, not two. */
+export declare function resolveTier(value: unknown): Tier | null;
+export declare function resolveModel(value: unknown): string;
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type Effort = (typeof EFFORT_LEVELS)[number];
+/**
+ * `null` for both "not set" and "not a level we know" — unlike a model, the
+ * set is closed, so passing an unrecognised word through would be a 400 from
+ * the API rather than someone's pinned choice. Callers that can report say
+ * which it was with `isEffortWord`.
+ */
+export declare function resolveEffort(value: unknown): Effort | null;
+/** True when a non-empty `effort:` was written but names no level — the
+ *  one case worth a line in the run trace, because silence there looks
+ *  exactly like the setting having been applied. */
+export declare function isEffortWord(value: unknown): boolean;
+/** `"5/s"`, `"100/m"`, `"1000/h"` → a bucket size and refill rate. Null for
+ *  anything else: an unreadable limit is ignored rather than guessed. */
+export declare function parseRate(value: unknown): {
+    count: number;
+    perSec: number;
+} | null;
+export declare function parseApis(raw: unknown): ApiSpec[];
+export interface FlowStep {
+    agent: string;
+    instruction: string;
+    group: number;
+    optional: boolean;
+    /** Set when the step targets another flow (`[[flow:name]]`) instead of an agent. */
+    subflow?: string;
+    /** Overrides the agent's own model for this step only. */
+    model?: string;
+    /** Overrides the agent's own effort for this step only — the expensive
+     *  step in an otherwise cheap flow is exactly what this is for. */
+    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. */
+    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. */
+    case?: string;
+    /** The route of last resort: runs only when none of its group's `case:`
+     *  steps matched. */
+    else?: boolean;
+    /** Attempts on failure, beyond the first. */
+    retry?: number;
+    /** Abandon the step after this many seconds. */
+    timeout?: number;
+    /** Another agent takes the step over when it fails: same instruction, the
+     *  failure as context. Success continues the flow with the rescuer's
+     *  result; a second failure fails the step as it always did. */
+    onFail?: string;
+    /** Seconds to hold before this step runs — "wait: 3d" parses to 259200.
+     *  The run parks in the queue, not in a process. */
+    waitSecs?: number;
+    /** `wait: event` — hold until something outside POSTs the run's event
+     *  URL. Same parking as an approval, released by a machine instead of a
+     *  person; the body it sends reaches the step as its event payload. This
+     *  is what lets a flow send a quote, wait for the reply, then follow up,
+     *  without the platform becoming a chat product. */
+    waitFor?: "event";
+    /** For `each: rows` — the CSV whose rows fan the step out, agent-relative
+     *  like every other path an instruction uses. */
+    eachPath?: string;
+    /** A question for a human. The step parks like an approval; the answer
+     *  typed at the gate reaches the step's prompt. */
+    ask?: string;
+    /** What the gate shows before a person decides: paths under storage/,
+     *  globs allowed (`draft/*.mdx, draft/images/*.webp`). Declared in the
+     *  flow so the preview does not depend on the previous step remembering
+     *  to name its files. Resolved against storage/ when the run parks. */
+    preview?: string[];
+    /** Model-led delegation, bounded by declaration: this step's agent picks
+     *  which of THESE agents run next, one instruction each. The choice set
+     *  is the file's, the picks are the model's, the record shows both. */
+    delegate?: string[];
+    /** Evaluator loop: when this step's result lacks `until:`'s marker, wind
+     *  back to the previous group and go again — at most this many extra
+     *  cycles. Bounded by declaration, so the worst-case cost is still
+     *  readable off the file. */
+    loop?: number;
+    /** The marker (case-insensitive) whose presence in this step's result ends
+     *  the loop early. Required for `loop:` to mean anything. */
+    until?: string;
+    /** Fan-out: run one instance of this step per item of the previous
+     *  group's result. `lines` — one item per non-empty line of the prose;
+     *  `rows` — one per CSV row of a file; `items` — one per element of the
+     *  JSON array a previous `output: json` step returned. */
+    each?: "lines" | "rows" | "items";
+    /** Fan-out cap. Items beyond it are dropped, and the run log says so. */
+    max?: number;
+    /** A check run after the step; failing it fails the step. Either a shell
+     *  command (non-zero exit fails) or one of the eval assertions —
+     *  `contains: x`, `not-contains: x`, `matches: regex`, `file: path`,
+     *  `judge: sentence` — so a flow and an eval share one vocabulary. */
+    verify?: string;
+    /** The step returns data, not just prose: its reply must end with one JSON
+     *  value in a ```json block. The runner parses it, fails the step when it
+     *  cannot, and hands the value to the next group losslessly — the narrow
+     *  move the grammar ADR allowed instead of variables. */
+    output?: "json";
+    /** 1-indexed line in the flow file. Diagnostics without a line make you
+     *  search; every real linter emits file:line. */
+    line?: number;
+}
+export interface FlowInfo {
+    name: string;
+    file: string;
+    trigger: string;
+    schedule: string | null;
+    timezone: string | null;
+    /** The model every step in this flow runs on, unless the step names its
+     *  own. Nearest wins: step, then flow, then the agent's own frontmatter. */
+    model: string | null;
+    /** Same, for effort. */
+    effort: string | null;
+    /** What a new fire does while a run of this flow is still live:
+     *  "skip" doesn't start one, "queue" starts it but the worker holds it
+     *  until the live run finishes. Unset keeps today's behaviour (runs may
+     *  overlap) — a default that changed underfoot would surprise every flow
+     *  that legitimately runs in parallel. */
+    overlap: "skip" | "queue" | 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;
+    /** `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";
+    /** `trigger: once` — an ISO 8601 instant; fires the first tick at or after
+     *  it, once, then never again. */
+    at: string | null;
+    /** `trigger: watch` — a URL polled every `every:` seconds (default 15m);
+     *  fires when its content changes, with the new content as the task. */
+    url: string | null;
+    every: number | null;
+    /** `trigger: webhook` may also demand a provider's signature on every
+     *  delivery: GitHub (X-Hub-Signature-256), Stripe (Stripe-Signature), Slack
+     *  (X-Slack-Signature, plus the url_verification handshake) or a plain
+     *  `hmac` (X-Signature, hex SHA-256 of the body). `signingSecret` is the
+     *  NAME of the vault secret holding the shared key, never its value. */
+    signature: "github" | "stripe" | "slack" | "hmac" | null;
+    signingSecret: string | null;
+    /** `trigger: storage` — a path prefix under storage/; a file landing
+     *  there starts the flow with the path as its task. */
+    path: string | null;
+    steps: FlowStep[];
+}
+export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+export type FlowTrigger = (typeof FLOW_TRIGGERS)[number];
+export interface AgentAssets {
+    skills: string[];
+    memory: string[];
+}
+export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
+export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
+/** "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;
+/** 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. */
+export declare function parseInstant(raw: unknown): string | null;
+/**
+ * Strip the quotes a person wrapped a whole value in, and only those.
+ *
+ * `schedule: "0 8 * * *"` is quoted so YAML-minded readers are comfortable,
+ * and the cron parser must not see the quotes. But the rule that did this
+ * 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"
+ *
+ * reached bash unbalanced, which exited 2 with "unexpected EOF" on every
+ * run. The step could never pass, whatever the agent did, and nothing said
+ * why: the trace printed the command the parser had already broken.
+ *
+ * So a pair is only stripped when the value opens and closes with the same
+ * quote AND contains no other instance of it — which is what "the whole
+ * value is quoted" actually means. `"a" = "b"` keeps its quotes, because
+ * they are two pairs, not one wrapper.
+ */
+export declare function unquote(raw: string): string;
+export declare function parseFlow(file: string, raw: string): FlowInfo;
+/** A live run of this flow — the fact overlap: decisions are made on. */
+export declare function flowHasLiveRun(tenant: string, workspace: string, flowName: string): boolean;
+/**
+ * Rewrite a flow's trigger in place — the dashboard's trigger picker.
+ *
+ * Line-level surgery on the frontmatter, not a YAML round-trip: everything
+ * the author wrote (comments, key order, unrelated keys) survives verbatim,
+ * 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: {
+    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;
+/** Append a step as its own group at the end of the flow. */
+export declare function addFlowStep(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 function listFlows(tenant: string, workspace: string): FlowInfo[];
+export interface WorkspaceSummary {
+    name: string;
+    description: string;
+    agents: number;
+    flows: number;
+    deployedAt: string;
+    runCount: number;
+    /** Set when this workspace is a branch's preview of another (preview.ts):
+     *  which one, which branch, which commit. Read from the marker beside the
+     *  directory here rather than through preview.ts, which imports this file. */
+    preview?: {
+        source: string;
+        branch: string;
+        commit: string;
+        at: string;
+    };
+    /** The workspace's picture, as a URL, when the page that lists it looked
+     *  one up (avatars.ts) — the store itself does not. */
+    avatar?: string | null;
+}
+/**
+ * Every account this installation holds.
+ *
+ * A tenant is a directory under the data root, but not every directory there
+ * is one — `.runtimes/` sits beside them, and so do keys.json and the secret
+ * key. What makes a tenant is that it holds workspaces, so that is the test.
+ *
+ * Single-workspace mode has no accounts at all: the workspace *is* the whole
+ * installation, and there is nothing above it to enumerate.
+ */
+export declare function listTenants(): string[];
+export declare function listWorkspaces(tenant: string): WorkspaceSummary[];
+/**
+ * May this path be edited — and therefore, must it be listed?
+ *
+ * The listing and the writer used to answer this separately, and drifted
+ * twice. First `state/notes.md` could be written and never appeared; that was
+ * fixed by adding a state rule to the listing. Then folder tools arrived and
+ * `tools/x/run.mjs` — the program half of every script tool — was writable,
+ * readable, and invisible in the file tree, so the code you were told to edit
+ * could not be found.
+ *
+ * Writable and invisible is the worst of both. One rule decides now: the
+ * listing asks the writer, so a path that can be saved is a path that shows.
+ */
+export declare function isEditablePath(rel: string): boolean;
+export declare function accountFileSealed(rel: string): string | null;
+/**
+ * The account directory as it actually is on disk.
+ *
+ * A faithful walk, with one rule for what it leaves out: show what a person
+ * authors or an agent reads. That keeps the path you see the path an agent
+ * types, which is the whole point of the tree — while sparing you rows that
+ * exist only to be refused.
+ *
+ * The vault is not an exception to that rule. Secrets are authored in Settings
+ * and reach an agent as environment variables — never as a file, deliberately,
+ * so that no single read can carry them all off. `secrets.json` is therefore
+ * neither authored here nor read by an agent, and a row that can only refuse
+ * the person who clicks it teaches nothing. The reader still guards it.
+ */
+export declare function listAccountFiles(tenant: string, cap?: number): string[];
+/** One file under the account directory, or the reason it will not be served. */
+export declare function readAccountFile(tenant: string, rel: string): {
+    content: string;
+} | {
+    sealed: string;
+};
+export declare function listWorkspaceFiles(tenant: string, workspace: string): string[];
+export declare function readWorkspaceFile(tenant: string, workspace: string, rel: string): string;
+/** Who made a change and why — recorded on its revision. */
+export interface ChangeMeta {
+    by?: string;
+    message?: string;
+}
+export declare function writeWorkspaceFile(tenant: string, workspace: string, rel: string, content: string, meta?: ChangeMeta): void;
+export declare function syncBundleFor(file: string, change?: "Creation" | "Update"): void;
+/**
+ * Rename one editable file. Both ends pass the same gate as a write — a
+ * rename must not be able to move a file somewhere a write couldn't create
+ * it — and an existing target refuses rather than silently replacing
+ * someone's work. Bundle indexes on both sides are re-synced, because a
+ * memory file leaving a bundle is as much a change to its index as one
+ * arriving.
+ */
+/**
+ * Why a path can never be moved or renamed, in a sentence — or null when it
+ * can. One vocabulary for the tree, the API and the tests, because "not an
+ * editable path" told the person *that* they were refused and made them
+ * guess at *why*, when the why is the whole lesson: in this format,
+ * location is meaning.
+ */
+export declare function anchoredReason(rel: string): string | null;
+export declare function renameWorkspaceFile(tenant: string, workspace: string, from: string, to: string, meta?: ChangeMeta): void;
+export declare function deleteWorkspacePath(tenant: string, workspace: string, rel: string, meta?: ChangeMeta): void;
+export declare function deleteWorkspace(tenant: string, workspace: string): void;
+/**
+ * What a rename would break, so the caller can say so before doing it.
+ *
+ * The workspace name is not just a directory: it is in every webhook URL *and*
+ * in the token those URLs carry, which is derived from `tenant/workspace/flow`.
+ * So a rename invalidates both halves — an old hook doesn't 404, it fails the
+ * signature check, which reads like an attack rather than a rename. Anything
+ * calling those URLs has to be re-pointed by hand.
+ */
+export declare function renameImpact(tenant: string, workspace: string): {
+    webhookFlows: string[];
+};
+/**
+ * Rename a workspace: move the directory, then update the `name:` in AGENTS.md
+ * so the file and its folder don't disagree.
+ *
+ * Runs, state and secrets travel with it — they live inside the directory, so
+ * there is nothing to migrate and nothing to lose.
+ */
+export declare function renameWorkspace(tenant: string, from: string, to: string): void;
+/** Set a workspace's description, in AGENTS.md, without touching anything else. */
+export declare function setWorkspaceDescription(tenant: string, workspace: string, description: string): void;
+/**
+ * Starter files for "+ New workspace" in the dashboard.
+ *
+ * Kept as a name because the API route and its callers use it; the content
+ * lives in starter.ts so this and `foldrun init` cannot drift. They did:
+ * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
+ * so every workspace made from the dashboard was born in the old format.
+ */
+export declare function templateFiles(workspace: string): DeployFile[];
+export declare const AGENT_TEMPLATE: (name: string) => string;
+export declare const FLOW_TEMPLATE: (name: string, firstAgent: string) => string;
+export declare const FLOW_PATTERNS: readonly ["pipeline", "review-loop", "fan-out", "debate", "router"];
+export type FlowPattern = (typeof FLOW_PATTERNS)[number];
+export declare function flowPatternTemplate(pattern: FlowPattern, name: string, agents: string[]): string;
+export interface RunEvent {
+    t: string;
+    type: "text" | "tool" | "error" | "info";
+    text: string;
+    /** Tool events come in pairs: the call, and its completion. Both carry
+     *  the provider's tool_use id so a reader can pair them; the completion
+     *  also carries how long the tool ran and whether it errored. The
+     *  timeline draws a span from the pair; the trace shows one line. Absent
+     *  on records from before this existed — then a tool is a tick, not a bar. */
+    call?: string;
+    ms?: number;
+    err?: boolean;
+}
+export interface StepRecord {
+    agent: string;
+    instruction: string;
+    group: number;
+    optional: boolean;
+    /** Carried from the flow — see FlowStep. Both are resolved at run
+     *  time rather than stored resolved, so a record stays readable as
+     *  what its author wrote. */
+    model?: string;
+    effort?: string;
+    approve?: boolean;
+    when?: string;
+    case?: string;
+    else?: boolean;
+    retry?: number;
+    timeout?: number;
+    verify?: string;
+    /** Attempts made so far, for the run trace. */
+    attempts?: number;
+    /** 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
+     *  parked at a gate has events long before it runs. Kept across retries:
+     *  startedAt is the first attempt's, finishedAt the last's. Absent on
+     *  records from before this existed; readers fall back to the events. */
+    startedAt?: string;
+    finishedAt?: string;
+    /** Why a step was skipped, shown in the trace. */
+    skipReason?: string;
+    /** Evaluator loop, carried from the flow — see FlowStep. `loopRemaining`
+     *  counts down on the record so a resumed run knows how many cycles are
+     *  left rather than starting the budget over. */
+    loop?: number;
+    until?: string;
+    loopRemaining?: number;
+    /** Fan-out, carried from the flow — see FlowStep. */
+    each?: "lines" | "rows" | "items";
+    eachPath?: string;
+    max?: number;
+    /** Carried from the flow — see FlowStep. */
+    output?: "json";
+    /** 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. */
+    data?: unknown;
+    /** Set on the instances a fan-out step expanded into: the item this one
+     *  works on. The template step itself becomes status "expanded". */
+    item?: string;
+    /** Carried from the flow — see FlowStep for each. */
+    onFail?: string;
+    waitSecs?: number;
+    /** Stamped when the run reaches the step; the queue holds it until then.
+     *  On the record so a restart resumes the same deadline, not a new one. */
+    waitUntil?: string;
+    /** Carried from the flow — see FlowStep. */
+    waitFor?: "event";
+    /** What the outside world POSTed to release a `wait: event` step. Rides
+     *  into the step's prompt the way an approval note does. */
+    eventPayload?: string;
+    ask?: string;
+    /** Carried from the flow — see FlowStep. */
+    preview?: string[];
+    /** `preview:` resolved against storage/ at the moment the run parked —
+     *  the files the gate renders, relative to storage/. */
+    previewFiles?: string[];
+    delegate?: string[];
+    /** Set once a delegate step's picks have been expanded — the guard that
+     *  a loop rewind cannot fan the same choice out twice. */
+    delegated?: boolean;
+    /**
+     * When a person approved this step. Set by the approval API and never
+     * cleared, because approval is a fact about the past.
+     *
+     * Status alone cannot carry it: approving flips the step back to `pending`,
+     * which is indistinguishable from never having been asked. A run that was
+     * approved and then abandoned could not be resumed without asking the same
+     * person the same question again.
+     */
+    approvedAt?: string;
+    /** What the approver said while approving — carried into the step's prompt
+     *  as operator guidance. This turns the gate from a yes/no button into a
+     *  place to steer: "approve, but skip the Sydney batch". */
+    approvalNote?: string;
+    status: "pending" | "awaiting-approval" | "running" | "completed" | "failed" | "skipped";
+    events: RunEvent[];
+    result: string | null;
+    /** The model's final text block — its answer, without the narration that
+     *  preceded the tool calls. Absent on steps recorded before this existed,
+     *  which is why every reader falls back to `result`. */
+    conclusion?: string | null;
+    costUsd: number | null;
+    /** Set on steps copied into a re-run from an earlier run: the run they
+     *  actually executed in. Carried steps provide context and are never
+     *  billed again — the original run's ledger line already paid for them. */
+    carriedFrom?: string;
+    /**
+     * Sandbox seconds this step rented, and how many of them were cold start.
+     * Set only on the isolated path — an in-process step rents nothing, so
+     * `null` is the honest value and billing must read it as zero, not as
+     * "unknown, charge something".
+     *
+     * Wall time is deliberately not a substitute: a step parked at an approval
+     * gate has no pod, and billing a customer for a person taking the weekend
+     * to click approve is charging them for their own deliberation.
+     */
+    computeSecs?: number | null;
+    startupSecs?: number | null;
+    /** Which reservation class the sandbox held (small | large), and the
+     *  actual limits it held, as numbers. Facts of the step: a price is per
+     *  core-second, so what was reserved must come from the record, never
+     *  from what the config says when the bill is computed. Absent on steps
+     *  from before sizes existed — billing falls back to the flat rate. */
+    size?: "small" | "large" | "heavy";
+    reserved?: {
+        cpus: number;
+        memGiB: number;
+    } | null;
+    /** Token counts behind costUsd, kept so usage reports can say "how many"
+     *  and not only "how much" — the price of a token changes, the count is
+     *  the fact. Absent on steps recorded before this existed. */
+    tokens?: {
+        input: number;
+        output: number;
+    } | null;
+    /** What the sandbox actually touched, against what it reserved: CPU
+     *  busy-seconds and peak memory from the pod's own cgroup, bytes on the
+     *  wire from /proc/net/dev. Null per-field where the kernel interface
+     *  wasn't readable in the sandbox — never estimated. */
+    actual?: {
+        busyCpuSecs: number | null;
+        peakMemBytes: number | null;
+        rxBytes: number | null;
+        txBytes: number | null;
+    } | null;
+}
+export interface RunRecord {
+    id: string;
+    flow: string;
+    /** Tags supplied when the run started — skills can require one. */
+    tags?: string[];
+    status: "queued" | "running" | "awaiting-approval" | "completed" | "failed";
+    startedAt: string;
+    finishedAt: string | null;
+    /** Set when a worker parked this run at an approval gate and returned its
+     *  slot to the queue. The approval API re-enqueues exactly when this is
+     *  set — without the marker it would also re-enqueue runs whose starting
+     *  process is still alive and polling, and two drivers would race. */
+    parkedAt?: string | null;
+    /** Set when a person stopped this run. Kept on the record rather than
+     *  expressed only as a status, because "failed" and "someone stopped it"
+     *  are different facts and the trace should not conflate them. */
+    stopRequested?: boolean;
+    /**
+     * What this run concluded, in one line — the first line of the last step
+     * that produced a result, captured when the run finishes.
+     *
+     * A run has always recorded its status and its cost but never its outcome,
+     * so "what did this actually do" could only be answered by opening it and
+     * reading. That does not scale past a couple of flows, and the sentence was
+     * already sitting in the record: agents are asked to lead with it.
+     *
+     * Deliberately NOT a schema the author has to fill in. Nothing new goes in
+     * the folder, nothing new is learned, and an agent that writes no headline
+     * simply gets its first line — which is still better than a status.
+     */
+    summary?: string | 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. */
+    budgetUsd?: number | null;
+    /** Memory files this run created or changed, workspace-relative — what
+     *  the agents decided was worth remembering, listed so a person can review
+     *  the lesson without diffing the folder. */
+    memoryWrites?: string[];
+    steps: StepRecord[];
+}
+export declare function runFilePath(tenant: string, workspace: string, runId: string): string;
+/**
+ * Erase a run from history: its record and the outputs archived under its
+ * id.
+ *
+ * The ledger line stays, and that is settled rather than provisional: if
+ * deleting a run voided its charge, deletion would be a refund button — run
+ * the expensive extraction, read the result, delete, never pay. Money is
+ * not deleted because a trace was.
+ *
+ * What deletion *does* owe the books is an explanation. A charge pointing
+ * at a run that no longer exists reads as unexplained forever, so the
+ * deletion writes itself down: a zero-value adjustment naming the run, on
+ * the same append-only file the charge lives in. The balance is untouched;
+ * the story is complete.
+ */
+export declare function deleteRun(tenant: string, workspace: string, runId: string): boolean;
+/** ledger.ts registers here — store cannot import it without a cycle, and
+ *  money must not depend on one. */
+declare let onRunDeleted: ((tenant: string, workspace: string, runId: string) => void) | undefined;
+export declare function registerRunDeletionListener(fn: typeof onRunDeleted): void;
+export interface RunOutputFile {
+    agent: string;
+    /** Relative to that agent's outputs/ — the name the agent wrote. */
+    path: string;
+    bytes: number;
+}
+/**
+ * What a run archived: every file its agents left in outputs/, copied under
+ * runs/<id>/outputs/<agent>/ when the run finished (runner.ts, archive()).
+ *
+ * Per agent, not per step — the archive is a copy of each agent's folder,
+ * and the record cannot say which step wrote which file. An agent that
+ * steps twice in one run shows the same files against both steps.
+ */
+export declare function listRunOutputs(tenant: string, workspace: string, runId: string): RunOutputFile[];
+/** The absolute path of one archived output, or null when the name escapes
+ *  the archive or names nothing — the API serves only what this returns. */
+export declare function runOutputPath(tenant: string, workspace: string, runId: string, agent: string, rel: string): string | null;
+export declare function readRun(tenant: string, workspace: string, runId: string): RunRecord | null;
+export declare function writeRun(tenant: string, workspace: string, run: RunRecord): void;
+export interface RunWithWorkspace extends RunRecord {
+    workspace: string;
+}
+export declare function listAllRuns(tenant: string): RunWithWorkspace[];
+/**
+ * The status a person should see. "failed" and "someone stopped it" are
+ * different facts — the record keeps them apart (stopRequested), and the
+ * display must too: a run a person chose to end is not a run that broke,
+ * and showing it red teaches people that stopping things is dangerous.
+ */
+export declare function runDisplayStatus(run: Pick<RunRecord, "status" | "stopRequested">): string;
+export declare function runCost(run: RunRecord): number;
+/**
+ * What a finished run consumed, in the units the format itself has — the
+ * shape ledger.ts prices. Structural, not an import, because ledger.ts
+ * imports this module and money must not depend on a cycle.
+ *
+ * Only steps that actually ran count. A pending step never happened, a
+ * skipped one was skipped by the flow's own `when`, and an `expanded`
+ * fan-out template is a row in the trace rather than work — billing any of
+ * them would charge for steps the customer can see never executed, which is
+ * the fastest way to lose an argument about an invoice.
+ */
+export declare function runMeter(run: RunRecord): {
+    tokenCostUsd: number;
+    steps: number;
+    computeSecs: number;
+    /** The subset of computeSecs held at the small reservation. Steps from
+     *  before sizes existed count as large — they held the large limits. */
+    smallSecs: number;
+    netBytes: number;
+};
+/**
+ * The compute meter for hold+work pricing: core-seconds and GiB-seconds
+ * actually reserved (from each step's own recorded reservation), and CPU
+ * seconds actually burned (from the sandbox's cgroup, where readable).
+ * Steps with no recorded reservation contribute plain seconds only — the
+ * flat-rate fallback prices those.
+ */
+export declare function runComputeMeter(run: RunRecord): {
+    coreSecs: number;
+    gibSecs: number;
+    busyCpuSecs: number;
+    flatSecs: number;
+};
+export declare function runDurationSecs(run: RunRecord): number | null;
+/**
+ * Why a failed run failed, said in one line: the failing step and its last
+ * error event. The journal has the whole story; a runs *list* needs the
+ * sentence — "failed" with no reason makes every diagnosis start by opening
+ * the run, and the answer was sitting in the record all along.
+ */
+export declare function runFailure(run: RunRecord): {
+    agent: string;
+    reason: string;
+} | null;
+/**
+ * The one-line outcome, pulled out of the reply that already says it.
+ *
+ * The last step with a result, because that is the one that concluded —
+ * a reporter at the end of a flow, or on a failed run whatever got furthest,
+ * which is the most informative line available either way.
+ *
+ * Markdown decoration is stripped rather than rendered: this lands in an
+ * email subject and a table cell, where `## ` and `**` are noise. Sibling of
+ * 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 function runSummary(run: RunRecord): string | null;
+/**
+ * What one step concluded, in a line.
+ *
+ * The model's ANSWER first, falling back to the whole reply. `result` is every
+ * text block joined, and a model that narrates before calling a tool puts
+ * "Now let me read the outputs…" at the top of it — so reading the joined
+ * text reported the plan of every step that used a tool, which is most of
+ * them. Steps recorded before `conclusion` existed have only `result`, and
+ * for those this is exactly what it always was.
+ */
+export declare function stepHeadline(step: StepRecord): string | null;
+/**
+ * The first line of a reply that a person would recognise as its point.
+ *
+ * Markdown decoration is stripped rather than skipped, so a reply that opens
+ * with `## Done: 4 findings` still has a headline. A line that is only
+ * punctuation — a bare `#`, a rule, a row of asterisks — is decoration, and a
+ * code fence is the shape of an `output: json` reply, not its headline.
+ *
+ * Exported because a run's summary and one agent's step both want it, and two
+ * copies would be two answers to the same question.
+ */
+export declare function headlineOf(result: string | null | undefined): string | null;
+/** One step this agent ran, with the run it belongs to. */
+export interface AgentStep {
+    runId: string;
+    flow: string;
+    status: RunRecord["status"];
+    startedAt: string;
+    /** The step's own first line — what THIS agent concluded, which is not
+     *  the run's summary unless it happened to run last. */
+    headline: string | null;
+    instruction: string;
+    stepStatus: StepRecord["status"];
+    costUsd: number | null;
+    /** Set on a fan-out instance: the item this one worked on. */
+    item?: string;
+    /** Path refusals in this step — see deniedPaths. */
+    denied: number;
+}
+/**
+ * Everything one agent has done, newest first.
+ *
+ * The runs list answers "what ran"; it is keyed by flow, so an agent that
+ * appears in four flows has its work scattered across four filters and an
+ * agent used by none is invisible unless someone remembers the `adhoc:`
+ * prefix. This is the other axis, and the one you want when the question is
+ * "is this agent any good" rather than "did Monday's flow finish".
+ */
+/** Path refusals in a step — see deniedPaths in the dashboard's
+ *  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[];
+export declare function listRuns(tenant: string, workspace: string): RunRecord[];
+/**
+ * `provider:` — which endpoint the model calls run against, and the two
+ * knobs that make a non-Anthropic gateway usable rather than merely
+ * reachable.
+ *
+ *   provider:
+ *     base_url: https://openrouter.ai/api
+ *     token: ${OPENROUTER_API_KEY}
+ *     models:
+ *       fast: google/gemini-2.5-flash
+ *       max: anthropic/claude-opus-4.1
+ *     headers:
+ *       X-Title: foldrun
+ *
+ * `models:` is what makes tiers portable rather than merely renamed-proof:
+ * without it `model: fast` means the literal string "haiku" on every
+ * endpoint, which is only true on one of them. `headers:` is the escape
+ * hatch for whatever a gateway wants that our schema will never have —
+ * routing preferences, attribution, tags. Both are the gateway's business,
+ * so neither grows a per-vendor branch in here.
+ */
+export interface ProviderSpec {
+    /** The preset this block was built from, when `name:` named one. */
+    name: string | null;
+    /** What the endpoint speaks. `anthropic` is reached directly; `openai`
+     *  through the runtime's own translator on localhost (translator.ts). */
+    format: WireFormat;
+    /** Which header carries the key on an Anthropic-format endpoint. */
+    auth: AuthShape;
+    baseUrl: string;
+    /** May still contain `${SECRET}` — resolving needs a tenant. */
+    token: string;
+    /** Tier → the id this gateway calls that tier. Absent tiers keep ours. */
+    models: Partial<Record<Tier, string>>;
+    /** Header name → value; values may contain `${SECRET}`. */
+    headers: Record<string, string>;
+    /** Extra request fields for a translated (`format: openai`) endpoint,
+     *  merged into the outgoing body verbatim. `null` removes a field the
+     *  translation would otherwise send. The escape hatch for every knob this
+     *  format deliberately does not model. */
+    params: Record<string, unknown>;
+    /** Things wrong enough to say out loud but not to fail a run over. */
+    warnings: string[];
+    /** A second endpoint, tried once when the first refuses over money, auth
+     *  or limits (not when the work itself fails). Same shape, one level deep
+     *  — a fallback with its own fallback is a routing table, and that lives
+     *  in a gateway, not in frontmatter. */
+    fallback?: ProviderSpec | null;
+}
+export declare function parseProvider(raw: unknown): ProviderSpec | null;
+/**
+ * The whole of a provider block as the env the Agent SDK reads. The one
+ * place our format meets the SDK's, so the mapping is testable without a
+ * vault: the caller resolves `${SECRET}` first and passes values.
+ *
+ * The token goes to ANTHROPIC_AUTH_TOKEN (a bearer credential) and
+ * ANTHROPIC_API_KEY is explicitly blanked. Both matter. A key left in the
+ * environment is sent as `x-api-key` and treated as a direct-Anthropic
+ * credential, so a gateway that wants `Authorization: Bearer` gets the
+ * wrong header — and worse, an *unset* key lets the SDK fall back to
+ * authenticating against Anthropic directly, which fails somewhere far from
+ * the file that caused it. A gateway that genuinely wants the key header
+ * asks for it by name: `headers: { x-api-key: ${TOKEN} }`.
+ */
+export declare function providerEnvFor(spec: {
+    baseUrl?: string;
+    /** Already secret-substituted. */
+    token?: string;
+    /** Which header the key rides in. Bearer unless the endpoint says
+     *  otherwise: the SDK sends ANTHROPIC_API_KEY as x-api-key and
+     *  ANTHROPIC_AUTH_TOKEN as a bearer, and blanks the other so it cannot
+     *  fall back to Anthropic's own endpoint with the wrong credential. */
+    auth?: AuthShape;
+    models: Partial<Record<Tier, string>>;
+    headers: Record<string, string>;
+}): Record<string, string>;