@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/loop/chat-stream.js

@@ -0,0 +1,237 @@
+/**
+ * The durable stream of a chat turn, and of each sub-agent of the turn.
+ *
+ * The turn writes to the stream of its workflow with the writer of
+ * `@dbos-inc/vercel-ai`: each model call writes its text from inside its step,
+ * and the harness writes each of its own frames as one `data-harness-frame`
+ * chunk. The reader converts the chunks to the `ChatFrame`s that a host gives
+ * its client. A model record also holds the input of each tool call, and the
+ * converter drops it, thus a client gets the frames of an in-process turn.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { functionIDGetIncrement, getCurrentContextStore } from "@dbos-inc/dbos-sdk/internal/context";
+import { readDurableStream, toolWriter, writeDurableStream } from "@dbos-inc/vercel-ai";
+import { z } from "zod";
+import { checkChatPart, isRootFrame, toChatFrame } from "../contracts/chat-frame.js";
+import { isKnownPartType, PART_REGISTRY } from "../contracts/part-registry.js";
+import { ChatEventSchema } from "../contracts/schemas/chat-events.js";
+/** The key of the durable stream of a chat turn. */
+export const CHAT_STREAM_KEY = "chat";
+/** The data part that names the child workflow of a sub-agent call in the stream of its caller. */
+export const SUB_AGENT_STREAM_PART = "data-subagent-stream";
+const SubAgentStreamFrameSchema = z.object({ type: z.literal(SUB_AGENT_STREAM_PART), workflowId: z.string() });
+const HARNESS_FRAME_CHUNK = "data-harness-frame";
+/** The source of a frame that comes before the first frame of the harness. A turn writes no such frame. */
+const UNKNOWN_SOURCE = { agentId: "", callPath: [] };
+const HarnessFrameChunkSchema = z.object({
+    type: z.literal(HARNESS_FRAME_CHUNK),
+    data: z.looseObject({ type: z.string() }),
+});
+/** The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is live only. */
+export function chunkOfFrame(frame, transient = false) {
+    return transient ? { type: HARNESS_FRAME_CHUNK, data: frame, transient: true } : { type: HARNESS_FRAME_CHUNK, data: frame };
+}
+/**
+ * Whether a frame from a tool step shows progress only. The library gives such a frame live, and a replay of the
+ * step does not give it again. Each other frame of a tool step is checkpointed with the step, and the display of a
+ * round that a recovery stores keeps it: the end of each call, and each part of the root agent.
+ */
+function isProgressFrame(frame) {
+    if (!isRootFrame(frame) || frame.type === "tool-started" || frame.type === "iteration")
+        return true;
+    return isKnownPartType(frame.type) && PART_REGISTRY[frame.type].transient;
+}
+/**
+ * Run each body write of one workflow after the body write before it ends.
+ *
+ * DBOS gives a stream write its offset inside the insert, thus two writes in flight take the same offset, and the
+ * write that loses sleeps 100 ms before it tries again. A body write must still take its function id at the call,
+ * because a replay finds each checkpoint by the order of the calls. Thus the call reserves its id now, and the
+ * chained write takes the reserved id from the context of the workflow when it starts.
+ */
+function chainBodyWrites() {
+    let tail = Promise.resolve();
+    return (start) => {
+        const ctx = getCurrentContextStore();
+        if (ctx === undefined || !DBOS.isInWorkflow() || DBOS.isInStep())
+            return start();
+        const reserved = functionIDGetIncrement();
+        const run = () => {
+            // A continuation keeps the async context of its call, thus DBOS reads the id from this same context.
+            if (getCurrentContextStore() !== ctx)
+                throw new Error("A chained stream write lost the context of its workflow.");
+            const next = ctx.curWFFunctionId;
+            ctx.curWFFunctionId = reserved;
+            try {
+                // DBOS takes the function id before its first await, thus the swap ends before any other call can read it.
+                return start();
+            }
+            finally {
+                ctx.curWFFunctionId = next;
+            }
+        };
+        const write = tail.then(run, run);
+        tail = write.then(() => undefined, () => undefined);
+        return write;
+    };
+}
+/**
+ * The writer of the stream of a turn workflow. `observe` gets each frame of the turn that goes to the stream: the
+ * frames of the body, and the frames of each tool step, the frames that a replay of a step gives again included.
+ *
+ * From the body a write is checkpointed, thus a replay writes nothing again. From a step a write is at-least-once,
+ * and a fold of the frames by the id of a tool call or a part makes a second copy harmless.
+ */
+export function createTurnStreamWriter(rootSource, observe) {
+    const pending = [];
+    const chained = chainBodyWrites();
+    const track = (write) => {
+        // Observed now, thus a failure before the settle is not an unhandled rejection. The settle still sees it.
+        write.catch(() => undefined);
+        pending.push(write);
+    };
+    const writer = {
+        write(chunk) {
+            const frame = harnessFrameOf(chunk);
+            if (frame !== undefined)
+                observe(frame);
+            track(chained(() => writeDurableStream(CHAT_STREAM_KEY, [chunk])));
+        },
+        merge(stream) {
+            track((async () => {
+                for await (const chunk of stream)
+                    writer.write(chunk);
+            })());
+        },
+        onError: undefined,
+    };
+    const write = async (frame) => {
+        observe(frame);
+        await chained(() => writeDurableStream(CHAT_STREAM_KEY, [chunkOfFrame(frame)]));
+    };
+    const emit = async (event) => {
+        const frame = toChatFrame(event, rootSource);
+        if (frame === null)
+            return;
+        // A tool step gives its frames to the library, which checkpoints each one that is not progress.
+        if (DBOS.isInStep()) {
+            toolWriter().write(chunkOfFrame(frame, isProgressFrame(frame)));
+            return;
+        }
+        await write(frame);
+    };
+    return {
+        emit,
+        toolWriter: writer,
+        write,
+        async settle() {
+            while (pending.length > 0)
+                await Promise.all(pending.splice(0));
+        },
+    };
+}
+/** The frame that one harness chunk carries, checked as a frame from outside the process. */
+function harnessFrameOf(chunk) {
+    const carried = HarnessFrameChunkSchema.safeParse(chunk);
+    if (!carried.success)
+        return undefined;
+    if (carried.data.data.type.startsWith("data-")) {
+        const part = checkChatPart(carried.data.data);
+        return part.ok ? part.frame : undefined;
+    }
+    const event = ChatEventSchema.safeParse(carried.data.data);
+    return event.success ? event.data : undefined;
+}
+/**
+ * The frames of one chunk of the stream. The text of a model call is the text of the root agent, because a
+ * sub-agent writes to the stream of its own workflow. The end chunks of the library carry no fact of the turn,
+ * except the error and the abort of a workflow that ended before the turn wrote its own end.
+ */
+export function framesOfChunk(chunk, rootSource) {
+    switch (chunk.type) {
+        case "text-delta":
+            return chunk.delta.length === 0 ? [] : [{ type: "text-delta", text: chunk.delta, source: rootSource }];
+        case "error":
+            return [{ type: "error", message: chunk.errorText, source: rootSource }];
+        case "abort":
+            return [{ type: "finish", source: rootSource }];
+        default: {
+            const frame = harnessFrameOf(chunk);
+            return frame === undefined ? [] : [frame];
+        }
+    }
+}
+/** How long a read waits for a child workflow that its caller named, and the interval of each look. */
+const CHILD_START_WAIT_MS = 10_000;
+const CHILD_START_POLL_MS = 50;
+/**
+ * The chunks of the stream of a sub-agent child. The caller names the child in the same tick as it starts the child,
+ * thus the name can arrive before the child exists, and a read of a stream of no workflow fails. A child that never
+ * starts fails the tool call of its caller, and the result of that call tells it.
+ */
+async function* childChunks(workflowID, client) {
+    const source = client ?? DBOS;
+    const deadline = Date.now() + CHILD_START_WAIT_MS;
+    while ((await source.retrieveWorkflow(workflowID).getStatus()) === null) {
+        if (Date.now() > deadline)
+            return;
+        await sleep(CHILD_START_POLL_MS);
+    }
+    yield* readDurableStream({ workflowID, key: CHAT_STREAM_KEY, client, sendReasoning: false });
+}
+/**
+ * Read the frames of a turn from its start, live, until the turn ends. A second read gives the same frames.
+ *
+ * The read merges the stream of each sub-agent child that the turn names, in the order of arrival. A child stream
+ * gives only the frames of the harness: the child ends before its caller continues, and the result of its tool call
+ * tells its outcome. The end frame of the turn comes last.
+ */
+export async function* readChatTurn(turnId, options) {
+    const readers = [];
+    const reads = new Map();
+    const pull = (reader) => {
+        reads.set(reader, reader.next().then((next) => ({ reader, next })));
+    };
+    const open = (chunks) => {
+        const reader = chunks[Symbol.asyncIterator]();
+        readers.push(reader);
+        pull(reader);
+        return reader;
+    };
+    const root = open(readDurableStream({ workflowID: turnId, key: CHAT_STREAM_KEY, client: options.client, sendReasoning: false }));
+    let rootSource = options.rootSource;
+    const ends = [];
+    try {
+        while (reads.size > 0) {
+            const { reader, next } = await Promise.race(reads.values());
+            if (next.done === true) {
+                reads.delete(reader);
+                continue;
+            }
+            pull(reader);
+            const frame = harnessFrameOf(next.value);
+            const child = SubAgentStreamFrameSchema.safeParse(frame);
+            if (child.success) {
+                open(childChunks(child.data.workflowId, options.client));
+                continue;
+            }
+            if (reader !== root) {
+                if (frame !== undefined)
+                    yield frame;
+                continue;
+            }
+            rootSource ??= frame?.source;
+            for (const rootFrame of framesOfChunk(next.value, rootSource ?? UNKNOWN_SOURCE)) {
+                if (rootFrame.type === "finish" || rootFrame.type === "error")
+                    ends.push(rootFrame);
+                else
+                    yield rootFrame;
+            }
+        }
+        yield* ends;
+    }
+    finally {
+        await Promise.all(readers.map(async (reader) => await reader.return?.()));
+    }
+}

