@inflexa-ai/harness 0.19.0 → 0.19.1

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

@@ -157,15 +157,20 @@ export interface ReportSessionState {
  */
 export type SessionStateToken = DraftDocument | null;
 /**
- * The outcome of a gateway load. `found` carries the state, the analysis that owns the thread, and the
- * concurrency token. `absent` and `wrong-type` are permanent conditions, and `failed` is a transient fault
- * that names its cause.
+ * The outcome of a gateway load. `found` carries the state, the analysis that owns the thread, the
+ * concurrency token, and the seen-document hash of the look-before-record rule. `absent` and `wrong-type`
+ * are permanent conditions, and `failed` is a transient fault that names its cause.
+ *
+ * `seenDocumentHash` is the hash that the last eyes capture saw, or `null` before the first look. The record
+ * tool compares it against the hash of the current draft, thus a never-seen page and a stale look each
+ * refuse.
  */
 export type SessionStateLoad = {
     outcome: "found";
     state: ReportSessionState;
     analysisId: string;
     token: SessionStateToken;
+    seenDocumentHash: string | null;
 } | {
     outcome: "absent";
 } | {
@@ -184,6 +189,35 @@ export type SessionStatePersist = {
     outcome: "failed";
     detail: string;
 };
+/**
+ * The outcome of a gateway stamp. `stamped` wrote the marker. `absent` means that no row holds the thread.
+ * `failed` is a transient store fault that names its cause. Each arm is plain data, thus a stamp never
+ * throws for one of them.
+ */
+export type StampResult = {
+    outcome: "stamped";
+} | {
+    outcome: "absent";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/**
+ * The outcome of the seen stamp through the gateway. `stamped` copied a rendered hash onto the seen hash.
+ * `no-rendered` means that the row holds no rendered hash to copy, thus no preview stamped one. `absent`
+ * means that no row holds the thread. `failed` is a transient store fault that names its cause. Each arm is
+ * plain data, thus a stamp never throws for one of them.
+ */
+export type SeenStampResult = {
+    outcome: "stamped";
+} | {
+    outcome: "no-rendered";
+} | {
+    outcome: "absent";
+} | {
+    outcome: "failed";
+    detail: string;
+};
 /**
  * The session-state gateway that the tools read and write.
  *
@@ -195,13 +229,29 @@ export type SessionStatePersist = {
 export interface ReportSessionStateGateway {
     load(threadId: string): Promise<SessionStateLoad>;
     persist(threadId: string, document: DraftDocument, expected: SessionStateToken): Promise<SessionStatePersist>;
+    /**
+     * Stamp the hash of the rendered draft on the session state. The preview calls it when the page lands,
+     * thus the runtime knows which draft the page shows.
+     */
+    stampRendered(threadId: string, hash: string): Promise<StampResult>;
+    /**
+     * Copy the rendered hash onto the seen hash. The eyes call it after a capture, thus the seen hash holds
+     * the hash of the draft that the picture shows, and never the current one. The outcome names whether a
+     * rendered hash existed to copy, thus the eyes tell a real stamp from a missed one.
+     */
+    stampSeen(threadId: string): Promise<SeenStampResult>;
 }
-/** The thread of a call, its analysis, the loaded state, and the concurrency token that the persist compares against. */
+/**
+ * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
+ * against, and the seen-document hash of the look-before-record rule.
+ */
 export interface OpenedThread {
     readonly threadId: string;
     readonly analysisId: string;
     readonly state: ReportSessionState;
     readonly token: SessionStateToken;
+    /** The hash that the last eyes capture saw, or `null` before the first look. */
+    readonly seenDocumentHash: string | null;
 }
 /**
  * Resolve the report thread of a call, and load its state through the gateway.

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

@@ -119,7 +119,7 @@ export async function openReportThread(gateway, scope) {
             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 });
+    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) {

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

@@ -6,3 +6,5 @@
  * 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

@@ -6,3 +6,5 @@
  * 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";

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

@@ -15,14 +15,18 @@
  * this tree. A hosted view of a session page is a later capability, with a URL space of its own.
  *
  * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
- * absence, an unresolved reference, a bridge mismatch, a render problem, a figure that escapes the
- * workspace root, and a write failure. The tool never throws for one of them. The filesystem speaks the
+ * absence, an unresolvable root at resolver construction, an unresolved reference, a bridge mismatch, a
+ * render problem, a figure that escapes the workspace root, a write failure, and a stamp failure. The tool
+ * never throws for one of them. When the page
+ * lands, the tool stamps the hash of the rendered draft on the session state, thus the eyes and the record
+ * know which draft the page shows. The filesystem speaks the
  * throw protocol, and the workspace-root seam signals an unresolvable resource the same way. Thus the
  * write runs through the `tryFs` glue, which turns a genuine fault into the ok-channel outcome and lets a
  * control-flow exception propagate.
  */
 import { z } from "zod";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import type { AuthContext } from "../../auth/types.js";
 import { type Logger } from "../../lib/logger.js";
 import { type FinishGap } from "../../report-model/draft-finish.js";
 import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
@@ -46,6 +50,9 @@ export type PreviewReportResult = {
     gaps: FinishGap[];
 } | {
     outcome: "resolver-unavailable";
+} | {
+    outcome: "root-unresolvable";
+    detail: string;
 } | {
     outcome: "unresolved-references";
     unresolved: ResolutionFailure[];
@@ -62,6 +69,10 @@ export type PreviewReportResult = {
 } | {
     outcome: "write-failed";
     detail: string;
+} | {
+    outcome: "stamp-failed";
+    pagePath: string;
+    detail: string;
 } | {
     outcome: "rendered";
     pagePath: string;
@@ -70,12 +81,16 @@ export type PreviewReportResult = {
  * The construction deps of the preview tool.
  *
  * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
- * serves every analysis and it resolves the root per call from the scope. `resolver` is optional, because a
- * resolver realization can be absent.
+ * serves every analysis and it resolves the root per call from the scope. `makeResolver` is optional, because
+ * a resolver realization can be absent. It binds one analysis, thus the tool makes the resolver over the
+ * scope of the call.
  */
 export interface PreviewReportToolDeps {
     readonly gateway: ReportSessionStateGateway;
-    readonly resolver?: ReferenceResolver;
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly logger?: Logger;
 }

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

@@ -15,8 +15,11 @@
  * this tree. A hosted view of a session page is a later capability, with a URL space of its own.
  *
  * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
- * absence, an unresolved reference, a bridge mismatch, a render problem, a figure that escapes the
- * workspace root, and a write failure. The tool never throws for one of them. The filesystem speaks the
+ * absence, an unresolvable root at resolver construction, an unresolved reference, a bridge mismatch, a
+ * render problem, a figure that escapes the workspace root, a write failure, and a stamp failure. The tool
+ * never throws for one of them. When the page
+ * lands, the tool stamps the hash of the rendered draft on the session state, thus the eyes and the record
+ * know which draft the page shows. The filesystem speaks the
  * throw protocol, and the workspace-root seam signals an unresolvable resource the same way. Thus the
  * write runs through the `tryFs` glue, which turns a genuine fault into the ok-channel outcome and lets a
  * control-flow exception propagate.
@@ -29,6 +32,7 @@ import { resolveWorkspacePath } from "../../workspace/paths.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
 import { defaultErrorFields } from "../../lib/logger.js";
+import { computeDraftHash } from "../../report-model/draft-hash.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
 import { resolveDocumentReferences } from "../../report-model/validate.js";
 import { bridgeValues } from "../../report-render/value-bridge.js";
@@ -203,10 +207,21 @@ export function createPreviewReportTool(deps) {
                 return ok({ outcome: "gaps", gaps: finished.gaps });
             }
             const document = finished.document;
-            if (deps.resolver === undefined) {
+            if (deps.makeResolver === undefined) {
                 return ok({ outcome: "resolver-unavailable" });
             }
-            const { resolutions, unresolved } = await resolveDocument(document, deps.resolver, snapshot);
+            // The resolver construction resolves the workspace root inside, and that seam throws on an
+            // unresolvable root. The guard turns the throw into a typed outcome that names the fault, thus a
+            // control-flow exception propagates and the unresolvable root does not.
+            let resolver;
+            try {
+                resolver = deps.makeResolver({ analysisId, auth: ctx.session.auth });
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "root-unresolvable", detail: "the workspace root did not resolve" });
+            }
+            const { resolutions, unresolved } = await resolveDocument(document, resolver, snapshot);
             if (unresolved.length > 0) {
                 return ok({ outcome: "unresolved-references", unresolved });
             }
@@ -239,6 +254,15 @@ export function createPreviewReportTool(deps) {
                 logger.warn("the page did not land", { threadId, analysisId, ...defaultErrorFields(failure.error.cause) });
                 return ok({ outcome: "write-failed", detail: describeFsError(failure.error) });
             }
+            // The page shows the draft that the finish read. The stamp records that draft, thus the eyes
+            // copy this hash and the record compares against it. A failed stamp is a transient store fault,
+            // and the page stays on disk. The agent runs the preview again to stamp the marker.
+            const stamped = await deps.gateway.stampRendered(threadId, computeDraftHash(draft));
+            if (stamped.outcome !== "stamped") {
+                const detail = stamped.outcome === "failed" ? stamped.detail : "the session state row is absent";
+                logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
+                return ok({ outcome: "stamp-failed", pagePath: written.value, detail });
+            }
             return ok({ outcome: "rendered", pagePath: written.value });
         },
     });

package/dist/tools/report-session/record-version.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The record tool of a report session.
+ *
+ * The tool records one version of the report. The store is append-only with no delete, thus a version that
+ * the gate did not accept must never exist. The tool runs the whole gate first, and only a pass reaches the
+ * store.
+ *
+ * The gate has three parts, in order of cost. The finish gates the schema, the unique ids, and the
+ * structural tier, and a gap list returns as data. The look-before-record rule then compares the seen hash
+ * against the hash of the current draft, on the state that the load already read. A never-seen page and a
+ * stale look each refuse with a distinct reason, and the rule reads no model judgment. The full validation
+ * resolves every reference through the injected resolver, matches each chart encoding, and matches each
+ * assert. A failure names the block that holds the failed part, thus the agent repairs one block and not the
+ * report at large.
+ *
+ * The look runs before the validation on purpose. The validation builds the resolver and its prepare pass
+ * can start a container, thus the cheap look guards the expensive pass. A never-seen or stale draft refuses
+ * before the resolver constructs.
+ *
+ * On a pass the store records the document that the gate validated, the pinned snapshot, and the anchor from
+ * the thread row. The one-per-thread rule of the store bounds a concurrent race, and that refusal returns as
+ * data. The outcome of a pass carries the version id.
+ */
+import { z } from "zod";
+import type { AuthContext } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import type { ThreadStore } from "../../memory/thread-store.js";
+import { type FinishGap } from "../../report-model/draft-finish.js";
+import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
+import { type ResolutionFailure, type SchemaIssue } from "../../report-model/validate.js";
+import type { ReportVersionStore } from "../../state/report-versions.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool records the current draft of the thread, thus it needs no field. */
+declare const recordVersionInput: z.ZodObject<{}, z.core.$strip>;
+export type RecordVersionInput = z.infer<typeof recordVersionInput>;
+/**
+ * The typed outcome of the record tool. Each arm is ok-channel data, thus the tool never throws for a
+ * degraded condition.
+ *
+ * `gaps` names each completeness gap of the draft. `never-seen` means that no eyes ran on the current draft.
+ * `stale-look` means that the eyes ran, and the agent then changed the draft. `root-unresolvable` means that
+ * the resolver construction cannot resolve the workspace root. `invalid` names each gate failure, and a
+ * resolution failure carries the block that holds it. `already-recorded` means that the thread already holds
+ * a version. `recorded` carries the version id.
+ */
+export type RecordVersionResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "gaps";
+    gaps: FinishGap[];
+} | {
+    outcome: "never-seen";
+} | {
+    outcome: "stale-look";
+} | {
+    outcome: "resolver-unavailable";
+} | {
+    outcome: "root-unresolvable";
+    detail: string;
+} | {
+    outcome: "invalid";
+    schemaIssues?: SchemaIssue[];
+    duplicateIds?: string[];
+    resolutionFailures?: ResolutionFailure[];
+} | {
+    outcome: "already-recorded";
+} | {
+    outcome: "record-failed";
+    detail: string;
+} | {
+    outcome: "recorded";
+    versionId: string;
+};
+/**
+ * The construction deps of the record tool.
+ *
+ * `store` is the append-only version store. `threads` reads the anchor of the report thread, thus the
+ * version carries the parent conversation and the transcript position. `makeResolver` is optional, because a
+ * resolver realization can be absent, and the gate needs one. It binds one analysis, thus the tool makes the
+ * resolver over the scope of the call.
+ */
+export interface RecordVersionToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly store: ReportVersionStore;
+    readonly threads: Pick<ThreadStore, "getThread">;
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
+    readonly logger?: Logger;
+}
+/**
+ * Make the record tool over the session-state gateway, the version store, the thread store, and the
+ * resolver.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the state through the gateway. Thus
+ * one factory serves every thread. The tool holds no per-session value.
+ */
+export declare function createRecordVersionTool(deps: RecordVersionToolDeps): Tool<RecordVersionInput, RecordVersionResult>;
+export {};