@inflexa-ai/harness 0.18.0 → 0.19.1

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

@@ -1,19 +1,24 @@
 /**
  * The authoring tool surface over the draft operations.
  *
- * The factory closes over a private draft holder and the pinned snapshot. It gives eight tools and a
- * read of the current draft. The tools read no ambient state, thus two factories hold two independent
- * drafts.
+ * The factory takes a session-state gateway, and it holds no draft. Each tool reads the thread id from the
+ * scope of the call, loads the state of that thread, applies the pure operation, and persists the new
+ * document. Thus two threads never share one draft, and a landed document outlives a host restart.
  *
- * Each tool maps its flat input onto a core operation, and it applies the pure operation. The holder
- * swaps only on a landed operation. A refused operation returns typed data in the ok channel, and the
- * error channel stays for an unexpected failure.
+ * Each tool maps its flat input onto a core operation, and it applies the pure operation. A landed
+ * document persists before the tool reports `applied: true`. A refused operation returns typed data in the
+ * ok channel, and the error channel stays for an unexpected failure.
+ *
+ * A call with no report thread in its scope, a thread with no stored state, and a gateway fault each
+ * refuse as typed data too. That refusal sits beside the core refusal, and it names the absent thread
+ * scope or the absent state.
  *
  * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
  * nested union. A conflict between the flat fields refuses before the core runs.
  */
 import { err, ok } from "neverthrow";
 import { z } from "zod";
+import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
@@ -78,6 +83,44 @@ const setTitleInput = z.object({
     title: z.string().min(1),
 });
 const finishDraftInput = z.object({});
+/**
+ * Resolve the report thread of a call, and load its state through the gateway.
+ *
+ * The report thread and its analysis ride on the analysis scope. The thread id becomes one segment of a
+ * session directory, thus the safe-id check sits here beside the shape check: a scope whose id carries a
+ * separator or a traversal segment names no thread that a tool can write under.
+ *
+ * The stored analysis of the thread must match the scope. A mismatch reads one analysis's draft and writes
+ * into another analysis's workspace, thus the resolution refuses it with a permanent reason that names the
+ * two ids. A scope of a different kind, an unsafe id, an absent thread, a wrong thread type, and a gateway
+ * fault each refuse as a typed `SessionRefusal` too.
+ *
+ * The authoring tools and the preview tool share this one resolution, thus the two surfaces accept the
+ * same thread id and map a load outcome onto a refusal the same way.
+ */
+export async function openReportThread(gateway, scope) {
+    if (scope.kind !== "analysis" || scope.threadId === undefined || !isSafeId(scope.threadId)) {
+        return err({ reason: "no-thread-scope", detail: "the scope of the call names no usable report thread id" });
+    }
+    const { threadId, analysisId } = scope;
+    const loaded = await gateway.load(threadId);
+    if (loaded.outcome === "absent") {
+        return err({ reason: "absent-state", detail: `no report session exists for the thread ${threadId}, and this condition is permanent` });
+    }
+    if (loaded.outcome === "wrong-type") {
+        return err({ reason: "wrong-thread-type", detail: `${loaded.detail}, and this condition is permanent` });
+    }
+    if (loaded.outcome === "failed") {
+        return err({ reason: "state-unavailable", detail: loaded.detail });
+    }
+    if (loaded.analysisId !== analysisId) {
+        return err({
+            reason: "scope-analysis-mismatch",
+            detail: `the scope names the analysis ${analysisId}, but the thread ${threadId} belongs to the analysis ${loaded.analysisId}`,
+        });
+    }
+    return ok({ threadId, analysisId, state: loaded.state, token: loaded.token, seenDocumentHash: loaded.seenDocumentHash });
+}
 /** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
 function given(value) {
     return value ?? undefined;
@@ -197,37 +240,59 @@ function containerIn(document, parentId) {
 /**
  * Every tool of this surface runs inline.
  *
- * The draft is closure memory with no durable backing. A step-mode tool goes through `DBOS.runStep`, which
- * caches the result of a step and replays it without running the body. A replay after a host restart would
- * hand the agent the cached `applied: true` outline of each landed operation while the rebuilt closure
- * holds an empty draft, and the finish would then report an empty document for a report that the
- * transcript shows as complete. Inline mode keeps the tool result and the draft in one lifetime.
+ * A tool loads the state of its thread, applies the pure operation, and persists the result in one body.
+ * The reported outline must agree with the row that the body just wrote. A step-mode tool goes through
+ * `DBOS.runStep`, which caches the result of a step and replays it without a fresh load. A replay could
+ * then report an outline that the current row no longer holds. Inline mode reads and writes the row in one
+ * lifetime, thus the outline never drifts from the state.
  */
 const AUTHORING_EXECUTION_MODE = "inline";
 /**
- * Make the eight authoring tools over one draft.
+ * Make the eight authoring tools over a session-state gateway.
  *
- * The holder is a private `let`. Each tool reads the holder at call time, thus a landing through one tool
- * shows in the next call of every tool. The holder swaps only inside `land`, thus a refused operation
- * leaves the draft as it was.
+ * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
+ * 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.
  */
