@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/loop/call-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The call guard: a bound on repeated tool calls inside one agent run.
+ *
+ * A model that treats a tool answer as a state to poll calls the same tool
+ * with the same input again and again, or drifts through one query after
+ * another, until the iteration cap or the wall clock ends the run. A frontier
+ * model reads an "unavailable" answer once and continues; a smaller model
+ * does not. The guard makes that difference a host decision: the third call
+ * with an input the run already sent, the call past the budget of one tool,
+ * or the call past the budget of the whole run, answers a tool error that
+ * tells the model to continue with what it has. The service behind the tool never sees the refused call.
+ *
+ * The guard wraps a list of tools for ONE run. Build it where the tools of
+ * the run are built, never at construction of the host, thus the counters
+ * start at zero for every run. A terminal tool (one that ends the run) must
+ * not be wrapped: a refusal there would strand the run.
+ */
+import type { Tool } from "../tools/define-tool.js";
+export interface CallGuardPolicy {
+    /** The calls with one identical input that a run may make to one tool. The next one is refused. */
+    readonly identicalLimit: number;
+    /** The calls, with any input, that a run may make to one tool. The next one is refused. */
+    readonly perToolLimit: number;
+    /** The calls, with any input, that a run may make across every guarded tool. The next one is refused by every tool. */
+    readonly totalLimit: number;
+}
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export declare const DEFAULT_CALL_GUARD: CallGuardPolicy;
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export declare function canonicalInputKey(input: unknown): string;
+export interface GuardedCallRefusal {
+    readonly tool: string;
+    readonly kind: "identical" | "budget" | "total";
+    readonly calls: number;
+}
+export interface CallGuardOptions {
+    readonly policy?: CallGuardPolicy;
+    /** Called on each refusal, for the log of the host. */
+    readonly onRefusal?: (refusal: GuardedCallRefusal) => void;
+}
+/** Wrap each tool so its `execute` obeys the policy for the life of the returned list. */
+export declare function guardRepeatedCalls(tools: readonly Tool[], options?: CallGuardOptions): Tool[];

package/dist/loop/call-guard.js

@@ -0,0 +1,90 @@
+/**
+ * The call guard: a bound on repeated tool calls inside one agent run.
+ *
+ * A model that treats a tool answer as a state to poll calls the same tool
+ * with the same input again and again, or drifts through one query after
+ * another, until the iteration cap or the wall clock ends the run. A frontier
+ * model reads an "unavailable" answer once and continues; a smaller model
+ * does not. The guard makes that difference a host decision: the third call
+ * with an input the run already sent, the call past the budget of one tool,
+ * or the call past the budget of the whole run, answers a tool error that
+ * tells the model to continue with what it has. The service behind the tool never sees the refused call.
+ *
+ * The guard wraps a list of tools for ONE run. Build it where the tools of
+ * the run are built, never at construction of the host, thus the counters
+ * start at zero for every run. A terminal tool (one that ends the run) must
+ * not be wrapped: a refusal there would strand the run.
+ */
+import { err } from "neverthrow";
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export const DEFAULT_CALL_GUARD = { identicalLimit: 2, perToolLimit: 12, totalLimit: 40 };
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export function canonicalInputKey(input) {
+    return JSON.stringify(sortKeys(input));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort())
+            out[key] = sortKeys(value[key]);
+        return out;
+    }
+    return value;
+}
+/** Wrap each tool so its `execute` obeys the policy for the life of the returned list. */
+export function guardRepeatedCalls(tools, options = {}) {
+    const policy = options.policy ?? DEFAULT_CALL_GUARD;
+    let total = 0;
+    return tools.map((tool) => {
+        let calls = 0;
+        const byInput = new Map();
+        const guarded = {
+            ...tool,
+            ...(tool.describeCall ? { describeCall: tool.describeCall.bind(tool) } : {}),
+            ...(tool.describeResult ? { describeResult: tool.describeResult.bind(tool) } : {}),
+            async execute(input, ctx) {
+                calls += 1;
+                const key = canonicalInputKey(input);
+                const identical = (byInput.get(key) ?? 0) + 1;
+                byInput.set(key, identical);
+                if (identical > policy.identicalLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "identical", calls: identical });
+                    return err({
+                        error: `This run already called ${tool.id} with this exact input ${identical - 1} times, and the answer does not change within a run. ` +
+                            "Use the answer you have and continue. If the answer was that a resource is absent, plan without it or ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                total += 1;
+                if (total > policy.totalLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "total", calls: total });
+                    return err({
+                        error: `This run made ${policy.totalLimit} calls across its search tools, which is the search budget of one run. ` +
+                            "Submit the plan you have now. If a required resource is absent, ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                if (calls > policy.perToolLimit) {
+                    options.onRefusal?.({ tool: tool.id, kind: "budget", calls });
+                    return err({
+                        error: `This run made ${policy.perToolLimit} calls of ${tool.id}, which is the budget of one run for one tool. ` +
+                            "Continue with what you have. If a required resource is absent, ask for it; do not search again.",
+                        retryable: false,
+                    });
+                }
+                return tool.execute(input, ctx);
+            },
+        };
+        return guarded;
+    });
+}

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

@@ -153,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
@@ -372,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;
@@ -420,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.
@@ -512,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() } };
@@ -552,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

