@inflexa-ai/harness 0.41.1 → 0.42.0

package/dist/lib/page-capture.js

@@ -5,12 +5,16 @@
  * readiness signal of the page, and gives back base64 screenshots. The eyes tool of a report session reads
  * this module.
  *
+ * The layout resolves at the CSS width of a reader, and the picture renders at half the device scale. A
+ * picture costs tokens in proportion to its area, thus the half scale lets one look hold a whole report.
+ *
  * A short page captures as one full-page shot. A tall page captures as consecutive vertical slices, because
- * one tall picture dies twice on the provider path: a picture past the hard dimension cap rejects the whole
- * request, and a legal tall picture downscales to about 1568 pixels on the long side, which compresses the
- * text past legibility. A slice of about two window heights survives both. The slice budget bounds what one
- * look costs, and a page past the budget truncates with the captured and the total pixels on the coverage,
- * thus the truncation is never silent.
+ * the model reads a picture whole only up to a limit on the long edge, and a taller picture downscales or
+ * refuses the request. The slice budget bounds what one look costs, and a page past the budget truncates
+ * with the captured and the total pixels on the coverage, thus the truncation is never silent.
+ *
+ * A capture can also take one block alone. The renderer marks each block with its id, and the capture clips
+ * the union box of the marked elements with a margin. A page that holds no such mark gives no picture.
  *
  * The readiness contract is the reason for one shared body. The renderer emits the event name and the
  * sentinel name, and `report-render/page.ts` owns both constants together with the two budgets. This module
@@ -26,6 +30,7 @@
  */
 import { withPage } from "./chrome.js";
 import { PAGE_NAV_TIMEOUT_MS, PAGE_READY_TIMEOUT_MS, THEME_READY_EVENT, THEME_READY_SENTINEL } from "../report-render/page.js";
+import { BLOCK_ID_ATTRIBUTE } from "../report-render/views/block-mark.js";
 /** The budget of the optional selector wait. The wait is best-effort, thus a miss captures the page anyway. */
 const SELECTOR_TIMEOUT_MS = 5_000;
 /**
@@ -37,22 +42,22 @@ const SELECTOR_TIMEOUT_MS = 5_000;
 const VIEWPORT_WIDTH = 1440;
 const VIEWPORT_HEIGHT = 900;
 /**
- * The height of one capture slice, in CSS pixels, and the bound of a single-shot page.
- *
- * The provider downscales every picture to about 1568 pixels on the long side before the model reads it. Two
- * window heights survive that downscale with readable text, and a taller picture reaches the model compressed
- * past that. Thus a page at this height or under captures as one full-page shot, and a taller page captures
- * as slices of this height.
+ * The device scale of one capture. The layout keeps the CSS width of a reader, and the picture holds half
+ * the pixels on each side. A picture costs about one token for each 750 pixels of its area.
  */
-const TILE_HEIGHT_PX = VIEWPORT_HEIGHT * 2;
+const DEVICE_SCALE_FACTOR = 0.5;
 /**
- * The most slices of one capture.
- *
- * Each slice is one picture on the tool result, and the budget bounds what one look costs the context. A page
- * taller than the budget covers truncates, and the coverage carries the captured and the total pixels, thus
- * the truncation is never silent.
+ * The height of one slice and the bound of a single-shot page, in CSS pixels. At the half scale a slice is
+ * 720 by 2000 pixels, under the long edge of 2576 pixels that the model reads with no downscale.
  */
-const MAX_TILES = 6;
+const TILE_HEIGHT_PX = 4_000;
+/**
+ * The most slices of one capture: 20,000 CSS pixels, about 9,600 tokens, thus a report of 16,000 pixels
+ * fits whole. A taller page truncates, and the coverage carries the captured and the total pixels.
+ */
+const MAX_TILES = 5;
+/** The margin around the box of one block, in CSS pixels. Content that overflows its box stays in the picture. */
+const BLOCK_MARGIN_PX = 16;
 /**
  * The body of the readiness wait, in the browser context. The sentinel arm resolves a page that dispatched
  * the event before this wait registered, thus a plain listener never blocks forever. The timer arm bounds a
@@ -94,26 +99,67 @@ async function measureTotalHeight(page) {
     return typeof measured === "number" && Number.isFinite(measured) ? measured : 0;
 }
 /**
- * Capture the slices of one tall page, in document order. Each slice clips {@link TILE_HEIGHT_PX} rows at the
- * reader width, and the last slice ends at the document height or at the budget, whichever comes first.
+ * Capture the rows of one area as slices, in document order. Each slice clips {@link TILE_HEIGHT_PX} rows,
+ * and the last slice ends at the area or at the budget, whichever comes first.
  */