-export function createReportAuthoringTools(state) {
-    const snapshot = state.snapshot;
-    let draft = state.initialDraft ?? { title: "", sections: [] };
+export function createReportAuthoringTools(gateway) {
+    /**
+     * Resolve the thread of the call, and load its state.
+     *
+     * The shared `openReportThread` holds the one resolution. A scope of a different kind, an unsafe or
+     * absent thread id, an absent row, and a gateway fault each refuse before the call reaches a core
+     * operation.
+     */
+    const openThread = (ctx) => openReportThread(gateway, ctx.session.scope);
     /**
-     * Swap the holder on a landing, and report the containers that the operation changed.
+     * Persist a landing, and report the containers that the operation changed.
      *
-     * `holders` names them by id, and it reads the draft as it was and the draft as it becomes, because a
-     * removed block has a holder only in the first and an added block has one only in the second. The
-     * child order comes out of `next` in either case.
+     * `holders` names them by id, and it reads the previous document and the next document, because a
+     * removed block has a holder only in the first and an added block has one only in the second. The child
+     * order comes out of `next` in either case. A persist fault refuses with `state-unavailable`, thus the
+     * tool reports `applied: true` only after the row holds the new document.
+     *
+     * 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`.
      */
-    const land = (result, holders) => result.match((next) => {
-        const previous = draft;
-        draft = next;
+    const land = async (threadId, token, previous, result, holders) => {
+        if (result.isErr()) {
+            return { applied: false, refusal: result.error };
+        }
+        const next = result.value;
+        const persisted = await gateway.persist(threadId, next, token);
+        if (persisted.outcome === "conflict") {
+            return {
+                applied: false,
+                refusal: { reason: "stale-state", detail: "another turn changed the report since this turn read it, thus read the state again" },
+            };
+        }
+        if (persisted.outcome === "failed") {
+            return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
+        }
         // A move inside one container names the same holder two times.
         const unique = [...new Set(holders(previous, next))];
         return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
-    }, (refusal) => ({ applied: false, refusal }));
+    };
     const refuse = (refusal) => ({ applied: false, refusal });
     const add_block = defineTool({
         id: "add_block",
@@ -241,16 +306,19 @@ export function createReportAuthoringTools(state) {
             const kind = readKind(decodeBlockPayload(input.block));
             return kind !== undefined ? `add ${kind}` : "add a block";
         },
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
             const block = decodeBlockPayload(input.block);
             const addedId = readId(block);
-            return ok(land(addBlock(draft, { block, destination: destination.value }, snapshot), (_previous, next) => [
-                addedId === undefined ? undefined : holderIdOf(next, addedId),
-            ]));
+            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)]));
         },
     });
     const change_block = defineTool({
@@ -260,12 +328,19 @@ export function createReportAuthoringTools(state) {
         inputSchema: changeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `change ${input.targetId}`,
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const operation = toChangeOperation(input);
             if (operation.isErr()) {
                 return ok(refuse(operation.error));
             }
-            return ok(land(changeBlock(draft, operation.value, snapshot), (_previous, next) => [holderIdOf(next, input.targetId)]));
+            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [
+                holderIdOf(next, input.targetId),
+            ]));
         },
     });
     const remove_block = defineTool({
@@ -274,7 +349,16 @@ export function createReportAuthoringTools(state) {
         inputSchema: removeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `remove ${input.targetId}`,
-        execute: async (input) => ok(land(removeBlock(draft, { targetId: input.targetId }, snapshot), (previous) => [holderIdOf(previous, input.targetId)])),
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [
+                holderIdOf(previous, input.targetId),
+            ]));
+        },
     });
     const move_block = defineTool({
         id: "move_block",
@@ -283,15 +367,17 @@ export function createReportAuthoringTools(state) {
         inputSchema: moveBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `move ${input.targetId}`,
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
-            return ok(land(moveBlock(draft, { targetId: input.targetId, destination: destination.value }, snapshot), (previous, next) => [
-                holderIdOf(previous, input.targetId),
-                holderIdOf(next, input.targetId),
-            ]));
+            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)]));
         },
     });
     const set_title = defineTool({
@@ -302,7 +388,14 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `title the report ${input.title}`,
         // The title sits on the document, thus no container changes its child order.
-        execute: async (input) => ok(land(ok(setTitle(draft, input.title)), () => [])),
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => []));
+        },
     });
     const read_outline = defineTool({
         id: "read_outline",
@@ -313,7 +406,13 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
-        execute: async () => ok({ outline: buildOutline(draft) }),
+        execute: async (_input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            return ok({ outline: buildOutline(opened.value.state.document) });
+        },
     });
     const read_block = defineTool({
         id: "read_block",
@@ -322,8 +421,12 @@ export function createReportAuthoringTools(state) {
         inputSchema: readBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `read ${input.targetId}`,
-        execute: async (input) => {
-            const block = readBlock(draft, input.targetId);
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            const block = readBlock(opened.value.state.document, input.targetId);
             const result = block !== undefined ? { found: true, block } : { found: false };
             return ok(result);
         },
@@ -336,7 +439,13 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
-        execute: async () => ok(finishDraft(draft, snapshot)),
+        execute: async (_input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot));
+        },
     });
     return {
         add_block,
@@ -347,6 +456,5 @@ export function createReportAuthoringTools(state) {
         read_outline,
         read_block,
         finish_draft,
-        currentDraft: () => draft,
     };
 }

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