@@ -102,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/conversation-display-recorder.d.ts

@@ -18,8 +18,6 @@ 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;
 }

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

@@ -64,8 +64,10 @@ 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 = [];
@@ -103,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/thread-history.d.ts

@@ -29,7 +29,7 @@ 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;
@@ -172,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.
@@ -195,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
@@ -209,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.

package/dist/memory/thread-history.js

@@ -224,6 +224,102 @@ function closeTurnRecord(client, threadId, startSeq, close) {
                 SET status = $3, reason = $4, reported_usage = $5::jsonb, turn_duration_ms = $6, closed_at = NOW()
               WHERE thread_id = $1 AND start_seq = $2 AND status = 'open'`, [threadId, startSeq, close.status, close.reason === undefined ? null : stripNulCharacters(close.reason), rollup, close.turnDurationMs ?? null])).map(() => undefined);
 }
+/** The columns of a display-read row, and the join that the turn record needs. Both display reads select them. */
+const STORED_ROW_COLUMNS = `messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
+                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
+                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
+                turns.turn_duration_ms::text AS turn_record_duration_ms`;
+function storedRowFrom(turnJoinBounds = "") {
+    return `FROM messages
+         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq${turnJoinBounds}`;
+}
+/** The largest `bigint`, the bound of a cursor that the caller did not give. */
+const MAX_SEQ = "9223372036854775807";
+/** The smallest `bigint`, below every `seq`. */
+const MIN_SEQ = "'-9223372036854775808'";
+const PAGE_LOWER_BOUND = `COALESCE((SELECT seq FROM page_lower), ${MIN_SEQ}::bigint)`;
+const PAGE_UPPER_BOUND = `COALESCE((SELECT seq FROM page_upper), ${MAX_SEQ}::bigint)`;
+/**
+ * The statement of one page of the display read (`$1` thread, `$2` cursor or `NULL`, `$3` limit).
+ *
+ * One statement reads one snapshot, thus an append or a retract cannot add a turn between the
+ * read of the page edges and the read of the rows. The parts:
+ *
+ * - `page_walk`: a walk down from the cursor, one row for each step, that counts the turn starts
+ *   and stops at the `$3`-th. Each step is a `LIMIT 1` read of the primary key `(thread_id, seq)`
+ *   that evaluates the start predicate in the select list.
+ * - `page_lower`: the row where the walk reached `$3` starts, else `NULL`. A page that is not
+ *   full reaches the start of the thread and holds the rows before the first turn start.
+ * - `page_climb` and `page_upper`: a walk up from the cursor to the first turn start at or above
+ *   it, else `NULL`. For a cursor that a page gave this is the cursor row. For a cursor inside a
+ *   turn it is the start of the next turn, thus the turn of the cursor stays whole.
+ * - `page_next`: `page_lower` when a row lies below it. The `EXISTS` reads no envelope.
+ *
+ * The start predicate is never a `WHERE` condition of a scan that has an `ORDER BY` and a `LIMIT`.
+ * The planner has no statistics for a JSON path, so it estimates that very few rows match. It then
+ * chooses a bitmap scan and a sort of each row of the thread, and it evaluates the predicate on the
+ * envelope of each row (a tool result can be many KB). A walk of `LIMIT 1` reads of the key does
+ * not depend on that estimate, and its work grows with the rows of the page.
+ *
+ * An absent cursor, `page_lower`, and `page_upper` each become a `bigint` extreme through
+ * `COALESCE`, never a `NULL` in a comparison: `seq >= NULL` matches no row, and a form such as
+ * `($2 IS NULL OR seq < $2)` is a filter, which would visit each newer row. Each bound is an
+ * index condition on `(thread_id, seq)`. The join to the turn records carries the same bounds,
+ * because the planner estimates a bounded range as a fixed fraction of the thread and then reads
+ * each turn record of the thread through a hash join.
+ */
+const PAGE_SQL = `WITH RECURSIVE page_walk(seq, starts) AS (
+           SELECT COALESCE($2::bigint, ${MAX_SEQ}::bigint), 0::bigint
+           UNION ALL
+           SELECT below.seq, page_walk.starts + below.is_start::int
+             FROM page_walk
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq < page_walk.seq
+               ORDER BY messages.seq DESC
+               LIMIT 1
+            ) below
+            WHERE page_walk.starts < $3::bigint
+         ),
+         page_lower AS (
+           SELECT (SELECT page_walk.seq FROM page_walk WHERE page_walk.starts = $3::bigint) AS seq
+         ),
+         page_climb(seq, is_start) AS (
+           SELECT above.seq, above.is_start FROM (
+             SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+              WHERE messages.thread_id = $1 AND messages.seq >= COALESCE($2::bigint, ${MAX_SEQ}::bigint)
+              ORDER BY messages.seq ASC
+              LIMIT 1
+           ) above
+           UNION ALL
+           SELECT above.seq, above.is_start
+             FROM page_climb
+            CROSS JOIN LATERAL (
+              SELECT messages.seq, COALESCE(${GENUINE_USER_START_SQL}, false) AS is_start FROM messages
+               WHERE messages.thread_id = $1 AND messages.seq > page_climb.seq
+               ORDER BY messages.seq ASC
+               LIMIT 1
+            ) above
+            WHERE NOT page_climb.is_start
+         ),
+         page_upper AS (
+           SELECT page_climb.seq FROM page_climb WHERE page_climb.is_start
+         ),
+         page_next AS (
+           SELECT page_lower.seq FROM page_lower
+            WHERE page_lower.seq IS NOT NULL
+              AND EXISTS (SELECT 1 FROM messages WHERE thread_id = $1 AND seq < page_lower.seq)
+         )
+         SELECT ${STORED_ROW_COLUMNS}, (SELECT seq::text FROM page_next) AS next_before
+         ${storedRowFrom(` AND turns.start_seq >= ${PAGE_LOWER_BOUND} AND turns.start_seq < ${PAGE_UPPER_BOUND}`)}
+         WHERE messages.thread_id = $1
+           AND messages.seq >= ${PAGE_LOWER_BOUND}
+           AND messages.seq < ${PAGE_UPPER_BOUND}
+         ORDER BY messages.seq ASC`;
+/** The limit that the page statement receives: an integer, at least 1, and a bigint-safe size. */
+function pageLimit(limit) {
+    return Number.isFinite(limit) ? Math.min(Math.max(1, Math.trunc(limit)), Number.MAX_SAFE_INTEGER) : 1;
+}
 /**
  * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
  * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is
@@ -296,59 +392,72 @@ export function createThreadHistory(pool, logger) {
             return view.messages;
         });
     }
-    // Display reads are turn-bounded, not row-bounded. A serial-tool assistant
-    // turn is persisted as one row per step (plus its tool_result `user` rows),
-    // so a row-windowed page could split a turn — truncating the trailing
-    // report card/text out of the page the UI fetches. Read the thread and group
-    // into turns, so a turn always reloads intact. Threads are conversation-scoped
-    // and bounded, so reading every row here matches `loadRecent`'s existing
+    // A display read is turn-bounded, not row-bounded. A serial-tool assistant
+    // turn is persisted as one row per step (plus its tool_result rows), so a
+    // row-windowed read could split a turn and truncate the trailing report
+    // card or text out of what the UI fetches. Both reads group rows into turns,
+    // so a turn always reloads intact.
+    // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+    // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+    // The duration and the author obey the same rule, each from its own column.
+    // The creation time is unconditional: its column is NOT NULL, thus it has no
+    // absence to represent.
+    async function toStoredMessage(threadId, r) {
+        const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
+        const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
+        const turn = r.turn_status === null
+            ? undefined
+            : {
+                status: r.turn_status,
+                ...(r.turn_reason === null ? {} : { reason: r.turn_reason }),
+                ...(r.turn_usage === null ? {} : { usage: r.turn_usage }),
+                ...(r.turn_record_duration_ms === null ? {} : { durationMs: Number(r.turn_record_duration_ms) }),
+            };
+        return {
+            seq: Number(r.seq),
+            envelope,
+            message: envelope.message,
+            ...(displayEnvelope ? { displayEnvelope } : {}),
+            ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
+            ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
+            ...(turn === undefined ? {} : { turn }),
+            ...(r.author === null ? {} : { author: r.author }),
+            createdAt: r.created_at,
+        };
+    }
+    async function toTurns(threadId, rows) {
+        const stored = await Promise.all(rows.map((row) => toStoredMessage(threadId, row)));
+        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+    }
     async function readTurns(threadId) {
         const { rows } = await pool.query(
         // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
         // `seq::text AS seq` output alias (Postgres resolves an unqualified
         // ORDER BY name to the output column), sorting the bigint as text:
         // "10" before "2". The qualified name forces the bigint column.
-        `SELECT messages.seq::text AS seq, messages.message_envelope, messages.display_envelope, messages.reported_usage,
-                messages.turn_duration_ms::text AS turn_duration_ms, messages.author, messages.created_at,
-                turns.status AS turn_status, turns.reason AS turn_reason, turns.reported_usage AS turn_usage,
-                turns.turn_duration_ms::text AS turn_record_duration_ms
-         FROM messages
-         LEFT JOIN cortex_thread_turns turns ON turns.thread_id = messages.thread_id AND turns.start_seq = messages.seq
+        `SELECT ${STORED_ROW_COLUMNS}
+         ${storedRowFrom()}
          WHERE messages.thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
-        // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
-        // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
-        // The duration and the author obey the same rule, each from its own column.
-        // The creation time is unconditional: its column is NOT NULL, thus it has no
-        // absence to represent.
-        const stored = await Promise.all(rows.map(async (r) => {
-            const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-            const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`, logger);
-            const turn = r.turn_status === null
-                ? undefined
-                : {
-                    status: r.turn_status,
-                    ...(r.turn_reason === null ? {} : { reason: r.turn_reason }),
-                    ...(r.turn_usage === null ? {} : { usage: r.turn_usage }),
-                    ...(r.turn_record_duration_ms === null ? {} : { durationMs: Number(r.turn_record_duration_ms) }),
-                };
-            return {
-                seq: Number(r.seq),
-                envelope,
-                message: envelope.message,
-                ...(displayEnvelope ? { displayEnvelope } : {}),
-                ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
-                ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
-                ...(turn === undefined ? {} : { turn }),
-                ...(r.author === null ? {} : { author: r.author }),
-                createdAt: r.created_at,
-            };
-        }));
-        return groupTurns(stored, (row) => isGenuineUserStart(row.message));
+        return toTurns(threadId, rows);
+    }
+    async function readPage(threadId, options) {
+        const { rows } = await pool.query(PAGE_SQL, [
+            threadId,
+            options.before === undefined ? null : String(options.before),
+            pageLimit(options.limit),
+        ]);
+        // The cursor rides each row, and an empty page has no row. An empty page has no cursor either:
+        // `page_lower` is set only when its row is in the page.
+        const next = rows[0]?.next_before ?? null;
+        return { turns: await toTurns(threadId, rows), before: next === null ? null : Number(next) };
     }
     function loadAll(threadId) {
         return tryQuery("thread-history.loadAll", () => readTurns(threadId));
     }
+    function loadPage(threadId, options) {
+        return tryQuery("thread-history.loadPage", () => readPage(threadId, options));
+    }
     function retractLastTurn(threadId) {
         return withTransaction(pool, "thread-history.retractLastTurn", (client) => 
         // Take the SAME per-thread advisory lock `appendTurn` takes, and take it
@@ -426,5 +535,5 @@ export function createThreadHistory(pool, logger) {
                 AND seq > $2::bigint
                 AND ${GENUINE_USER_START_SQL}`, [threadId, seq])).map(({ rows }) => Number(rows[0].turns));
     }
-    return { appendTurn, writeTurn, loadRecent, loadAll, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
+    return { appendTurn, writeTurn, loadRecent, loadAll, loadPage, retractLastTurn, latestSeq, latestTurnAt, countUserTurnsAfter };
 }