@inflexa-ai/harness 0.19.0 → 0.19.1

package/dist/agents/report-session-agent.d.ts

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools and the preview tool bind to the session-state gateway, thus one
- * assembled definition serves every thread, and the per-session state stays behind
- * the tool boundary.
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -19,20 +19,24 @@
  * across threads, and the provider cache reuses it.
  */
 import type { Pool } from "pg";
+import type { AuthContext } from "../auth/types.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { EmbeddingProvider } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ChromeConfig } from "../lib/chrome.js";
 import type { Logger } from "../lib/logger.js";
+import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
+import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
 /**
  * The shared dependencies of the report agent. The gateway binds the per-session
  * state to the thread, thus every tool that touches the state gets the same
- * gateway. The resolver is optional, because a resolver realization can be absent,
- * and the preview tool degrades as data when it is.
+ * gateway. The resolver factory is optional, because a resolver realization can be
+ * absent, and the preview tool and the record tool degrade as data when it is.
  */
 export interface ReportSessionAgentDeps {
     /** Model id -- the provenance and metric label. The provider owns the wire model. */
@@ -43,12 +47,24 @@ export interface ReportSessionAgentDeps {
     readonly embedding: EmbeddingProvider;
     /** Workspace filesystem read seam -- the four read tools. */
     readonly workspaceFs: WorkspaceFilesystem;
-    /** Session-state gateway -- the authoring tools and the preview tool bind to it. */
+    /** Session-state gateway -- the authoring tools, the preview tool, the eyes tool, and the record tool bind to it. */
     readonly gateway: ReportSessionStateGateway;
-    /** Workspace-root resolution seam -- the preview tool resolves the page root per call. */
+    /** Workspace-root resolution seam -- the preview tool and the eyes tool resolve the page root per call. */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
-    /** Reference-resolution seam -- absent until a realization lands; the preview tool degrades as data. */
-    readonly resolver?: ReferenceResolver;
+    /** Append-only version store -- the record tool gates the whole document first, then records one version. */
+    readonly store: ReportVersionStore;
+    /** Thread reader -- the record tool reads the anchor of the report thread. */
+    readonly threads: Pick<ThreadStore, "getThread">;
+    /** Headless-Chrome config -- the eyes tool opens the rendered page. */
+    readonly chrome: ChromeConfig;
+    /**
+     * Reference-resolution factory -- absent until a realization lands; the preview tool and the record tool
+     * degrade as data. The factory binds one analysis, thus a tool makes the resolver over the scope of the call.
+     */
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

package/dist/agents/report-session-agent.js

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools and the preview tool bind to the session-state gateway, thus one
- * assembled definition serves every thread, and the per-session state stays behind
- * the tool boundary.
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -19,7 +19,7 @@
  * across threads, and the provider cache reuses it.
  */
 import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
-import { createPreviewReportTool } from "../tools/report-session/preview-report.js";
+import { createExaminePageTool, createPreviewReportTool, createRecordVersionTool } from "../tools/report-session/index.js";
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
 import { createInspectDataProfileTool, createInspectRunTool } from "../tools/research/index.js";
 import { reportSessionPrompt } from "../prompts/report-session.js";
@@ -33,7 +33,7 @@ export const REPORT_SESSION_AGENT_ID = "report-session";
 const REPORT_SESSION_MAX_ITERATIONS = 50;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
-    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, resolver, logger } = deps;
+    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, makeResolver, logger } = deps;
     const authoring = createReportAuthoringTools(gateway);
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
@@ -58,7 +58,22 @@ export function createReportSessionAgent(deps) {
         createPreviewReportTool({
             gateway,
             resolveWorkspaceRoot,
-            ...(resolver ? { resolver } : {}),
+            ...(makeResolver ? { makeResolver } : {}),
+            ...(logger ? { logger } : {}),
+        }),
+        // The eyes tool. It opens the rendered page in headless Chrome.
+        createExaminePageTool({
+            gateway,
+            resolveWorkspaceRoot,
+            chrome,
+            ...(logger ? { logger } : {}),
+        }),
+        // The record tool. It gates the whole document, then records one version.
+        createRecordVersionTool({
+            gateway,
+            store,
+            threads,
+            ...(makeResolver ? { makeResolver } : {}),
             ...(logger ? { logger } : {}),
         }),
     ];

package/dist/app/report-session-runtime.js