@@ -0,0 +1,90 @@
+/**
+ * The eyes tool of a report session.
+ *
+ * The tool opens the rendered page of a thread in headless Chrome, and it gives back what a reviewer would
+ * 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.
+ *
+ * The session tree has no URL space, thus 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 typed outcome, not a throw.
+ *
+ * The `file://` URL resolves on the filesystem of the Chrome sidecar, because the connection is out of
+ * process. Thus the sidecar must mount the workspace tree of the harness host at the same path. A sidecar
+ * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
+ *
+ * A composition that names no browser and injects no capture seam has no eyes at all. The tool reports that
+ * condition once, up front, and it stamps nothing. A per-attempt capture failure would instead read as a
+ * transient fault and invite a repeat of a call that can never pass.
+ *
+ * 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.
+ *
+ * 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,
+ * because a repeated look never stamps a marker that no preview wrote.
+ *
+ * The chrome navigation and the workspace-root seam each speak the throw protocol. The tool runs the capture
+ * inside a guard, thus a genuine fault becomes a typed outcome and a control-flow exception propagates.
+ */
+import { z } from "zod";
+import { type ChromeConfig } from "../../lib/chrome.js";
+import { type Logger } from "../../lib/logger.js";
+import { 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 };
+/** 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 typed outcome of the eyes tool. Each arm is ok-channel data, thus the tool never throws for a
+ * degraded condition. `examined` carries the console errors, the failed requests, and the page path. 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.
+ */
+export type ExaminePageResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "no-browser";
+    detail: string;
+} | {
+    outcome: "no-page";
+} | {
+    outcome: "missed-stamp";
+} | {
+    outcome: "capture-failed";
+    detail: string;
+} | {
+    outcome: "examined";
+    consoleErrors: string[];
+    failedRequests: FailedRequest[];
+    pagePath: string;
+};
+/**
+ * The construction deps of the eyes tool.
+ *
+ * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
+ * serves every analysis. `chrome` configures the headless browser, and the sidecar that it names must mount
+ * the workspace tree at the same path, because the tool navigates to a `file://` URL. `capture` is optional
+ * and defaults to the shared capture, thus a test injects a seam that reads no browser.
+ */
+export interface ExaminePageToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly chrome: ChromeConfig;
+    readonly capture?: CapturePage;
+    readonly logger?: Logger;
+}
+/**
+ * Make the eyes tool over the session-state gateway, the workspace-root seam, and the chrome config.
+ *
+ * The tool reads the thread id from the scope of the call, and it resolves the page path under the workspace
+ * root. Thus one factory serves every thread. The tool holds no per-session value.
+ */
+export declare function createExaminePageTool(deps: ExaminePageToolDeps): Tool<ExaminePageInput, ExaminePageResult>;

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

