@inflexa-ai/harness 0.41.2 → 0.42.0

package/dist/report-render/views/values.js

@@ -27,6 +27,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "hono/jsx/jsx-
 import { raw } from "hono/html";
 import { declaredForColumn } from "../../contracts/report-reference.js";
 import { stagedSource, tableSidecarName } from "../assets.js";
+import { blockMark } from "./block-mark.js";
 import { DEFAULT_VIEW_OPTIONS, lineagePlace, lineageStamp } from "./lineage.js";
 import { Marker } from "./references-view.js";
 import { formatNumberCell, formatTableCell, holdsANumber, selectColumnKind, selectNumberKind, smallestPositiveValue } from "../number-format.js";
@@ -75,7 +76,7 @@ const DOWNLOAD_LABEL = "Download";
 export function renderMetric(block, ledger, value, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.value);
     const shown = formatNumberCell(value.value, selectNumberKind(block.label, value.value));
-    return String(_jsxs("div", { class: "stat-card corner-accents", ...lineageStamp(view.lineage, block.id, [block.value]), children: [_jsx("div", { class: "stat-card-value", title: shown.full, children: shown.text }), _jsxs("div", { class: "stat-card-label", children: [block.label, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.value) })] })] }));
+    return String(_jsxs("div", { class: "stat-card corner-accents", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, [block.value]), children: [_jsx("div", { class: "stat-card-value", title: shown.full, children: shown.text }), _jsxs("div", { class: "stat-card-label", children: [block.label, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.value) })] })] }));
 }
 /**
  * Wrap a run of stat cards in one responsive grid. The caller renders each card first, and it passes the
@@ -212,7 +213,7 @@ export function renderTable(block, ledger, rowCount, total, view = DEFAULT_VIEW_
     const n = ledger.mark(binding);
     const download = tableSidecarName(binding.hash, binding.path);
     const bound = boundText(binding);
-    return String(_jsxs("div", { class: "report-table", ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsxs("div", { class: "report-table-title", children: [block.title, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) })] }), _jsxs("div", { class: "corner-accents", children: [_jsx("div", { class: "report-grid", [GRID_MOUNT_ATTRIBUTE]: block.id }), _jsxs("div", { class: "report-table-footer", children: [_jsxs("div", { class: "report-table-footer-row", children: [_jsxs("span", { class: "report-table-status", children: [_jsx("span", { class: GRID_COUNT_CLASS, children: tableStatusText(rowCount, total ?? rowCount) }), bound !== undefined ? _jsx("span", { class: "report-table-bound", children: bound }) : null] }), _jsx("a", { class: "report-table-download", href: stagedSource(download), download: download, children: downloadLabel(binding.path) })] }), _jsx("div", { class: GRID_NOTE_CLASS })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
+    return String(_jsxs("div", { class: "report-table", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsxs("div", { class: "report-table-title", children: [block.title, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) })] }), _jsxs("div", { class: "corner-accents", children: [_jsx("div", { class: "report-grid", [GRID_MOUNT_ATTRIBUTE]: block.id }), _jsxs("div", { class: "report-table-footer", children: [_jsxs("div", { class: "report-table-footer-row", children: [_jsxs("span", { class: "report-table-status", children: [_jsx("span", { class: GRID_COUNT_CLASS, children: tableStatusText(rowCount, total ?? rowCount) }), bound !== undefined ? _jsx("span", { class: "report-table-bound", children: bound }) : null] }), _jsx("a", { class: "report-table-download", href: stagedSource(download), download: download, children: downloadLabel(binding.path) })] }), _jsx("div", { class: GRID_NOTE_CLASS })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
 }
 /**
  * Render a figure block as a corner-accent card. The source rides the `src` attribute, and the caption
@@ -229,7 +230,7 @@ export function renderTable(block, ledger, rowCount, total, view = DEFAULT_VIEW_
 export function renderFigure(block, ledger, value, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.binding);
     const caption = block.caption;
-    return String(_jsxs("figure", { class: "report-figure corner-accents", ...lineageStamp(view.lineage, block.id, [block.binding]), children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), _jsxs("figcaption", { class: "report-caption", children: [caption, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.binding) })] })] }));
+    return String(_jsxs("figure", { class: "report-figure corner-accents", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, [block.binding]), children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), _jsxs("figcaption", { class: "report-caption", children: [caption, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.binding) })] })] }));
 }
 /**
  * The PubMed address of one identifier. The address is deterministic, and an anchor loads nothing, thus a
@@ -252,5 +253,5 @@ export function renderCitation(block, ledger, record, view = DEFAULT_VIEW_OPTION
     const n = ledger.mark(block.binding);
     const binding = block.binding;
     const key = citationKeyOf(binding);
-    return String(_jsxs("div", { class: "report-citation corner-accents", ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) }), record !== undefined ? (_jsxs(_Fragment, { children: [" ", binding.idKind === "pmid" ? (_jsx("a", { class: "report-citation-source", href: `${PUBMED_BASE}${encodeURIComponent(binding.id)}/`, children: record.citation })) : (_jsx("span", { class: "report-citation-source", children: record.citation }))] })) : null, block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null, " ", _jsx("span", { class: "report-citation-key", children: key })] }));
+    return String(_jsxs("div", { class: "report-citation corner-accents", ...blockMark(block.id), ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) }), record !== undefined ? (_jsxs(_Fragment, { children: [" ", binding.idKind === "pmid" ? (_jsx("a", { class: "report-citation-source", href: `${PUBMED_BASE}${encodeURIComponent(binding.id)}/`, children: record.citation })) : (_jsx("span", { class: "report-citation-source", children: record.citation }))] })) : null, block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null, " ", _jsx("span", { class: "report-citation-key", children: key })] }));
 }

package/dist/state/migrations/20260927180000_thread_title_set_by_user.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Record whether a person set the title of a thread, thus an automatic title
+ * never replaces a name that a person chose.
+ */
+import type { Migration } from "kysely/migration";
+export declare const threadTitleSetByUser: Migration;