-async function captureTiles(page, totalPx) {
-    const tileCount = Math.min(Math.ceil(totalPx / TILE_HEIGHT_PX), MAX_TILES);
+async function captureSlices(page, area) {
+    const heightPx = area.toY - area.fromY;
+    const tileCount = Math.min(Math.ceil(heightPx / TILE_HEIGHT_PX), MAX_TILES);
     const screenshots = [];
     for (let index = 0; index < tileCount; index++) {
-        const fromY = index * TILE_HEIGHT_PX;
-        const toY = Math.min(fromY + TILE_HEIGHT_PX, totalPx);
-        const clip = { x: 0, y: fromY, width: VIEWPORT_WIDTH, height: toY - fromY };
+        const fromY = area.fromY + index * TILE_HEIGHT_PX;
+        const toY = Math.min(fromY + TILE_HEIGHT_PX, area.toY);
+        const clip = { x: area.x, y: fromY, width: area.width, height: toY - fromY };
         screenshots.push({ base64: toBase64(await page.screenshot({ encoding: "base64", clip })), range: { fromY, toY } });
     }
-    const capturedPx = Math.min(tileCount * TILE_HEIGHT_PX, totalPx);
-    return { screenshots, coverage: { kind: "tiled", capturedPx, totalPx } };
+    return { screenshots, capturedPx: Math.min(tileCount * TILE_HEIGHT_PX, heightPx) };
+}
+/**
+ * The body of the block measure, in the browser context: the union box of the marked elements, with the
+ * margin, or `null`. The body compares each attribute value, thus an id never becomes part of a selector.
+ */
+function measureBlock(attribute, blockId, margin) {
+    let left = Number.POSITIVE_INFINITY;
+    let top = Number.POSITIVE_INFINITY;
+    let right = Number.NEGATIVE_INFINITY;
+    let bottom = Number.NEGATIVE_INFINITY;
+    for (const node of Array.from(document.querySelectorAll(`[${attribute}]`))) {
+        if (node.getAttribute(attribute) !== blockId)
+            continue;
+        const rect = node.getBoundingClientRect();
+        left = Math.min(left, rect.left + window.scrollX);
+        top = Math.min(top, rect.top + window.scrollY);
+        right = Math.max(right, rect.right + window.scrollX);
+        bottom = Math.max(bottom, rect.bottom + window.scrollY);
+    }
+    if (left === Number.POSITIVE_INFINITY) {
+        return null;
+    }
+    const root = document.documentElement;
+    const x = Math.max(0, Math.floor(left - margin));
+    const fromY = Math.max(0, Math.floor(top - margin));
+    const toX = Math.min(root.scrollWidth, Math.ceil(right + margin));
+    const toY = Math.min(root.scrollHeight, Math.ceil(bottom + margin));
+    // A block of no height still gives a strip, thus the picture shows the empty place of the block.
+    return { x, width: Math.max(1, toX - x), fromY, toY: Math.max(fromY + 1, toY) };
+}
+/**
+ * Take the pictures of one block. A refused bitmap propagates, because the window shows the top of the page
+ * and not the block.
+ */
+async function captureBlock(page, blockId) {
+    const area = await page.evaluate(measureBlock, BLOCK_ID_ATTRIBUTE, blockId, BLOCK_MARGIN_PX);
+    if (area === null) {
+        return { screenshots: [], coverage: { kind: "no-block" } };
+    }
+    const sliced = await captureSlices(page, area);
+    return { screenshots: sliced.screenshots, coverage: { kind: "block", capturedPx: sliced.capturedPx, totalPx: area.toY - area.fromY } };
 }
 /**
  * Take the pictures of one settled page.
  *
  * A page at the single-shot bound or under gives one full-page shot. A taller page gives consecutive slices,
- * because the provider path compresses or rejects one tall picture; the module comment carries the account.
+ * because the model downscales or refuses one tall picture; the module comment carries the account.
  *
  * The compositor can refuse a bitmap of either shape while the bitmap of the window is fine. A degraded
  * picture beats a dead look, thus a refusal retries one time at the window. A second throw names a broken
@@ -122,8 +168,10 @@ async function captureTiles(page, totalPx) {
 async function captureShots(page) {
     const totalPx = await measureTotalHeight(page);
     try {
-        if (totalPx > TILE_HEIGHT_PX)
-            return await captureTiles(page, totalPx);
+        if (totalPx > TILE_HEIGHT_PX) {
+            const sliced = await captureSlices(page, { x: 0, width: VIEWPORT_WIDTH, fromY: 0, toY: totalPx });
+            return { screenshots: sliced.screenshots, coverage: { kind: "tiled", capturedPx: sliced.capturedPx, totalPx } };
+        }
         return { screenshots: [{ base64: toBase64(await page.screenshot({ encoding: "base64", fullPage: true })) }], coverage: { kind: "full" } };
     }
     catch (refused) {
@@ -146,7 +194,7 @@ async function captureShots(page) {
  * The pictures hold the document, and not the window alone. Thus a caller can judge a section that a reader
  * reaches by a scroll. A short page arrives as one full-page shot, and a tall page arrives as consecutive
  * slices in document order. A refused bitmap degrades to the window, and the coverage of the result names
- * what the pictures hold.
+ * what the pictures hold. A capture that names a block holds that block alone.
  *
  * The readiness wait is best-effort. A page that never signals still captures at the readiness budget, thus
  * a broken page gives a picture that shows what broke.
@@ -165,7 +213,7 @@ export function capturePage(chrome, url, options = {}) {
         });
         // The size is set before the navigation, because a layout resolves at load time. The connection gives
         // a small default window, and that window collapses each multi-column band of the design.
-        await page.setViewport({ width: VIEWPORT_WIDTH, height: VIEWPORT_HEIGHT });
+        await page.setViewport({ width: VIEWPORT_WIDTH, height: VIEWPORT_HEIGHT, deviceScaleFactor: DEVICE_SCALE_FACTOR });
         // The preference is active before the navigation, because the page reveals its sections as it loads.
         // A preference that arrives after the load reaches a page that already runs its transitions.
         await page.emulateMediaFeatures([{ name: "prefers-reduced-motion", value: "reduce" }]);
@@ -185,7 +233,7 @@ export function capturePage(chrome, url, options = {}) {
         }
         // The pictures must show the whole document at the layout that a reader gets. Thus a defect below the
         // fold is visible, and a question about content that never appeared has an answer.
-        const shots = await captureShots(page);
+        const shots = options.blockId === undefined ? await captureShots(page) : await captureBlock(page, options.blockId);
         return {
             screenshots: shots.screenshots,
             coverage: shots.coverage,

package/dist/loop/compaction.d.ts

@@ -3,10 +3,15 @@ import type { ToolMask } from "./tool-mask.js";
 import type { LoopMessage } from "./types.js";
 /** The cap of requests of one compaction exchange: up to 3 rounds of memory edits, and then the summary. */
 export declare const COMPACTION_MAX_REQUESTS = 4;
-/** How the loop compacts its conversation when the view passes the budget. */
-export interface CompactionPolicy {
-    /** The budget of the view, in estimated tokens. */
+/** When an agent compacts its conversation, in the input tokens that the provider reported for the last request. */
+export interface CompactionRules {
+    /** The budget before each request of a turn. */
     readonly budget: number;
+    /** The budget before the user message of a turn joins the conversation. Absent: no compaction before the user message. */
+    readonly turnStartBudget?: number;
+}
+/** How the loop compacts its conversation when the last request passed a budget. */
+export interface CompactionPolicy extends CompactionRules {
     /** The provider of the conversation, with no text stream to the surface: the summary is no reply. */
     readonly provider: AgentChat;
     /** The text of the compaction request. */

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

@@ -67,6 +67,12 @@ export interface RunAgentOptions {
      * `recordsAfter` reads the database outside a step.
      */
     readonly compaction?: CompactionPolicy;
+    /**
+     * The messages that open the turn of a chat thread: the user message and its context records. The loop appends
+     * them after the turn-start compaction, thus the conversation holds each message in the order that it was sent.
+     * Absent: `initial` holds the whole conversation.
+     */
+    readonly turnInput?: readonly LoopMessage[];
     /**
      * Per-turn user-approval seam threaded into every tool's `ToolContext` as
      * `ctx.ask`. A conversation tool calls it to pause for an explicit user
@@ -184,6 +190,11 @@ export interface LoopSegment {
  * prefix (system prompt, tools, tool choice) as the one before it.
  */
 export interface OpenLoop {
+    /**
+     * Compact the conversation when the last request passed the turn-start budget, and then append the input of the
+     * turn. The result of the run when an abort ends the compaction, or `undefined` when the run continues.
+     */
+    startTurn(input: readonly LoopMessage[]): Promise<RunAgentResult | undefined>;
     /** Run one segment: the result of the run when a reply ends it, or `"capped"` when the segment used its cap. */
     runSegment(segment: LoopSegment): Promise<SegmentResult | "capped">;
     /** End a run after its last segment used its cap. */

package/dist/loop/run-agent.js

@@ -8,8 +8,8 @@ import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/ot
 import { ResultError, unwrapOrThrow } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
-import { dropMarkerMessage, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, } from "../memory/ai-sdk-message-storage.js";
-import { conversationView, keptTurnsForDrop, viewTokens } from "../memory/conversation-view.js";
+import { contextRecordOf, markCompactionExchange, markInterruptedMessage, summaryMarkerMessage, syntheticUserMessage, withRequestInputTokens, } from "../memory/ai-sdk-message-storage.js";
+import { conversationView, lastRequestInputTokens } from "../memory/conversation-view.js";
 import { answerUnansweredToolCalls } from "../memory/tool-call-integrity.js";
 import { classifyProviderError, extractStatus } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, withPromptCacheBreakpoint, withSystemPromptBreakpoint } from "../providers/prompt-cache.js";
@@ -42,6 +42,11 @@ export const WRAP_UP_MAX_REQUESTS = 2;
 async function runAgentLoop(agent, initial, session, opts) {
     const formatStepName = opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER;
     const loop = openLoop(agent, initial, session, opts, agent.id);
+    if (opts.turnInput !== undefined) {
+        const ended = await loop.startTurn(opts.turnInput);
+        if (ended !== undefined)
+            return ended;
+    }
     const task = await loop.runSegment({ mask: opts.toolMask, maxRequests: agent.maxIterations, stepNames: formatStepName, firstIndex: 0, checksBudget: true });
     if (task !== "capped")
         return task;
@@ -100,6 +105,8 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     let continuesTruncation = false;
     let compactionStopped = false;
     let compactions = 0;
+    // The first request after a summary shows if the summary brought the conversation under the budget.
+    let summarizedLast = false;
     // Bound from the same `source` the emitted events carry: one derivation feeding
     // both sinks, so a record and an event cannot disagree about who produced them.
     // `callPath` rides as an array rather than a joined string — the queryable form;
@@ -224,7 +231,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
         if (!endsOnRequestRefusal) {
             const reply = await resultStep(callStep)(stepName, chat);
             accountForChatCall(reply, { ...accounting, stepName });
-            return reply;
+            return withRequestAnchor(reply);
         }
         // The step gives the `Result` as its value, thus a refusal ends the segment and no step throws for it.
         const result = await callStep(stepName, async () => await chat());
@@ -233,7 +240,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
             return { refusal };
         const reply = unwrapOrThrow(result);
         accountForChatCall(reply, { ...accounting, stepName });
-        return reply;
+        return withRequestAnchor(reply);
     };
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
@@ -327,13 +334,13 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
         return { messages, finish: { reason: "error", cappedOut: false, truncationRecoveries, ...finishUsage() }, refusal };
     };
     /** The result of the run when an abort ends the exchange, or `undefined` when the run continues. */
-    const compact = async (active, tokensBefore, index) => {
+    const compact = async (active, tokensBefore, index, trigger) => {
         const id = randomUUID();
         const stepNamespace = `compaction-${compactions++}`;
         const startedAt = performance.now();
-        const emitPart = (data) => emit({ type: "data-compaction", source, data });
+        const emitPart = (data) => emit({ type: "data-compaction", source, data: { ...data, trigger } });
         await emitPart({ id, status: "running", tokensBefore });
-        const { onRound: _onRound, compaction: _compaction, ...conversationOptions } = opts;
+        const { onRound: _onRound, compaction: _compaction, turnInput: _turnInput, ...conversationOptions } = opts;
         let settled = false;
         try {
             const exchange = await continueAgent(agent, viewOf(), {
@@ -357,36 +364,25 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
                 return { messages, finish: { reason: "aborted", cappedOut: false, truncationRecoveries, ...finishUsage() } };
             }
             const summary = summaryOf(exchange);
-            const keptTurns = summary === undefined ? keptTurnsForDrop(messages, viewOptions, active.budget) : 0;
-            const markerOf = (tokensAfter, durationMs) => summary === undefined
-                ? dropMarkerMessage({ kind: "drop", id, tokensBefore, tokensAfter, durationMs, keptTurns })
-                : summaryMarkerMessage(summary, { kind: "summary", id, tokensBefore, tokensAfter, durationMs });
+            if (summary === undefined) {
+                settled = true;
+                const durationMs = Math.round(performance.now() - startedAt);
+                await emitPart({ id, status: "failed", tokensBefore, durationMs });
+                const refusal = exchange.refusal === undefined ? {} : { status: exchange.refusal.status, providerError: exchange.refusal.message };
+                log.error("compaction gave no summary, thus the run compacts no more", { compactionId: id, trigger, tokensBefore, durationMs, ...refusal });
+                compactionStopped = true;
+                return undefined;
+            }
+            const markerOf = (durationMs) => summaryMarkerMessage(summary, { kind: "summary", id, tokensBefore, durationMs, trigger });
             // The figures of a marker do not change the view, thus a draft marker gives the view of the real one.
-            const view = conversationView([...messages, markerOf(0, 0)], viewOptions).messages;
-            const records = await active.recordsAfter(view);
-            const tokensAfter = viewTokens([...view, ...records]);
+            const records = await active.recordsAfter(conversationView([...messages, markerOf(0)], viewOptions).messages);
             const durationMs = Math.round(performance.now() - startedAt);
-            messages.push(markerOf(tokensAfter, durationMs), ...records);
+            messages.push(markerOf(durationMs), ...records);
             await giveRound();
             settled = true;
-            await emitPart({ id, status: summary === undefined ? "failed" : "done", tokensBefore, tokensAfter, durationMs });
-            const fields = { compactionId: id, tokensBefore, tokensAfter, durationMs };
-            if (summary === undefined) {
-                const refusal = exchange.refusal === undefined ? {} : { status: exchange.refusal.status, providerError: exchange.refusal.message };
-                log.warn("compaction gave no summary, thus the oldest turns left the view", { ...fields, keptTurns, ...refusal });
-            }
-            else {
-                log.info("conversation compacted", fields);
-            }
-            if (summary !== undefined && tokensAfter > active.budget) {
-                log.warn("the compacted view still exceeds the budget, thus the run compacts no more", {
-                    compactionId: id,
-                    tokensAfter,
-                    budget: active.budget,
-                });
-            }
-            if (summary === undefined || tokensAfter > active.budget)
-                compactionStopped = true;
+            await emitPart({ id, status: "done", tokensBefore, durationMs });
+            log.info("conversation compacted", { compactionId: id, trigger, tokensBefore, durationMs });
+            summarizedLast = true;
             return undefined;
         }
         finally {
@@ -394,11 +390,36 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
                 await emitPart({ id, status: "failed", tokensBefore, durationMs: Math.round(performance.now() - startedAt) });
         }
     };
+    const startTurn = async (input) => {
+        const budget = policy?.turnStartBudget;
+        const tokens = lastRequestInputTokens(messages);
+        if (policy === undefined || budget === undefined || tokens === undefined || tokens <= budget) {
+            messages.push(...input);
+            return undefined;
+        }
+        const ended = await compact(policy, tokens, 0, "turn-start");
+        if (ended !== undefined)
+            return ended;
+        // The records after a summary give the current context, thus a record of the input would only repeat one.
+        messages.push(...(summarizedLast ? input.filter((message) => contextRecordOf(message) === undefined) : input));
+        return undefined;
+    };
     const compactOverBudget = async (index) => {
         if (policy === undefined || continuesTruncation || compactionStopped)
             return undefined;
-        const tokensBefore = viewTokens(viewOf());
-        return tokensBefore > policy.budget ? compact(policy, tokensBefore, index) : undefined;
+        const tokens = lastRequestInputTokens(messages);
+        if (tokens === undefined)
+            return undefined;
+        const afterSummary = summarizedLast;
+        summarizedLast = false;
+        if (tokens <= policy.budget)
+            return undefined;
+        if (afterSummary) {
+            log.warn("the first request after the summary still exceeds the budget, thus the run compacts no more", { tokens, budget: policy.budget });
+            compactionStopped = true;
+            return undefined;
+        }
+        return compact(policy, tokens, index, "mid-turn");
     };
     const runSegment = async (segment) => {
         const names = segment.stepNames;
@@ -558,6 +579,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
         }
     };
     return {
+        startTurn: (input) => giveRoundBeforeThrow(() => startTurn(input)),
         runSegment: (segment) => giveRoundBeforeThrow(() => runSegment(segment)),
         endCapped: () => giveRoundBeforeThrow(endCapped),
     };
@@ -577,6 +599,11 @@ function summaryOf(exchange) {
     const text = finalText(exchange.messages).trim();
     return text.length > 0 ? text : undefined;
 }
+/** The reply whose message holds the input tokens of its request, which the budget checks read. */
+function withRequestAnchor(reply) {
+    const tokens = reply.usage?.inputTokens;
+    return tokens === undefined ? reply : { ...reply, message: withRequestInputTokens(reply.message, tokens) };
+}
 /**
  * Called at the fold point, before any run-ending branch, so an aborted or
  * dead run is still accounted. Token counters grow inside the call's step

package/dist/loop/types.d.ts

@@ -11,6 +11,7 @@ import type { ModelMessage } from "ai";
 import type { ToolCallDetail, ToolOutcome } from "../contracts/chat-events.js";
 import type { ChatStreamEvent } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
+import type { CompactionRules } from "./compaction.js";
 /**
  * A loop message. The harness's working message array is AI SDK-shaped
  * `ModelMessage`.
@@ -28,6 +29,8 @@ export interface AgentDefinition {
     readonly tools: readonly Tool[];
     /** Runaway guard: at the cap the loop runs up to two masked wrap-up requests, until it gets a text answer. */
     readonly maxIterations: number;
+    /** The compaction rules of an agent that a chat thread runs. Absent: the conversation never compacts. */
+    readonly compaction?: CompactionRules;
 }
 /**
  * The durability seam. `passthroughStep` (`(_, fn) => fn()`) in the chat

package/dist/memory/ai-sdk-message-storage.d.ts

@@ -1,4 +1,4 @@
-import { type ModelMessage, type UserContent } from "ai";
+import { type AssistantModelMessage, type ModelMessage, type UserContent } from "ai";
 import { z } from "zod";
 export declare const SUPPORTED_AI_SDK_MAJOR = 7;
 export declare const StoredMessageEnvelopeSchema: z.ZodObject<{
@@ -110,21 +110,36 @@ export declare function isSyntheticRecordMessage(message: ModelMessage): boolean
 export declare const COMPACTION_EXCHANGE_KEY = "compactionExchange";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the figures of a compaction marker, which the view rule reads. */
 export declare const COMPACTION_MARKER_KEY = "compactionMarker";
+declare const COMPACTION_TRIGGERS: readonly ["turn-start", "mid-turn"];
+/** Where a compaction started: before the user message of a turn, or before a later request. */
+export type CompactionTrigger = (typeof COMPACTION_TRIGGERS)[number];
 declare const CompactionMarkerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     tokensBefore: z.ZodNumber;
-    tokensAfter: z.ZodNumber;
     durationMs: z.ZodNumber;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        "turn-start": "turn-start";
+        "mid-turn": "mid-turn";
+    }>>;
     kind: z.ZodLiteral<"summary">;
 }, z.core.$strip>, z.ZodObject<{
     keptTurns: z.ZodNumber;
     id: z.ZodString;
     tokensBefore: z.ZodNumber;
-    tokensAfter: z.ZodNumber;
     durationMs: z.ZodNumber;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        "turn-start": "turn-start";
+        "mid-turn": "mid-turn";
+    }>>;
     kind: z.ZodLiteral<"drop">;
 }, z.core.$strip>], "kind">;
 export type CompactionMarker = z.infer<typeof CompactionMarkerSchema>;
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the input tokens that the provider reported for the request of an assistant message. */
+export declare const REQUEST_INPUT_TOKENS_KEY = "requestInputTokens";
+/** A copy of `message` whose harness namespace holds the input tokens of its request. The mark keeps each other namespace. */
+export declare function withRequestInputTokens(message: AssistantModelMessage, tokens: number): AssistantModelMessage;
+/** The input tokens of the request of an assistant message, or `undefined` when the provider reported none. */
+export declare function requestInputTokensOf(message: ModelMessage): number | undefined;
 /** A copy of `message` whose harness namespace, which no provider reads, holds the compaction id. */
 export declare function markCompactionExchange(message: ModelMessage, id: string): ModelMessage;
 export declare function compactionExchangeOf(message: ModelMessage): string | undefined;

