@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/app/chat-turn-workflow.js

@@ -0,0 +1,307 @@
+/**
+ * The chat turn as a DBOS workflow.
+ *
+ * The host opens a turn in its request: the harness checks the thread, resolves
+ * the agent, claims the thread for the turn, and starts the workflow. The
+ * workflow input holds ids and settings, the sanitized user text, and no
+ * credential. The live credential stays in the memory of the process, and the
+ * function of the host gives it to a turn that a recovery runs in a new process.
+ *
+ * The body prepares the opening in one step, reads the view of the thread up to
+ * the last row before the turn, and runs the turn of `chat-turn.ts` with the
+ * transport of a workflow: each model call and each tool call is a step, each
+ * write of the turn is a step with a key, and the frames go to the durable
+ * stream of the workflow. A host reads them with `read`.
+ */
+import { randomUUID } from "node:crypto";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { closeDurableStream } from "@dbos-inc/vercel-ai";
+import { z } from "zod";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { createConversationDisplayRecorder } from "../memory/conversation-display-recorder.js";
+import { createThreadHistory } from "../memory/thread-history.js";
+import { createWorkingMemory } from "../memory/working-memory.js";
+import { claimThreadForTurn, closeOpenTurnRecords, releaseThreadOfTurn, turnOfAsk } from "../state/active-turns.js";
+import { clearPausesOfWork } from "../state/paused-work.js";
+import { workPause } from "../workflows/pause.js";
+import { askPartOf } from "../tools/approval/gateway.js";
+import { stepUuid } from "../tools/workspace/edit-file.js";
+import { openThread, readTurnContext, runOpenTurn, userTextOf, } from "./chat-turn.js";
+import { CHAT_STREAM_KEY, createTurnStreamWriter, readChatTurn } from "../loop/chat-stream.js";
+import { credentialGuard, turnCredentials, withRootTurn } from "../loop/turn-credentials.js";
+import { assembleMessages, loadHistoryView, sanitizedUserMessage } from "./message-assembly.js";
+/** The name of the turn workflow. */
+export const CHAT_TURN_WORKFLOW = "chat-turn";
+/** A turn waits half an hour for the answer of an ask, and then the ask expires. */
+export const DEFAULT_ASK_WAIT_SECONDS = 30 * 60;
+const AskReplySchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("once") }),
+    z.object({ kind: z.literal("always") }),
+    z.object({ kind: z.literal("reject"), feedback: z.string().optional() }),
+]);
+/** The topic of the message that carries the answer of one ask to its turn. */
+function askTopic(askId) {
+    return `ask:${askId}`;
+}
+const ACTIVE_STATUSES = new Set(["PENDING", "ENQUEUED"]);
+/** The part of the stored input of a turn workflow that the stop of a turn reads. */
+const StoredTurnInputSchema = z.tuple([z.looseObject({ threadId: z.string() })]);
+/**
+ * Register the turn workflow and give the chat turns of the runtime. Call it before DBOS launches, because DBOS
+ * finds the workflow of a recovery by its registered name.
+ */
+export function registerChatTurns(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    // The live credential of each turn that this process opened, and the stop of each turn that this process runs.
+    const controls = new Map();
+    turnCredentials.setHostCredential(deps.credentialFor);
+    const workflow = DBOS.registerWorkflow(async (input) => {
+        const controller = new AbortController();
+        controls.set(input.turnId, controller);
+        try {
+            return await withRootTurn(input.turnId, () => runTurnWorkflow(deps, input, controller.signal));
+        }
+        finally {
+            controls.delete(input.turnId);
+            turnCredentials.drop(input.turnId);
+        }
+    }, { name: CHAT_TURN_WORKFLOW });
+    const stillRuns = async (turnId) => {
+        const status = await DBOS.getWorkflowStatus(turnId);
+        return status !== null && ACTIVE_STATUSES.has(status.status);
+    };
+    return {
+        async open(session, request) {
+            const startedAtMs = request.startedAtMs ?? Date.now();
+            let threadType;
+            try {
+                const opened = await openThread(deps, request);
+                if (opened.kind === "not_found")
+                    return opened;
+                threadType = opened.threadType;
+            }
+            catch (cause) {
+                return { kind: "prepare_failed", cause };
+            }
+            const agent = deps.agents.forThread(threadType);
+            if (agent.isErr())
+                return { kind: "agent_unresolved", threadType };
+            const turnId = randomUUID();
+            const claim = await claimThreadForTurn(deps.pool, request.threadId, turnId, stillRuns);
+            if (claim.isErr())
+                return { kind: "prepare_failed", cause: claim.error };
+            if (claim.value.kind === "no_thread")
+                return { kind: "not_found" };
+            if (claim.value.kind === "held")
+                return { kind: "turn_in_progress" };
+            turnCredentials.put(turnId, session.auth);
+            const input = {
+                turnId,
+                analysisId: request.analysisId,
+                threadId: request.threadId,
+                threadType,
+                userText: userTextOf(sanitizedUserMessage(request.userInput)),
+                userId: session.identity.user,
+                author: request.author,
+                startedAtMs,
+                promptCache: request.promptCache,
+            };
+            try {
+                await DBOS.startWorkflow(workflow, { workflowID: turnId })(input);
+            }
+            catch (cause) {
+                turnCredentials.drop(turnId);
+                await releaseThreadOfTurn(deps.pool, request.threadId, turnId).unwrapOr(undefined);
+                return { kind: "prepare_failed", cause };
+            }
+            return { kind: "started", turnId, agent: agent.value };
+        },
+        read(turnId) {
+            return readChatTurn(turnId, {});
+        },
+        async stop(turnId) {
+            const controller = controls.get(turnId);
+            if (controller !== undefined) {
+                controller.abort(new DOMException("The user stopped the turn.", "AbortError"));
+                return;
+            }
+            // No process of this host runs the turn: the cancel ends the workflow and its sub-agents, and the harness
+            // closes its records.
+            const status = await DBOS.getWorkflowStatus(turnId);
+            if (status === null || !ACTIVE_STATUSES.has(status.status))
+                return;
+            await DBOS.cancelWorkflow(turnId, { cancelChildren: true });
+            const cleared = await clearPausesOfWork(deps.pool, turnId);
+            if (cleared.isErr())
+                logger.warn("the pauses of a canceled turn did not clear", { turnId, op: cleared.error.op });
+            const input = StoredTurnInputSchema.safeParse(status.input);
+            if (!input.success)
+                return;
+            const [{ threadId }] = input.data;
+            const closed = await closeOpenTurnRecords(deps.pool, threadId);
+            if (closed.isErr())
+                logger.warn("the record of a canceled turn did not close", { turnId, op: closed.error.op });
+            await releaseThreadOfTurn(deps.pool, threadId, turnId).unwrapOr(undefined);
+        },
+        async answer(askId, reply) {
+            if (deps.askGateway === undefined)
+                return "not_found";
+            const outcome = await deps.askGateway.answer(askId, reply);
+            if (outcome !== "applied")
+                return outcome;
+            const turnId = await turnOfAsk(deps.pool, askId).unwrapOr(undefined);
+            if (turnId !== undefined)
+                await DBOS.send(turnId, reply, askTopic(askId));
+            return outcome;
+        },
+        async outcome(turnId) {
+            try {
+                return await DBOS.retrieveWorkflow(turnId).getResult();
+            }
+            catch (err) {
+                // The stop of a turn in a different process cancels its workflow, and the stop closes its records.
+                logger.debug("a chat turn ended with no outcome", { turnId, ...logger.errorFields(err) });
+                return null;
+            }
+        },
+    };
+}
+/**
+ * The approval of a turn workflow. The raise of the ask is a step, and the turn waits for the answer with a durable
+ * wait of its body, thus a recovery waits again for the same ask. A stop of the turn ends the wait.
+ */
+function workflowApproval(gateway, input, emitPart, signal, waitSeconds) {
+    return async (request, call) => {
+        const id = stepUuid(`${input.turnId}:ask:${call.toolCallId}`);
+        const scope = { analysisId: input.analysisId, userId: input.userId, threadId: input.threadId };
+        const raised = await DBOS.runStep(() => gateway.raise(id, request, scope), { name: "chat-turn.ask" });
+        if (raised === "granted") {
+            await emitPart(askPartOf(id, request, "resolved", "always"));
+            return { kind: "approved" };
+        }
+        await emitPart(askPartOf(id, request, "pending"));
+        const stopped = new Promise((resolve) => {
+            if (signal.aborted)
+                resolve("stopped");
+            signal.addEventListener("abort", () => resolve("stopped"), { once: true });
+        });
+        const answered = await Promise.race([DBOS.recv(askTopic(id), waitSeconds), stopped]);
+        if (answered === "stopped") {
+            await DBOS.runStep(() => gateway.abort(id), { name: "chat-turn.ask-abort" });
+            await emitPart(askPartOf(id, request, "aborted"));
+            throw signal.reason ?? new DOMException("The user stopped the turn.", "AbortError");
+        }
+        const reply = AskReplySchema.safeParse(answered);
+        if (!reply.success) {
+            await DBOS.runStep(() => gateway.expire(id), { name: "chat-turn.ask-expire" });
+            await emitPart(askPartOf(id, request, "expired"));
+            return { kind: "denied", feedback: "The approval expired unanswered." };
+        }
+        if (reply.data.kind === "reject") {
+            await emitPart(askPartOf(id, request, "rejected", "reject"));
+            return { kind: "denied", feedback: reply.data.feedback };
+        }
+        await emitPart(askPartOf(id, request, "resolved", reply.data.kind));
+        return { kind: "approved" };
+    };
+}
+async function runTurnWorkflow(deps, input, signal) {
+    const agent = deps.agents.forThread(input.threadType);
+    if (agent.isErr())
+        throw new Error(`No agent is registered for the thread type "${input.threadType}".`);
+    const rootSource = { agentId: agent.value.id, callPath: [agent.value.id] };
+    const history = createThreadHistory(deps.pool, deps.logger);
+    const opening = await DBOS.runStep(async () => {
+        const endSeq = unwrapOrThrow(await history.latestSeq(input.threadId)) ?? -1;
+        const assembled = await assembleMessages({
+            threadId: input.threadId,
+            threadType: input.threadType,
+            analysisId: input.analysisId,
+            userInput: input.userText,
+            ...(await readTurnContext(deps.pool, input.analysisId)),
+            history,
+            workingMemory: createWorkingMemory(deps.pool),
+            logger: deps.logger,
+            throughSeq: endSeq,
+        });
+        return { endSeq, userMessage: assembled.userMessage, contextRecords: assembled.contextRecords };
+    }, { name: "chat-turn.prepare" });
+    // The rows up to the turn never change, thus a replay reads the same view, and no checkpoint holds the thread.
+    const view = await loadHistoryView({ threadId: input.threadId, threadType: input.threadType, history, logger: deps.logger, throughSeq: opening.endSeq });
+    const userText = userTextOf(opening.userMessage);
+    const recorder = createConversationDisplayRecorder({
+        userText,
+        agentId: agent.value.id,
+        sink: () => undefined,
+        messageIds: { user: stepUuid(`${input.turnId}:user`), assistant: (index) => stepUuid(`${input.turnId}:assistant:${index}`) },
+    });
+    const writer = createTurnStreamWriter(rootSource, (frame) => recorder.observe(frame));
+    await writer.write({ type: "message-start", messageId: recorder.userMessageId(), role: "user", text: userText, source: rootSource });
+    await writer.write({ type: "message-start", messageId: recorder.assistantMessageId(), role: "assistant", source: rootSource });
+    const transport = {
+        signal,
+        emit: writer.emit,
+        chatStream: CHAT_STREAM_KEY,
+        toolWriter: writer.toolWriter,
+        recorder,
+        durably: (name, write) => DBOS.runStep(write, { name }),
+        groupKey: (index) => `${input.turnId}:${index}`,
+        announce: (messageId) => writer.write({ type: "message-start", messageId, role: "assistant", source: rootSource }),
+        modelMiddleware: [credentialGuard(() => turnCredentials.of(input.turnId))],
+        approve: deps.askGateway === undefined
+            ? undefined
+            : workflowApproval(deps.askGateway, input, async (part) => {
+                await writer.emit({ type: "data-ask", data: part });
+            }, signal, deps.askWaitSeconds ?? DEFAULT_ASK_WAIT_SECONDS),
+        pause: workPause({
+            pool: deps.pool,
+            workId: input.turnId,
+            workKind: "turn",
+            analysisId: input.analysisId,
+            threadId: input.threadId,
+            emit: async (part) => {
+                await writer.emit({ type: "data-pause", source: rootSource, data: part });
+            },
+            retryDelaysMs: deps.pauseRetryDelaysMs,
+            logger: deps.logger,
+        }).afterFailure,
+    };
+    const session = {
+        identity: { user: input.userId },
+        scope: { kind: "analysis", analysisId: input.analysisId, threadId: input.threadId },
+        // The credential comes at each read, thus a call after a resume uses the credential that the resume put. A
+        // turn with no credential makes no model call, thus no adapter reads the empty value.
+        get auth() {
+            return turnCredentials.of(input.turnId) ?? {};
+        },
+    };
+    const ran = await runOpenTurn(deps, { analysisId: input.analysisId, threadId: input.threadId, userInput: input.userText }, { kind: "ok", threadType: input.threadType, history: view, userMessage: opening.userMessage, contextRecords: opening.contextRecords }, agent.value, { session, author: input.author, startedAtMs: input.startedAtMs, promptCache: input.promptCache }, transport);
+    const { outcome } = ran;
+    await writer.write(outcome.status === "failed"
+        ? { type: "error", message: outcome.reason, reason: outcome.code, source: rootSource }
+        : { type: "finish", source: rootSource, turnUsage: ran.turnUsage });
+    await writer.settle();
+    await closeDurableStream(CHAT_STREAM_KEY, outcome.status === "done" ? "stop" : outcome.status === "aborted" ? "aborted" : "error");
+    // A sub-agent that a stop canceled in its pause leaves its row, thus the end of the turn clears each row of the turn.
+    await DBOS.runStep(async () => unwrapOrThrow(await clearPausesOfWork(deps.pool, input.turnId)), { name: "chat-turn.clear-pauses" });
+    await DBOS.runStep(async () => unwrapOrThrow(await releaseThreadOfTurn(deps.pool, input.threadId, input.turnId)), { name: "chat-turn.release" });
+    return chatTurnEndOf(ran);
+}
+/** How a turn that ran ended, as a host reads it. */
+export function chatTurnEndOf(ran) {
+    const { outcome } = ran;
+    const finish = outcome.status === "failed" ? undefined : outcome.finish;
+    return {
+        status: outcome.status,
+        reason: outcome.status === "failed" ? outcome.reason : undefined,
+        code: outcome.status === "failed" ? outcome.code : undefined,
+        durationMs: ran.durationMs,
+        opened: ran.opened,
+        finishReason: finish?.reason,
+        rawFinishReason: finish?.rawFinishReason,
+        turnUsage: ran.turnUsage,
+        fallbackText: ran.fallbackText,
+        storeFailed: ran.storeError === undefined ? undefined : true,
+    };
+}

