@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/loop/compaction.d.ts

@@ -10,6 +10,11 @@ export interface CompactionRules {
     /** 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. */

package/dist/loop/compaction.js

@@ -1,2 +1,19 @@
 /** The cap of requests of one compaction exchange: up to 3 rounds of memory edits, and then the summary. */
 export const COMPACTION_MAX_REQUESTS = 4;
+/** The share of a context window that a request can fill before the loop compacts. */
+const CONTEXT_WINDOW_SHARE = 0.8;
+/**
+ * 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 function rulesForContextWindow(rules, contextWindow) {
+    if (contextWindow === undefined)
+        return rules;
+    const budget = Math.min(rules.budget, Math.floor(contextWindow * CONTEXT_WINDOW_SHARE));
+    if (budget === rules.budget)
+        return rules;
+    return {
+        budget,
+        ...(rules.turnStartBudget === undefined ? {} : { turnStartBudget: Math.floor((rules.turnStartBudget * budget) / rules.budget) }),
+    };
+}

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

@@ -91,6 +91,15 @@ export interface RunAgentOptions {
      * prompt cache and a signed thinking block bind to.
      */
     readonly toolChoice?: ChatRequest["toolChoice"];
+    /**
+     * An early cap. Read at the top of each iteration; when it answers true the
+     * loop leaves the tool phase as if `maxIterations` were reached and takes the
+     * same tool-less wrap-up path, thus a terminal wrapper salvages the run the
+     * same way. A host uses it to end a run that a policy has judged to be a
+     * loop, for example one the call guard refused too many times, without
+     * waiting for the iteration cap or the wall clock.
+     */
+    readonly stopWhen?: () => boolean;
     /**
      * Optional outcome predicate for loop-driving agents whose result is
      * recorded by a tool into closure state. Checked immediately after each

package/dist/loop/run-agent.js

@@ -97,6 +97,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     const source = {
         agentId: session.provenance.agentId ?? agent.id,
         callPath: session.provenance.callPath,
+        ...(opts.invocationId === undefined ? {} : { invocationId: opts.invocationId }),
     };
     const policy = opts.compaction;
     const viewOptions = { keepFirstTurn: policy?.keepFirstTurn === true };
@@ -152,6 +153,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     });
     let iterations = 0;
     let truncationRecoveries = 0;
+    let stoppedEarly = false;
     // Counted rather than listed: the finish record stays one bounded line for a run of
     // any length, and "50 iterations, 49 tool calls, 47 of them errored" already separates
     // a productive long run from a loop stuck retrying one failing call. The per-iteration
@@ -371,9 +373,11 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
             const records = await active.recordsAfter(conversationView([...messages, markerOf(0)], viewOptions).messages);
             const durationMs = Math.round(performance.now() - startedAt);
             messages.push(markerOf(durationMs), ...records);
-            await giveRound();
             settled = true;
+            // The `done` part goes out before the marker round: a chat turn gives the rounds after a marker a new
+            // assistant message, and the `running` and `done` parts of one compaction must stream into the same message.
             await emitPart({ id, status: "done", tokensBefore, durationMs });
+            await giveRound();
             log.info("conversation compacted", { compactionId: id, trigger, tokensBefore, durationMs });
             summarizedLast = true;
             return undefined;
@@ -419,6 +423,13 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
         if (segment.requestText !== undefined)
             messages.push(syntheticUserMessage(segment.requestText));
         for (let k = 0; k < segment.maxRequests; k++) {
+            // The early cap ends a segment before the cap as if the cap were reached, thus a run takes its
+            // tool-less wrap-up. The segment that closes a capped run is that wrap-up, and it runs to its end.
+            if (segment.closesCappedRun !== true && opts.stopWhen?.()) {
+                stoppedEarly = true;
+                log.warn("run stopped early by the host policy, taking the wrap-up path", { iterations });
+                return "capped";
+            }
             const index = segment.firstIndex + k;
             // The last request of a segment that closes a capped run ends the run,
             // whatever its reply, thus its `iteration` event is the final one.
@@ -511,6 +522,8 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
                     // abort (user cut the turn) from a plain `max_iterations` cap-out.
                     const reason = reply.finishReason === "aborted" ? "aborted" : "max_iterations";
                     recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: true });
+                    if (stoppedEarly)
+                        log.warn("run finished on the early cap", { iterations });
                     logFinish("warn", reason, true);
                     await giveRound();
                     return { messages, finish: { reason, cappedOut: true, truncationRecoveries, ...finishUsage() } };
@@ -551,6 +564,8 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     const endCapped = async () => {
         settleTranscript();
         recordAgentRun({ agentId: metricAgentId, iterations, cappedOut: true });
+        if (stoppedEarly)
+            log.warn("run finished on the early cap", { iterations });
         logFinish("warn", "max_iterations", true);
         await giveRound();
         return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries, ...finishUsage() } };

package/dist/loop/run-to-terminal.js

@@ -54,7 +54,10 @@ export async function runToTerminal(agent, initial, session, opts, salvage) {
         salvageTools: salvage.tools.map((t) => t.id),
         salvageMaxIterations: salvageBudget,
     });
-    const salvaged = await continueAgent(agent, first.messages, { text: salvage.nudge, mask: { allow: salvage.tools.map((t) => t.id) }, maxRequests: salvageBudget, stepNamespace: "salvage" }, session, opts);
+    // The early cap of the first run must not end the salvage turn, whose whole
+    // purpose is to submit after the first run stopped.
+    const { stopWhen: _stopWhen, ...continuation } = opts;
+    const salvaged = await continueAgent(agent, first.messages, { text: salvage.nudge, mask: { allow: salvage.tools.map((t) => t.id) }, maxRequests: salvageBudget, stepNamespace: "salvage" }, session, continuation);
     // The continuation is the same logical run as the first attempt, so its
     // rollups must cover both, or the caller reads the salvage's tokens as the whole cost.
     //

package/dist/loop/types.d.ts

@@ -46,6 +46,8 @@ export type RunStep = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
 export interface EventSource {
     readonly agentId: string;
     readonly callPath: readonly string[];
+    /** The id of the tool call that runs this loop. For a data profile, the workflow id of its attempt. */
+    readonly invocationId?: string;
 }
 /**
  * Orchestration events the loop emits: iteration boundaries and tool-call
@@ -100,6 +102,12 @@ export type EmitEvent = {
      * taken. As a result a host can fall back to its own observation.
      */
     readonly durationMs?: number;