package/dist/loop/compaction.d.ts

@@ -1,24 +1,24 @@
-import type { AgentChat } from "../providers/types.js";
-import type { ToolMask } from "./tool-mask.js";
+import type { ToolMask } from "./call-policy.js";
 import type { LoopMessage } from "./types.js";
 /** The cap of requests of one compaction exchange: up to 3 rounds of memory edits, and then the summary. */
 export declare const COMPACTION_MAX_REQUESTS = 4;
 /** When an agent compacts its conversation, in the input tokens that the provider reported for the last request. */
-export interface CompactionRules {
+export type CompactionRules = {
     /** The budget before each request of a turn. */
     readonly budget: number;
     /** The budget before the user message of a turn joins the conversation. Absent: no compaction before the user message. */
     readonly turnStartBudget?: number;
-}
+};
 /**
  * The rules of an agent for a model with `contextWindow`. The budget is the smaller of the declared budget and 80% of
  * the window. The turn-start budget keeps its ratio to the budget. An absent window keeps the declared rules.
  */
 export declare function rulesForContextWindow(rules: CompactionRules, contextWindow: number | undefined): CompactionRules;
-/** How the loop compacts its conversation when the last request passed a budget. */
-export interface CompactionPolicy extends CompactionRules {
-    /** The provider of the conversation, with no text stream to the surface: the summary is no reply. */
-    readonly provider: AgentChat;
+/**
+ * How the loop compacts its conversation when the last request passed a budget. The exchange streams no
+ * text to the surface, because the summary is no reply.
+ */
+export type CompactionPolicy = CompactionRules & {
     /** The text of the compaction request. */
     readonly request: string;
     /** The tools that can run in the exchange. */
@@ -27,4 +27,4 @@ export interface CompactionPolicy extends CompactionRules {
     readonly keepFirstTurn: boolean;
     /** The context records that come after a new marker, for the view that starts at the marker. */
     readonly recordsAfter: (view: readonly LoopMessage[]) => Promise<readonly LoopMessage[]>;
-}
+};

package/dist/loop/compaction.js

@@ -14,6 +14,6 @@ export function rulesForContextWindow(rules, contextWindow) {
         return rules;
     return {
         budget,
-        ...(rules.turnStartBudget === undefined ? {} : { turnStartBudget: Math.floor((rules.turnStartBudget * budget) / rules.budget) }),
+        turnStartBudget: rules.turnStartBudget === undefined ? undefined : Math.floor((rules.turnStartBudget * budget) / rules.budget),
     };
 }

package/dist/loop/metrics.d.ts

@@ -12,11 +12,11 @@
  * agree on whether `outputTokens` includes the reasoning tokens, so the
  * reasoning counter keeps a `provider` label.
  *
- * Each `runAgent` completion also records, with the `agent_id` label only:
- *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.
+ * Each run of the loop also records, with the `agent_id` label only:
+ *   - cortex.harness.agent.iterations — histogram of model requests per run.
  *     A creeping distribution is a leading indicator of prompt drift.
  *   - cortex.harness.agent.cap_hits — counter, incremented once per run that
- *     exhausted `maxIterations` and took the forced wrap-up path.
+ *     reached its step cap.
  *
  * The two cache counters are what make prompt caching *observable*: the hit
  * rate for an agent type is `cache_read_tokens / input_tokens` (the harness's
@@ -33,19 +33,19 @@
  * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
  */
 import { type TokenUsageRollup } from "../contracts/usage.js";
-import type { ChatResponse, ChatUsage } from "../providers/types.js";
+import type { ChatUsage } from "../providers/types.js";
 /**
- * Token usage summed over LLM calls, either one `runAgent` run or a whole
+ * Token usage summed over LLM calls, either one run of the loop or a whole
  * turn. A field stays `undefined` until a call reports it, so an unreported
  * field never masquerades as a measured zero.
  */
-export interface AgentRunUsage {
+export type AgentRunUsage = {
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationInputTokens?: number;
     cacheReadInputTokens?: number;
     reasoningTokens?: number;
-}
+};
 /** Fold one call's reported usage into a run's running total. */
 export declare function addChatUsage(total: AgentRunUsage, usage: ChatUsage | undefined): void;
 /**
@@ -59,17 +59,14 @@ export declare function addChatUsage(total: AgentRunUsage, usage: ChatUsage | un
  * at either end is how the two would come to disagree.
  */
 export declare function hasReportedUsage(usage: AgentRunUsage | ChatUsage | TokenUsageRollup | undefined): boolean;
-/**
- * Maps a step's response to grow its token counters. Use inside the step
- * body, `provider.chat(...).map(countChatTokens(agentId))`. A call that gives
- * `err` counts nothing.
- */
-export declare function countChatTokens(agentId: string): (response: ChatResponse) => ChatResponse;
+/** Grow the token counters by one completed call. A figure that the provider did not report counts nothing. */
 export declare function recordChatCall(call: {
     readonly agentId: string;
-    readonly response: ChatResponse;
+    readonly usage: ChatUsage;
+    readonly servedModelId?: string;
+    readonly provider?: string;
 }): void;
-/** Record one completed `runAgent` invocation. */
+/** Record one completed run of the loop. */
 export declare function recordAgentRun(run: {
     readonly agentId: string;
     readonly iterations: number;

package/dist/loop/metrics.js

@@ -12,11 +12,11 @@
  * agree on whether `outputTokens` includes the reasoning tokens, so the
  * reasoning counter keeps a `provider` label.
  *
- * Each `runAgent` completion also records, with the `agent_id` label only:
- *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.
+ * Each run of the loop also records, with the `agent_id` label only:
+ *   - cortex.harness.agent.iterations — histogram of model requests per run.
  *     A creeping distribution is a leading indicator of prompt drift.
  *   - cortex.harness.agent.cap_hits — counter, incremented once per run that
- *     exhausted `maxIterations` and took the forced wrap-up path.
+ *     reached its step cap.
  *
  * The two cache counters are what make prompt caching *observable*: the hit
  * rate for an agent type is `cache_read_tokens / input_tokens` (the harness's
@@ -40,11 +40,11 @@ function getInstruments() {
         const meter = metrics.getMeter("cortex.harness.loop");
         instruments = {
             iterations: meter.createHistogram("cortex.harness.agent.iterations", {
-                description: "LLM iterations executed per runAgent completion",
+                description: "Model requests of each run of the agent loop",
                 unit: "{iteration}",
             }),
             capHits: meter.createCounter("cortex.harness.agent.cap_hits", {
-                description: "runAgent completions that exhausted maxIterations and took the " + "forced wrap-up path",
+                description: "Runs of the agent loop that reached their step cap",
             }),
             inputTokens: meter.createCounter("cortex.harness.agent.input_tokens", {
                 description: "Input tokens billed for each completed LLM call, cache reads included",
@@ -94,29 +94,17 @@ export function addChatUsage(total, usage) {
 export function hasReportedUsage(usage) {
     if (usage === undefined)
         return false;
-    return Object.values(usage).some((value) => value !== undefined);
-}
-/**
- * Maps a step's response to grow its token counters. Use inside the step
- * body, `provider.chat(...).map(countChatTokens(agentId))`. A call that gives
- * `err` counts nothing.
- */
-export function countChatTokens(agentId) {
-    return (response) => {
-        recordChatCall({ agentId, response });
-        return response;
-    };
+    return TOKEN_USAGE_FIELDS.some((field) => usage[field] !== undefined);
 }
+/** Grow the token counters by one completed call. A figure that the provider did not report counts nothing. */
 export function recordChatCall(call) {
-    const { usage, servedModelId, provider } = call.response;
-    if (usage === undefined)
-        return;
+    const { usage } = call;
     const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens } = getInstruments();
-    const attributes = {
-        agent_id: call.agentId,
-        ...(servedModelId === undefined ? {} : { model: servedModelId }),
-        ...(provider === undefined ? {} : { provider }),
-    };
+    const attributes = { agent_id: call.agentId };
+    if (call.servedModelId !== undefined)
+        attributes.model = call.servedModelId;
+    if (call.provider !== undefined)
+        attributes.provider = call.provider;
     if (usage.inputTokens !== undefined)
         inputTokens.add(usage.inputTokens, attributes);
     if (usage.outputTokens !== undefined)
@@ -128,7 +116,7 @@ export function recordChatCall(call) {
     if (usage.reasoningTokens !== undefined)
         reasoningTokens.add(usage.reasoningTokens, attributes);
 }
-/** Record one completed `runAgent` invocation. */
+/** Record one completed run of the loop. */
 export function recordAgentRun(run) {
     const { iterations, capHits } = getInstruments();
     const attributes = { agent_id: run.agentId };

package/dist/loop/run-loop.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The agent loop: one conversation of one agent with a model and its tools.
+ *
+ * The AI SDK drives each request series with `streamText`. Inside a DBOS
+ * workflow, `durableCalls` makes each model call a step, and the tool adapter
+ * makes each tool call a step, thus a recovery replays each completed call
+ * from its checkpoint. Outside a workflow, each call runs directly. The same
+ * loop serves a chat turn, a workflow step, and a sub-agent.
+ *
+ * The loop keeps the transcript itself, and each request sends its view of
+ * the transcript. This gives the loop the work that the SDK does not do: the
+ * append-only record of each round, the round sink, the compaction, the
+ * follow-up request, the salvage, the not-run answer of each unanswered call
+ * at an exit, and the finish record.
+ */
+import { type LanguageModelMiddleware, type UIMessageStreamWriter } from "ai";
+import { type AgentSession } from "../auth/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { Logger } from "../lib/logger.js";
+import type { ChatProvider, PromptCachePolicy, ReasoningPolicy } from "../providers/types.js";
+import type { AskRequest } from "../tools/approval/contract.js";
+import { type CallPolicy, type ToolMask } from "./call-policy.js";
+import { type CompactionPolicy } from "./compaction.js";
+import { type AgentRunUsage } from "./metrics.js";
+import { type ToolCallOutput } from "./tool-adapter.js";
+import { type ToolOutputStore } from "./tool-output.js";
+import type { AgentDefinition, EmitFn, LoopMessage } from "./types.js";
+export type AgentFinish = {
+    /**
+     * The stop reason: the finish reason of the last reply, `aborted`, `max_iterations` at the step cap, or
+     * `denied` after a denial of the user. A word outside the modeled union stays as the provider sent it.
+     */
+    readonly reason: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "aborted" | "max_iterations" | "denied" | (string & {});
+    /** The word of the endpoint for the stop, when the provider captured one. */
+    readonly rawFinishReason?: string;
+    readonly cappedOut: boolean;
+    /** What the model calls of this run reported. Absent when no call reported anything — never an all-zero figure. */
+    readonly usage?: AgentRunUsage;
+    /**
+     * The whole turn's total, every descendant loop included. Present only on
+     * the loop that created the turn accumulator — the run whose options
+     * carried none, which is by construction the turn's root.
+     */
+    readonly turnUsage?: AgentRunUsage;
+};
+/** One tool call of a completed request, in the order that the model made the calls. */
+export type LoopToolCall = {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    /** The output of a call that ran. Absent for a refused call and for an input that did not parse. */
+    readonly output?: ToolCallOutput;
+    /** The policy of the run refused the call, thus it did not run. */
+    readonly refused: boolean;
+    /** The call has a result in the conversation. */
+    readonly answered: boolean;
+};
+/** One completed model request of a run, and the tool calls of its reply. */
+export type LoopStep = {
+    readonly finishReason: string;
+    readonly rawFinishReason?: string;
+    readonly calls: readonly LoopToolCall[];
+};
+export type LoopResult = {
+    readonly messages: LoopMessage[];
+    readonly finish: AgentFinish;
+    /** Each completed request of the run, in order. A selector reads the outcome of a run from them. */
+    readonly steps: readonly LoopStep[];
+};
+/** A request that the provider refused for its content: the HTTP status and the text of the provider error. */
+export type RequestRefusal = {
+    readonly status: number;
+    readonly message: string;
+};
+/** The messages that the loop appended after the last call of the round sink. */
+export type AgentRound = {
+    readonly messages: readonly LoopMessage[];
+};
+/** The decision of the user on the approval of one call. */
+export type ApprovalDecision = {
+    readonly kind: "approved";
+} | {
+    readonly kind: "denied";
+    readonly feedback?: string;
+};
+export type LoopOptions = {
+    readonly provider: ChatProvider;
+    readonly signal: AbortSignal;
+    readonly emit: EmitFn;
+    /** Receives each text delta of the reply as it streams. A loop with a live reader of its text gives it. */
+    readonly onText?: (text: string) => void | Promise<void>;
+    /**
+     * The round sink. The loop awaits it before each model request, at each exit, and before a throw.
+     * A durable loop passes no sink, because DBOS replays the loop body.
+     */
+    readonly onRound?: (round: AgentRound) => Promise<void>;
+    /**
+     * The compaction policy. Each request then sends the view of the transcript, and the loop compacts
+     * before a task request whose view passes the budget. A durable loop passes no policy, because
+     * `recordsAfter` reads the database outside a step.
+     */
+    readonly compaction?: CompactionPolicy;
+    /**
+     * The messages that open the turn of a chat thread: the user message and its context records. The loop appends
+     * them after the turn-start compaction, thus the conversation holds each message in the order that it was sent.
+     * Absent: `initial` holds the whole conversation.
+     */
+    readonly turnInput?: readonly LoopMessage[];
+    /**
+     * The decision of the user on a call whose tool asks for approval. The loop asks before the call runs, after the
+     * call policy. Absent: no surface can answer, and the loop denies each such call.
+     */
+    readonly approve?: (request: AskRequest, call: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+    }) => Promise<ApprovalDecision>;
+    /** The mask of the task, the budget, and the guard of the run. A refused call does not run. */
+    readonly policy?: CallPolicy;
+    /** Ends the run when its outcome is final, for example a blocker of a step agent. The finish reason is `stop`. */
+    readonly stopWhen?: (steps: readonly LoopStep[]) => boolean;
+    /** An early cap: the run ends as if it reached its step cap, for example after the refusal limit of a guard. */
+    readonly capWhen?: () => boolean;
+    /**
+     * Prompt-cache policy for every model call of this run. Defaults to `DEFAULT_PROMPT_CACHE` (5m) — an agent
+     * loop always re-sends its prefix, so it breaks even by the second request. A host whose endpoint ignores
+     * or charges badly for cache directives passes `"off"`.
+     */
+    readonly promptCache?: PromptCachePolicy;
+    /**
+     * The reasoning effort for each model call of this run. Anthropic discards its message cache when the
+     * top-level effort changes, so the run sends the same value, or none, throughout.
+     */
+    readonly reasoning?: ReasoningPolicy;
+    readonly logger?: Logger;
+    /** Per-call usage accounting. Omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
+    /** Keeps the text of each cut tool result. A run with no store cuts, and it keeps nothing. */
+    readonly toolOutputStore?: ToolOutputStore;
+    /**
+     * The turn's usage accumulator, supplied by whatever ran this loop as part of a larger turn (a
+     * sub-agent-running tool passes `ctx.turnUsage`). A run that receives none creates its own and is
+     * therefore the turn's root: it alone reports `turnUsage` on its finish.
+     */
+    readonly turnUsage?: AgentRunUsage;
+    /**
+     * The durable stream that each model call of the run writes its text to, from inside its step. A loop
+     * outside a workflow writes nothing, and `onText` gives its text.
+     */
+    readonly chatStream?: string;
+    /** Receives the chunks that each tool step writes through the tool writer of the library, on a replay too. */
+    readonly toolWriter?: UIMessageStreamWriter;
+    /** Model middleware inside the step of each model call, thus a replay of a recorded call does not run it. */
+    readonly modelMiddleware?: readonly LanguageModelMiddleware[];
+    /**
+     * The id of the tool call this loop runs inside, supplied by a sub-agent-running tool from its
+     * `ctx.invocationId`. It separates two dispatches of the same sub-agent in one round in the usage record
+     * key. The data profile gives the workflow id of its attempt, because each profile runs under the same
+     * constant frame.
+     */
+    readonly invocationId?: string;
+    /**
+     * Waits out a failed request whose cause a person or time can repair, and gives how the wait ended: the deadline
+     * of a retry, a resume, or a stop. `undefined`: the failure does not pause, and the loop throws it. The body of a
+     * workflow gives the pause of its work. A loop with no pause throws each failure.
+     */
+    readonly pause?: (failure: unknown, attempt: number, signal: AbortSignal) => Promise<"retry" | "resume" | "abort" | undefined>;
+};
+/** The harness request after a reply that a failed request cut. The model reads its partial reply, and continues it. */
+export declare const CONTINUE_REQUEST = "[The model request failed during your reply above. Continue the reply from where it stopped.]";
+/** A run that receives no turn accumulator is the turn's root. See `LoopOptions.turnUsage`. */
+export declare const isTurnRoot: (opts: Pick<LoopOptions, "turnUsage">) => boolean;
+/** Run an agent over `initial` until its reply ends the run. */
+export declare function runLoop(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: LoopOptions): Promise<LoopResult>;
+/** One harness request that continues a finished conversation. */
+export type FollowUpRequest = {
+    /** Appended as a synthetic user message, thus it opens no turn in a stored thread. */
+    readonly text: string;
+    /** The tools that can run. The request still declares every tool of the agent. */
+    readonly mask: ToolMask;
+    readonly maxRequests: number;
+    /**
+     * When set, metrics and token counts are attributed to this id instead of
+     * `agent.id`, through `forSubAgent`. Omitted, both stay the agent's own.
+     */
+    readonly accountingAgentId?: string;
+    /** A `provider` error with the status `400` or `413` ends the request with the finish reason `error`, and no throw. */
+    readonly endOnRequestRefusal?: boolean;
+};
+export type FollowUpResult = LoopResult & {
+    /** The refusal that ended a request with `endOnRequestRefusal`. */
+    readonly refusal?: RequestRefusal;
+};
+/**
+ * Continue a finished conversation with one harness request. `agent` and `opts`
+ * must match the conversation's own, since each request extends its cached
+ * prefix. `conversation` itself is never changed. The result holds only the new
+ * messages, starting with the request.
+ */
+export declare function continueLoop(agent: AgentDefinition, conversation: readonly LoopMessage[], request: FollowUpRequest, session: AgentSession, opts: LoopOptions): Promise<FollowUpResult>;
+/** Default salvage budget: one submit plus a fix of a refused submission or two. */
+export declare const DEFAULT_SALVAGE_REQUESTS = 3;
+/** How to salvage a run that ended with no outcome. */
+export type TerminalSalvage = {
+    /** The tools that can run in the salvage request. Each one must be a declared tool of the agent. */
+    readonly tools: readonly string[];
+    /** Opens the salvage request as a synthetic user message. */
+    readonly nudge: string;
+    /** The cap of salvage requests. Defaults to {@link DEFAULT_SALVAGE_REQUESTS}. */
+    readonly maxRequests?: number;
+    /** Whether the recorded steps hold the outcome of the agent. */
+    readonly hasOutcome: (steps: readonly LoopStep[]) => boolean;
+};
+/**
+ * What a salvage request was and how it went — present only when one ran. The first finish is the
+ * diagnosis of why a salvage was needed: a run that capped out spent its budget, and a run that ended
+ * on prose gave up early.
+ */
+export type SalvageRecord = {
+    readonly firstFinish: AgentFinish;
+    readonly finish: AgentFinish;
+};
+export type SalvagedResult = LoopResult & {
+    /** Null when the first run reached its outcome and no salvage ran. */
+    readonly salvage: SalvageRecord | null;
+};
+/**
+ * Run an agent that has an outcome, and send one salvage request when the run
+ * ends with none and was not aborted. The salvage request lets only the
+ * terminal tools of the agent run. A salvaged result carries both runs'
+ * messages and steps and the summed rollups, with the finish of the salvage.
+ */
+export declare function runWithSalvage(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: LoopOptions, salvage: TerminalSalvage): Promise<SalvagedResult>;
+export declare function finalText(messages: readonly LoopMessage[]): string;