package/dist/app/chat-turn.d.ts

@@ -1,26 +1,28 @@
 /**
- * The chat turn of a host: a turn is `runChatTurn`, which is `openChatTurn` and then the `run` of the
- * open turn. `prepareChatTurn` is the first step of the open. The host gives only its transport
- * values, and the harness stores the opening, each round, and the outcome.
+ * The run of one chat turn: `runOpenTurn` runs the root loop over a prepared turn, stores the opening and each
+ * round, and closes the turn with its outcome. A transport gives the surface and the store of the turn. The turn
+ * workflow (`chat-turn-workflow.ts`) gives the transport of a workflow, and a host reaches the turn through it.
  */
-import type { Pool } from "pg";
+import type { LanguageModelMiddleware, ModelMessage, UIMessageStreamWriter } from "ai";
 import type { RequestSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { TokenUsageRollup } from "../contracts/usage.js";
-import type { DbError } from "../lib/db-result.js";
-import { type AgentFinish } from "../loop/run-agent.js";
+import { type Connectable, type DbError } from "../lib/db-result.js";
+import type { Querier } from "../state/db.js";
+import { type AgentFinish, type LoopOptions } from "../loop/run-loop.js";
 import type { AgentDefinition, EmitFn } from "../loop/types.js";
+import type { ConversationDisplayRecorder } from "../memory/conversation-display-recorder.js";
 import { type ThreadType } from "../memory/thread-store.js";
-import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
+import type { ChatProvider, PromptCachePolicy } from "../providers/types.js";
 import type { ThreadAgentResolver } from "../runtime/assemble.js";
-import type { AskApproval, AskRequest } from "../tools/approval/contract.js";
+import type { AskGateway } from "../tools/approval/gateway.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
 import { type ProvenanceSeam } from "../provenance/seam.js";
-export interface PrepareChatTurnDeps {
+export type PrepareChatTurnDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-    readonly pool: Pool;
+    readonly pool: Querier & Connectable;
     /**
      * The provenance seam. The turn reads its session emit member, and no other
      * member. The turn holds the one site that writes the conversation thread of
@@ -31,58 +33,65 @@ export interface PrepareChatTurnDeps {
      * of a report session.
      */
     readonly provenance?: ProvenanceSeam;
-}
-export interface PrepareChatTurnParams {
+};
+export type PrepareChatTurnParams = {
     readonly analysisId: string;
     readonly threadId: string;
     readonly userInput: string;
-}
+};
 export type PrepareChatTurnResult = ({
     readonly kind: "ok";
     readonly threadType: ThreadType;
 } & AssembledMessages) | {
     readonly kind: "not_found";
 };
