@yycholla/pi-dynamic-workflows 3.3.0

package/dist/model-tier-config.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Model tier configuration for workflow subagent model routing.
+ *
+ * A tier is a named slot (small/medium/big) holding exactly ONE model spec
+ * string (e.g. "openai/gpt-4.1-mini" or "openai-codex/gpt-5.5:xhigh").
+ * When an agent() call specifies opts.tier, that single model is resolved with
+ * Pi CLI-style parsing and used as the subagent's model/thinking level (unless
+ * an explicit opts.model is given, which always wins — see agent.ts).
+ *
+ * This augments the phase-pattern routing in model-routing.ts: phase routing
+ * maps workflow phases → models via the script's meta; tiers give scripts a
+ * coarse, user-configurable small/medium/big knob that is independent of any
+ * concrete provider/model id.
+ */
+/**
+ * Model tier configuration. Maps tier names (e.g. "small", "medium", "big")
+ * to a single model spec string (e.g. "gpt-4.1-mini", "openai/gpt-4.1-mini",
+ * or "openai-codex/gpt-5.5:xhigh").
+ */
+export interface ModelTierConfig {
+    tiers: Record<string, string>;
+}
+/**
+ * The minimal projection of a model that tier ranking needs. Deliberately NOT
+ * the SDK's full `Model` type: tier logic depends only on these three fields,
+ * so it stays decoupled from the SDK (no `@earendil-works/pi-ai` import here)
+ * and is trivially unit-testable with plain objects. `agent.ts`'s
+ * `listAvailableModels()` produces these from the live registry.
+ */
+export interface RankableModel {
+    /** Canonical "provider/id" spec string. */
+    spec: string;
+    /** Per-token output price, if the registry reports one. Missing or 0 = unknown. */
+    costOutput?: number;
+    /** Context window size, if the registry reports one. */
+    contextWindow?: number;
+}
+/** Path to the model tiers JSON config file (~/.pi/workflows/model-tiers.json). */
+export declare function getModelTierConfigPath(): string;
+/**
+ * Substrings that identify small/cheap models (case-insensitive), used only as
+ * a fallback capability hint when price signals are absent or tied.
+ */
+export declare const SMALL_MODEL_HINTS: readonly ["mini", "flash", "haiku", "nano", "small"];
+/**
+ * Substrings that identify large/capable models (case-insensitive), used only
+ * as a fallback capability hint when price signals are absent or tied.
+ */
+export declare const BIG_MODEL_HINTS: readonly ["opus", "pro", "ultra", "large", "plus"];
+/**
+ * Fallback capability hint from a model's name: -1 for a small/cheap name, +1
+ * for a large/capable name, 0 otherwise. If a name matches both sets, the small
+ * hint wins (we never want a "mini"-labelled model to outrank a neutral or
+ * clearly-large one). This is only a FALLBACK: `rankByCapability` prefers the
+ * registry's price signal, which is robust to new vendor names (e.g. "fable",
+ * "mimo") that match no hint and would otherwise all score 0.
+ */
+export declare function hintScore(spec: string): number;
+/**
+ * Rank models from least → most capable.
+ *
+ * PRIMARY signal is output price (higher price ≈ more capable): within a single
+ * registry, price tracks the vendor's capability tier far more robustly than
+ * model-name substrings, and it works for models whose names match no hint.
+ *
+ * Models with an UNKNOWN price (missing or 0 — common for self-hosted
+ * `models.json` entries) are NOT treated as "cheapest = weakest". Instead they
+ * are projected onto the known price range via their substring hint: a
+ * big-hint name lands at the top of the range, a small-hint name at the bottom,
+ * a neutral name at the middle. When NO model has a known price at all, this
+ * degrades to pure hint ordering (the previous behavior).
+ *
+ * The comparison is a single total order (projected cost → hint → contextWindow
+ * → stable registry index), so the sort is transitive and stable.
+ */
+export declare function rankByCapability(models: readonly RankableModel[]): RankableModel[];
+/**
+ * Build a default tier config. When the available model registry is known,
+ * spread it across tiers so small/medium/big routing is meaningful out of the
+ * box. When the registry is empty or unavailable, fall back to the current Pi
+ * model so fresh installs still get usable tier values.
+ *
+ * Models are first ranked least → most capable via `rankByCapability` (price
+ * first, name-substring hint as fallback). Tiers are then assigned from this
+ * single ranked pool with exclusion — each model is used for at most one tier —
+ * so distinct tiers never collapse onto the same model and a weaker model can
+ * never outrank a stronger one (no inversion):
+ *
+ *   - big    = the most capable model (last in the ranking)
+ *   - small  = the least capable model (first in the ranking)
+ *   - medium = the middle-ranked model
+ *
+ * When fewer than 3 distinct models are available, this degrades gracefully by
+ * reusing the *strongest* available model for the higher tier(s):
+ *
+ *   - 2 models: small = weaker, medium = big = stronger
+ *   - 1 / 0 models: small = medium = big = that model (or the current model /
+ *     "" fallback)
+ *
+ * `availableModels` is injectable for testing and for callers that already
+ * fetched the registry. When omitted, this reads from the live registry.
+ */
+export declare function buildDefaultTierConfig(currentModelSpec?: string, availableModels?: readonly RankableModel[]): ModelTierConfig;
+/**
+ * One-time notice shown when an agent requests `opts.tier` but no
+ * model-tiers.json is configured — in that state tiers silently fall back to
+ * the session model (see `resolveAgentModelSpec` in agent.ts), which is easy to
+ * miss. This surfaces the fallback and the mapping the user *would* get by
+ * configuring, using the same `buildDefaultTierConfig` ranking so the hint is
+ * actionable. Pure/string-only so the caller owns how it's emitted.
+ */
+export declare function formatTierFallbackNotice(mainModel: string | undefined, availableModels: readonly RankableModel[]): string;
+/**
+ * Load the model tier config from disk. Returns null if the file does not
+ * exist or is unparseable (callers fall back to a default).
+ */
+export declare function loadModelTierConfig(configPath?: string): ModelTierConfig | null;
+/**
+ * Save a model tier config to disk. Creates parent directories if needed.
+ *
+ * Refuses a degenerate `tiers` (e.g. all-empty-string, from buildDefaultTierConfig
+ * with an empty model registry) using the same isValidTiersMap check the loader
+ * uses — otherwise the write side could produce exactly the shape loadModelTierConfig
+ * now rejects on the next read, silently discarding the "saved" config.
+ */
+export declare function saveModelTierConfig(config: ModelTierConfig, configPath?: string): void;
+/**
+ * Resolve a tier name to its configured model spec, or undefined if the tier
+ * is not configured.
+ */
+export declare function resolveTierModel(tier: string, config: ModelTierConfig): string | undefined;
+/** Return all tier names sorted: small < medium < big, then alphabetically. */
+export declare function sortedTierNames(config: ModelTierConfig): string[];