package/dist/state/migrations/20260927180000_thread_title_set_by_user.js

@@ -0,0 +1,10 @@
+/**
+ * Record whether a person set the title of a thread, thus an automatic title
+ * never replaces a name that a person chose.
+ */
+import { sql } from "kysely";
+export const threadTitleSetByUser = {
+    async up(db) {
+        await sql `ALTER TABLE cortex_analysis_threads ADD COLUMN IF NOT EXISTS title_set_by_user BOOLEAN NOT NULL DEFAULT false`.execute(db);
+    },
+};

package/dist/state/migrations/index.js

@@ -6,8 +6,10 @@
  * entry, with a name that sorts after every existing one.
  */
 import { baseline } from "./20260927120000_baseline.js";
+import { threadTitleSetByUser } from "./20260927180000_thread_title_set_by_user.js";
 export function cortexMigrations(logger) {
     return {
         "20260927120000_baseline": baseline(logger),
+        "20260927180000_thread_title_set_by_user": threadTitleSetByUser,
     };
 }

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -23,7 +23,8 @@ import type { Logger } from "../../lib/logger.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
-import { type FinishResult } from "../../report-model/draft-finish.js";
+import type { ReportWarning } from "../../report-model/block-walk.js";
+import { type FinishGap } from "../../report-model/draft-finish.js";
 import type { DraftDocument } from "../../report-model/draft.js";
 import type { ReportSnapshot } from "../../report-model/reference-resolver.js";
 import type { DerivationRecord } from "../../state/report-session-state.js";
@@ -144,8 +145,18 @@ export type ReadBlockResult = {
 } | {
     refused: SessionRefusal;
 };