@@ -0,0 +1,136 @@
+/**
+ * The eyes tool of a report session.
+ *
+ * The tool opens the rendered page of a thread in headless Chrome, and it gives back what a reviewer would
+ * 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.
+ *
+ * The session tree has no URL space, thus 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 typed outcome, not a throw.
+ *
+ * The `file://` URL resolves on the filesystem of the Chrome sidecar, because the connection is out of
+ * process. Thus the sidecar must mount the workspace tree of the harness host at the same path. A sidecar
+ * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
+ *
+ * A composition that names no browser and injects no capture seam has no eyes at all. The tool reports that
+ * condition once, up front, and it stamps nothing. A per-attempt capture failure would instead read as a
+ * transient fault and invite a repeat of a call that can never pass.
+ *
+ * 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.
+ *
+ * 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,
+ * because a repeated look never stamps a marker that no preview wrote.
+ *
+ * The chrome navigation and the workspace-root seam each speak the throw protocol. The tool runs the capture
+ * inside a guard, thus a genuine fault becomes a typed outcome and a control-flow exception propagates.
+ */
+import { ok } from "neverthrow";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { hasBrowserUrl } from "../../lib/chrome.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { defaultErrorFields } from "../../lib/logger.js";
+import { capturePage } from "../../lib/page-capture.js";
+import { defineTool, withToolResultImage } 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({});
+/** The IANA media type of the screenshot. `page.screenshot` gives PNG bytes. */
+const SCREENSHOT_MEDIA_TYPE = "image/png";
+/** The line that the agent reads when the composition gives no browser. */
+const NO_BROWSER_DETAIL = "the composition gives no browser, thus this session cannot look at its page";
+/**
+ * Make the eyes tool over the session-state gateway, the workspace-root seam, and the chrome config.
+ *
+ * The tool reads the thread id from the scope of the call, and it resolves the page path under the workspace
+ * root. Thus one factory serves every thread. The tool holds no per-session value.
+ */
+export function createExaminePageTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("examine-page");
+    // An injected seam is the eyes of a test. A named browser is the eyes of a deployment. With neither, the
+    // composition has no eyes, and that answer is fixed at construction.
+    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
+    const capture = deps.capture ?? ((url) => capturePage(deps.chrome, url));
+    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 console errors, and the failed requests. " +
+            "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.",
+        inputSchema: examinePageInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (_input, ctx) => {
+            // 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.
+            if (!eyesAvailable) {
+                logger.warn("the composition gives no browser, thus no look can run");
+                return ok({ outcome: "no-browser", detail: NO_BROWSER_DETAIL });
+            }
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr()) {
+                return ok({ outcome: "refused", refusal: opened.error });
+            }
+            const { threadId, analysisId } = opened.value;
+            let root;
+            try {
+                root = deps.resolveWorkspaceRoot(analysisId);
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "capture-failed", detail: "the workspace root did not resolve" });
+            }
+            const relativePagePath = join("report-sessions", threadId, "index.html");
+            const pagePath = join(root, relativePagePath);
+            try {
+                await access(pagePath);
+            }
+            catch (cause) {
+                if (cause.code === "ENOENT") {
+                    // No preview wrote the page yet. The agent runs the preview first.
+                    return ok({ outcome: "no-page" });
+                }
+                logger.warn("the session page could not be read", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "capture-failed", detail: "the session page could not be read" });
+            }
+            let captured;
+            try {
+                captured = await capture(pathToFileURL(pagePath).href);
+            }
+            catch (cause) {
+                logger.warn("the page capture failed", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "capture-failed", detail: cause instanceof Error ? cause.message : String(cause) });
+            }
+            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
+                // repeated look never fixes this, because it copies a marker that no preview wrote. The agent
+                // runs a new preview, which stamps the rendered hash for the next look.
+                logger.warn("the seen stamp found no rendered hash", { threadId, analysisId });
+                return ok({ outcome: "missed-stamp" });
+            }
+            // A transient stamp fault and an absent row each leave the seen hash short, and the record gate
+            // then refuses a never-seen page. A later look re-stamps the marker, thus the picture stays valid
+            // and the tool gives it back.
+            if (stamped.outcome !== "stamped") {
+                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({
+                outcome: "examined",
+                consoleErrors: captured.consoleErrors,
+                failedRequests: captured.failedRequests,
+                pagePath: relativePagePath,
+            }, { base64: captured.screenshotBase64, mediaType: SCREENSHOT_MEDIA_TYPE }));
+        },
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The report-session tool barrel.
+ *
+ * These tools serve a `report` thread. The runtime constructs them over the session-state gateway and the
+ * render seams, thus each tool binds the per-session state to the thread of the call. The barrel exports
+ * the factories and their public types for the composition root.
+ */
+export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps } from "./preview-report.js";
+export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, } from "./examine-page.js";
+export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";

package/dist/tools/report-session/index.js

@@ -0,0 +1,10 @@
+/**
+ * The report-session tool barrel.
+ *
+ * These tools serve a `report` thread. The runtime constructs them over the session-state gateway and the
+ * render seams, thus each tool binds the per-session state to the thread of the call. The barrel exports
+ * the factories and their public types for the composition root.
+ */
+export { createPreviewReportTool } from "./preview-report.js";
+export { createExaminePageTool, } from "./examine-page.js";
+export { createRecordVersionTool } from "./record-version.js";