+/** A prepared turn: the type of its thread, the view of the thread, and the opening. */
+export type PreparedChatTurn = Extract<PrepareChatTurnResult, {
+    kind: "ok";
+}>;
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
  * inside {@link assembleMessages} (applied once to the new user input only).
  */
 export declare function prepareChatTurn(deps: PrepareChatTurnDeps, params: PrepareChatTurnParams): Promise<PrepareChatTurnResult>;
-export interface RunChatTurnDeps extends PrepareChatTurnDeps {
+/**
+ * Open the thread of a turn: check that the analysis owns it, make it when it is absent, and seed its title. A
+ * thread that a different analysis owns is `not_found`.
+ */
+export declare function openThread(deps: PrepareChatTurnDeps, params: PrepareChatTurnParams): Promise<{
+    readonly kind: "ok";
+    readonly threadType: ThreadType;
+} | {
+    readonly kind: "not_found";
+}>;
+/** The analysis context and the run activity of a turn. A failed read gives the fallback of its kind. */
+export declare function readTurnContext(pool: Querier, analysisId: string): Promise<{
+    readonly analysisContext: string | null;
+    readonly runActivityContext: string;
+}>;
+/** The runtime values of a turn. `assembleCoreRuntime` gives them to the turn workflow. */
+export type RunChatTurnDeps = PrepareChatTurnDeps & {
     /** The agent of a turn comes from the thread type, which only the preparation knows. */
     readonly agents: ThreadAgentResolver;
-}
+    /** The model of the conversation. A host that switches the model swaps the provider between two turns. */
+    readonly provider: ChatProvider;
+    /** Each model call of the turn reaches it, the calls of a sub-agent included. */
+    readonly usageRecorder: UsageRecorder;
+    /** The ledger of the asks of a turn. Absent, the loop denies each call that asks for an approval. */
+    readonly askGateway?: AskGateway;
+};
 /**
  * The session of a turn without its provenance. The harness sets the provenance from the agent that
  * it resolves, because only the preparation knows the thread type.
  */
 export type ChatTurnSession = Omit<RequestSession, "provenance">;
 /** What opens a turn: the thread and the user input. */