@@ -115,6 +115,7 @@ export function createReportSessionRuntime(deps) {
             state: { document: state.document ?? EMPTY_DRAFT, snapshot: state.snapshot },
             analysisId: state.analysisId,
             token: state.document,
+            seenDocumentHash: state.seenDocumentHash,
         };
     }
     const gateway = {
@@ -152,6 +153,31 @@ export function createReportSessionRuntime(deps) {
                 return { outcome: "failed", detail: describeDbError(error) };
             });
         },
+        async stampRendered(threadId, hash) {
+            const result = await store.stampRendered(threadId, hash);
+            return result.match((outcome) => (outcome === "stamped" ? { outcome: "stamped" } : { outcome: "absent" }), (error) => {
+                log.error("the rendered-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+        async stampSeen(threadId) {
+            const result = await store.stampSeen(threadId);
+            return result.match((outcome) => {
+                switch (outcome) {
+                    case "stamped":
+                        return { outcome: "stamped" };
+                    case "no-rendered":
+                        // The row holds no rendered hash, thus no preview stamped one and the copy found
+                        // none. The eyes direct a new preview from this arm.
+                        return { outcome: "no-rendered" };
+                    case "absent":
+                        return { outcome: "absent" };
+                }
+            }, (error) => {
+                log.error("the seen-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
     };
     return { gateway, ensureSessionState };
 }

package/dist/app/spawn-report-session.d.ts

@@ -18,10 +18,19 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import type { DbError } from "../lib/db-result.js";
+import { type ChromeConfig } from "../lib/chrome.js";
+import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -34,9 +43,15 @@ import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType }
  * state is not permitted. `parent_not_a_conversation` keeps the tree flat: a
  * report session cannot spawn another. `empty_parent_transcript` refuses a
  * report on a parent that holds no messages, because such a report reports
- * nothing.
+ * nothing. `no_browser` refuses every spawn under a composition that gives no
+ * eyes, and it carries the line that explains the absent capability.
  */
 export type SpawnRefusal = {
+    readonly type: "no_browser";
+    readonly op: string;
+    readonly parentThreadId: string;
+    readonly detail: string;
+} | {
     readonly type: "parent_not_found";
     readonly op: string;
     readonly parentThreadId: string;
@@ -57,6 +72,18 @@ export interface ReportSessionPaging {
 }
 export interface ReportSessionSpawnDeps {
     readonly pool: Pool;
+    /**
+     * The chrome config that the same composition gives to the eyes tool. The
+     * spawn reads only whether it names a browser, thus the spawn and the tool
+     * decide the availability of the eyes from one value.
+     */
+    readonly chrome: ChromeConfig;
+    /**
+     * The capture seam that the same composition gives to the eyes tool. A
+     * present seam is a route to a look with no browser endpoint, thus it
+     * satisfies the gate on its own.
+     */
+    readonly capture?: CapturePage;
 }
 export interface ReportSessionSpawn {
     /**
@@ -64,10 +91,10 @@ export interface ReportSessionSpawn {
      * The child takes the analysis of the parent, the parent thread id, and the
      * anchor — the parent's latest `messages.seq` at this moment.
      *
-     * Refused with a `SpawnRefusal`, no row written: an absent or archived
-     * parent, a parent that is not a conversation, and a parent with no
-     * messages. A store refusal (`DbError`, `ThreadInputError`) passes through
-     * unchanged.
+     * Refused with a `SpawnRefusal`, no row written: a composition with no
+     * eyes, an absent or archived parent, a parent that is not a conversation,
+     * and a parent with no messages. A store refusal (`DbError`,
+     * `ThreadInputError`) passes through unchanged.
      */
     spawnReportSession(parentThreadId: string): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
     /**

package/dist/app/spawn-report-session.js

@@ -18,13 +18,23 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { randomUUID } from "node:crypto";
 import { errAsync } from "neverthrow";
+import { hasBrowserUrl } from "../lib/chrome.js";
 import { createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 const _assertDomainError = true;
 const OP = "spawn-report-session";
+/** The line that the caller reads when the composition gives no eyes. */
+const NO_BROWSER_DETAIL = "the composition gives no browser, thus a report session can never record a version";
 /**
  * Compose the child title. N counts the existing report children of the parent
  * plus one. A parent with no title yields `Report N` alone, because the seed of
@@ -43,7 +53,16 @@ export function createReportSessionSpawn(deps) {
     const { pool } = deps;
     const store = createThreadStore(pool);
     const history = createThreadHistory(pool);
+    // The eyes of the composition are fixed at construction, thus the gate reads
+    // one boolean and never a live probe of the sidecar.
+    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
     function spawnReportSession(parentThreadId) {
+        // The gate runs before the parent read. A session with no route to a look
+        // reaches the record gate and refuses there forever, thus the spawn is the
+        // one honest place to say so.
+        if (!eyesAvailable) {
+            return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
+        }
         return store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.

package/dist/config/environment-stores.d.ts

@@ -18,17 +18,22 @@
  * one. Neither store is ever written through these paths.
  *
  * Both are optional, and absence is a NORMAL state rather than an error: an
- * omitted path makes its tool report the store as unavailable or unknown, which
- * is a truthful answer an agent can act on. Absence must never be reported as a
- * failure, and never papered over with a guessed path.
+ * omitted path falls back to the store's container mountpoint — correct for a
+ * host whose own process sees the store the way a sandbox does, and harmless for
+ * one that does not, because every consumer stats the root before it reports
+ * anything. A host with nothing mounted there gets the same "unavailable" or
+ * "unknown" answer an omitted path has always produced, so the fallback can no
+ * more invent a store than an explicit path can. Set a path only to name a
+ * location the container mountpoint does not describe; absence must never be
+ * reported as a failure.
  */
 export interface EnvironmentStorePaths {
     /**
      * Host path of the reference store — the same bytes sandboxes mount at
-     * `/mnt/refs`. Omit when no store is provisioned; reference discovery then
-     * reports the store as unavailable. Note that an installed store reads as
-     * absent if this is omitted, which is indistinguishable to an agent from
-     * having no data — so omit it only when there is genuinely nothing staged.
+     * `/mnt/refs`. Omit when the host's own process sees the store at that same
+     * path, as a K8s pod holding the ref-store PVC does; set it when the host
+     * reads the store somewhere else, as a native process bind-mounting a host
+     * directory into Docker does.
      */
     readonly refStorePath?: string;
     /**

package/dist/config/resource-limits.d.ts

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 export declare const GpuSpecSchema: z.ZodObject<{
@@ -47,13 +50,6 @@ export declare const DEFAULT_SANDBOX_MAX_STEPS = 75;
 export declare class ResourceLimitsConfigError extends Error {
     constructor(message: string);
 }
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export declare function loadResourceLimits(): ResourceLimits;
 /**
  * Validate an embedder-supplied resource policy.
  *

package/dist/config/resource-limits.js

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 // ── Schemas ─────────────────────────────────────────────────────────
@@ -38,47 +41,6 @@ export class ResourceLimitsConfigError extends Error {
         this.name = "ResourceLimitsConfigError";
     }
 }
-// ── Parsing ─────────────────────────────────────────────────────────
-function parsePositiveNumber(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num <= 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a positive number, got: ${value}`);
-    }
-    return num;
-}
-function parseNonNegativeInt(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num < 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a non-negative number, got: ${value}`);
-    }
-    if (!Number.isInteger(num)) {
-        throw new ResourceLimitsConfigError(`${name} must be an integer, got: ${value}`);
-    }
-    return num;
-}
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export function loadResourceLimits() {
-    const maxCpu = parsePositiveNumber("SANDBOX_MAX_CPU", process.env.SANDBOX_MAX_CPU);
-    const maxMemoryGb = parsePositiveNumber("SANDBOX_MAX_MEMORY_GB", process.env.SANDBOX_MAX_MEMORY_GB);
-    const maxGpuCount = parseNonNegativeInt("SANDBOX_MAX_GPU_COUNT", process.env.SANDBOX_MAX_GPU_COUNT);
-    const limits = { maxCpu, maxMemoryGb, maxGpuCount };
-    const result = ResourceLimitsSchema.safeParse(limits);
-    if (!result.success) {
-        throw new ResourceLimitsConfigError(`Invalid resource limits configuration: ${result.error.message}`);
-    }
-    return result.data;
-}
 /**
  * Validate an embedder-supplied resource policy.
  *

package/dist/contracts/report-reference.d.ts

@@ -313,6 +313,8 @@ export declare const ScalarReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject
  * the path. `unreadable-artifact` means that the entry exists, and that the resolver cannot read the
  * artifact as a table. Two conditions give the second reason. The file type refuses a read of a cell, or
  * the bytes are unrecoverable.
+ *
+ * `extraction-unavailable` means that the value tier must use an extraction arm that is not wired.
  */
 export declare const UnresolvedReasonSchema: z.ZodEnum<{
     "artifact-missing": "artifact-missing";
@@ -321,6 +323,7 @@ export declare const UnresolvedReasonSchema: z.ZodEnum<{
     "ambiguous-match": "ambiguous-match";
     "assertion-failed": "assertion-failed";
     "unreadable-artifact": "unreadable-artifact";
+    "extraction-unavailable": "extraction-unavailable";
 }>;
 /** A reference that resolution could not bind, with the reason and an optional detail. */
 export declare const UnresolvedReferenceSchema: z.ZodObject<{
@@ -419,6 +422,7 @@ export declare const UnresolvedReferenceSchema: z.ZodObject<{
         "ambiguous-match": "ambiguous-match";
         "assertion-failed": "assertion-failed";
         "unreadable-artifact": "unreadable-artifact";
+        "extraction-unavailable": "extraction-unavailable";
     }>;
     detail: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;

package/dist/contracts/report-reference.js

@@ -175,6 +175,8 @@ export const ScalarReferenceSchema = z.discriminatedUnion("kind", [ArtifactValue
  * the path. `unreadable-artifact` means that the entry exists, and that the resolver cannot read the
  * artifact as a table. Two conditions give the second reason. The file type refuses a read of a cell, or
  * the bytes are unrecoverable.
+ *
+ * `extraction-unavailable` means that the value tier must use an extraction arm that is not wired.
  */
 export const UnresolvedReasonSchema = z.enum([
     "artifact-missing",
@@ -183,6 +185,7 @@ export const UnresolvedReasonSchema = z.enum([
     "ambiguous-match",
     "assertion-failed",
     "unreadable-artifact",
+    "extraction-unavailable",
 ]);
 /** A reference that resolution could not bind, with the reason and an optional detail. */
 export const UnresolvedReferenceSchema = z.strictObject({

package/dist/index.d.ts

@@ -5,7 +5,8 @@
  * the agent with its own seam realizations.
  */
 export { assembleCoreRuntime } from "./runtime/assemble.js";
-export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable } from "./runtime/assemble.js";
+export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable, MakeReportReferenceResolver, ReportResolverScope, } from "./runtime/assemble.js";
+export type { ReferenceResolver, ReportSnapshot, ResolvedValue } from "./report-model/reference-resolver.js";
 export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";

package/dist/lib/chrome.d.ts

@@ -11,8 +11,22 @@ import type { Logger } from "./logger.js";
 export interface ChromeConfig {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /**
+     * The endpoint of the Chrome sidecar. The connection is out of process, thus the sidecar has its own
+     * filesystem and its own network position. A `file://` URL resolves against the filesystem of the
+     * sidecar and never against the filesystem of the harness host. A caller that navigates to a workspace
+     * file must run a sidecar that mounts the same workspace tree at the same path.
+     *
+     * An absent value means that the composition gives no browser at all. A caller that needs a look must
+     * report that condition, not attempt a connection.
+     */
     readonly browserUrl?: string;
     readonly maxPages?: number;
 }
+/**
+ * Whether the config names a browser to connect to. A composition with no endpoint has no eyes, and a
+ * caller reads that up front instead of failing once for each attempted connection.
+ */
+export declare function hasBrowserUrl(cfg: ChromeConfig): boolean;
 export declare function getBrowser(browserUrl?: string, injected?: Logger): Promise<Browser>;
 export declare function withPage<T>(cfg: ChromeConfig, fn: (page: Page, context: BrowserContext) => Promise<T>): Promise<T>;

package/dist/lib/chrome.js

@@ -8,6 +8,13 @@
  */
 import puppeteer from "puppeteer-core";
 import { createNoopLogger } from "./console-logger.js";
+/**
+ * Whether the config names a browser to connect to. A composition with no endpoint has no eyes, and a
+ * caller reads that up front instead of failing once for each attempted connection.
+ */
+export function hasBrowserUrl(cfg) {
+    return cfg.browserUrl !== undefined && cfg.browserUrl.trim().length > 0;
+}
 let browser;
 let connecting;
 let semaphore;

package/dist/lib/page-capture.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one page capture over the Chrome sidecar.
+ *
+ * A capture navigates to a page URL, collects the console errors and the failed requests, waits for the
+ * readiness signal of the page, and gives back a base64 screenshot. Two tools capture a report page: the
+ * preview snapshot of the old report path and the eyes tool of a report session. Both read this module.
+ *
+ * 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
+ * imports them, thus a rename or a retime reaches the waiter at compile time. A second copy of the wait
+ * script would instead degrade every capture to the readiness timeout, and no type would break.
+ *
+ * The capture speaks the throw protocol, because the chrome connection does. A caller that needs a typed
+ * outcome guards the call.
+ */
+import { type ChromeConfig } from "./chrome.js";
+/** One request that the page could not load, with the reason that the browser gave. */
+export interface FailedRequest {
+    url: string;
+    reason: string;
+}
+/** The picture and the faults of one page capture. */
+export interface PageCapture {
+    screenshotBase64: string;
+    consoleErrors: string[];
+    failedRequests: FailedRequest[];
+}
+/**
+ * The capture seam. It navigates to a page URL, and it gives back the screenshot and the faults. The seam
+ * speaks the throw protocol, because the chrome connection does. A test injects a seam that reads no
+ * browser, thus a tool orchestration runs with no chrome sidecar.
+ */
+export type CapturePage = (url: string) => Promise<PageCapture>;
+/** The extra settle steps that one call site needs. A call site that needs neither passes nothing. */
+export interface CaptureOptions {
+    /** A CSS selector to wait for after the readiness signal. The wait is best-effort. */
+    readonly waitForSelector?: string;
+    /** An extra settle time in milliseconds after the readiness signal, for a late paint. */
+    readonly waitMs?: number;
+}
+/**
+ * Capture one page: the screenshot, the console errors, and the failed requests.
+ *
+ * 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.
+ */
+export declare function capturePage(chrome: ChromeConfig, url: string, options?: CaptureOptions): Promise<PageCapture>;

package/dist/lib/page-capture.js

@@ -0,0 +1,83 @@
+/**
+ * The one page capture over the Chrome sidecar.
+ *
+ * A capture navigates to a page URL, collects the console errors and the failed requests, waits for the
+ * readiness signal of the page, and gives back a base64 screenshot. Two tools capture a report page: the
+ * preview snapshot of the old report path and the eyes tool of a report session. Both read this module.
+ *
+ * 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
+ * imports them, thus a rename or a retime reaches the waiter at compile time. A second copy of the wait
+ * script would instead degrade every capture to the readiness timeout, and no type would break.
+ *
+ * The capture speaks the throw protocol, because the chrome connection does. A caller that needs a typed
+ * outcome guards the call.
+ */
+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";
+/** 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;
+/**
+ * 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
+ * page that never signals.
+ *
+ * The browser runs this body as source text. Thus the body reads no module binding, and each value that it
+ * needs arrives as a parameter. The page evaluation sends a parameter as data, thus no value becomes code.
+ */
+function waitForThemeReady(sentinel, event, timeout) {
+    return new Promise((resolve) => {
+        // The sentinel name arrives as a value, thus no declared property of the global object describes it.
+        if (window[sentinel]) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            resolve();
+        }, timeout);
+        document.addEventListener(event, () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/**
+ * Capture one page: the screenshot, the console errors, and the failed requests.
+ *
+ * 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.
+ */
+export function capturePage(chrome, url, options = {}) {
+    return withPage(chrome, async (page) => {
+        const consoleErrors = [];
+        const failedRequests = [];
+        page.on("console", (msg) => {
+            if (msg.type() === "error")
+                consoleErrors.push(msg.text());
+        });
+        page.on("pageerror", (err) => consoleErrors.push(`pageerror: ${err.message}`));
+        page.on("requestfailed", (req) => {
+            failedRequests.push({ url: req.url(), reason: req.failure()?.errorText ?? "unknown" });
+        });
+        await page.goto(url, { waitUntil: "networkidle2", timeout: PAGE_NAV_TIMEOUT_MS });
+        // The two names and the budget ride as arguments, because the browser context has no module scope.
+        await page.evaluate(waitForThemeReady, THEME_READY_SENTINEL, THEME_READY_EVENT, PAGE_READY_TIMEOUT_MS).catch(() => {
+            /* the picture captures as it stands */
+        });
+        if (options.waitForSelector !== undefined) {
+            await page.waitForSelector(options.waitForSelector, { timeout: SELECTOR_TIMEOUT_MS }).catch(() => {
+                /* the picture captures as it stands */
+            });
+        }
+        if (options.waitMs !== undefined && options.waitMs > 0) {
+            const settle = options.waitMs;
+            await new Promise((resolve) => setTimeout(resolve, settle));
+        }
+        const screenshot = await page.screenshot({ encoding: "base64", fullPage: false });
+        return {
+            screenshotBase64: typeof screenshot === "string" ? screenshot : Buffer.from(screenshot).toString("base64"),
+            consoleErrors,
+            failedRequests,
+        };
+    });
+}