@inflexa-ai/harness 0.24.0 → 0.26.0

package/dist/tasks/data-profile.js

@@ -1,9 +1,10 @@
 /**
- * Data-profile DBOS workflow — profiles the already-staged input files, runs
- * the data-profiler sandbox agent, writes per-file metadata to
- * cortex_artifacts, and indexes descriptions into the pgvector store. Inputs
- * are staged under `data/inputs/` by the embedder before the run (see the data-profile-init spec);
- * the body assumes a populated tree and never downloads.
+ * Data-profile DBOS workflow — scans the already-staged input tree, runs the
+ * data-profiler sandbox agent over the resulting manifest, registers each staged
+ * file in cortex_artifacts, and indexes the profile's kinds and entities into the
+ * pgvector store. Inputs are staged under `data/inputs/` by the embedder before the
+ * run (see the data-profile-init spec); the body assumes a populated tree and never
+ * downloads.
  *
  * Recoverable: a crashed Cortex pod resumes the workflow from the DBOS step
  * cache. The run authorization is minted at the async edge (`triggerDataProfile`)
@@ -34,6 +35,11 @@ import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
 import { createVectorStore } from "../state/vector-store.js";
 import { ProfilerOutputSchema } from "../schemas/data-profile-schemas.js";
+import { computeInputSignature } from "../execution/input-signature.js";
+import { computeCoverage } from "../input-scan/coverage.js";
+import { enrichShapes } from "../input-scan/enrich.js";
+import { renderInputScanManifest, scanInputTree } from "../input-scan/scan.js";
+import { buildProfileIndexEntries } from "./data-profile-index.js";
 import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
@@ -42,39 +48,20 @@ import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.j
 import { DATA_PROFILE_RUN_LITERAL } from "../contracts/data-profile.js";
 const DATA_PROFILE_STEP_LITERAL = "profile";
 const DATA_PROFILE_AGENT_ID = "data-profiler";
-/** Sandbox-server exec budget for the profile run. */
-const DEFAULT_DEADLINE_MS = 300_000;
+/**
+ * Sandbox-server exec budget for the profile run. Twenty minutes: the deterministic
+ * scan bounds the discovery half, and what remains is the agent's own reading of a
+ * bounded number of example files.
+ */
+const DEFAULT_DEADLINE_MS = 1_200_000;
+/** Index entries embedded and upserted per round trip. */
+const INDEX_BATCH_SIZE = 256;
+/** Where the embedder stages this analysis's inputs (see the data-profile-init spec). */
+const STAGED_INPUT_ROOT = "data/inputs";
 /** Build the canonical artifact path for a staged input file. */
 function inputArtifactPath(f) {
     return `data/${f.relativePath}`;
 }
-/** Lowercased extension of a path, or `"unknown"` when none. */
-function fileExtension(p) {
-    const base = p.slice(p.lastIndexOf("/") + 1);
-    const dot = base.lastIndexOf(".");
-    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "unknown";
-}
-/**
- * Build the drift-signature comparand a completed profile persists, or `undefined`
- * to omit it. `inputFiles` records whether the profiled files still hold the same
- * bytes; it sits beside the `inputFileIds` audit record (WHICH files) in the stored
- * `DataProfileResult`.
- *
- * A workflow input persisted before `StagedInput.mtimeMs` existed (recovered across
- * the deploy that added it) carries entries with NO `mtimeMs` despite the compile-time
- * type — the same recovered-legacy-input case `ownsMandate` handles. A per-entry
- * `{ …, mtimeMs: undefined }` would JSON.stringify to `{ fileId, size }` and violate
- * `DataProfileInputFile`, so the WHOLE signature is omitted when ANY entry lacks
- * `mtimeMs`: an absent comparand reads back as drift and buys one clean re-profile,
- * exactly as a wholly-absent `result` already does (see `DataProfileResult.inputFiles`).
- * The cast defeats the required-`number` type precisely to observe that legacy gap.
- */
-export function buildDriftSignature(stagedInputs) {
-    const mtimeOf = (f) => f.mtimeMs;
-    if (!stagedInputs.every((f) => mtimeOf(f) !== undefined))
-        return undefined;
-    return stagedInputs.map((f) => ({ fileId: f.fileId, size: f.size, mtimeMs: mtimeOf(f) }));
-}
 /**
  * Project the profiler's structured output plus the staged manifest into the record
  * persisted on `cortex_analysis_state`.
@@ -91,7 +78,7 @@ export function buildDriftSignature(stagedInputs) {
  * indistinguishable from a legacy snapshot that predates the field, which is exactly
  * the reading a consumer must already tolerate.
  */
