@foldrun/core 0.4.0 → 0.6.0

package/dist/src/runner.d.ts

@@ -1,4 +1,12 @@
+import { type SubagentSpec } from "./subagents.ts";
 import { type FlowStep, type RunRecord, type StepRecord } from "./store.ts";
+import { type Catalog } from "./catalog.ts";
+import { type ScriptSpec } from "./script-tools.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;
@@ -48,20 +56,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.
  *
@@ -69,6 +130,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.
@@ -113,6 +191,14 @@ 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.
  *
@@ -123,10 +209,29 @@ export declare function resolveDocLinks(text: string, workspaceRoot: string): st
  * 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, n: number, status: "completed" | "failed", startedAt: string, eventsBefore: number, 
+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.
  *
@@ -140,6 +245,13 @@ reattach?: boolean): void;
  * 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. */
@@ -157,9 +269,31 @@ export declare const OVERLOAD_RETRIES = 3;
  */
 export declare function isTransientOverload(text: string): boolean;
 export declare function backoffMs(attempt: number, text?: string, random?: () => number): number;
+/**
+ * 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 (`../../schemas/lead.json`), confined to the
+ * 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.
  */
@@ -275,3 +409,37 @@ export declare function waitForRun(tenant: string, workspace: string, runId: str
  * nothing is what makes `?wait=true` useful rather than merely blocking.
  */
 export declare function runResult(run: RunRecord): string | null;
+/**
+ * What a Docker-run script sees of the workspace and the account: their
+ * scripts/ and their tools/, read-only. A folder tool's code lives in its
+ * tools/<name>/ folder, not in scripts/ — without those two mounts every
+ * folder tool (the hello template's wordcount among them) was handed a host
+ * path the container did not have, and failed on every call. A gallery tool
+ * nobody installed runs from the gallery's own shelf, so that is mounted too
+ * when there is one. A folder that does not exist is skipped by the copy.
+ */
+export declare function scriptMounts(agentDir: string, tenant: string): Record<string, string>;
+/**
+ * The skills an agent can see, nearest first, each with the path the agent
+ * is told to read it at. Own skills, then the workspace's, then the
+ * workspace's `.agents/skills/` (the cross-client convention, scanned after
+ * the native location so a foldrun-native skill wins a name clash), then the
+ * account library. The nearest definition of a name wins.
+ *
+ * The workspace's are written `workspace/skills/…`, the one spelling for the
+ * workspace root, which the file tools expand themselves. `../../skills/…`
+ * left the model to resolve it against a path it had to guess, and on the
+ * hello template it climbed one level too far and was refused.
+ */
+export declare function skillsInScope(agentDir: string, tenant: string): DiscoveredSkill[];
+/**
+ * The interpreters a set of scripts needs, read from what they are: the
+ * extension of `run:` (or of inline code), or an explicit `interpreter:`.
+ * Docker's script image is built from the runtime spec, and the base one is
+ * Python only, so a JavaScript tool that declared no `runtime:` (the demo's
+ * inline crm-upload, any folder tool's run.mjs) failed with no node to run
+ * it. Python is named too whenever a .py script is present, because asking
+ * for node alone builds on node:22-slim, which has no python3. Null when
+ * nothing beyond the default is needed.
+ */
+export declare function scriptLanguages(scripts: ScriptSpec[]): RuntimeSpec | null;