@foldrun/core 0.2.0 → 0.4.0

package/dist/src/script-tools.d.ts

@@ -26,12 +26,24 @@ export interface ScriptSpec {
      *  default, `materialised`, is a program that reads values from its
      *  environment and needs them real — a browser seeding cookies. */
     secrets?: "proxied" | "materialised";
+    /** `outward: true` — this program makes something happen outside (sends,
+     *  posts, orders). On a test run a step that grants it is handed no real
+     *  secret at all, whatever their names. */
+    outward?: boolean;
+    /** `test_mode: allow` — a reader that happens to use a send-capable
+     *  secret's name (a GBP reader on a GBP token): on a test run the step
+     *  still gets the real values. An `outward` tool in the same step wins. */
+    testMode?: "allow";
 }
 export declare function parseScripts(raw: unknown): ScriptSpec[];
 export declare function commandFor(spec: ScriptSpec, abs: string, overrides?: Record<string, string>): {
     cmd: string;
     args: string[];
 };
+export declare function runScript(cwd: string, spec: ScriptSpec, values: Record<string, string>, env: Record<string, string>, libraryScripts: string, interpreters: Record<string, string>, exec: ExecutionContext | null): Promise<{
+    code: number | null;
+    out: string;
+}>;
 export interface ExecutionContext {
     /** "docker" nests each script in its own container; "sandbox" spawns it
      *  directly inside the isolation the step already has. */

package/dist/src/script-tools.js

@@ -19,6 +19,7 @@ import { spawn } from "node:child_process";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { runInContainer } from "./container.js";
+import { hostSafeEnv } from "./host-env.js";
 // A script's only clock is the `timeout:` its own tool.md declares. There
 // was a two-minute default and a ten-minute cap here; both were the
 // platform's opinion about how long a person's script may take, and the
@@ -55,6 +56,8 @@ export function parseScripts(raw) {
             args,
             interpreter: typeof e.interpreter === "string" ? e.interpreter : undefined,
             secrets: e.secrets === "proxied" ? "proxied" : undefined,
+            outward: e.outward === true ? true : undefined,
+            testMode: e.test_mode === "allow" ? "allow" : undefined,
             timeout: Number.isFinite(timeout) && timeout > 0 ? timeout : undefined,
         });
     }
@@ -96,7 +99,7 @@ function containerInterpreter(abs) {
     };
     return byExt[path.extname(abs).toLowerCase()] ?? abs;
 }
-function runScript(cwd, spec, values, env, libraryScripts, interpreters, exec) {
+export function runScript(cwd, spec, values, env, libraryScripts, interpreters, exec) {
     // An inline-code tool has no file yet: write it inside the agent's own
     // directory — already an allowed root — and run it like any other script.
     // Materialised per call rather than per build, so an edit to the tool's
@@ -188,9 +191,14 @@ function runScript(cwd, spec, values, env, libraryScripts, interpreters, exec) {
             }).then(resolve, (err) => resolve({ code: null, out: `container error: ${err instanceof Error ? err.message : String(err)}` }));
             return;
         }
+        // Not process.env: on a platform that is every tenant's root key and
+        // the datastore credentials. The child starts from the allowlisted
+        // base and gets what the agent declared, by name — see host-env.ts.
+        // In a run container `env` already carries the container's whole
+        // environment, which is the boundary, so nothing is lost there.
         const child = spawn(cmd, args, {
             cwd,
-            env: { ...process.env, ...env },
+            env: { ...hostSafeEnv(), ...env },
             timeout: timeoutFor(spec),
         });
         let out = "";

package/dist/src/secret-health.d.ts