-export function buildDataProfileResult(profile, stagedInputs, profiledAt) {
+export function buildDataProfileResult(profile, stagedInputs, profiledAt, coverage) {
     return {
         summary: profile.analysisSummary,
         files: profile.files.map((f) => ({
@@ -105,8 +92,23 @@ export function buildDataProfileResult(profile, stagedInputs, profiledAt) {
             warnings: f.warnings,
             metrics: f.metrics,
         })),
-        inputFileIds: stagedInputs.map((f) => f.fileId),
-        inputFiles: buildDriftSignature(stagedInputs),
+        kinds: profile.kinds.map((k) => ({
+            name: k.name,
+            memberRepresents: k.memberRepresents,
+            description: k.description,
+            count: k.count,
+            pathPattern: k.pathPattern,
+            format: k.format,
+            axisLabels: k.axisLabels,
+        })),
+        axes: profile.axes?.map((a) => ({
+            label: a.label,
+            cardinality: a.cardinality,
+            exampleValues: a.exampleValues,
+            description: a.description,
+        })),
+        inputSignature: computeInputSignature(stagedInputs),
+        coverage,
         profiledAt,
         domain: profile.domain,
         subtype: profile.subtype,
@@ -119,6 +121,37 @@ export function buildDataProfileResult(profile, stagedInputs, profiledAt) {
         qualityAssessment: profile.qualityAssessment,
     };
 }
+/**
+ * Walk the staged tree and enrich its shapes with a header readout.
+ *
+ * The walk and the shape observation run in this process over the workspace read seam;
+ * only the readout reaches into the sandbox, and only once per shape. A readout that
+ * fails is logged and dropped: it is enrichment, and a manifest without it still
+ * carries every structural observation the agent's grouping rests on, so failing the
+ * profile over it would trade the whole capability for a nicety.
+ */
+async function runInputScan(args) {
+    const { session, deps, analysisId, sandbox, execId, deadlineMs, logger } = args;
+    const scan = await scanInputTree({ session, fs: deps.workspaceFs, root: STAGED_INPUT_ROOT });
+    if (scan.manifest.shapes.length === 0)
+        return scan;
+    try {
+        const shapes = await enrichShapes({
+            shapes: scan.manifest.shapes,
+            sandboxClient: deps.sandboxClient,
+            sandbox,
+            mountRoot: `/${analysisId}`,
+            execId,
+            deadlineMs,
+            emit: async () => { },
+        });
+        return { ...scan, manifest: { ...scan.manifest, shapes } };
+    }
+    catch (err) {
+        logger.warn("input-scan header readout failed (non-fatal)", logger.errorFields(err));
+        return scan;
+    }
+}
 /**
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
@@ -192,34 +225,6 @@ export async function runDataProfileBody(input, deps) {
         // meaningless, so no softer handling is warranted.
         const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
         const profileWritePrefix = `${workspaceRoot}/runs/${DATA_PROFILE_RUN_LITERAL}/${DATA_PROFILE_STEP_LITERAL}`;
-        const fileList = stagedInputs.map((f) => inputArtifactPath(f));
-        // The profiler runs outside `executeAnalysis`, so no scheduler composes a
-        // briefing for it — this prompt IS its briefing, and the sandbox system
-        // prompt names no paths (it is static per agent type, for the prompt cache).
-        // Its workspace frame therefore has to be stated here, in the same words the
-        // step briefing uses.
-        const prompt = [
-            `Profile all input data files for this analysis.`,
-            ``,
-            renderWorkspace({
-                analysisRoot: `/${analysisId}`,
-                workingDir: toSandboxPath(workspaceRoot, analysisId, profileWritePrefix),
-            }),
-            ``,
-            `IMPORTANT: You MUST use execute_command to profile files before submitting results. Do NOT submit empty files or placeholder text.`,
-            ``,
-            `CRITICAL: File and directory paths may contain spaces. You MUST always double-quote paths in shell commands (e.g. head "/${analysisId}/data/inputs/My Folder/file.csv"). Unquoted paths with spaces will silently break commands.`,
-            ``,
-            `The following input files are available (paths relative to the analysis root):`,
-            ...fileList.map((f) => `- ${f}`),
-            ``,
-            `Steps:`,
-            `1. For each file, use head and wc to inspect structure (ALWAYS double-quote file paths)`,
-            `2. Write a Python script for detailed profiling — use pathlib or os.path for path handling (handles spaces natively)`,
-            `3. Call the \`submit_profile\` tool with structured metadata for EVERY file listed above`,
-            ``,
-            `All file paths in your response must be relative to the analysis root and must EXACTLY match the paths listed above.`,
-        ].join("\n");
         logger.info("starting sandbox", { executionId });
         // Reported BEFORE the container exists, deliberately: provisioning is the longest single
         // operation in a profile and it precedes the agent entirely, so a body that reported only
@@ -255,6 +260,48 @@ export async function runDataProfileBody(input, deps) {
             // which captures its step deadline the same way).
             const deadlineAbs = (await DBOS.now()) + DEFAULT_DEADLINE_MS;
             const nextFunctionId = makeNextFunctionId();
+            // The deterministic scan, before the agent's first turn. It is always needed
+            // and its result does not depend on agent judgement, so spending an agent turn
+            // to request it would be waste — and a briefing carrying one line per input
+            // file consumes context that carries no structure (~270 KB of bare paths for
+            // the tree that motivated this, against ~2 KB of shapes).
+            await activity.scanning();
+            const scan = await runInputScan({
+                session: childSession,
+                deps,
+                analysisId,
+                sandbox,
+                execId: `${workflowId}:${DATA_PROFILE_STEP_LITERAL}:${nextFunctionId()}`,
+                deadlineMs: deadlineAbs,
+                logger,
+            });
+            logger.info("input scan complete", {
+                files: scan.manifest.fileCount,
+                shapes: scan.manifest.shapes.length,
+                unstructured: scan.manifest.unstructured.count,
+                truncated: scan.manifest.truncated,
+            });
+            // The profiler runs outside `executeAnalysis`, so no scheduler composes a
+            // briefing for it — this prompt IS its briefing, and the sandbox system
+            // prompt names no paths (it is static per agent type, for the prompt cache).
+            // Its workspace frame therefore has to be stated here, in the same words the
+            // step briefing uses.
+            const prompt = [
+                `Profile the input data for this analysis: say what the dataset IS, so planning can proceed.`,
+                ``,
+                renderWorkspace({
+                    analysisRoot: `/${analysisId}`,
+                    workingDir: toSandboxPath(workspaceRoot, analysisId, profileWritePrefix),
+                }),
+                ``,
+                `CRITICAL: File and directory paths may contain spaces. You MUST always double-quote paths in shell commands (e.g. head "/${analysisId}/data/inputs/My Folder/file.csv"). Unquoted paths with spaces will silently break commands.`,
+                ``,
+                renderInputScanManifest(scan.manifest),
+                ``,
+                `Decide the dataset's kinds from these observations — you may split a shape, span several shapes, or`,
+                `label an axis the scan did not observe. Inspect ONE example file per kind where a description needs`,
+                `content the scan did not capture, then call \`submit_profile\` once.`,
+            ].join("\n");
             const sandboxAgentDeps = {
                 provider: deps.provider,
                 pool: deps.pool,
@@ -322,78 +369,64 @@ export async function runDataProfileBody(input, deps) {
             }, {
                 tools: [submitProfileTool],
                 nudge: "You stopped without calling submit_profile, so no profile was " +
-                    "recorded. Call submit_profile now with structured metadata for " +
-                    "every input file — base it on the profiling you already did.",
+                    "recorded. Call submit_profile now with the kinds this dataset is " +
+                    "made of, the axes that vary across them, and any individually " +
+                    "notable files — base it on the scan and the work you already did.",
             });
             if (!capturedProfile) {
                 throw new Error("Data profiling failed: agent did not call submit_profile");
             }
             const profilerData = capturedProfile;
-            // 4. Index into vector store — real files only, consistent type metadata
+            // 4. Index into vector store — one entry per kind, one per entity, none per file.
             //
             // Reported as `indexing`, not `persisting`: the contract defines `persisting` as step
             // bytes uploading to an artifact store, and a profile uploads nothing — its durable
             // products are this vector index and the ledger row.
             await activity.indexing();
-            const profilerByPath = new Map(profilerData.files.map((f) => [f.path, f]));
-            const normPath = (p) => p
-                .replace(/\/+/g, "/")
-                .replace(/^\/|\/$/g, "")
-                .trim();
-            const profilerByNorm = new Map(profilerData.files.map((f) => [normPath(f.path), f]));
+            const profileRecord = buildDataProfileResult(profilerData, stagedInputs, new Date().toISOString(), 
+            // Coverage measures the PROFILE, not the scan: the agent's own patterns are
+            // matched against the scanned tree, so a profile whose kinds leave most of
+            // the tree unmatched is visibly incomplete instead of reading as fresh.
+            computeCoverage(scan.files.map((f) => f.path), profilerData.kinds.map((kind) => kind.pathPattern)));
             await ensureSearchIndex(deps.pool, analysisId, deps.embedding.dimensions);
             const vectorStore = createVectorStore(deps.pool);
-            const embedOne = async (text, session) => {
-                const [vec] = unwrapOrThrow(await deps.embedding.embed([text], session));
-                if (!vec)
-                    throw new Error("data-profile: empty embedding response");
-                return vec;
-            };
             const indexName = searchIndexName(analysisId);
-            let indexed = 0;
-            let fallbackCount = 0;
-            for (const matFile of stagedInputs) {
-                const dbPath = inputArtifactPath(matFile);
-                const desc = profilerByPath.get(dbPath) ?? profilerByNorm.get(normPath(dbPath));
-                // Lossless: a materialized input file the profiler agent omitted
-                // still gets a deterministic, no-LLM description so it stays
-                // discoverable via search. The agent's profile is enrichment, not a
-                // gate on indexing — mirrors the step-output metadata fallback.
-                const searchMeta = desc
-                    ? {
-                        text: desc.description,
-                        type: "input",
-                        dataType: desc.dataType,
-                        format: desc.format,
-                        ...(desc.tags ? { tags: desc.tags } : {}),
-                    }
-                    : {
-                        text: `${dbPath} — input file (${fileExtension(dbPath)}, ${matFile.size} bytes); automated profile unavailable.`,
-                        type: "input",
-                        dataType: "unknown",
-                        format: fileExtension(dbPath),
-                    };
-                if (!desc)
-                    fallbackCount++;
-                const embedding = await embedOne(searchMeta.text, runSession);
+            const entries = buildProfileIndexEntries({
+                analysisId,
+                kinds: profileRecord.kinds ?? [],
+                ...(profileRecord.axes ? { axes: profileRecord.axes } : {}),
+                scan,
+                files: profileRecord.files,
+            });
+            // Batched: both interfaces already take arrays, and one round trip per entry is
+            // what made indexing 12 of the 39 minutes the motivating profile took.
+            for (let start = 0; start < entries.length; start += INDEX_BATCH_SIZE) {
+                const batch = entries.slice(start, start + INDEX_BATCH_SIZE);
+                const vectors = unwrapOrThrow(await deps.embedding.embed(batch.map((entry) => entry.text), runSession));
+                if (vectors.length !== batch.length)
+                    throw new Error(`data-profile: embedding returned ${vectors.length} vectors for ${batch.length} entries`);
                 unwrapOrThrow(await vectorStore.upsert({
                     indexName,
-                    vectors: [embedding],
-                    metadata: [searchMeta],
-                    ids: [`/${analysisId}/${dbPath}`],
+                    vectors,
+                    metadata: batch.map((entry) => ({ ...entry.metadata, text: entry.text })),
+                    ids: batch.map((entry) => entry.id),
                 }));
-                indexed++;
             }
-            if (fallbackCount > 0) {
-                logger.warn("input file(s) used a deterministic fallback description — profiler omitted them", {
-                    fallbackCount,
-                    stagedCount: stagedInputs.length,
+            logger.info("indexed profile", {
+                entries: entries.length,
+                kinds: profileRecord.kinds?.length ?? 0,
+                stagedCount: stagedInputs.length,
+            });
+            if (profileRecord.coverage && profileRecord.coverage.unmatched > 0) {
+                logger.warn("profile kinds do not cover the scanned tree", {
+                    matched: profileRecord.coverage.matched,
+                    unmatched: profileRecord.coverage.unmatched,
+                    total: profileRecord.coverage.total,
                 });
             }
-            logger.info("indexed file(s)", { indexed });
-            // 5. Complete — store the FULL profiler finding plus the input snapshot for
+            // 5. Complete — store the FULL profiler finding plus the input signature for
             // staleness detection. The scratch tree is gone; this row is all that survives.
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, buildDataProfileResult(profilerData, stagedInputs, new Date().toISOString())))) {
+            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord))) {
                 logTerminalNoop(logger, analysisId, "completion");
             }
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");

package/dist/tools/define-tool.d.ts

@@ -39,9 +39,9 @@ export type ToolExecutionMode = "step" | "workflow" | "inline";
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export declare function isToolError(value: unknown): value is ToolError;
 /**
- * The picture that a tool ok value carries beside its JSON data. `base64` holds
+ * One picture that a tool ok value carries beside its JSON data. `base64` holds
  * the bytes, and `mediaType` names the IANA type, for example "image/png". The
- * loop splits the picture out of the JSON text, and it rides the tool result as
+ * loop splits each picture out of the JSON text, and it rides the tool result as
  * an image content block. Thus the model sees the picture, and the JSON text
  * holds no bytes.
  */
@@ -50,23 +50,34 @@ export interface ToolResultImage {
     readonly mediaType: string;
 }
 /**
- * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * The reserved key that carries the pictures on a tool ok value. It is a symbol,
  * thus it never collides with a data field. `JSON.stringify` also omits a symbol
  * key, thus the bytes never reach the JSON text by accident.
  */
 export declare const toolResultImageKey: unique symbol;
-/** A tool ok value that can carry a picture under the reserved key. */
+/** A tool ok value that can carry one picture or an ordered list of them under the reserved key. */
 export type WithToolResultImage<T> = T & {
-    readonly [toolResultImageKey]?: ToolResultImage;
+    readonly [toolResultImageKey]?: ToolResultImage | readonly ToolResultImage[];
 };
 /**
- * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * Attach one picture to a tool ok value. The value keeps its own fields, and the
  * picture rides under the reserved key. The loop reads the key, and it moves the
  * bytes into an image content block on the tool result.
  */
 export declare function withToolResultImage<T extends object>(value: T, image: ToolResultImage): WithToolResultImage<T>;
-/** Read the picture that a tool ok value carries, or undefined when it carries none. */
-export declare function readToolResultImage(value: unknown): ToolResultImage | undefined;
+/**
+ * Attach an ordered list of pictures to a tool ok value. The order is the order
+ * that the model reads, and the loop keeps it on the wire. A tool that slices a
+ * page attaches the slices in document order.
+ */
+export declare function withToolResultImages<T extends object>(value: T, images: readonly ToolResultImage[]): WithToolResultImage<T>;
+/**
+ * Read the pictures that a tool ok value carries, in order. A value with none
+ * gives the empty list. The one-picture shape reads as a list of one, thus a
+ * tool that attaches one picture and a tool that attaches a list meet the loop
+ * in the same shape.
+ */
+export declare function readToolResultImages(value: unknown): ToolResultImage[];
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
  * dependencies (see the harness-durable-runtime spec) — invocation identity,

package/dist/tools/define-tool.js

@@ -21,30 +21,46 @@ export function isToolError(value) {
     return typeof value === "object" && value !== null && typeof value.error === "string" && typeof value.retryable === "boolean";
 }
 /**
- * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * The reserved key that carries the pictures on a tool ok value. It is a symbol,
  * thus it never collides with a data field. `JSON.stringify` also omits a symbol
  * key, thus the bytes never reach the JSON text by accident.
  */
 export const toolResultImageKey = Symbol("toolResultImage");
 /**
- * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * Attach one picture to a tool ok value. The value keeps its own fields, and the
  * picture rides under the reserved key. The loop reads the key, and it moves the
  * bytes into an image content block on the tool result.
  */
 export function withToolResultImage(value, image) {
     return { ...value, [toolResultImageKey]: image };
 }
-/** Read the picture that a tool ok value carries, or undefined when it carries none. */
-export function readToolResultImage(value) {
+/**
+ * Attach an ordered list of pictures to a tool ok value. The order is the order
+ * that the model reads, and the loop keeps it on the wire. A tool that slices a
+ * page attaches the slices in document order.
+ */
+export function withToolResultImages(value, images) {
+    return { ...value, [toolResultImageKey]: images };
+}
+/** Does one entry under the reserved key carry the picture shape? */
+function isToolResultImage(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const { base64, mediaType } = entry;
+    return typeof base64 === "string" && typeof mediaType === "string";
+}
+/**
+ * Read the pictures that a tool ok value carries, in order. A value with none
+ * gives the empty list. The one-picture shape reads as a list of one, thus a
+ * tool that attaches one picture and a tool that attaches a list meet the loop
+ * in the same shape.
+ */
+export function readToolResultImages(value) {
     if (typeof value !== "object" || value === null)
-        return undefined;
-    const image = value[toolResultImageKey];
-    if (typeof image !== "object" || image === null)
-        return undefined;
-    const { base64, mediaType } = image;
-    if (typeof base64 !== "string" || typeof mediaType !== "string")
-        return undefined;
-    return { base64, mediaType };
+        return [];
+    const carried = value[toolResultImageKey];
+    const entries = Array.isArray(carried) ? carried : [carried];
+    return entries.filter(isToolResultImage);
 }
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level

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

@@ -29,9 +29,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 picture of the window alone
- * is a true picture of the current document, thus it stamps the same and the coverage of the result is what
- * tells the agent what it saw.
+ * 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.
  *
  * 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,
@@ -49,11 +49,11 @@ import type { AuthContext } from "../../auth/types.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
 import { type AcquireEyes } from "../../lib/eyes.js";
 import { type Logger } from "../../lib/logger.js";
-import { type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
+import { type CaptureCoverage, type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
 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";
-export type { CapturePage, FailedRequest, PageCapture };
+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.
  * A composition whose browser cannot reach the workspace tree binds a resolver that names a served URL.
@@ -69,15 +69,23 @@ export type ResolvePageUrl = (args: {
 /** 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>;
 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 {
+    index: number;
+    fromY: number;
+    toY: number;
+}
 /**
  * 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 picture, the console errors, the failed
- * requests, and the page path. The coverage names what the agent saw: the whole document, or the window
- * alone when the browser refused a full-page bitmap. The screenshot does not ride the JSON. It rides the
- * image path of the tool result, thus the model sees the picture 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.
+ * 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.
+ * 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.
  */
 export type ExaminePageResult = {
     outcome: "refused";
@@ -94,7 +102,8 @@ export type ExaminePageResult = {
     detail: string;
 } | {
     outcome: "examined";
-    coverage: PageCapture["coverage"];
+    coverage: CaptureCoverage;
+    tiles?: ExaminedTile[];
     consoleErrors: string[];
     failedRequests: FailedRequest[];
     pagePath: string;

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

@@ -29,9 +29,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 picture of the window alone
- * is a true picture of the current document, thus it stamps the same and the coverage of the result is what
- * tells the agent what it saw.
+ * 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.
  *
  * 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,
@@ -55,7 +55,7 @@ import { createStaticEyes } from "../../lib/eyes.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { capturePage } from "../../lib/page-capture.js";
 import { reportSessionDir } from "../../workspace/paths.js";
-import { defineTool, withToolResultImage } from "../define-tool.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({});
@@ -226,8 +226,9 @@ export function createExaminePageTool(deps) {
     return defineTool({
         id: "examine_page",
         description: "Open the rendered report page in a real headless browser, and report what you see. " +
-            "Give back a screenshot, the coverage of that screenshot, the console errors, and the failed requests. " +
-            "The coverage says whether the picture holds the whole page, or the top window alone. " +
+            "Give back 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. " +
             "Run it after the preview to look at the current page, and to confirm that the layout and the charts read clean. " +
             "The report tool records a version only after you look at the current page. " +
             "If the page has no confirmed render, run the preview again first.",
@@ -317,15 +318,19 @@ export function createExaminePageTool(deps) {
                 const detail = stamped.outcome === "failed" ? stamped.detail : "the session state row is absent";
                 logger.warn("the seen hash did not stamp", { threadId, analysisId, detail });
             }
-            // The screenshot rides the image path of the tool result, thus the model sees the picture. The
-            // JSON keeps the faults and the page path only, thus the JSON text holds no bytes.
-            return ok(withToolResultImage({
+            // 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.
+            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,
                 pagePath: relativePagePath,
-            }, { base64: captured.screenshotBase64, mediaType: SCREENSHOT_MEDIA_TYPE }));
+            }, captured.screenshots.map((shot) => ({ base64: shot.base64, mediaType: SCREENSHOT_MEDIA_TYPE }))));
         },
     });
 }

package/dist/tools/report-session/index.d.ts

@@ -6,7 +6,7 @@
  * the factories and their public types for the composition root.
  */
 export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, type SessionPageAccess, } from "./preview-report.js";
-export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
+export { createExaminePageTool, type CaptureCoverage, type CapturePage, type ExaminedTile, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
 export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageMintFailure, type SessionPageMintResult, type SessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
 export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";

package/dist/tools/research/generate-plan.js

@@ -36,7 +36,6 @@ import { createListAvailablePackagesTool } from "../sandbox/list-available-packa
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
 import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
-import { isDataProfileStale } from "../../app/data-profile-policy.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../../config/resource-limits.js";
 import { plannerPrompt } from "../../prompts/planner.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
@@ -157,10 +156,9 @@ function formatPriorPlan(parentPlanId, plan) {
 /**
  * Read the profile ledger row into a grounding variant.
  *
- * Staleness is `isDataProfileStale` — the single definition in
- * `app/data-profile-policy.ts` that the embedder's re-trigger policy and
- * `inspect_data_profile` also use, so the planner and the conversation agent can
- * never disagree about whether a profile still describes the data.
+ * A profile is re-invoked by the embedder when the input set changes, never derived
+ * as stale on read, so the only qualification this can raise is one the ledger row
+ * states outright: an attempt that superseded this result is running, or failed.
  */
 function classifyGrounding(status) {
     // `loadDataProfileStatus` collapses "no analysis row" and "profile cleared"
@@ -182,9 +180,6 @@ function classifyGrounding(status) {
     // preserve `data_profile_result` on purpose, so a non-`completed` status
     // carrying a result means what is on the row is the PREVIOUS profile.
     const reasons = [];
-    if (isDataProfileStale(status.seedInputFileIds ?? [], result.inputFileIds)) {
-        reasons.push("the analysis's input file set changed after this profile was taken");
-    }
     if (status.status === "pending" || status.status === "running") {
         reasons.push("a re-profile is in progress — this is the previous profile");
     }