package/dist/memory/ai-sdk-message-storage.js

@@ -162,11 +162,33 @@ export function isSyntheticRecordMessage(message) {
 export const COMPACTION_EXCHANGE_KEY = "compactionExchange";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the figures of a compaction marker, which the view rule reads. */
 export const COMPACTION_MARKER_KEY = "compactionMarker";
-const compactionFigures = { id: z.string(), tokensBefore: z.number(), tokensAfter: z.number(), durationMs: z.number() };
+const COMPACTION_TRIGGERS = ["turn-start", "mid-turn"];
+// A row from before the trigger has none.
+const compactionFigures = { id: z.string(), tokensBefore: z.number(), durationMs: z.number(), trigger: z.enum(COMPACTION_TRIGGERS).optional() };
 const CompactionMarkerSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("summary"), ...compactionFigures }),
     z.object({ kind: z.literal("drop"), ...compactionFigures, keptTurns: z.number() }),
 ]);
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the input tokens that the provider reported for the request of an assistant message. */
+export const REQUEST_INPUT_TOKENS_KEY = "requestInputTokens";
+/** A copy of `message` whose harness namespace holds the input tokens of its request. The mark keeps each other namespace. */
+export function withRequestInputTokens(message, tokens) {
+    const existingOptions = message.providerOptions ?? {};
+    return {
+        ...message,
+        providerOptions: {
+            ...existingOptions,
+            [HARNESS_PROVIDER_NAMESPACE]: { ...existingOptions[HARNESS_PROVIDER_NAMESPACE], [REQUEST_INPUT_TOKENS_KEY]: tokens },
+        },
+    };
+}
+/** The input tokens of the request of an assistant message, or `undefined` when the provider reported none. */
+export function requestInputTokensOf(message) {
+    if (message.role !== "assistant")
+        return undefined;
+    const tokens = message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[REQUEST_INPUT_TOKENS_KEY];
+    return typeof tokens === "number" && Number.isFinite(tokens) ? tokens : undefined;
+}
 /** A copy of `message` whose harness namespace, which no provider reads, holds the compaction id. */
 export function markCompactionExchange(message, id) {
     const existingOptions = message.providerOptions ?? {};

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

@@ -15,9 +15,15 @@ export interface ConversationDisplayRecorder {
 }
 export interface ConversationDisplayRecorderOptions {
     readonly userText: string;
-    readonly topLevelCallPath: readonly string[];
+    /** 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;
 }
+/**
+ * Record the display of a turn through the same translation path as a live surface: each event becomes a
+ * frame (`toChatFrame`), and the frames build the messages of the round (`applyChatFrame`). Only a part that
+ * the conversation keeps enters the record.
+ */
 export declare function createConversationDisplayRecorder(options: ConversationDisplayRecorderOptions): ConversationDisplayRecorder;