package/dist/model-tier-config.js

@@ -0,0 +1,249 @@
+/**
+ * Model tier configuration for workflow subagent model routing.
+ *
+ * A tier is a named slot (small/medium/big) holding exactly ONE model spec
+ * string (e.g. "openai/gpt-4.1-mini" or "openai-codex/gpt-5.5:xhigh").
+ * When an agent() call specifies opts.tier, that single model is resolved with
+ * Pi CLI-style parsing and used as the subagent's model/thinking level (unless
+ * an explicit opts.model is given, which always wins — see agent.ts).
+ *
+ * This augments the phase-pattern routing in model-routing.ts: phase routing
+ * maps workflow phases → models via the script's meta; tiers give scripts a
+ * coarse, user-configurable small/medium/big knob that is independent of any
+ * concrete provider/model id.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { listAvailableModels } from "./agent.js";
+import { MODEL_TIERS_FILE } from "./config.js";
+// ---------------------------------------------------------------------------
+// Configuration path
+// ---------------------------------------------------------------------------
+/** Path to the model tiers JSON config file (~/.pi/workflows/model-tiers.json). */
+export function getModelTierConfigPath() {
+    return join(homedir(), MODEL_TIERS_FILE);
+}
+// ---------------------------------------------------------------------------
+// Capability signal
+// ---------------------------------------------------------------------------
+/**
+ * Substrings that identify small/cheap models (case-insensitive), used only as
+ * a fallback capability hint when price signals are absent or tied.
+ */
+export const SMALL_MODEL_HINTS = ["mini", "flash", "haiku", "nano", "small"];
+/**
+ * Substrings that identify large/capable models (case-insensitive), used only
+ * as a fallback capability hint when price signals are absent or tied.
+ */
+export const BIG_MODEL_HINTS = ["opus", "pro", "ultra", "large", "plus"];
+/**
+ * Fallback capability hint from a model's name: -1 for a small/cheap name, +1
+ * for a large/capable name, 0 otherwise. If a name matches both sets, the small
+ * hint wins (we never want a "mini"-labelled model to outrank a neutral or
+ * clearly-large one). This is only a FALLBACK: `rankByCapability` prefers the
+ * registry's price signal, which is robust to new vendor names (e.g. "fable",
+ * "mimo") that match no hint and would otherwise all score 0.
+ */
+export function hintScore(spec) {
+    const lower = spec.toLowerCase();
+    if (SMALL_MODEL_HINTS.some((hint) => lower.includes(hint)))
+        return -1;
+    if (BIG_MODEL_HINTS.some((hint) => lower.includes(hint)))
+        return 1;
+    return 0;
+}
+/**
+ * Rank models from least → most capable.
+ *
+ * PRIMARY signal is output price (higher price ≈ more capable): within a single
+ * registry, price tracks the vendor's capability tier far more robustly than
+ * model-name substrings, and it works for models whose names match no hint.
+ *
+ * Models with an UNKNOWN price (missing or 0 — common for self-hosted
+ * `models.json` entries) are NOT treated as "cheapest = weakest". Instead they
+ * are projected onto the known price range via their substring hint: a
+ * big-hint name lands at the top of the range, a small-hint name at the bottom,
+ * a neutral name at the middle. When NO model has a known price at all, this
+ * degrades to pure hint ordering (the previous behavior).
+ *
+ * The comparison is a single total order (projected cost → hint → contextWindow
+ * → stable registry index), so the sort is transitive and stable.
+ */
+export function rankByCapability(models) {
+    const knownCosts = models
+        .map((m) => m.costOutput)
+        .filter((c) => typeof c === "number" && c > 0)
+        .sort((a, b) => a - b);
+    const hasPriceSignal = knownCosts.length > 0;
+    const min = knownCosts[0];
+    const max = knownCosts[knownCosts.length - 1];
+    const median = knownCosts[Math.floor(knownCosts.length / 2)];
+    // Project every model onto the price axis. Undefined only when there is no
+    // price signal anywhere (all models unpriced) — then the sort falls through
+    // to the hint comparison below.
+    const costKey = (m) => {
+        if (typeof m.costOutput === "number" && m.costOutput > 0)
+            return m.costOutput;
+        if (!hasPriceSignal)
+            return undefined;
+        const hint = hintScore(m.spec);
+        return hint > 0 ? max : hint < 0 ? min : median;
+    };
+    return models
+        .map((m, index) => ({ m, index, cost: costKey(m), hint: hintScore(m.spec), ctx: m.contextWindow ?? 0 }))
+        .sort((a, b) => {
+        if (a.cost !== undefined && b.cost !== undefined && a.cost !== b.cost)
+            return a.cost - b.cost;
+        if (a.hint !== b.hint)
+            return a.hint - b.hint;
+        if (a.ctx !== b.ctx)
+            return a.ctx - b.ctx;
+        return a.index - b.index;
+    })
+        .map((entry) => entry.m);
+}
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+/**
+ * Build a default tier config. When the available model registry is known,
+ * spread it across tiers so small/medium/big routing is meaningful out of the
+ * box. When the registry is empty or unavailable, fall back to the current Pi
+ * model so fresh installs still get usable tier values.
+ *
+ * Models are first ranked least → most capable via `rankByCapability` (price
+ * first, name-substring hint as fallback). Tiers are then assigned from this
+ * single ranked pool with exclusion — each model is used for at most one tier —
+ * so distinct tiers never collapse onto the same model and a weaker model can
+ * never outrank a stronger one (no inversion):
+ *
+ *   - big    = the most capable model (last in the ranking)
+ *   - small  = the least capable model (first in the ranking)
+ *   - medium = the middle-ranked model
+ *
+ * When fewer than 3 distinct models are available, this degrades gracefully by
+ * reusing the *strongest* available model for the higher tier(s):
+ *
+ *   - 2 models: small = weaker, medium = big = stronger
+ *   - 1 / 0 models: small = medium = big = that model (or the current model /
+ *     "" fallback)
+ *
+ * `availableModels` is injectable for testing and for callers that already
+ * fetched the registry. When omitted, this reads from the live registry.
+ */
+export function buildDefaultTierConfig(currentModelSpec, availableModels) {
+    const models = availableModels ?? listAvailableModels();
+    const ranked = rankByCapability(models).map((m) => m.spec);
+    if (ranked.length >= 3) {
+        const small = ranked[0];
+        const big = ranked[ranked.length - 1];
+        const medium = ranked[Math.floor(ranked.length / 2)];
+        return { tiers: { small, medium, big } };
+    }
+    if (ranked.length === 2) {
+        const [weaker, stronger] = ranked;
+        return { tiers: { small: weaker, medium: stronger, big: stronger } };
+    }
+    const fallback = ranked[0] ?? currentModelSpec ?? "";
+    return {
+        tiers: {
+            small: fallback,
+            medium: fallback,
+            big: fallback,
+        },
+    };
+}
+/**
+ * One-time notice shown when an agent requests `opts.tier` but no
+ * model-tiers.json is configured — in that state tiers silently fall back to
+ * the session model (see `resolveAgentModelSpec` in agent.ts), which is easy to
+ * miss. This surfaces the fallback and the mapping the user *would* get by
+ * configuring, using the same `buildDefaultTierConfig` ranking so the hint is
+ * actionable. Pure/string-only so the caller owns how it's emitted.
+ */
+export function formatTierFallbackNotice(mainModel, availableModels) {
+    const fallback = mainModel ?? "the session default model";
+    const suggested = buildDefaultTierConfig(mainModel, availableModels);
+    const mapping = sortedTierNames(suggested)
+        .map((tier) => `${tier}=${suggested.tiers[tier] || "?"}`)
+        .join("  ");
+    return (`[workflow] An agent requested opts.tier but no model-tiers.json is configured, so tiers currently ` +
+        `fall back to ${fallback}. Run /workflows-models to configure them` +
+        (mapping ? `. Suggested mapping from your available models: ${mapping}` : "."));
+}
+// ---------------------------------------------------------------------------
+// Load / Save
+// ---------------------------------------------------------------------------
+/**
+ * True iff `value` is a usable tiers map: a plain (non-array) object with at
+ * least one entry, every key and value a non-empty string. Anything else
+ * (an array, `{}`, or a tier mapped to `""`) is treated as absent rather than
+ * a truthy-but-broken config — resolveTierModel would silently resolve such
+ * entries to `undefined`/`""` while the caller's "no model-tiers.json
+ * configured" warning only fires on an exactly-null config.
+ */
+function isValidTiersMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return false;
+    return entries.every(([key, val]) => key.trim().length > 0 && typeof val === "string" && val.trim().length > 0);
+}
+/**
+ * Load the model tier config from disk. Returns null if the file does not
+ * exist or is unparseable (callers fall back to a default).
+ */
+export function loadModelTierConfig(configPath) {
+    const path = configPath ?? getModelTierConfigPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (!isValidTiersMap(parsed.tiers))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save a model tier config to disk. Creates parent directories if needed.
+ *
+ * Refuses a degenerate `tiers` (e.g. all-empty-string, from buildDefaultTierConfig
+ * with an empty model registry) using the same isValidTiersMap check the loader
+ * uses — otherwise the write side could produce exactly the shape loadModelTierConfig
+ * now rejects on the next read, silently discarding the "saved" config.
+ */
+export function saveModelTierConfig(config, configPath) {
+    if (!isValidTiersMap(config?.tiers)) {
+        throw new Error("Refusing to save a degenerate model tier config: tiers must be a non-empty map of tier name to a non-empty model spec string.");
+    }
+    const path = configPath ?? getModelTierConfigPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2), "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Resolve / helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a tier name to its configured model spec, or undefined if the tier
+ * is not configured.
+ */
+export function resolveTierModel(tier, config) {
+    return config.tiers[tier];
+}
+/** Return all tier names sorted: small < medium < big, then alphabetically. */
+export function sortedTierNames(config) {
+    const names = Object.keys(config.tiers);
+    const rank = { small: 0, medium: 1, big: 2 };
+    return names.sort((a, b) => (rank[a] ?? 99) - (rank[b] ?? 99) || a.localeCompare(b));
+}

package/dist/run-persistence.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Workflow run state persistence for pause/resume support.
+ */
+import type { AgentUsage } from "./agent.js";
+import type { AgentHistoryEntry } from "./agent-history.js";
+import type { WorkflowErrorCode } from "./errors.js";
+import { type PersistenceFsLayer } from "./fs-persistence.js";
+export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "aborted";
+export interface PersistedAgentState {
+    id: number;
+    /** Runtime call identity (`${runId}:${callIndex}`), used to rehydrate journaled results. */
+    callId?: string;
+    label: string;
+    phase?: string;
+    prompt: string;
+    status: "queued" | "running" | "done" | "error" | "skipped";
+    result?: unknown;
+    /** Compact result written by releases before full agent results were retained. */
+    resultPreview?: string;
+    error?: string;
+    errorCode?: WorkflowErrorCode;
+    recoverable?: boolean;
+    history?: AgentHistoryEntry[];
+    startedAt?: string;
+    endedAt?: string;
+    /** Tokens used by this agent (a scalar estimate when the provider reports no usage). */
+    tokens?: number;
+    /** Per-agent token usage breakdown, when the provider reported one. */
+    tokenUsage?: AgentUsage;
+    /** The model this agent ran on (provider/id), when known. */
+    model?: string;
+}
+export interface PersistedRunState {
+    runId: string;
+    workflowName: string;
+    script: string;
+    args?: unknown;
+    /** The pi session this run belongs to. Runs persist on disk across sessions but
+     * the navigator shows only the current session's runs (undefined = legacy/global). */
+    sessionId?: string;
+    status: RunStatus;
+    /** Why a paused run is paused (e.g. "usage_limit" when a provider quota was hit). */
+    pauseReason?: string;
+    /** Provider reset hint for a usage-limit pause, e.g. "Resets in ~3h" (verbatim). */
+    resetHint?: string;
+    phases: string[];
+    currentPhase?: string;
+    agents: PersistedAgentState[];
+    logs: string[];
+    result?: unknown;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+        cost?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+    };
+    /**
+     * Cached agent/checkpoint results for resume, keyed by deterministic call
+     * index. `runId` namespaces `index` (a nested workflow() call restarts its
+     * own callSeq at 0) — absent on journals persisted before that namespacing
+     * existed; see JournalEntry.runId in workflow.ts for the resume-time
+     * legacy-degradation behavior. `storeDelta` is this call's SharedStore
+     * write delta, replayed additively on resume.
+     */
+    journal?: Array<{
+        index: number;
+        runId?: string;
+        hash: string;
+        result: unknown;
+        storeDelta?: Record<string, unknown>;
+    }>;
+    /**
+     * Opt-out of auto-resume for this run (default true, i.e. eligible unless
+     * explicitly set to false via ExecOptions.autoResume). Set once at run start
+     * and carried through resumes; see UsageLimitScheduler.
+     */
+    autoResume?: boolean;
+    /**
+     * The run's resolved hard token budget, fixed at start (per-run value, else
+     * the manager default at the time). Resume re-applies THIS value — never the
+     * current default — so an explicit no-budget (`null`) or custom cap survives
+     * a pause/resume cycle. Absent on legacy runs (resumed unbudgeted).
+     */
+    tokenBudget?: number | null;
+    /**
+     * Named toolset tag (WorkflowManagerOptions.toolsets). ToolDefinitions are
+     * functions and can't be serialized, so this tag is how a resumed run (e.g.
+     * /deep-research with web tools) re-resolves the tool set it started with.
+     */
+    toolset?: string;
+    /**
+     * The run's resolved cap on total agents, fixed at start (per-run value,
+     * else undefined so runWorkflow applies its own MAX_AGENTS_PER_RUN default).
+     * Resume re-applies THIS value — never the manager's current default — same
+     * rationale as tokenBudget. Absent on legacy runs (resumed with no cap
+     * carried forward, i.e. runWorkflow's own default applies).
+     */
+    maxAgents?: number;
+    /**
+     * The run's resolved per-agent timeout, fixed at start (per-run value, else
+     * the manager default at the time). Absent on legacy runs — unlike
+     * tokenBudget, a legacy run's real timeout was never "no timeout" by
+     * omission; it was always the manager's default (pre-A1 resume always fell
+     * back to it), so resume applies the manager's CURRENT default for such
+     * runs rather than null, preserving both the run's original semantics and
+     * pre-fix resume behavior.
+     */
+    agentTimeoutMs?: number | null;
+    /**
+     * The run's resolved concurrency, fixed at start (per-run value, else the
+     * manager's concurrency at the time). Same rationale as tokenBudget.
+     */
+    concurrency?: number;
+    /**
+     * The run's resolved agent-retry count, fixed at start (per-run value, else
+     * the manager default at the time). Same rationale as tokenBudget.
+     */
+    agentRetries?: number;
+    /**
+     * Auto-resume attempt counter for the current usage_limit pause-cycle, owned
+     * and persisted by UsageLimitScheduler (best-effort). Absent/0 means no
+     * auto-resume attempt has been recorded yet.
+     */
+    autoResumeAttempts?: number;
+}
+export interface RunPersistence {
+    /** Save current run state. */
+    save(state: PersistedRunState): void;
+    /** Load a persisted run by ID. */
+    load(runId: string): PersistedRunState | null;
+    /** List all persisted runs. */
+    list(): PersistedRunState[];
+    /** Delete a persisted run. */
+    delete(runId: string): boolean;
+    /**
+     * Acquire an exclusive cross-process lease for a run. Returns null when another
+     * live process owns the run; stale/corrupt lock files are removed and retried.
+     */
+    acquireRunLease(runId: string): RunLease | null;
+    /** Release a lease previously returned by acquireRunLease(). */
+    releaseRunLease(lease: RunLease): void;
+    /** Get runs directory path. */
+    getRunsDir(): string;
+}
+export interface RunLease {
+    runId: string;
+    token: string;
+}
+/**
+ * Filesystem operations used by run persistence.
+ * Exposed for testing – pass overrides to inject mock implementations.
+ * (Alias of the shared PersistenceFsLayer — see fs-persistence.ts.)
+ */
+export type FsLayer = PersistenceFsLayer;
+/**
+ * Retention policy for terminal (completed/failed/aborted) runs kept on
+ * disk. Bounded so a long-lived project directory can't accumulate an
+ * unbounded number of run files (each polled/listed on every list() call).
+ * A run in "running" or "paused" status is NEVER counted against this cap
+ * or evicted by it — only genuinely finished runs age out, oldest (by
+ * updatedAt) first, once the terminal-run count exceeds the cap. 300 is
+ * generous enough to cover weeks of typical usage while keeping list()'s
+ * per-call directory scan bounded.
+ */
+export declare const DEFAULT_MAX_TERMINAL_RUNS_ON_DISK = 300;
+export interface RunPersistenceOptions {
+    /** Override DEFAULT_MAX_TERMINAL_RUNS_ON_DISK (tests; advanced tuning). */
+    maxTerminalRunsOnDisk?: number;
+}
+export declare function createRunPersistence(cwd: string, fsOverride?: Partial<FsLayer>, options?: RunPersistenceOptions): RunPersistence;
+/**
+ * Generate a unique run ID.
+ */
+export declare function generateRunId(): string;