@@ -0,0 +1,59 @@
+/** How a credential is identified here. A name alone is not enough: the
+ *  account and each workspace can hold a secret by the same name, and they
+ *  are different credentials with different health. */
+export declare function healthKey(name: string, scope: "account" | "workspace", workspace?: string | null): string;
+export interface SecretUse {
+    /** ISO time of the most recent use. */
+    at: string;
+    /** The host it was sent to, so "which of my four keys is this" has an
+     *  answer without opening a run. */
+    host: string;
+    /** The response status, when there was one. */
+    status: number | null;
+    /** Refused means the credential itself was rejected: 401, 402 or 403.
+     *  A 500 is the other end failing, which says nothing about the key. */
+    outcome: "accepted" | "refused" | "error";
+}
+export interface SecretRecord {
+    last: SecretUse;
+    /** Consecutive refusals, newest first — one is a fluke, five is a dead
+     *  key. Reset by any acceptance. */
+    refusals: number;
+    /** The last acceptance, kept through a run of refusals so a page can say
+     *  "worked until Tuesday", which is the sentence that dates the breakage. */
+    lastAccepted: string | null;
+}
+type HealthFile = Record<string, SecretRecord>;
+/** 401, 402 and 403 are the credential being refused. Everything else is
+ *  the request, the model or the provider — none of which is the key's
+ *  fault, and calling them a credential failure would send people to
+ *  rotate a key that was never the problem. */
+export declare function outcomeFor(status: number | null): SecretUse["outcome"];
+/**
+ * Record one use. `key` is a health key (see healthKey), never a bare name.
+ * Never throws and never blocks: the write is queued and happens off the
+ * caller's path, because this runs on every proxied request.
+ */
+export declare function noteSecretUse(tenant: string, key: string, use: {
+    host: string;
+    status: number | null;
+    at?: string;
+}): void;
+/** Wait for queued writes to land — for tests, and for a process that is
+ *  about to exit. */
+export declare function flushSecretHealth(): Promise<void>;
+/** Everything known about this account's credentials, by name. Names the
+ *  vault holds but nothing has used are simply absent, which is the honest
+ *  answer: unused is not the same as broken. */
+export declare function secretHealth(tenant: string): HealthFile;
+/** The credentials worth saying something about: refused the last time they
+ *  were used. Sorted worst first — most consecutive refusals, then oldest
+ *  last-success, which is the order someone would work through them. */
+export declare function failingSecrets(tenant: string): {
+    name: string;
+    record: SecretRecord;
+}[];
+/** Drop what is known about a secret — for a delete, and for a rotation,
+ *  where the old key's refusals say nothing about the new one. */
+export declare function forgetSecretHealth(tenant: string, name: string): void;
+export {};

package/dist/src/secret-health.js

