@foldrun/core 2.4.0 → 2.6.0

package/dist/src/runner.d.ts

@@ -33,6 +33,46 @@ export declare function slotPool(size: number): {
     acquire: () => Promise<void>;
     release: () => void;
 };
+export declare function markResponding(step: StepRecord): void;
+/**
+ * Is this step's prompt in the cache yet? An entry is readable from the
+ * moment the response to the request that wrote it begins streaming
+ * (Anthropic's prompt-caching docs), which is what `responding` marks.
+ * The first text, tool call or recorded model call says the same a little
+ * later, for an executor that cannot see the stream (the stub, an older
+ * driver). Resolves on the first of those, or when the step is over
+ * without one (a refusal before the first turn, a failed start).
+ */
+export declare function untilFirstReply(step: StepRecord, done: Promise<unknown>, pollMs?: number): Promise<void>;
+/**
+ * Steps of one agent launched together share a prompt prefix — tools and
+ * system prompt — and that is what the model's cache keeps. The cache is
+ * written by the first request that carries a prefix and readable only
+ * once that response has begun, so N copies started at once all write it
+ * and none reads: a fan-out of twenty paid twenty cold prefixes. The gate
+ * lets the first instance of each agent go alone and holds its siblings
+ * until its first response has begun (or it ended); then they all start
+ * and read what it wrote — Claude Code holds a workflow's fan-out the same
+ * way. Not a fixed delay: a sandbox takes seconds to start before its
+ * first model call, so a timer from launch would release the siblings
+ * before there was anything to read. Keyed by agent and model, since a
+ * cache is per model.
+ */
+export declare function warmGate(launching: StepRecord[], pollMs?: number): {
+    /** Claim the step's place — synchronously, before anything awaits, or
+     *  the copies that reach their first await together would all find no
+     *  lead and all go (a `parallel:` pool's acquire was exactly that).
+     *  The first of its agent leads and gets null; a later one gets the
+     *  lead's gate to await before it starts; a lone step gets null too. */
+    claim(step: StepRecord): Promise<void> | null;
+    /** A lead that will not run after all (the run was stopped while it
+     *  waited for a pool slot) still opens its gate — or its siblings,
+     *  which also wake to the stop, would wait on it forever. */
+    release(step: StepRecord): void;
+    /** Run the step; a lead opens its agent's gate on its first reply (or
+     *  its end), whatever else happens to it. */
+    run(step: StepRecord, launch: () => Promise<void>): Promise<void>;
+};
 export interface DiscoveredSkill {
     name: string;
     description: string;
@@ -258,6 +298,8 @@ grantsOnly?: boolean): {
      *  reported by the step, not here, so it lands in the run's trace. */
     clock: ClockChoice;
     systemPrompt: string;
+    /** What the record keeps of each layer of that prompt. */
+    promptLayers: import("./tokens.ts").PromptLayerRecord[];
     allowed: string[];
     disabled: string[];
     unknownTools: string[];
@@ -280,6 +322,7 @@ grantsOnly?: boolean): {
     ask: {
         timeoutSec: number;
     } | null;
+    peers: boolean;
     runtime: {
         log: string[];
         error: string | null;
@@ -328,6 +371,7 @@ grantsOnly?: boolean): {
         maxTokensParam?: "max_tokens" | "max_completion_tokens";
         reasoningEffort?: boolean;
         params?: Record<string, unknown>;
+        cacheKey?: string;
         label?: string;
         egress?: string;
         timezone: string;
@@ -340,6 +384,7 @@ grantsOnly?: boolean): {
         maxTokensParam?: "max_tokens" | "max_completion_tokens";
         reasoningEffort?: boolean;
         params?: Record<string, unknown>;
+        cacheKey?: string;
         label?: string;
         egress?: string;
         timezone: string;
@@ -583,7 +628,13 @@ export interface Reconciliation {
  * 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, live?: ReadonlySet<string>): Reconciliation[];
+/** Told when a run reconcile closed, or resumed and saw to its end — so the
+ *  platform settles, notifies and chains it as it would a run its worker
+ *  drove (a run closed here had spent tokens, and nobody was charged or
+ *  told). Not told when a resumed run parks again: whatever resumes it next
+ *  goes through the worker. */
+export type ReconcileEnd = (tenant: string, workspace: string, runId: string) => void | Promise<void>;
+export declare function reconcileRuns(tenant: string, now?: number, live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[];
 /**
  * The same, for every account this installation holds.
  *
@@ -591,7 +642,7 @@ export declare function reconcileRuns(tenant: string, now?: number, live?: Reado
  * 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, live?: ReadonlySet<string>): Reconciliation[];
+export declare function reconcileAllRuns(now?: number, live?: ReadonlySet<string>, onEnd?: ReconcileEnd): Reconciliation[];
 /**
  * Wait for a run to stop being in progress.
  *