+} | {
+    /** The display recorder of a chat turn emits it, not the loop. See `MessageStartEvent`. */
+    readonly type: "message-start";
+    readonly source: EventSource;
+    readonly messageId: string;
+    readonly role: "user" | "assistant";
 };
 /**
  * A UI presentation event a tool streams to chat — an AI-SDK `data-*`

package/dist/memory/card-builders.d.ts

@@ -16,9 +16,12 @@
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+import type { PlanPart } from "../contracts/chat-parts.js";
+import { type PlanRecord } from "../state/index.js";
 export interface PlanCardData {
     id: string;
     planId: string;
+    parentPlanId?: string;
     title?: string;
     steps: unknown;
     analytical_narrative: unknown;
@@ -37,6 +40,14 @@ export interface RunCardData {
     title: string;
     stepCount: number;
 }
+/** Build the `data-plan` payload of a stored plan record. `null` when the
+ *  document no longer parses. An explicit `title` overrides the plan title. */
+export declare function planCardOf(record: PlanRecord, title?: string): PlanCardData | null;
+/** The `data-plan` part of a stored plan record, with the title of the plan. The
+ *  part schema drops each key that it does not name, thus the part equals the
+ *  stored card of a transcript. `null` when the document does not parse or the
+ *  schema refuses the part. */
+export declare function planPartOf(record: PlanRecord): PlanPart | null;
 /** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
  *  the plan is missing or no longer parses (absence is NOT an error) — the
  *  caller falls back to a chip. */

package/dist/memory/card-builders.js

@@ -16,8 +16,9 @@
 import { createHash } from "node:crypto";
 import { okAsync } from "neverthrow";
 import { tryQuery } from "../lib/db-result.js";
+import { PlanPartSchema } from "../contracts/schemas/chat-parts.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
-import { loadPlan } from "../state/index.js";
+import { loadPlan, loadPlanRecord } from "../state/index.js";
 import { parseStructureUrl } from "../contracts/structure-source.js";
 import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
 import { validatePath } from "../tools/lib/path-validation.js";