-/** The result of `finish_draft`. A load that gives no state refuses instead of a finish outcome. */
-export type FinishToolResult = FinishResult | {
+/**
+ * The result of `finish_draft`. A pass gives no document, because the document grows with the report and the
+ * preview and the record read it themselves.
+ */
+export type FinishToolResult = {
+    valid: true;
+    warnings: ReportWarning[];
+} | {
+    valid: false;
+    gaps: FinishGap[];
+    warnings: ReportWarning[];
+} | {
     refused: SessionRefusal;
 };
 /** The state of one report thread: the document under composition, and the frozen snapshot. */
@@ -308,8 +319,8 @@ export interface ReportAuthoringToolDeps {
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
  *
- * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
- * failed persist each emit nothing.
+ * A landed mutation emits one observation, and an add emits one for each block that it landed. The emit
+ * sits after the persist, thus a refused operation and a failed persist each emit nothing.
  */
 export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway, deps?: ReportAuthoringToolDeps): ReportAuthoringTools;
 export {};

package/dist/tools/report-authoring/authoring-tools.js

@@ -309,11 +309,11 @@ function holderIdOf(document, blockId) {
     return locate(document, blockId)?.parent?.id;
 }
 /**
- * The event of one block act, or `undefined` when the document holds no block of that id.
+ * The event of one block act, or no event when the document holds no block of that id.
  *
  * The kind rides beside the id, thus a reader of the record sees what the act touched and it needs no
  * document of its own. The kind comes out of the document that holds the block after the act: the next
- * document for an add, a change, and a move, and the previous one for a remove.
+ * document for a change and a move, and the previous one for a remove.
  *
  * A lookup of a landed operation always finds its block. The absent arm keeps the read total, and it drops
  * the event rather than state a kind that no block carries.
@@ -321,9 +321,30 @@ function holderIdOf(document, blockId) {
 function blockActOf(type, scope, document, blockId) {
     const kind = locate(document, blockId)?.block.kind;
     if (kind === undefined) {
-        return undefined;
+        return [];
+    }
+    return [{ type, analysisId: scope.analysisId, threadId: scope.threadId, blockId, blockKind: kind }];
+}
+/**
+ * The event of each block that one add landed, in document order. A section lands with its children in one
+ * call, and a reader of the record places each block by its own event.
+ */
+function addedActsOf(scope, document, blockId) {
+    const located = locate(document, blockId);
+    if (located === undefined) {
+        return [];
     }
-    return { type, analysisId: scope.analysisId, threadId: scope.threadId, blockId, blockKind: kind };
+    const events = [];
+    const visit = (block) => {
+        events.push({ type: "add-block", analysisId: scope.analysisId, threadId: scope.threadId, blockId: block.id, blockKind: block.kind });
+        if (block.kind === "section") {
+            for (const child of block.blocks) {
+                visit(child);
+            }
+        }
+    };
+    visit(located.block);
+    return events;
 }
 /** Read the child order of one container out of a document. */
 function containerIn(document, parentId) {
@@ -353,8 +374,8 @@ const AUTHORING_EXECUTION_MODE = "inline";
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
  *
- * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
- * failed persist each emit nothing.
+ * A landed mutation emits one observation, and an add emits one for each block that it landed. The emit
+ * sits after the persist, thus a refused operation and a failed persist each emit nothing.
  */
 export function createReportAuthoringTools(gateway, deps = {}) {
     const observe = bindSessionEmit(deps.provenance, (deps.logger ?? createNoopLogger()).named("report-authoring"));
@@ -377,12 +398,13 @@ export function createReportAuthoringTools(gateway, deps = {}) {
      * The persist is a compare-and-swap against the token that the load read. A concurrent turn that landed
      * first turns the persist into a conflict, and the tool refuses with `stale-state`.
      *
-     * `event` is the observation of the operation, and it emits after the persist landed. Thus one site owns
-     * the rule, and a refusal, a conflict, and a persist fault each emit nothing. It reads the two documents
-     * for the same reason that `holders` does: a removed block sits in the first alone, and an added block
-     * sits in the second alone. A caller that cannot name the block of its own operation gives no event.
+     * `events` gives the observations of the operation, and they emit after the persist landed. Thus one
+     * site owns the rule, and a refusal, a conflict, and a persist fault each emit nothing. It reads the two
+     * documents for the same reason that `holders` does: a removed block sits in the first alone, and an
+     * added block sits in the second alone. A caller that cannot name the block of its own operation gives
+     * no event.
      */
-    const land = async (threadId, token, previous, result, holders, event) => {
+    const land = async (threadId, token, previous, result, holders, events) => {
         if (result.isErr()) {
             return { applied: false, refusal: result.error };
         }
@@ -397,8 +419,7 @@ export function createReportAuthoringTools(gateway, deps = {}) {
         if (persisted.outcome === "failed") {
             return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
         }
-        const observed = event(previous, next);
-        if (observed !== undefined) {
+        for (const observed of events(previous, next)) {
             observe(observed);
         }
         // A move inside one container names the same holder two times.
@@ -408,8 +429,10 @@ export function createReportAuthoringTools(gateway, deps = {}) {
     const refuse = (refusal) => ({ applied: false, refusal });
     const add_block = defineTool({
         id: "add_block",
-        description: "Add one block to the draft. The `block` schema gives the eight kinds and the fields of each one. " +
-            "You choose the `id` of the block, and it must be unique in the draft. " +
+        description: "Add one block to the draft. The block can be a section that carries its child blocks, thus one call can add a whole section with its atoms. " +
+            "The `block` schema gives the eight kinds and the fields of each one. " +
+            "You choose the `id` of each block, and each id must be unique in the draft. " +
+            "The validation covers the block and each block under it, and the whole payload lands or no part of it lands. " +
             "Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
             "The root admits a section only, and an atom needs a section as its parent. " +
             "A reference names the path of a pinned artifact, and the session stamps the hash from the pinned evidence.",
@@ -439,7 +462,7 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)], 
             // The grammar requires an id on the payload, thus a landed add always names one. A
             // payload with no id reaches the core, which refuses it, and no event is due.
-            (_previous, next) => (addedId === undefined ? undefined : blockActOf("add-block", { analysisId, threadId }, next, addedId))));
+            (_previous, next) => (addedId === undefined ? [] : addedActsOf({ analysisId, threadId }, next, addedId))));
         },
     });
     const change_block = defineTool({
@@ -518,12 +541,14 @@ export function createReportAuthoringTools(gateway, deps = {}) {
                 return ok(refuse(opened.error));
             }
             const { threadId, analysisId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => [], () => ({
-                type: "set-title",
-                analysisId,
-                threadId,
-                title: input.title,
-            })));
+            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => [], () => [
+                {
+                    type: "set-title",
+                    analysisId,
+                    threadId,
+                    title: input.title,
+                },
+            ]));
         },
     });
     const read_outline = defineTool({
@@ -563,7 +588,9 @@ export function createReportAuthoringTools(gateway, deps = {}) {
     });
     const finish_draft = defineTool({
         id: "finish_draft",
-        description: "Finish the draft. The result gives each completeness gap, or the valid report document, and each advisory warning. " +
+        description: "Finish the draft. The result gives each completeness gap, or a pass, and each advisory warning. " +
+            "A pass gives back no document. " +
+            "preview_report and record_report_version run the same check before they act, thus a finish directly before one of them does that check a second time. " +
             "Use it to make sure that the draft passes the whole document schema, the id rule, and the structural tier.",
         inputSchema: finishDraftInput,
         executionMode: AUTHORING_EXECUTION_MODE,
@@ -574,7 +601,8 @@ export function createReportAuthoringTools(gateway, deps = {}) {
             if (opened.isErr()) {
                 return ok({ refused: opened.error });
             }
-            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot, opened.value.derivations));
+            const finished = finishDraft(opened.value.state.document, opened.value.state.snapshot, opened.value.derivations);
+            return ok(finished.valid ? { valid: true, warnings: finished.warnings } : finished);
         },
     });
     return {

package/dist/tools/report-session/examine-page.d.ts

@@ -5,6 +5,9 @@
  * see: the screenshot, the console errors, and the failed requests. The agent reads the picture and the
  * faults, decides, and repairs. The tool never judges, thus it never blocks the loop.
  *
+ * A look takes the whole page, or one block that the input names, thus a look that confirms a repair pays
+ * for that block alone. The faults arrive as a digest (`page-faults.ts`).
+ *
  * The composition says which URL one look opens, and the URL seam is that answer. Absent the seam, the tool
  * navigates to the page file through a `file://` URL. The page lives at `report-sessions/{threadId}/index.html`
  * under the workspace root, which the preview writes. A missed page means that no preview ran, and it is a
@@ -30,8 +33,9 @@
  * On a capture the tool copies the rendered hash onto the seen hash through the gateway. Thus the look
  * counts, and the record tool lets the current draft record. The copy takes the rendered hash and never the
  * current one, thus a later edit makes the look stale and the record refuses. A partial look — the window
- * alone, or slices that a budget truncated — is a true look at the current document, thus it stamps the same
- * and the coverage of the result is what tells the agent what it saw.
+ * alone, slices that a budget truncated, or one block — is a true look at the current document, thus it
+ * stamps the same and the coverage of the result is what tells the agent what it saw. A block look that
+ * finds no such block took no picture, thus it stamps nothing.
  *
  * The gateway reports whether a rendered hash existed to copy. When the row holds none, no preview stamped
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
@@ -56,6 +60,7 @@ import { type CaptureCoverage, type CapturePage, type FailedRequest, type PageCa
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ConsoleErrorEntry, type FailedRequestEntry } from "./page-faults.js";
 export type { CaptureCoverage, CapturePage, FailedRequest, PageCapture };
 /**
  * The URL formation of one look. It maps the page of the thread onto the URL that the browser opens.
@@ -69,8 +74,10 @@ export type ResolvePageUrl = (args: {
     threadId: string;
     auth: AuthContext;
 }) => ResultAsync<string, GateFailure>;
-/** The empty input. The tool examines the current page of the thread, thus it needs no field. */
-declare const examinePageInput: z.ZodObject<{}, z.core.$strip>;
+/** The input of one look. Nullish, because under strict function calling a model sends `null` for an unused field. */
+declare const examinePageInput: z.ZodObject<{
+    blockId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
 export type ExaminePageInput = z.infer<typeof examinePageInput>;
 /** The document range of one slice of a tiled look, in the order that the pictures ride. */
 export interface ExaminedTile {
@@ -80,15 +87,16 @@ export interface ExaminedTile {
 }
 /**
  * The typed outcome of the eyes tool. Each arm is ok-channel data, thus the tool never throws for a
- * degraded condition. `examined` carries the coverage of the look, the console errors, the failed
- * requests, and the page path. The coverage names what the agent saw: the whole document in one shot,
- * consecutive slices with the captured and the total pixels, or the window alone when the browser refused
- * the bitmap. A tiled look carries `tiles` — the document range of each slice, in the order of the
- * pictures — thus the model reads which rows each picture holds. The screenshots do not ride the JSON.
+ * degraded condition. `examined` carries the coverage of the look, the digest of the console errors and the
+ * failed requests, and the page path. The coverage names what the agent saw: the whole document in one
+ * shot, consecutive slices with the captured and the total pixels, the window alone when the browser refused
+ * the bitmap, or one block. A sliced look carries `tiles` — the document range of each slice, in the order
+ * of the pictures — thus the model reads which rows each picture holds. The screenshots do not ride the JSON.
  * They ride the image path of the tool result in document order, thus the model sees the pictures and the
- * JSON text holds no bytes. `missed-stamp` means that the row holds no rendered hash, thus no preview
- * stamped one and the agent must run a new preview before the next look. `no-browser` means that the
- * composition gives no browser, thus no look is possible at all and a repeat gives the same answer.
+ * JSON text holds no bytes. `no-block` means that the current page holds no block of the id that the input
+ * named. `missed-stamp` means that the row holds no rendered hash, thus no preview stamped one and the
+ * agent must run a new preview before the next look. `no-browser` means that the composition gives no
+ * browser, thus no look is possible at all and a repeat gives the same answer.
  */
 export type ExaminePageResult = {
     outcome: "refused";
@@ -98,6 +106,9 @@ export type ExaminePageResult = {
     detail: string;
 } | {
     outcome: "no-page";
+} | {
+    outcome: "no-block";
+    blockId: string;
 } | {
     outcome: "missed-stamp";
 } | {
@@ -107,8 +118,12 @@ export type ExaminePageResult = {
     outcome: "examined";
     coverage: CaptureCoverage;
     tiles?: ExaminedTile[];
-    consoleErrors: string[];
-    failedRequests: FailedRequest[];
+    consoleErrors: ConsoleErrorEntry[];
+    failedRequests: FailedRequestEntry[];
+    omittedFaults?: {
+        consoleErrors: number;
+        failedRequests: number;
+    };
     pagePath: string;
 };
 /**

package/dist/tools/report-session/examine-page.js

@@ -5,6 +5,9 @@
  * see: the screenshot, the console errors, and the failed requests. The agent reads the picture and the
  * faults, decides, and repairs. The tool never judges, thus it never blocks the loop.
  *
+ * A look takes the whole page, or one block that the input names, thus a look that confirms a repair pays
+ * for that block alone. The faults arrive as a digest (`page-faults.ts`).
+ *
  * The composition says which URL one look opens, and the URL seam is that answer. Absent the seam, the tool
  * navigates to the page file through a `file://` URL. The page lives at `report-sessions/{threadId}/index.html`
  * under the workspace root, which the preview writes. A missed page means that no preview ran, and it is a
@@ -30,8 +33,9 @@
  * On a capture the tool copies the rendered hash onto the seen hash through the gateway. Thus the look
  * counts, and the record tool lets the current draft record. The copy takes the rendered hash and never the
  * current one, thus a later edit makes the look stale and the record refuses. A partial look — the window
- * alone, or slices that a budget truncated — is a true look at the current document, thus it stamps the same
- * and the coverage of the result is what tells the agent what it saw.
+ * alone, slices that a budget truncated, or one block — is a true look at the current document, thus it
+ * stamps the same and the coverage of the result is what tells the agent what it saw. A block look that
+ * finds no such block took no picture, thus it stamps nothing.
  *
  * The gateway reports whether a rendered hash existed to copy. When the row holds none, no preview stamped
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
@@ -58,8 +62,15 @@ import { capturePage } from "../../lib/page-capture.js";
 import { reportSessionDir } from "../../workspace/paths.js";
 import { defineTool, withToolResultImages } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
-/** The empty input. The tool examines the current page of the thread, thus it needs no field. */
-const examinePageInput = z.object({});
+import { digestPageFaults } from "./page-faults.js";
+/** The input of one look. Nullish, because under strict function calling a model sends `null` for an unused field. */
+const examinePageInput = z.object({
+    blockId: z
+        .string()
+        .min(1)
+        .nullish()
+        .describe("The id of one block, as the outline gives it. The look then holds that block alone. Leave it out to look at the whole page."),
+});
 /**
  * Resolve the transport of the tool from its deps, one time.
  *
@@ -177,7 +188,7 @@ async function runLook(args) {
     const { transport } = args;
     if (transport.kind === "capture") {
         try {
-            return ok(await transport.capture(args.url));
+            return ok(await transport.capture(args.url, args.options));
         }
         catch (cause) {
             return err({ stage: "capture", cause });
@@ -194,7 +205,7 @@ async function runLook(args) {
     }
     const lease = acquired.value;
     try {
-        return ok(await capturePage({ ...args.chrome, browserUrl: lease.browserUrl }, args.url));
+        return ok(await capturePage({ ...args.chrome, browserUrl: lease.browserUrl }, args.url, args.options));
     }
     catch (cause) {
         return err({ stage: "capture", cause });
@@ -228,20 +239,29 @@ export function createExaminePageTool(deps) {
         id: "examine_page",
         description: "Open the rendered report page in a real headless browser, and give back what a reviewer sees: " +
             "one or more screenshots, the coverage of the look, the console errors, and the failed requests. " +
-            "A tall page arrives as consecutive top-to-bottom slices in document order, and the tiles list names the rows of each slice. " +
-            "The coverage says whether the pictures hold the whole page, a truncated top portion of it, or the top window alone. " +
+            "Without `blockId` the look holds the whole page. With `blockId` the look holds that one block alone: a section with its content, or one atom. " +
+            "A tall page or a tall block arrives as consecutive top-to-bottom slices in document order, and the tiles list names the rows of each slice. " +
+            "The coverage says whether the pictures hold the whole page, a truncated top portion of it, the top window alone, or the one block. " +
+            "A look costs about 500 image tokens for each 1,000 pixels of height that it holds, and one look holds at most 20,000 pixels. " +
+            "Each look adds its pictures to the conversation, and each later request of the turn carries them again. " +
+            "Each repeated console error or failed request comes back one time with a count, and a placeholder replaces each inline data. " +
             "Run it after the preview to look at the current page, and to confirm that the layout and the charts read clean. " +
-            "A look at the page of the current draft is what lets record_report_version record. " +
+            "A look at the page of the current draft is what lets record_report_version record, and a block look counts the same as a look at the whole page. " +
+            "The outcome no-block means that the current page holds no block of that id. " +
             "The outcomes no-page and missed-stamp mean that no preview rendered the current page: run preview_report, then look again. " +
             "The outcome no-browser means that this host gives no browser, and a repeat gives the same outcome.",
         inputSchema: examinePageInput,
         executionMode: "inline",
-        describeCall: "none",
+        describeCall: (input) => {
+            const blockId = input.blockId ?? undefined;
+            return blockId === undefined ? "look at the page" : `look at ${blockId}`;
+        },
         // A look gives a picture, and a picture has no one-line form. Thus the outcome of the look is the
         // whole line: a watcher reads that the eyes saw the page, or that the page was absent, or that the
         // capture failed.
         describeResult: (_input, result) => result.outcome,
-        execute: async (_input, ctx) => {
+        execute: async (input, ctx) => {
+            const blockId = input.blockId ?? undefined;
             // The check runs before every read, thus one clear signal replaces a capture failure for each
             // page. The arm stamps no seen hash, because no eyes saw the page. It also narrows the transport
             // for the look below, thus the acquire needs no assertion.
@@ -302,6 +322,7 @@ export function createExaminePageTool(deps) {
                 chrome: deps.chrome,
                 scope: { analysisId, workspaceRoot: root },
                 url,
+                options: blockId === undefined ? {} : { blockId },
                 acquireMs,
                 releaseMs,
                 logger,
@@ -312,6 +333,10 @@ export function createExaminePageTool(deps) {
                 return ok({ outcome: "capture-failed", detail: cause instanceof Error ? cause.message : String(cause) });
             }
             const captured = looked.value;
+            if (blockId !== undefined && captured.coverage.kind === "no-block") {
+                // No picture exists, thus no eyes saw the page and the look stamps nothing.
+                return ok({ outcome: "no-block", blockId });
+            }
             const stamped = await deps.gateway.stampSeen(threadId);
             if (stamped.outcome === "no-rendered") {
                 // The row holds no rendered hash, thus no preview stamped one and the look cannot count. A
@@ -328,16 +353,15 @@ export function createExaminePageTool(deps) {
                 logger.warn("the seen hash did not stamp", { threadId, analysisId, detail });
             }
             // The screenshots ride the image path of the tool result in document order, thus the model sees
-            // the pictures. The JSON keeps the faults, the tile ranges, and the page path only, thus the
-            // JSON text holds no bytes. The tiles list mirrors the picture order, thus the model reads which
-            // rows each picture holds.
+            // the pictures. The JSON keeps the digest of the faults, the tile ranges, and the page path only,
+            // thus the JSON text holds no bytes. The tiles list mirrors the picture order, thus the model reads
+            // which rows each picture holds.
             const tiles = captured.screenshots.flatMap((shot, index) => shot.range === undefined ? [] : [{ index, fromY: shot.range.fromY, toY: shot.range.toY }]);
             return ok(withToolResultImages({
                 outcome: "examined",
                 coverage: captured.coverage,
                 ...(tiles.length === 0 ? {} : { tiles }),
-                consoleErrors: captured.consoleErrors,
-                failedRequests: captured.failedRequests,
+                ...digestPageFaults(captured.consoleErrors, captured.failedRequests),
                 pagePath: relativePagePath,
             }, captured.screenshots.map((shot) => ({ base64: shot.base64, mediaType: SCREENSHOT_MEDIA_TYPE }))));
         },

package/dist/tools/report-session/list-artifacts.d.ts

@@ -1,10 +1,14 @@
 /**
  * The pinned-artifact listing tool of a report session.
  *
- * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the content
- * hash, the file type, and the header columns of a tabular artifact, plus the pinned citations with the
- * short citation of each. Thus one call orients the agent, and a reference binds to a path or to a
- * citation key of that set.
+ * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the file type,
+ * and the count of the header columns of a tabular artifact, plus the pinned citations with the short
+ * citation of each. Thus one call orients the agent, and a reference binds to a path or to a citation key of
+ * that set. A call with a path gives the header columns of that one artifact.
+ *
+ * A wide table can have hundreds of columns, and the listing stays in the context of each later request.
+ * Thus the listing counts the columns, and the agent reads the names of one artifact when it binds to it.
+ * A reference names the path alone and the session stamps the hash, thus the tool gives no hash.
  *
  * The order is the code-unit order of the path. Two calls over one snapshot give one listing, thus the
  * agent reads a stable set. A snapshot can pin many thousands of staged inputs, thus the listing stops at
@@ -22,19 +26,22 @@ import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Logger } from "../../lib/logger.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
-/** The empty input. The tool lists the pinned set of the thread, thus it needs no field. */
-declare const listPinnedArtifactsInput: z.ZodObject<{}, z.core.$strip>;
+/** No path lists the pinned set. A path gives the header columns of that one pinned artifact. */
+declare const listPinnedArtifactsInput: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export type ListPinnedArtifactsInput = z.infer<typeof listPinnedArtifactsInput>;
 /**
- * One pinned artifact of the listing.
+ * One pinned artifact.
  *
- * `fileType` states a role, and it does not state a data format. `columns` is present only for a header
- * that the read recovered, thus an absent `columns` says nothing about the content of the file.
+ * `fileType` states a role, and it does not state a data format. `columnCount` and `columns` are present
+ * only for a header that the read recovered, thus their absence says nothing about the content of the file.
+ * The listing gives `columnCount`, and a call with a path gives `columns` as well.
  */
 export interface PinnedArtifact {
     path: string;
-    hash: string;
     fileType?: string;
+    columnCount?: number;
     columns?: string[];
 }
 /**
@@ -67,6 +74,12 @@ export type ListPinnedArtifactsResult = {
     total: number;
     truncated: boolean;
     citations: PinnedCitation[];
+} | {
+    outcome: "artifact";
+    artifact: PinnedArtifact;
+} | {
+    outcome: "not-pinned";
+    path: string;
 };
 /**
  * The construction deps of the listing tool.