-export interface OpenChatTurnParams {
+export type OpenChatTurnParams = {
     readonly analysisId: string;
     readonly threadId: string;
     readonly userInput: string;
-}
-/** The transport values of a turn that is open. */
-export interface RunOpenChatTurnParams {
-    readonly session: ChatTurnSession;
-    /** Makes the provider of the turn over the emit sink of the display recorder. */
-    readonly chat: (emit: EmitFn) => AgentChat;
-    readonly emit: EmitFn;
-    readonly signal: AbortSignal;
-    readonly usageRecorder: UsageRecorder;
-    /** The approval binding. It gets the emit sink of the display recorder, thus the display records each `data-ask`. */
-    readonly ask?: (request: AskRequest, emit: EmitFn) => Promise<AskApproval>;
-    /** Who sent the user message. */
-    readonly author?: string;
-    /** When the host opened the turn. Absent counts from the call to {@link openChatTurn}. */
-    readonly startedAtMs?: number;
-    /** The cache policy of the root loop. Absent gives {@link CONVERSATION_PROMPT_CACHE}. */
-    readonly promptCache?: PromptCachePolicy;
-}
-/** The values of one whole turn. */
-export type RunChatTurnParams = OpenChatTurnParams & RunOpenChatTurnParams;
+};
 export type ChatTurnOutcome = {
     readonly status: "done";
     readonly finish: AgentFinish;
@@ -92,6 +101,7 @@ export type ChatTurnOutcome = {
 } | {
     readonly status: "failed";
     readonly reason: string;
+    readonly code: string;
     readonly cause: unknown;
 };
 /** A turn that ended before its run. It wrote no row and no turn record. */
@@ -104,7 +114,7 @@ export type ChatTurnRefusal = {
     readonly kind: "agent_unresolved";
     readonly threadType: ThreadType;
 };
-export interface ChatTurnRan {
+export type ChatTurnRan = {
     readonly kind: "ran";
     readonly outcome: ChatTurnOutcome;
     /** True when the opening of the turn landed. */
@@ -115,25 +125,43 @@ export interface ChatTurnRan {
     readonly turnUsage?: TokenUsageRollup;
     /** The final text of a run that returned. */
     readonly fallbackText?: string;
-}
-export type ChatTurnResult = ChatTurnRefusal | ChatTurnRan;
-/**
- * A turn that is prepared, with its agent resolved. Call `run` one time: each call stores a new
- * opening of the same user message.
- */
-export interface OpenChatTurn {
-    readonly kind: "ready";
-    /** The agent that runs the turn. The harness stamps its provenance on the session of the run. */
-    readonly agent: AgentDefinition;
-    readonly run: (params: RunOpenChatTurnParams) => Promise<ChatTurnRan>;
-}
-/**
- * Open one chat turn: prepare it and resolve its agent. A refusal comes back before any row of the
- * turn exists, thus a host can answer it before it starts a stream.
- */
-export declare function openChatTurn(deps: RunChatTurnDeps, params: OpenChatTurnParams): Promise<OpenChatTurn | ChatTurnRefusal>;
+};
+/** How a turn reaches its surface and its store. A turn workflow streams to its durable stream and runs each write as a step. */
+export type TurnTransport = {
+    readonly signal: AbortSignal;
+    /** The emit sink of the loop. */
+    readonly emit: EmitFn;
+    /** Receives each text delta of the root reply. A turn workflow gives none, because its model calls stream the text. */
+    readonly onText?: (text: string) => void | Promise<void>;
+    /** The durable stream that the model calls write their text to. */
+    readonly chatStream?: string;
+    /** Receives the chunks of each tool step, on a replay too. */
+    readonly toolWriter?: UIMessageStreamWriter;
+    readonly recorder: ConversationDisplayRecorder;
+    /** Runs one write of the turn. A turn workflow runs it as a step. */
+    readonly durably: <T>(name: string, write: () => Promise<T>) => Promise<T>;
+    /** The key of the group of the turn at an index, thus a write that runs again stores nothing. */
+    readonly groupKey?: (index: number) => string;
+    /** Called when the display starts a new assistant message, after a marker. */
+    readonly announce?: (messageId: string) => Promise<void>;
+    /** Model middleware inside the step of each model call. */
+    readonly modelMiddleware?: readonly LanguageModelMiddleware[];
+    /** The decision of the user on a call whose tool asks for approval. Absent: the loop denies such a call. */
+    readonly approve?: LoopOptions["approve"];
+    /** The pause of the turn. A turn workflow gives it. Absent: each failure of a request fails the turn. */
+    readonly pause?: LoopOptions["pause"];
+};
+/** The values of a turn that its run reads. */
+export type TurnRunParams = {
+    readonly session: ChatTurnSession;
+    readonly author?: string;
+    readonly startedAtMs: number;
+    readonly promptCache?: PromptCachePolicy;
+};
 /**
- * Run one chat turn: open it, store its opening, run the root loop with a round sink that stores
- * each round, and close the turn with its outcome.
+ * Run a prepared turn: store its opening, run the root loop with a round sink that stores each round, and close the
+ * turn with its outcome.
  */
-export declare function runChatTurn(deps: RunChatTurnDeps, params: RunChatTurnParams): Promise<ChatTurnResult>;
+export declare function runOpenTurn(deps: RunChatTurnDeps, turn: OpenChatTurnParams, prepared: PreparedChatTurn, agent: AgentDefinition, params: TurnRunParams, transport: TurnTransport): Promise<ChatTurnRan>;
+/** The sanitized text of the user message, thus the display never holds a secret that the model does not see. */
+export declare function userTextOf(message: ModelMessage): string;