@@ -32,30 +33,43 @@ function presentationId(input) {
         .slice(0, 16);
     return `pres-${hash}`;
 }
+/** Build the `data-plan` payload of a stored plan record. `null` when the
+ *  document no longer parses. An explicit `title` overrides the plan title. */
+export function planCardOf(record, title) {
+    const parsed = AnalysisPlanSchema.safeParse(record.plan);
+    if (!parsed.success)
+        return null;
+    const id = `pres-${createHash("sha256").update(record.planId).digest("hex").slice(0, 16)}`;
+    // Explicit `show_plan({ title })` overrides; otherwise default to the
+    // planner-set plan title so both cards share one source.
+    const heading = title ?? parsed.data.title;
+    return {
+        id,
+        planId: record.planId,
+        ...(record.parentPlanId !== null ? { parentPlanId: record.parentPlanId } : {}),
+        ...(heading !== undefined ? { title: heading } : {}),
+        steps: parsed.data.steps,
+        analytical_narrative: parsed.data.analytical_narrative,
+        omicsType: parsed.data.omicsType,
+        omicsSubtype: parsed.data.omicsSubtype,
+    };
+}
+/** The `data-plan` part of a stored plan record, with the title of the plan. The
+ *  part schema drops each key that it does not name, thus the part equals the
+ *  stored card of a transcript. `null` when the document does not parse or the
+ *  schema refuses the part. */
+export function planPartOf(record) {
+    const card = planCardOf(record);
+    if (!card)
+        return null;
+    const part = PlanPartSchema.safeParse({ type: "data-plan", ...card });
+    return part.success ? part.data : null;
+}
 /** Build the `data-plan` payload by loading the stored plan. `ok(null)` when
  *  the plan is missing or no longer parses (absence is NOT an error) — the
  *  caller falls back to a chip. */
 export function buildPlanCardData(pool, planId, analysisId, title) {
-    return loadPlan(pool, planId, { analysisId }).map((plan) => {
-        if (!plan)
-            return null;
-        const parsed = AnalysisPlanSchema.safeParse(plan);
-        if (!parsed.success)
-            return null;
-        const id = `pres-${createHash("sha256").update(planId).digest("hex").slice(0, 16)}`;
-        // Explicit `show_plan({ title })` overrides; otherwise default to the
-        // planner-set plan title so both cards share one source.
-        const heading = title ?? parsed.data.title;
-        return {
-            id,
-            planId,
-            ...(heading !== undefined ? { title: heading } : {}),
-            steps: parsed.data.steps,
-            analytical_narrative: parsed.data.analytical_narrative,
-            omicsType: parsed.data.omicsType,
-            omicsSubtype: parsed.data.omicsSubtype,
-        };
-    });
+    return loadPlanRecord(pool, planId, { analysisId }).map((record) => (record ? planCardOf(record, title) : null));
 }
 /** Build the `data-run-card` payload for a started analysis run. Loads the
  *  plan (for `title` + `stepCount`) the same way `buildPlanCardData` does. The

package/dist/memory/conversation-display-recorder.d.ts

@@ -18,8 +18,8 @@ export interface ConversationDisplayRecorderOptions {
     /** The root agent of the turn. Its call path is `[agentId]`, and an event with a longer path is from a sub-agent. */
     readonly agentId: string;
     readonly sink: EmitFn;