@@ -0,0 +1,155 @@
+// Does this credential still work?
+//
+// The vault knows a secret's name, its scope and its shape. It knows nothing
+// about whether the thing on the other end still accepts it, and that is the
+// only question anyone actually has. A key that has quietly stopped working
+// looks identical to a key nobody has used yet, and both look identical to a
+// key that is fine — three very different situations rendered the same way.
+//
+// Two facts, recorded where they are already known and nowhere else:
+//
+//   when it was last used, and against which host
+//   what the other end said the last time — accepted, or refused
+//
+// The egress proxy sees both for every http tool and every model call,
+// because filling the credential is its whole job. Notifications and the
+// provider check report their own. Nothing new is instrumented, and a secret
+// materialised into a sandbox reports nothing, which the page says plainly
+// rather than guessing.
+//
+// Never the value, never a hash of the value, never the request body. A
+// name, a host, a status and a time.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { accountDir } from "./store.js";
+/** How a credential is identified here. A name alone is not enough: the
+ *  account and each workspace can hold a secret by the same name, and they
+ *  are different credentials with different health. */
+export function healthKey(name, scope, workspace) {
+    return scope === "workspace" && workspace ? `workspace:${workspace}:${name}` : `account:${name}`;
+}
+const healthFile = (tenant) => path.join(accountDir(tenant), "secret-health.json");
+function read(tenant) {
+    try {
+        return JSON.parse(fs.readFileSync(healthFile(tenant), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function write(tenant, data) {
+    const file = healthFile(tenant);
+    if (!fs.existsSync(path.dirname(file)))
+        return;
+    // pid alone is not unique across pods on a shared volume.
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file);
+}
+// Writes are queued and coalesced off the caller's path. The egress proxy
+// notes a use per secret per request, before it streams the response body,
+// and a synchronous read-modify-write of a JSON file there is latency on
+// every proxied call — "never blocks" has to be true, not aspirational.
+// One writer per process; the queue drains in order.
+const pending = new Map();
+let draining = false;
+function drain() {
+    if (draining)
+        return;
+    draining = true;
+    setImmediate(() => {
+        try {
+            for (const [tenant, uses] of pending) {
+                pending.delete(tenant);
+                const data = read(tenant);
+                for (const { name, use } of uses)
+                    apply(data, name, use);
+                write(tenant, data);
+            }
+        }
+        catch {
+            // best effort, always
+        }
+        finally {
+            draining = false;
+            if (pending.size)
+                drain();
+        }
+    });
+}
+function apply(data, name, use) {
+    const outcome = outcomeFor(use.status);
+    const at = use.at ?? new Date().toISOString();
+    const prev = data[name];
+    data[name] = {
+        last: { at, host: use.host, status: use.status, outcome },
+        // Only a refusal counts against a key. An error at the other end is
+        // the other end's problem and must not accumulate into a false alarm.
+        refusals: outcome === "refused" ? (prev?.refusals ?? 0) + 1 : outcome === "accepted" ? 0 : prev?.refusals ?? 0,
+        lastAccepted: outcome === "accepted" ? at : prev?.lastAccepted ?? null,
+    };
+}
+/** 401, 402 and 403 are the credential being refused. Everything else is
+ *  the request, the model or the provider — none of which is the key's
+ *  fault, and calling them a credential failure would send people to
+ *  rotate a key that was never the problem. */
+export function outcomeFor(status) {
+    if (status === null)
+        return "error";
+    if (status === 401 || status === 402 || status === 403)
+        return "refused";
+    if (status >= 200 && status < 400)
+        return "accepted";
+    return "error";
+}
+/**
+ * Record one use. `key` is a health key (see healthKey), never a bare name.
+ * Never throws and never blocks: the write is queued and happens off the
+ * caller's path, because this runs on every proxied request.
+ */
+export function noteSecretUse(tenant, key, use) {
+    if (!key)
+        return;
+    const list = pending.get(tenant) ?? [];
+    list.push({ name: key, use: { ...use, at: use.at ?? new Date().toISOString() } });
+    pending.set(tenant, list);
+    drain();
+}
+/** Wait for queued writes to land — for tests, and for a process that is
+ *  about to exit. */
+export function flushSecretHealth() {
+    return new Promise((resolve) => {
+        const check = () => (pending.size === 0 && !draining ? resolve() : setImmediate(check));
+        check();
+    });
+}
+/** Everything known about this account's credentials, by name. Names the
+ *  vault holds but nothing has used are simply absent, which is the honest
+ *  answer: unused is not the same as broken. */
+export function secretHealth(tenant) {
+    return read(tenant);
+}
+/** The credentials worth saying something about: refused the last time they
+ *  were used. Sorted worst first — most consecutive refusals, then oldest
+ *  last-success, which is the order someone would work through them. */
+export function failingSecrets(tenant) {
+    return Object.entries(read(tenant))
+        .filter(([, r]) => r.last.outcome === "refused")
+        .map(([name, record]) => ({ name, record }))
+        .sort((a, b) => b.record.refusals - a.record.refusals || (a.record.lastAccepted ?? "").localeCompare(b.record.lastAccepted ?? ""));
+}
+/** Drop what is known about a secret — for a delete, and for a rotation,
+ *  where the old key's refusals say nothing about the new one. */
+export function forgetSecretHealth(tenant, name) {
+    try {
+        const data = read(tenant);
+        if (!(name in data))
+            return;
+        delete data[name];
+        write(tenant, data);
+    }
+    catch {
+        // best effort
+    }
+}

package/dist/src/secrets.d.ts

@@ -1,5 +1,17 @@
 /** Which store a secret came from. */
 export type SecretScope = "account" | "workspace";
+/**
+ * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
+ * contents of `.secret-key` under the data root — created here, the first
+ * time anything asks, so there is never a moment when a derived token has
+ * nothing real to hang off. The vault, hook tokens, approval links and git
+ * push secrets all derive from this one value; rotating it invalidates every
+ * one of them together. Exported for webhook.ts, which used to fall back to
+ * a fixed dev string until the vault happened to create this file — so hook
+ * URLs were computable by anyone who read the source, and then changed the
+ * first time a secret was stored.
+ */
+export declare function installKeyMaterial(): string;
 /** How the stored value is used at run time — "oauth2"/"service-account"
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
@@ -102,7 +114,13 @@ export declare function isOAuth2Value(value: string): boolean;
  * refresh throws with the secret's name and the provider's reason — a run
  * should fail saying "GOOGLE_ADS_TOKEN: invalid_grant", not 401 somewhere.
  */
-export declare function materializeSecrets(env: Record<string, string>): Promise<Record<string, string>>;
+export declare function materializeSecrets(env: Record<string, string>, 
+/** Whose secrets these are, when the caller knows: lets the platform keep
+ *  each OAuth connection's health and quote a reconnect link on failure. */
+ctx?: {
+    tenant: string;
+    workspace?: string;
+}): Promise<Record<string, string>>;
 export interface ServiceAccountConfig {
     token_url: string;
     issuer: string;

package/dist/src/secrets.js

@@ -22,21 +22,46 @@ import fs from "node:fs";
 import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { platform } from "./platform.js";
+/**
+ * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
+ * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
+ * 12, 13, 14, 15 or 16 bytes — so a stored record whose tag had been cut to
+ * four bytes would still "verify" on 32 bits of authentication instead of
+ * 128. The tag comes from the record on disk; the record is the thing an
+ * attacker with file access would edit. One option makes a short tag an
+ * error rather than a weaker check.
+ */
+const GCM = { authTagLength: 16 };
 // The account's own data key, when the platform holds one; the install key
 // otherwise. See platform.ts — locally there is no account key.
 const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
+import { trimSlashes } from "./paths.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
-function masterKey() {
+/**
+ * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
+ * contents of `.secret-key` under the data root — created here, the first
+ * time anything asks, so there is never a moment when a derived token has
+ * nothing real to hang off. The vault, hook tokens, approval links and git
+ * push secrets all derive from this one value; rotating it invalidates every
+ * one of them together. Exported for webhook.ts, which used to fall back to
+ * a fixed dev string until the vault happened to create this file — so hook
+ * URLs were computable by anyone who read the source, and then changed the
+ * first time a secret was stored.
+ */
+export function installKeyMaterial() {
     const fromEnv = process.env.FOLDRUN_SECRET_KEY;
     if (fromEnv)
-        return crypto.createHash("sha256").update(fromEnv).digest();
+        return fromEnv;
     fs.mkdirSync(dataRoot(), { recursive: true });
     if (!fs.existsSync(keyFile())) {
         fs.writeFileSync(keyFile(), crypto.randomBytes(32).toString("hex"), { mode: 0o600 });
     }
-    return crypto.createHash("sha256").update(fs.readFileSync(keyFile(), "utf8")).digest();
+    return fs.readFileSync(keyFile(), "utf8");
+}
+function masterKey() {
+    return crypto.createHash("sha256").update(installKeyMaterial()).digest();
 }
 // `workspace` undefined means the account store.
 function secretsFile(tenant, workspace) {
@@ -98,7 +123,7 @@ function keyFor(tenant) {
 export function encryptValue(tenant, value) {
     const { key, mark } = keyFor(tenant);
     const iv = crypto.randomBytes(12);
-    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv, GCM);
     const enc = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
     return {
         iv: iv.toString("base64"),
@@ -134,7 +159,7 @@ function decrypt(tenant, rec) {
         else {
             key = masterKey();
         }
-        const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(rec.iv, "base64"));
+        const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(rec.iv, "base64"), GCM);
         decipher.setAuthTag(Buffer.from(rec.tag, "base64"));
         return Buffer.concat([
             decipher.update(Buffer.from(rec.data, "base64")),
@@ -279,7 +304,7 @@ export function rotateMasterKey(tenant, from, to) {
             }
             let plain;
             try {
-                const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"));
+                const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"), GCM);
                 d.setAuthTag(Buffer.from(rec.tag, "base64"));
                 plain = Buffer.concat([d.update(Buffer.from(rec.data, "base64")), d.final()]).toString("utf8");
             }
@@ -289,7 +314,7 @@ export function rotateMasterKey(tenant, from, to) {
                 continue;
             }
             const iv = crypto.randomBytes(12);
-            const c = crypto.createCipheriv("aes-256-gcm", newKey, iv);
+            const c = crypto.createCipheriv("aes-256-gcm", newKey, iv, GCM);
             const enc = Buffer.concat([c.update(plain, "utf8"), c.final()]);
             next[name] = {
                 iv: iv.toString("base64"),
@@ -376,7 +401,10 @@ async function exchange(config, cacheKey) {
  * refresh throws with the secret's name and the provider's reason — a run
  * should fail saying "GOOGLE_ADS_TOKEN: invalid_grant", not 401 somewhere.
  */
-export async function materializeSecrets(env) {
+export async function materializeSecrets(env, 
+/** Whose secrets these are, when the caller knows: lets the platform keep
+ *  each OAuth connection's health and quote a reconnect link on failure. */
+ctx) {
     const out = { ...env };
     for (const [name, value] of Object.entries(env)) {
         if (typeof value !== "string")
@@ -399,8 +427,12 @@ export async function materializeSecrets(env) {
                 out[name] = await exchange(config, `${name}:${config.client_id}:${fp}`);
             }
             catch (err) {
-                throw new Error(`secret ${name}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = err instanceof Error ? err.message : String(err);
+                const link = ctx ? await platform.noteOAuthRefresh(ctx, name, message).catch(() => undefined) : undefined;
+                throw new Error(`secret ${name}: ${message}${link ? ` — reconnect it in one click: ${link}` : ""}`);
             }
+            if (ctx)
+                await platform.noteOAuthRefresh(ctx, name, null).catch(() => undefined);
         }
         else if (value.startsWith(SERVICE_ACCOUNT_PREFIX)) {
             let config;
@@ -437,7 +469,7 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
         if (!config[field]?.trim())
             throw new Error(`service account secret needs ${field}`);
     }
-    if (!/BEGIN [A-Z ]*PRIVATE KEY/.test(config.private_key)) {
+    if (!/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM key (from the service account JSON)");
     }
     setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(config), workspace, "service-account");
@@ -534,7 +566,7 @@ export function setSshSecret(tenant, name, config, workspace) {
     const hasPassword = Boolean(config.password);
     if (hasKey === hasPassword)
         throw new Error("ssh secret needs a private key or a password (not both)");
-    if (hasKey && !/BEGIN [A-Z ]*PRIVATE KEY/.test(config.private_key)) {
+    if (hasKey && !/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM/OpenSSH private key");
     }
     if (hasPassword && /[\n\r]/.test(config.password))
@@ -571,7 +603,7 @@ export function setApiSecret(tenant, name, config, workspace) {
     const base = config.base_url?.trim();
     if (base && !/^https?:\/\//.test(base))
         throw new Error("base_url must be http(s)");
-    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: base.replace(/\/+$/, "") } : {}), headers: config.headers }), workspace, "api");
+    setSecret(tenant, name, API_PREFIX + JSON.stringify({ ...(base ? { base_url: trimSlashes(base) } : {}), headers: config.headers }), workspace, "api");
 }
 export function isApiValue(value) {
     return value.startsWith(API_PREFIX);

package/dist/src/starter.js

@@ -304,6 +304,7 @@ timezone: Australia/Sydney
 model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
+priority: normal         # high | normal | low — where its runs stand in the queue
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.
@@ -339,7 +340,10 @@ Indented under a step, any of:
 | \`preview: draft/*.mdx\` | what the approval box shows — paths under \`storage/\`, globs allowed |
 | \`delegate: [[a]], [[b]]\` | hand the step to whichever fits, up to 5 |
 | \`output: json\` | the reply ends with one JSON value; the next step gets it as data, \`each: items\` fans out over it |
+| \`schema: {...}\` | with \`output: json\` — the JSON Schema the value must satisfy; inline, a YAML block under the key, or a file path |
 | \`each: items\` | run once per element of the previous step's JSON array |
+| \`parallel: 3\` | how many \`each:\` instances run at once — default all |
+| \`max_turns: 20\` | the most model turns before the step is stopped, beside \`budget:\` and \`timeout:\` |
 
 ## Writing an agent
 

package/dist/src/step-exec.d.ts

@@ -1,5 +1,6 @@
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import type { TestEffect } from "./test-mode.ts";
 export interface ExecOutcome {
     status: "completed" | "failed";
     result: string | null;
@@ -43,6 +44,9 @@ export interface ExecOptions {
      *  The runner derives it from the flow's `budget:` and what the run has
      *  already spent; absent means no ceiling on this step. */
     budgetUsd?: number | null;
+    /** Which line set the ceiling, for the error that names it — "budget: in
+     *  the flow file" or "budget: on the <agent> agent". */
+    budgetNote?: string;
     /** Price per token for the model, when the catalogue knows it, so spend
      *  can be counted turn by turn instead of learned at the end. Without it
      *  the step prices its turns from the SDK's own running total. */
@@ -58,28 +62,64 @@ export interface ExecOptions {
     /** `output: json` — the reply must carry one JSON value; extracting it is
      *  part of finishing the step, and failing to is failing the step. */
     output?: "json";
+    /** `schema:` — what that value must look like; a value that does not fit
+     *  fails the step naming the field. See json-schema.ts. */
+    schema?: Record<string, unknown> | boolean;
+    /** `max_turns:` — the most model turns before the step is stopped. The
+     *  SDK enforces it; the step reads the result's reason and says so. */
+    maxTurns?: number;
     /** false when the caller is already an isolation boundary (a run
      *  container): the SDK's bash sandbox is then redundant and would block
      *  declared network use. Default (undefined/true) keeps it on. */
     sandboxBash?: boolean;
+    /** Has a person asked for the run to stop? Polled every couple of
+     *  seconds while the model loop runs; true interrupts it. The in-process
+     *  runner answers from the run record (stopRun writes there from another
+     *  process); a container has a sandbox that is destroyed instead. */
+    stopRequested?: () => boolean;
     emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
 }
+/** How often the stop flag is read while a step runs. */
+export declare const STOP_POLL_MS = 2000;
+/** After an interrupt is asked for, how long the model loop gets to wind
+ *  down on its own before the query is aborted outright. */
+export declare const INTERRUPT_GRACE_MS = 10000;
+/** The model loop, as executeStep needs it — the SDK's `query`, or a test's
+ *  stand-in. Only the shape the loop reads. */
+export type QueryLike = AsyncIterable<unknown> & {
+    interrupt(): Promise<unknown>;
+};
+export type QueryFn = (args: {
+    prompt: string;
+    options: Record<string, unknown>;
+}) => QueryLike;
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
 export type EventExtra = {
     call?: string;
     ms?: number;
     err?: boolean;
+    effect?: TestEffect;
 };
-/** Conservative per-token rates for a model the catalogue cannot price —
- *  Opus-class — so a ceiling still means something on an unknown gateway. */
+/** Conservative per-token rates for a model nothing else can price — an
+ *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
+ *  still means something. Only ever reached when `knownPrice` below does
+ *  not recognise the model either. */
 export declare const FALLBACK_PRICE: {
     input: number;
     output: number;
 };
+/** What a token costs on this model, when we can say without a catalogue. */
+export declare function knownPrice(model: string | undefined): {
+    input: number;
+    output: number;
+} | null;
 /**
- * What one assistant turn cost. Cache traffic is counted as input at the
- * input rate, which over-approximates on gateways with cheaper cache reads
- * — on the money side, the honest direction to be wrong in. Pure.
+ * What one assistant turn cost, from the usage the SDK reports. Pure.
+ *
+ * A gateway whose cache is priced differently is over- or under-counted
+ * here by that difference alone; the run record's own cost is repriced
+ * from the catalogue afterwards and stays the authority on the bill. This
+ * number exists to stop a runaway step mid-turn, and wants to be close.
  */
 export declare function priceTurn(u: Record<string, number | undefined>, price: {
     input: number;
@@ -91,7 +131,23 @@ export declare function priceTurn(u: Record<string, number | undefined>, price:
  * over the cap however many steps it fans out to. No budget, no ceiling.
  */
 export declare function stepCeiling(budgetUsd: number | null | undefined, spentUsd: number, launching: number): number | null;
-export declare function executeStep(opts: ExecOptions): Promise<ExecOutcome>;
+/**
+ * The ceiling a step actually runs under, and which line set it.
+ *
+ * Two caps can apply to one step: the flow's `budget:` gives it an equal
+ * share of what the run has left; the agent's own `budget:` is the most that
+ * agent may spend in one run, less what its earlier steps in this run cost.
+ * The tighter one wins, and the note says which, because "over budget" with
+ * no line to go and raise is a message that sends someone to the wrong file.
+ */
+export declare function stepCeilingFor(flowShareUsd: number | null, agentBudgetUsd: number | null | undefined, agentSpentUsd: number, agent: string): {
+    ceilingUsd: number | null;
+    note: string;
+};
+export declare function executeStep(opts: ExecOptions, 
+/** The model loop. Injected so the clock and the stop can be tested
+ *  without a model; production passes nothing and gets the SDK. */
+runQuery?: QueryFn): Promise<ExecOutcome>;
 /**
  * The one JSON value a reply carries. A ```json fence wins — it is what the
  * step was asked to write — and the LAST one at that, because a model that