@foldrun/core 0.2.0

package/dist/src/runner.d.ts

@@ -0,0 +1,241 @@
+import { type FlowStep, type RunRecord } from "./store.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;
+/** tools: [desks] — how many other-workspace runs cross into a step, in all. */
+export declare const DESK_RUNS_CAP = 100;
+/**
+ * What a group is handed from the groups before it: all of them, oldest
+ * first, so a group-3 reporter sees what group 1 measured and not only what
+ * group 2 diagnosed. When the total is over the cap, the oldest groups are
+ * dropped whole before anything is cut mid-text — the newest is the one the
+ * step is most likely to be about.
+ */
+export declare function joinEarlierGroups(groupResults: (string | null)[], gi: number, cap?: number): string | null;
+export interface DiscoveredSkill {
+    name: string;
+    description: string;
+    /** Tags that must be present on the run for this skill to load. A skill
+     *  with none always loads. Mirrors "apply when this check failed". */
+    when: string[];
+    /** Path to SKILL.md (or the flat .md), relative to the agent directory. */
+    path: string;
+    /** Skill folder relative to the agent directory, or null for flat skills. */
+    dir: string | null;
+    hasScripts: boolean;
+    /** The rest of the Agent Skills layout: references/ and assets/. */
+    hasReferences: boolean;
+    hasAssets: boolean;
+}
+export declare function discoverSkills(agentDir: string, subdir?: string): DiscoveredSkill[];
+/**
+ * AGENTS.md, at both scopes it can live at.
+ *
+ * `AGENTS.md` is the Linux Foundation name; `project.md` is still read so
+ * nothing written before the rename breaks.
+ *
+ * Returns null rather than throwing on unparseable YAML: a broken shared file
+ * must not take down every agent under it.
+ */
+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.
+ */
+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 prose from AGENTS.md, outermost first.
+ *
+ * This was written by every scaffold, shown in the dashboard, described in the
+ * template as "context every agent here shares" — and never read. Only the
+ * frontmatter was, so the instructions people actually wrote reached no model.
+ */
+export declare function sharedInstructions(agentDir: string, tenant: string): string | null;
+/**
+ * Which of an agent's in-scope skills load for this run.
+ *
+ * Two independent gates: `skills:` in the agent's frontmatter is an allowlist
+ * (absent means everything in scope), and a skill's own `when:` names the run
+ * tags it is for (absent means every run).
+ *
+ * Note what an empty `tags` means — a skill with `when:` matches nothing, so
+ * an untagged run gets none of them. That is the intent, and it is also why
+ * failing to thread the run's tags this far made every `when:` skill
+ * permanently invisible instead of conditionally loaded.
+ */
+export declare function applicableSkills<T extends {
+    name: string;
+    when: string[];
+}>(skills: T[], only: string[], tags: string[]): T[];
+/**
+ * [[name]] as a reference to a document or file — the Obsidian instinct,
+ * honoured where it is safe. A prompt is text the model acts on, and a
+ * model cannot open "[[sources-of-conveyancers]]"; it can open
+ * `../../knowledge/sources-of-conveyancers.md`. So links resolve to real
+ * agent-relative paths BEFORE the prompt is built, matching by filename or
+ * OKF title, hyphen/underscore/case-blind. Anything unmatched — agent
+ * names, flow links, prose in brackets — passes through untouched: this is
+ * sugar over paths, never a gate in front of them.
+ */
+/**
+ * Whether an evaluator's reply actually carries its `until:` marker.
+ *
+ * Not a substring test. A reviewer that writes "APPROVED once the tribunal
+ * sentence is corrected" contains the word, and a substring match reads that
+ * conditional as a pass — the loop ends, the correction is never made, and the
+ * step after it inherits the problem the loop existed to catch. That happened:
+ * a factual error rode a conditional approval past the gate.
+ *
+ * So the marker has to stand alone on its own line, which is a thing a model
+ * does deliberately and cannot do by accident mid-sentence. Trailing
+ * punctuation is allowed ("APPROVED." is still a decision), and the line may
+ * sit anywhere in the reply, so an approval followed by notes still passes —
+ * the point is that the word is a switch, not a clause.
+ */
+export declare function saysUntilMarker(result: string | null, until: string): boolean;
+export declare function resolveDocLinks(text: string, workspaceRoot: string): string;
+/**
+ * Copy a directory tree by reading and writing the bytes.
+ *
+ * Not fs.cpSync: that copies through the kernel's clone/copy_file_range
+ * path, which on a bind-mounted or network volume — exactly where a hosted
+ * install keeps its data — can report success and leave a zero-length file
+ * behind. Every archived run output was empty, and nothing failed to say
+ * so, which is the worst shape a bug can take. This works on every
+ * filesystem, and normalises the mode while it is here: what an agent
+ * produced belongs to the platform, not to the container umask that
+ * happened to create it.
+ */
+export declare function copyTreeBytes(from: string, to: string): void;
+/** 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. */
+export declare const OVERLOAD_RETRIES = 3;
+/**
+ * A refusal the SAME supply may answer in a moment — the provider is busy,
+ * not the account broken.
+ *
+ * The distinction is the whole point. 429 means "too many requests", and a
+ * provider says it for two unrelated reasons: the endpoint is momentarily
+ * saturated (wait, and it works), or the account is out of credit or over
+ * its quota (wait forever, it never works). Money words decide it: a 429
+ * that mentions credit, quota or billing is the account, and belongs to the
+ * fallback provider, not to a retry that can only fail again.
+ */
+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;
+/**
+ * Drive a run to completion: groups in order, approval gates, retries.
+ *
+ * Separate from starting one so a run can be picked up again. The loop reads
+ * every decision off the run record — `pending` steps are the work left, and
+ * a completed group's results are already on it — so re-entering it on a
+ * partly-finished record continues rather than restarts.
+ *
+ * `parkOnApproval` — a queue worker's slot is too expensive to spend polling
+ * a file for a person who may answer tomorrow. With it set, an approval gate
+ * saves the run as parked and returns; the approval API re-enqueues it and a
+ * worker re-enters this loop, which continues where the record says it
+ * stopped. Without it (the CLI, whose process belongs to the person waiting)
+ * the gate blocks in place exactly as before.
+ */
+/**
+ * Turn a gate's `preview:` patterns into the files under storage/ that
+ * exist right now, relative to storage/. `*` matches within a segment,
+ * `**` across segments; a pattern with no wildcard is kept only if the file
+ * is there. Sorted, deduplicated, capped — a preview is a handful of files,
+ * not a directory dump.
+ */
+export declare function resolvePreview(storageDir: string, patterns: string[], cap?: number): string[];
+/** Store what a run has left in storage/ so far. Never fails the run: a
+ *  store that is down costs the gate its thumbnail, not the run its step. */
+/**
+ * Copy onto the in-memory run any gate decision that reached the record on
+ * disk while this driver was busy — status, stamps, note, the event line —
+ * so the driver's next save keeps it. Returns whether anything landed. Only
+ * steps this copy still shows as asking are touched: everything else on the
+ * record is this driver's own, and newer in memory than on disk.
+ */
+export declare function adoptDecisions(run: RunRecord, disk: RunRecord | null): boolean;
+/**
+ * The runs this process is driving right now. The one fact reconcile needs:
+ * a run in here is alive however quiet its step is, and a `running` run not
+ * in here has no driver — this is the only process that drives.
+ */
+export declare const drivingRuns: Set<string>;
+export declare function driveRun(tenant: string, workspace: string, run: RunRecord, modelOverride?: string | null, tags?: string[], opts?: {
+    parkOnApproval?: boolean;
+    effortOverride?: string | null;
+}): Promise<void>;
+export declare function loadFlow(tenant: string, workspace: string, flowName: string): import("./store.ts").FlowInfo | null;
+export interface Reconciliation {
+    runId: string;
+    tenant: string;
+    workspace: string;
+    /** What was done about it: closed as dead, or picked back up. */
+    action: "closed" | "resumed";
+    /** Steps that were mid-flight when the process went away. */
+    interrupted: string[];
+}
+/**
+ * Close out runs abandoned by a process that is no longer here.
+ *
+ * Runs execute in the server process, and nothing writes a terminal status
+ * when that process goes away — so a deploy, a crash or a Ctrl-C during a run
+ * leaves `status: "running"` on disk forever. The run history then contains
+ * entries that are not merely stale but false: they claim to be in progress,
+ * the dashboard renders them as live, and no one can tell them apart from a
+ * step that is genuinely still thinking.
+ *
+ * Called at startup, before anything reads run history. A run still being
+ * worked on by a live process is protected by the idle window, not by a lock —
+ * so this is safe to call while runs are in flight, and deliberately
+ * conservative about what it declares dead.
+ *
+ * A run genuinely waiting for a person is left alone: that state legitimately
+ * outlives any process. A run whose person already answered is not waiting,
+ * and is picked back up — see below.
+ */
+export declare function reconcileRuns(tenant: string, now?: number): Reconciliation[];
+/**
+ * The same, for every account this installation holds.
+ *
+ * A server reconciles on boot, and it boots for everyone — reconciling only
+ * one hard-coded account left every other account's interrupted runs marked
+ * `running` forever, with no process left to finish them.
+ */
+export declare function reconcileAllRuns(now?: number): Reconciliation[];
+/**
+ * Wait for a run to stop being in progress.
+ *
+ * Runs start and return immediately, which is right for a schedule and wrong
+ * for a caller putting an agent behind their own request: they want the
+ * answer, not a receipt. Polls the run record rather than holding a callback,
+ * so it works from a different process than the one doing the work.
+ *
+ * `awaiting-approval` counts as stopping. It is not finished, but it is not
+ * going to progress without a person, and a caller blocked on it would hang
+ * for as long as the approval window allows.
+ */
+export declare function waitForRun(tenant: string, workspace: string, runId: string, timeoutMs?: number): Promise<{
+    run: RunRecord | null;
+    timedOut: boolean;
+}>;
+/**
+ * What a run produced, for a caller that wanted an answer.
+ *
+ * The last step that actually returned something: a flow's final step is the
+ * conclusion, and skipping back past steps that were skipped or produced
+ * nothing is what makes `?wait=true` useful rather than merely blocking.
+ */
+export declare function runResult(run: RunRecord): string | null;