-    readonly userMessageId?: string;
-    readonly assistantMessageId?: string;
+    /** The clock for the times of the sub-agent activity, in milliseconds. The default is the wall clock. */
+    readonly now?: () => number;
 }
 /**
  * Record the display of a turn through the same translation path as a live surface: each event becomes a

package/dist/memory/conversation-display-recorder.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { applyChatFrame, checkChatPart, isRootFrame, toChatFrame } from "../contracts/chat-frame.js";
 import { PART_REGISTRY } from "../contracts/part-registry.js";
+import { createSubAgentActivityTracker } from "../contracts/subagent-activity.js";
 import { compactionExchangeOf, compactionMarkerOf } from "./ai-sdk-message-storage.js";
 import { conversationDisplayPart } from "./conversation-display-storage.js";
 function jsonCopy(value) {
@@ -63,12 +64,16 @@ function compactionDivider(marker) {
  */
 export function createConversationDisplayRecorder(options) {
     // One id for each message of the turn, thus the rounds of a turn replay as one assistant message.
-    const userMessageId = options.userMessageId ?? randomUUID();
-    let assistantMessageId = options.assistantMessageId ?? randomUUID();
+    const userMessageId = randomUUID();
+    let assistantMessageId = randomUUID();
+    let userAnnounced = false;
+    let announcedAssistantId;
     const rootSource = { agentId: options.agentId, callPath: [options.agentId] };
     // The messages of the open round. A later update of a part lands in the next round, and the replay replaces the earlier copy.
     let round = [];
     let finished = false;
+    const now = options.now ?? Date.now;
+    const subAgentActivity = createSubAgentActivityTracker();
     function apply(frame) {
         round = applyChatFrame(round, frame, assistantMessageId).messages;
     }
@@ -84,7 +89,13 @@ export function createConversationDisplayRecorder(options) {
     }
     function record(event) {
         const frame = toChatFrame(event, rootSource);
-        if (frame === null || !isRootFrame(frame))
+        if (frame === null)
+            return;
+        // The tracker reads the frames of the sub-agents, and `applyChatFrame` ignores them.
+        const activity = subAgentActivity.track(frame, now());
+        if (activity !== null && durableConversationType(activity.type))
+            apply(recordedPart(activity));
+        if (!isRootFrame(frame))
             return;
         if (frame.type.startsWith("data-")) {
             // Each chat event type is named without the `data-` prefix, thus a `data-` frame is a part frame.
@@ -94,10 +105,33 @@ export function createConversationDisplayRecorder(options) {
         }
         apply(frame);
     }
+    function messageStart(messageId, role) {
+        return { type: "message-start", messageId, role, source: rootSource };
+    }
+    /** The `message-start` of each id that the sink did not get yet. */
+    function announcements() {
+        const starts = [];
+        if (!userAnnounced) {
+            userAnnounced = true;
+            starts.push(messageStart(userMessageId, "user"));
+        }
+        if (announcedAssistantId !== assistantMessageId) {
+            announcedAssistantId = assistantMessageId;
+            starts.push(messageStart(assistantMessageId, "assistant"));
+        }
+        return starts;
+    }
+    // A `message-start` goes to the sink only immediately before an event: a host reads the first call of its sink
+    // as the start of the turn, and a turn that ends before any event must still get its plain refusal (for example an HTTP 402).
     const emit = (event) => {
         if (!finished)
             record(event);
-        return options.sink(event);
+        const starts = announcements();
+        if (starts.length === 0)
+            return options.sink(event);
+        // The calls start in the order of the stream with no await between them: a later emit that its caller does
+        // not await, for example a text delta, must not reach the sink before them.
+        return Promise.all([...starts, event].map((next) => options.sink(next))).then(() => undefined);
     };
     function takeOpening() {
         return [{ id: userMessageId, role: "user", parts: [{ type: "text", text: options.userText, state: "done" }] }];

package/dist/memory/conversation-display-storage.d.ts

@@ -15,7 +15,7 @@
  * reconstruction.
  */
 import { type DataUIPart, type UIMessage } from "ai";
-import type { AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart } from "../contracts/chat-parts.js";
+import type { AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, PlanApprovalPart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart, SubAgentActivityEntry, SubAgentActivityPart } from "../contracts/chat-parts.js";
 import type { ToolCallOutcome } from "../contracts/chat-events.js";
 import type { ChatMessage, MessagePart, ToolCallPart } from "../contracts/message.js";
 import type { Logger } from "../lib/logger.js";
@@ -37,11 +37,17 @@ export type ConversationUIData = {
     presentation: Payload<PresentationPart>;
     plan: Payload<PlanPart>;
     "run-card": Payload<RunCardPart>;
+    "plan-approval": Payload<PlanApprovalPart>;
     "file-reference": Payload<FileReferencePart>;
     ask: Payload<AskPart>;
     "child-session-started": Payload<ChildSessionStartedPart>;
     "report-rendered": Payload<ReportRenderedPart>;
     compaction: Payload<CompactionPart>;
+    "subagent-activity": Omit<Payload<SubAgentActivityPart>, "entries"> & {
+        entries: (Omit<SubAgentActivityEntry, "outcome"> & {
+            outcome: ToolCallOutcome;
+        })[];
+    };
 };
 export interface ConversationDisplayMetadata {
     interrupted?: boolean;
@@ -63,7 +69,8 @@ export declare function parseStoredDisplayEnvelope(value: unknown, identity: str
  * flight) and required here, because a record is of a call that is no longer
  * running. An in-flight call being recorded is one the turn never saw finish, so
  * absence resolves to `incomplete` at exactly this boundary — once, where the
- * lifetime changes — rather than at each reader.
+ * lifetime changes — rather than at each reader. An entry of a sub-agent call
+ * closes the same way, and an `incomplete` entry has no end time.
  */
 export declare function conversationDisplayPart(part: Exclude<MessagePart, {
     type: "text";

package/dist/memory/conversation-display-storage.js

@@ -16,7 +16,7 @@
  */
 import { validateUIMessages } from "ai";
 import { z } from "zod";
-import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, } from "../contracts/schemas/chat-parts.js";
+import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
 import { ToolCallOutcomeSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
 const DisplayEnvelopeHeaderSchema = z.object({
@@ -65,11 +65,15 @@ const dataSchemas = {
     presentation: PresentationPartSchema.omit({ type: true }),
     plan: PlanPartSchema.omit({ type: true }),
     "run-card": RunCardPartSchema.omit({ type: true }),
+    "plan-approval": PlanApprovalPartSchema.omit({ type: true }),
     "file-reference": FileReferencePartSchema.omit({ type: true }),
     ask: AskPartSchema.omit({ type: true }),
     "child-session-started": ChildSessionStartedPartSchema.omit({ type: true }),
     "report-rendered": ReportRenderedPartSchema.omit({ type: true }),
     compaction: CompactionPartSchema.omit({ type: true }),
+    "subagent-activity": SubAgentActivityPartSchema.omit({ type: true }).extend({
+        entries: z.array(SubAgentActivityEntrySchema.extend({ outcome: ToolCallOutcomeSchema })),
+    }),
 };
 export function envelopeDisplayMessages(messages) {
     if (messages.length === 0)
@@ -157,6 +161,12 @@ export async function parseStoredDisplayEnvelope(value, identity, logger) {
 function displayPartType(part) {
     return (part.type === "tool-call" ? "data-tool-call" : part.type);
 }
+function closedEntry(entry) {
+    if (entry.outcome !== undefined)
+        return { ...entry, outcome: entry.outcome };
+    const { endedAt: _endedAt, ...open } = entry;
+    return { ...open, outcome: "incomplete" };
+}
 /** The id a part reconciles on: a tool call by its call id, a card by its own stable id. */
 function displayPartId(part) {
     if (part.type === "tool-call")
@@ -171,11 +181,16 @@ function displayPartId(part) {
  * flight) and required here, because a record is of a call that is no longer
  * running. An in-flight call being recorded is one the turn never saw finish, so
  * absence resolves to `incomplete` at exactly this boundary — once, where the
- * lifetime changes — rather than at each reader.
+ * lifetime changes — rather than at each reader. An entry of a sub-agent call
+ * closes the same way, and an `incomplete` entry has no end time.
  */
 export function conversationDisplayPart(part) {
     const { type: _type, ...rest } = part;
-    const data = part.type === "tool-call" ? { ...rest, outcome: part.outcome ?? "incomplete" } : rest;
+    const data = part.type === "tool-call"
+        ? { ...rest, outcome: part.outcome ?? "incomplete" }
+        : part.type === "data-subagent-activity"
+            ? { ...rest, entries: part.entries.map(closedEntry) }
+            : rest;
     return { type: displayPartType(part), id: displayPartId(part), data };
 }
 /**

package/dist/memory/thread-history.d.ts

@@ -27,8 +27,9 @@ import type { TokenUsageRollup } from "../contracts/usage.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+import type { MessagePart } from "../contracts/message.js";
 import { type ConversationUIMessage, type StoredDisplayEnvelope } from "./conversation-display-storage.js";
-/** One stored message, as returned by the display read (`loadAll`). */
+/** One stored message, as returned by the display reads (`loadAll` and `loadPage`). */
 export interface StoredMessage {
     readonly seq: number;
     readonly envelope: StoredMessageEnvelope;
@@ -104,8 +105,14 @@ export interface ConversationTurn {
  * never shown. The harness owns the record-to-`system` mapping for the same
  * reason it owns the marker — a host that hand-assembled either could produce a
  * message the turn-boundary predicates fail to recognise.
+ *
+ * With `displayParts`, the display message holds those parts in place of the
+ * text part, and the model message is still the record of `text`. The text then
+ * stays for the model alone.
  */
-export declare function conversationRecordTurn(text: string): ConversationTurn;
+export declare function conversationRecordTurn(text: string, displayParts?: readonly Exclude<MessagePart, {
+    type: "text";
+}>[]): ConversationTurn;
 /** The status of a chat turn: `open` while it runs, then its outcome. */
 export type TurnStatus = "open" | "done" | "aborted" | "failed";
 /** The close of a chat turn. It sets the outcome on the turn record, one time. */
@@ -165,6 +172,20 @@ export interface LoadRecentOptions {
     /** Keep the first turn of the thread, the seed of a report thread, in front of the latest summary. */
     readonly keepFirstTurn?: boolean;
 }
+/** The options of {@link ThreadHistory.loadPage}. */
+export interface LoadPageOptions {
+    /** The cursor that the previous page gave. Absent for the newest page. */
+    readonly before?: number;
+    /** The maximum count of turns in the page. */
+    readonly limit: number;
+}
+/** One page of the display read, as {@link ThreadHistory.loadPage} gives it. */
+export interface TurnPage {
+    /** The whole turns of the page, oldest-first. */
+    readonly turns: StoredMessage[][];
+    /** The cursor of the next older page, or `null` when the page holds the oldest row of the thread. */
+    readonly before: number | null;
+}
 /**
  * The conversation message store. Two methods, by design — no generic row
  * insert (see the harness-thread-store spec). `threadId` is the conversation scope — one UI thread.
@@ -188,12 +209,8 @@ export interface ThreadHistory {
     /**
      * Return a thread's messages oldest-first for UI display, grouped into turns.
      * It gives each row, and the view of the agent loop is `loadRecent`'s job.
-     *
-     * There is no paginated form, because a page could never cost less: the read
-     * selects and parses every row of the thread and would slice only afterwards,
-     * so a page saves no query and no parse. It would only truncate the answer,
-     * which is a way to lose turns and not a way to save work. A reader wanting a
-     * window takes one here, where it knows what it is bounding.
+     * It selects and parses every row of the thread, thus its work grows with the
+     * thread. {@link ThreadHistory.loadPage} bounds that work.
      *
      * Grouped rather than flat because the grouping is what the read computes and
      * what a turn count means, and `.flat()` recovers the rows in `seq` order for
@@ -202,6 +219,23 @@ export interface ThreadHistory {
      * this read already found.
      */
     loadAll(threadId: string): ResultAsync<StoredMessage[][], DbError>;
+    /**
+     * Return the newest whole turns of a thread for UI display, up to `limit` turns, oldest-first.
+     * With `before`, it returns the newest whole turns below the turn that the cursor names.
+     * The rows are the same as the rows of {@link ThreadHistory.loadAll}.
+     *
+     * The read selects and parses only the rows of its page, thus its work does not grow with
+     * the turns before the page. The page edges inside the thread are turn starts, so the read
+     * never truncates a turn, also for a cursor that is not a turn start: the turn of the cursor
+     * row is then the newest turn of the page, and it is whole. The rows before the first turn
+     * start make one group, and the group counts as a turn.
+     *
+     * The cursor is the `seq` of the opening row of the oldest turn of the page. A `seq` never
+     * moves and a retract removes only the tail, thus a cursor stays correct across a later
+     * append and a later retract. A `limit` that is not finite reads as 1, and each other
+     * `limit` reads as its integer part with a minimum of 1.
+     */
+    loadPage(threadId: string, options: LoadPageOptions): ResultAsync<TurnPage, DbError>;
     /**
      * Remove the thread's most recent turn — every row from the last
      * genuine-user-start `seq` onward, and its turn record — in a single transaction.