@foldrun/core 0.3.0 → 0.5.0

package/dist/src/runner.d.ts

@@ -1,4 +1,11 @@
-import { type FlowStep, type RunRecord } from "./store.ts";
+import { type SubagentSpec } from "./subagents.ts";
+import { type FlowStep, type RunRecord, type StepRecord } from "./store.ts";
+import { type Catalog } from "./catalog.ts";
+import { type RuntimeSpec } from "./runtime.ts";
+import { type LanguageChoice } from "./language.ts";
+import { type RegionChoice } from "./locale.ts";
+import { type ClockChoice } from "./clock.ts";
+export { localDate } from "./clock.ts";
 /** How much of the earlier groups' output a step is handed, in characters.
  *  Newest groups are kept when the total is over it. */
 export declare const CONTEXT_CHARS = 30000;
@@ -12,6 +19,17 @@ export declare const DESK_RUNS_CAP = 100;
  * step is most likely to be about.
  */
 export declare function joinEarlierGroups(groupResults: (string | null)[], gi: number, cap?: number): string | null;
+/**
+ * `parallel: N` — a pool of N slots the instances of one fan-out share.
+ * Fan-out always ran every instance at once, and still does unless the
+ * step says otherwise: twenty browser steps against one site, or one
+ * vendor's rate limit, is what the cap is for. Nothing is rented while an
+ * instance waits for a slot.
+ */
+export declare function slotPool(size: number): {
+    acquire: () => Promise<void>;
+    release: () => void;
+};
 export interface DiscoveredSkill {
     name: string;
     description: string;
@@ -37,20 +55,73 @@ export declare function discoverSkills(agentDir: string, subdir?: string): Disco
  * Returns null rather than throwing on unparseable YAML: a broken shared file
  * must not take down every agent under it.
  */
+/**
+ * AGENTS.md without the block a coding tool reads.
+ *
+ * AGENTS.md is two things in a foldrun folder: the account's (or
+ * workspace's) own context, which every running agent is given, and — the
+ * convention Next.js set — the file a coding agent (Claude Code, Cursor,
+ * Codex) reads before it edits the folder. The CLI writes a short managed
+ * block for the second reader between these markers; it is about editing
+ * the files, not about doing the work, so no running agent is shown it.
+ */
+export declare const AGENT_RULES_START = "<!-- BEGIN:foldrun-agent-rules -->";
+export declare const AGENT_RULES_END = "<!-- END:foldrun-agent-rules -->";
+export declare function withoutAgentRules(body: string): string;
 export declare function readAgentsMd(dir: string): {
     data: Record<string, unknown>;
     body: string;
 } | null;
 /**
- * The calendar an agent works to. `timezone:` in AGENTS.md, nearest-wins like
- * every other key there; a flow's cron already means its own timezone, this
- * makes "today" mean it too. Unset is UTC — what the pods run — which for a
- * Sydney desk made an article dated today "one day in the future" until 10am.
- * An unknown name falls back to UTC rather than failing every step.
+ * The runtime one agent's steps are built with: its own declaration (else its
+ * workspace's), merged with every script tool it grants. The runner builds
+ * exactly this for a step; the platform builds it ahead of time when the
+ * workspace is deployed, so a package that will not install is reported at
+ * deploy and a scheduled step finds its environment ready. One function, so
+ * the two can never disagree about what an agent needs.
+ */
+export declare function agentRuntimeSpec(tenant: string, workspace: string, agentDir: string): RuntimeSpec | null;
+/** Every distinct runtime a workspace's agents need, with who needs it. */
+export declare function workspaceRuntimePlan(tenant: string, workspace: string): {
+    fingerprint: string;
+    spec: RuntimeSpec;
+    agents: string[];
+}[];
+/**
+ * The calendar a set of frontmatter asks for, with no cascade around it —
+ * one merged record in, one zone out. The full cascade lives in
+ * `agentClock` below and in clock.ts; this is what the account-level parts
+ * of the platform (a wallet's month, a budget window) call.
  */
 export declare function resolveTimezone(front: Record<string, unknown>): string;
-/** YYYY-MM-DD in a timezone — the date the workspace believes it is. */
-export declare function localDate(timeZone: string, now?: Date): string;
+/**
+ * The clock this step works to: agent, then flow, then workspace, then
+ * account, then FOLDRUN_TIMEZONE, then UTC. Nearest wins, and a value that
+ * is not a zone falls through to the next level with a line to say so —
+ * see clock.ts for why this exists at all.
+ */
+export declare function agentClock(agentDir: string, tenant: string, agentFront: Record<string, unknown>, flowTimezone?: string | null): ClockChoice;
+/**
+ * The language this step works in: agent, then workspace, then account, then
+ * FOLDRUN_LANGUAGE, then English. The flow level is not read yet — a flow's
+ * timezone: travels through three signatures to get here, and this will
+ * take the same road when a flow needs it.
+ */
+export declare function agentLanguage(agentDir: string, tenant: string, agentFront: Record<string, unknown>): LanguageChoice;
+/**
+ * The country this step works for, on the same road as the language, then
+ * FOLDRUN_REGION, then whatever the language tag carried (`en-AU` says AU).
+ * Everything a country changes — currency, units, calendar, weekend, text
+ * direction — is derived from it in locale.ts; the three overrides
+ * (`currency:`, `calendar:`, `units:`) are read at the nearest level that
+ * wrote them.
+ */
+export declare function agentRegion(agentDir: string, tenant: string, agentFront: Record<string, unknown>, languageTag: string): RegionChoice;
+export declare function agentLocaleOverrides(agentDir: string, tenant: string, agentFront: Record<string, unknown>): {
+    currency?: unknown;
+    calendar?: unknown;
+    units?: unknown;
+};
 /**
  * The prose from AGENTS.md, outermost first.
  *
@@ -58,6 +129,23 @@ export declare function localDate(timeZone: string, now?: Date): string;
  * template as "context every agent here shares" — and never read. Only the
  * frontmatter was, so the instructions people actually wrote reached no model.
  */
+/**
+ * The sub-agents a step may delegate to (`subagents:`), as the SDK will get
+ * them: each resolved through agentContext exactly as its own step would be
+ * (grants only — no runtime; it runs inside its parent's), then cut to what
+ * the parent holds. Problems are lines on the step, never a failed step.
+ */
+export declare function buildSubagentSpecs(o: {
+    names: unknown;
+    self: string;
+    workspaceRoot: string;
+    tenant: string;
+    tags?: string[];
+    runId?: string;
+    flowTimezone?: string | null;
+    parentAllowed: string[];
+    push: (type: "info" | "error", text: string) => void;
+}): SubagentSpec[];
 export declare function sharedInstructions(agentDir: string, tenant: string): string | null;
 /**
  * Which of an agent's in-scope skills load for this run.
@@ -102,6 +190,47 @@ export declare function applicableSkills<T extends {
  */
 export declare function saysUntilMarker(result: string | null, until: string): boolean;
 export declare function resolveDocLinks(text: string, workspaceRoot: string): string;
+export declare function repriced(catalog: Catalog | null, model: string, usage: {
+    inputTokens: number;
+    outputTokens: number;
+} | null, sdkCost: number | null, push: (type: "info" | "error", text: string) => void, 
+/** The step's turns each priced at its own model — set when a sub-agent
+ *  ran on a different model (ExecOutcome.turnsCostUsd). The lump `usage`
+ *  priced at the step's model would bill those turns at the wrong rate. */
+turnsCostUsd?: number | null): number | null;
+/**
+ * Write one attempt onto the step's history and re-total the step.
+ *
+ * runStep reports the attempt it just ran — its cost, tokens and sandbox
+ * seconds — by assigning the step's fields. Those become this attempt's row;
+ * the step's fields then become the sum of every row, which is what the
+ * run's spend, the flow's budget: and the platform's bill read. A retried
+ * step used to carry only its last attempt's cost, so a `retry: 2` step
+ * could spend three shares while reporting one.
+ */
+export declare function recordAttempt(step: StepRecord, 
+/** The step's attempt (`attempts`) these rows belong to. */
+attempt: number, status: "completed" | "failed", startedAt: string, eventsBefore: number, 
+/** The attempt re-attached to a sandbox a previous driver left: same
+ *  attempt, so its row is replaced rather than repeated. */
+reattach?: boolean): void;
+/**
+ * Did this attempt call its tools and then fail only on the check after —
+ * `verify:`, `output: json`, a schema? For a step whose tools act outward
+ * that is the one failure a retry must not answer: the email went, the post
+ * is up, and the check failing says nothing about whether they happened. A
+ * second attempt sends them again. Read off the attempt's own events, which
+ * both executors write the same way (step-exec.ts): every event a failed
+ * check writes carries `check: true`. It used to read only the LAST error's
+ * wording, and a failed shell verify or judge writes its detail after its
+ * headline — so the step was retried and the email went twice. The wording
+ * is still honoured, for a driver image older than the tag.
+ */
+export declare function actedThenFailedCheck(events: {
+    type: string;
+    text: string;
+    check?: boolean;
+}[]): boolean;
 /**
  * Copy a directory tree by reading and writing the bytes.
  *
@@ -115,6 +244,13 @@ export declare function resolveDocLinks(text: string, workspaceRoot: string): st
  * happened to create it.
  */
 export declare function copyTreeBytes(from: string, to: string): void;
+/**
+ * Wait, briefly, for the mounted credential to become one we have not
+ * already been refused on. Returns the new value, or null when the window
+ * passes without a change — which is the answer that means "this key is
+ * wrong", not "this key is stale".
+ */
+export declare function awaitRotatedCredential(before: string | undefined, now?: () => number, read?: () => string | undefined, waitMs?: number, pollMs?: number): Promise<string | null>;
 /** How many times a busy provider is given another moment, and the longest
  *  any one wait may be. Three is the industry's habit and the point where
  *  waiting longer stops being kinder than failing. */
@@ -132,8 +268,41 @@ export declare const OVERLOAD_RETRIES = 3;
  */
 export declare function isTransientOverload(text: string): boolean;
 export declare function backoffMs(attempt: number, text?: string, random?: () => number): number;
-export declare function createFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, status: "queued" | "running", tags?: string[]): RunRecord;
-export declare function startFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[], effortOverride?: string | null): RunRecord;
+/**
+ * The platform's model credential, read at the moment a step needs it.
+ *
+ * It used to come only from this process's environment, which meant the
+ * worker held whatever token it was started with. Refreshing an OAuth token
+ * REVOKES the old one, so a refresh without a restart left every run
+ * answering 401 — on 2026-09-18 that took every desk down for two hours, and
+ * nothing said so until a person read a failed run. The refresher's own
+ * comment had named the fix years of incidents earlier: stop shipping the
+ * token as an env var.
+ *
+ * So: when `FOLDRUN_MODEL_KEY_FILE` names a file (the Kubernetes secret,
+ * mounted rather than injected), it is read fresh every time. The kubelet
+ * updates a mounted secret in place within about a minute of it changing, so
+ * a refreshed token reaches the next step on its own, with no restart, no
+ * timing window, and nothing to skip while work is in flight.
+ *
+ * A missing or empty file falls back to the environment, which is what a
+ * local install, the CLI and every compose setup use.
+ */
+export declare function platformModelCredential(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function platformModelEnv(): Record<string, string | undefined>;
+/**
+ * `schema: <path>` — the file, read and parsed, or null. Agent-relative like
+ * every other path in a flow (`workspace/schemas/lead.json`), confined to the
+ * workspace: a schema is the author's document, never something a step
+ * can point outside.
+ */
+export declare function readSchemaFile(workspaceRoot: string, rel: string): Record<string, unknown> | boolean | null;
+export declare function createFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, status: "queued" | "running", tags?: string[], startedBy?: string | null, opts?: {
+    test?: boolean;
+}): RunRecord;
+export declare function startFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[], effortOverride?: string | null, startedBy?: string | null, opts?: {
+    test?: boolean;
+}): RunRecord;
 /**
  * Drive a run to completion: groups in order, approval gates, retries.
  *