@inflexa-ai/harness 0.18.0 → 0.19.1

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

@@ -0,0 +1,105 @@
+/**
+ * The render-and-preview tool of a report session.
+ *
+ * The tool renders the current draft of a thread. It runs the finish first, because a mid-composition
+ * draft is not a `ReportDocument`. A gap list returns as data, and no render runs. On a pass the tool
+ * resolves each reference through the injected resolver, bridges the resolved values into the render model,
+ * and renders the page.
+ *
+ * The page and its staged image assets land in `report-sessions/{threadId}/` under the workspace root. That
+ * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
+ * trees. The result carries the absolute page path, thus a local host shows the page with no seam.
+ *
+ * The result carries no access grant. `PreviewPublisher` authorizes the URL space
+ * `previews/{analysisId}/{previewId}` (`contracts/content-url.ts`), and that space cannot name a page of
+ * 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 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";
+import { type ResolutionFailure } from "../../report-model/validate.js";
+import { type BridgeMismatch } from "../../report-render/value-bridge.js";
+import type { RenderProblem } from "../../report-render/types.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
+declare const previewReportInput: z.ZodObject<{}, z.core.$strip>;
+export type PreviewReportInput = z.infer<typeof previewReportInput>;
+/**
+ * The typed outcome of the preview tool. Each arm is ok-channel data, thus the tool never throws for a
+ * degraded condition. `rendered` carries the absolute page path.
+ */
+export type PreviewReportResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "gaps";
+    gaps: FinishGap[];
+} | {
+    outcome: "resolver-unavailable";
+} | {
+    outcome: "root-unresolvable";
+    detail: string;
+} | {
+    outcome: "unresolved-references";
+    unresolved: ResolutionFailure[];
+} | {
+    outcome: "bridge-mismatch";
+    mismatches: BridgeMismatch[];
+} | {
+    outcome: "render-problems";
+    problems: RenderProblem[];
+} | {
+    outcome: "figure-out-of-scope";
+    blockId: string;
+    path: string;
+} | {
+    outcome: "write-failed";
+    detail: string;
+} | {
+    outcome: "stamp-failed";
+    pagePath: string;
+    detail: string;
+} | {
+    outcome: "rendered";
+    pagePath: string;
+};
+/**
+ * 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. `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 makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly logger?: Logger;
+}
+/**
+ * Make the render-and-preview tool over the session-state gateway and the render seams.
+ *
+ * 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, and it resolves the root of the
+ * analysis of the call.
+ */
+export declare function createPreviewReportTool(deps: PreviewReportToolDeps): Tool<PreviewReportInput, PreviewReportResult>;
+export {};

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

@@ -0,0 +1,269 @@
+/**
+ * The render-and-preview tool of a report session.
+ *
+ * The tool renders the current draft of a thread. It runs the finish first, because a mid-composition
+ * draft is not a `ReportDocument`. A gap list returns as data, and no render runs. On a pass the tool
+ * resolves each reference through the injected resolver, bridges the resolved values into the render model,
+ * and renders the page.
+ *
+ * The page and its staged image assets land in `report-sessions/{threadId}/` under the workspace root. That
+ * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
+ * trees. The result carries the absolute page path, thus a local host shows the page with no seam.
+ *
+ * The result carries no access grant. `PreviewPublisher` authorizes the URL space
+ * `previews/{analysisId}/{previewId}` (`contracts/content-url.ts`), and that space cannot name a page of
+ * 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 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 { err, ok } from "neverthrow";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { z } from "zod";
+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";
+import { renderReportPage } from "../../report-render/render.js";
+import { defineTool } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
+const previewReportInput = z.object({});
+/**
+ * The staged file name of one bound image: its content hash with the original extension.
+ *
+ * The colon of the `algorithm:hex` hash is not safe in a file name and in a relative source, thus the slug
+ * replaces each non-word run with one dash. The hash is unique, thus two figures with one basename cannot
+ * collide on the staged name.
+ */
+function assetFileName(file) {
+    const slug = file.hash.replace(/[^a-z0-9]+/gi, "-");
+    return slug + extname(file.path);
+}
+/** The relative source of a staged figure. The page directory is self-contained, thus the source is `assets/<name>`. */
+function figureSourcePolicy(file) {
+    return `assets/${assetFileName(file)}`;
+}
+/**
+ * Pair each block with the resolved value of its binding, in document order.
+ *
+ * A value-bearing kind carries the resolved value of its one reference, looked up by the block id from
+ * the map that the resolution pass filled. A no-value kind carries none. Where a reference sits in a
+ * block is the knowledge of `block-walk.ts`, thus this walk reads the block id alone and never a binding
+ * field.
+ *
+ * The switch is exhaustive over the eight block kinds. A ninth kind reaches the end with no return, and
+ * the declared return type fails the build. Thus the walk cannot drop a kind in silence. A value-bearing
+ * block reaches here only when its reference resolved, because an unresolved reference short-circuits
+ * before this walk.
+ */
+function collectResolutions(blocks, resolvedByBlock) {
+    const resolutions = [];
+    const visit = (block) => {
+        switch (block.kind) {
+            case "section":
+                resolutions.push({ blockId: block.id, kind: "section" });
+                for (const child of block.blocks) {
+                    visit(child);
+                }
+                return;
+            case "text":
+            case "claim":
+            case "citation":
+                resolutions.push({ blockId: block.id, kind: block.kind });
+                return;
+            case "metric":
+            case "table":
+            case "chart":
+            case "figure": {
+                const resolved = resolvedByBlock.get(block.id);
+                if (resolved !== undefined) {
+                    resolutions.push({ blockId: block.id, kind: block.kind, resolved });
+                }
+                return;
+            }
+        }
+    };
+    for (const block of blocks) {
+        visit(block);
+    }
+    return resolutions;
+}
+/**
+ * Resolve each reference of the document, and split the resolutions from the unresolved references.
+ *
+ * The shared `resolveDocumentReferences` walks the tree, resolves each reference under the concurrency
+ * bound, and runs the chart-encoding match, thus the preview and the record gate refuse the same
+ * references. On a clean pass the resolutions map onto the render model in document order.
+ */
+async function resolveDocument(document, resolver, snapshot) {
+    const { resolvedByBlock, failures } = await resolveDocumentReferences(document.sections, snapshot, resolver);
+    if (failures.length > 0) {
+        return { resolutions: [], unresolved: failures };
+    }
+    return { resolutions: collectResolutions(document.sections, resolvedByBlock), unresolved: [] };
+}
+/**
+ * Resolve the page root, stage each bound image, and write the page.
+ *
+ * The workspace-root seam signals an unresolvable resource by a throw, thus the resolution sits inside
+ * the protection and its throw becomes a value. Each `fs` call runs through `tryFsWrite`, the one
+ * sanctioned `fs` guard, thus a genuine I/O fault becomes a value and a control-flow exception such as a
+ * cancellation propagates.
+ *
+ * A bound figure names a snapshot path, which is untrusted. A registered `../../` path escapes the root,
+ * thus the containment test runs before any copy and reuses the one workspace-path resolver. A source
+ * outside the root refuses and names the block, and no copy runs.
+ */
+async function renderToWorkspace(args) {
+    let root;
+    try {
+        root = args.resolveWorkspaceRoot(args.analysisId);
+    }
+    catch (cause) {
+        return err({ kind: "fs", error: { type: "read_failed", op: "preview.resolveWorkspaceRoot", path: args.analysisId, cause } });
+    }
+    const sessionDir = join(root, "report-sessions", args.threadId);
+    const assetsDir = join(sessionDir, "assets");
+    const pagePath = join(sessionDir, "index.html");
+    // Each bound figure, contained and deduplicated by its staged name, mapped to its host source.
+    const sources = new Map();
+    for (const resolution of args.resolutions) {
+        if (resolution.kind !== "figure" || resolution.resolved.type !== "file") {
+            continue;
+        }
+        const file = resolution.resolved;
+        const name = assetFileName(file);
+        if (sources.has(name)) {
+            continue;
+        }
+        const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId: args.analysisId, path: file.path });
+        if (resolved.kind !== "ok") {
+            return err({ kind: "figure-out-of-scope", blockId: resolution.blockId, path: file.path });
+        }
+        sources.set(name, resolved.absolute);
+    }
+    const madeSession = await tryFsWrite("preview.mkdir", () => mkdir(sessionDir, { recursive: true }), { path: sessionDir });
+    if (madeSession.isErr()) {
+        return err({ kind: "fs", error: madeSession.error });
+    }
+    if (sources.size > 0) {
+        const madeAssets = await tryFsWrite("preview.mkdir", () => mkdir(assetsDir, { recursive: true }), { path: assetsDir });
+        if (madeAssets.isErr()) {
+            return err({ kind: "fs", error: madeAssets.error });
+        }
+        for (const [name, source] of sources) {
+            const copied = await tryFsWrite("preview.copyFile", () => copyFile(source, join(assetsDir, name)), { path: source });
+            if (copied.isErr()) {
+                return err({ kind: "fs", error: copied.error });
+            }
+        }
+    }
+    const wrote = await tryFsWrite("preview.writeFile", () => writeFile(pagePath, args.page, "utf8"), { path: pagePath });
+    if (wrote.isErr()) {
+        return err({ kind: "fs", error: wrote.error });
+    }
+    return ok(pagePath);
+}
+/**
+ * Make the render-and-preview tool over the session-state gateway and the render seams.
+ *
+ * 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, and it resolves the root of the
+ * analysis of the call.
+ */
+export function createPreviewReportTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("preview-report");
+    return defineTool({
+        id: "preview_report",
+        description: "Render the current draft to a self-contained HTML page, and give back the page path. " +
+            "The tool finishes the draft first: an incomplete draft gives back the gap list, and no page renders. " +
+            "On a pass it resolves each reference, stages each bound image beside the page, and writes the page. " +
+            "Use it to see the report, and to confirm that each reference resolves.",
+        inputSchema: previewReportInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (_input, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr()) {
+                return ok({ outcome: "refused", refusal: opened.error });
+            }
+            const { threadId, analysisId, state } = opened.value;
+            const { document: draft, snapshot } = state;
+            const finished = finishDraft(draft, snapshot);
+            if (!finished.valid) {
+                return ok({ outcome: "gaps", gaps: finished.gaps });
+            }
+            const document = finished.document;
+            if (deps.makeResolver === undefined) {
+                return ok({ outcome: "resolver-unavailable" });
+            }
+            // 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 });
+            }
+            const bridged = bridgeValues(resolutions, figureSourcePolicy);
+            if (bridged.isErr()) {
+                return ok({ outcome: "bridge-mismatch", mismatches: bridged.error });
+            }
+            const rendered = renderReportPage(document, bridged.value);
+            if (rendered.isErr()) {
+                return ok({ outcome: "render-problems", problems: rendered.error });
+            }
+            const written = await renderToWorkspace({
+                resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+                analysisId,
+                threadId,
+                resolutions,
+                page: rendered.value,
+            });
+            if (written.isErr()) {
+                const failure = written.error;
+                if (failure.kind === "figure-out-of-scope") {
+                    // A bound figure names a path outside the workspace root. The record gate refuses the
+                    // same figure, thus the preview refuses it too and names the block.
+                    logger.warn("a bound figure escapes the workspace root", { threadId, analysisId, blockId: failure.blockId, path: failure.path });
+                    return ok({ outcome: "figure-out-of-scope", blockId: failure.blockId, path: failure.path });
+                }
+                // An unresolvable root, a full volume, and a denied write each arrive here as a value. The
+                // tool contract is ok-channel data for each degraded condition, thus the fault becomes an
+                // outcome. The log keeps the full fault, because the outcome carries the description alone.
+                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 {};

package/dist/tools/report-session/record-version.js

@@ -0,0 +1,139 @@
+/**
+ * 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 { ok } from "neverthrow";
+import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { describeDbError } from "../../lib/db-result.js";
+import { finishDraft } from "../../report-model/draft-finish.js";
+import { computeDraftHash } from "../../report-model/draft-hash.js";
+import { validateReport } from "../../report-model/validate.js";
+import { defineTool } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool records the current draft of the thread, thus it needs no field. */
+const recordVersionInput = z.object({});
+/** A short account of a record refusal, for the detail of a transient failure. */
+function describeRecordFailure(error) {
+    switch (error.type) {
+        case "malformed_document":
+            return "the gate accepted a document that the store read as malformed";
+        case "malformed_snapshot":
+            return "the pinned snapshot is malformed";
+        case "parent_analysis_mismatch":
+            return "the parent version belongs to a different analysis";
+        case "thread_already_holds_version":
+            return "the thread already holds a recorded version";
+        default:
+            return describeDbError(error);
+    }
+}
+/**
+ * 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 function createRecordVersionTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("record-report-version");
+    return defineTool({
+        id: "record_report_version",
+        description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
+            "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
+            "and a failed reference gives back the block that broke. The tool records a version only after the eyes look at the current page. " +
+            "A thread holds one version, thus a second record gives back that the thread already holds one.",
+        inputSchema: recordVersionInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (_input, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr()) {
+                return ok({ outcome: "refused", refusal: opened.error });
+            }
+            const { threadId, analysisId, state, seenDocumentHash } = opened.value;
+            const { document: draft, snapshot } = state;
+            const finished = finishDraft(draft, snapshot);
+            if (!finished.valid) {
+                return ok({ outcome: "gaps", gaps: finished.gaps });
+            }
+            // The look-before-record rule runs before the resolver and the validation, on the state that the
+            // load already read. The preview stamps the rendered hash, and the eyes copy it onto the seen
+            // hash. A never-seen page carries no seen hash. A stale look carries the hash of an earlier draft,
+            // thus a mismatch against the current draft refuses. Each refusal skips the expensive validation.
+            const currentHash = computeDraftHash(draft);
+            if (seenDocumentHash === null) {
+                return ok({ outcome: "never-seen" });
+            }
+            if (seenDocumentHash !== currentHash) {
+                return ok({ outcome: "stale-look" });
+            }
+            if (deps.makeResolver === undefined) {
+                return ok({ outcome: "resolver-unavailable" });
+            }
+            // 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, ...logger.errorFields(cause) });
+                return ok({ outcome: "root-unresolvable", detail: "the workspace root did not resolve" });
+            }
+            const validation = await validateReport(finished.document, snapshot, resolver);
+            if (!validation.valid) {
+                return ok({
+                    outcome: "invalid",
+                    ...(validation.schemaIssues ? { schemaIssues: validation.schemaIssues } : {}),
+                    ...(validation.duplicateIds ? { duplicateIds: validation.duplicateIds } : {}),
+                    ...(validation.resolutionFailures ? { resolutionFailures: validation.resolutionFailures } : {}),
+                });
+            }
+            const thread = await deps.threads.getThread(threadId);
+            if (thread.isErr()) {
+                logger.warn("the thread row read failed", { threadId, analysisId, ...logger.errorFields(thread.error.cause) });
+                return ok({ outcome: "record-failed", detail: describeDbError(thread.error) });
+            }
+            if (thread.value === null) {
+                logger.warn("the report thread row is absent at record", { threadId, analysisId });
+                return ok({ outcome: "record-failed", detail: "the report thread row is absent" });
+            }
+            const recorded = await deps.store.record({
+                document: finished.document,
+                snapshot,
+                analysisId,
+                threadId,
+                parentThreadId: thread.value.parentThreadId,
+                parentSeq: thread.value.parentSeq,
+            });
+            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId }), (error) => {
+                if (error.type === "thread_already_holds_version") {
+                    return ok({ outcome: "already-recorded" });
+                }
+                logger.warn("the version did not record", { threadId, analysisId, reason: error.type });
+                return ok({ outcome: "record-failed", detail: describeRecordFailure(error) });
+            });
+        },
+    });
+}

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

@@ -30,6 +30,7 @@ import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { DEFAULT_SALVAGE_ITERATIONS, runToTerminal } from "../../loop/run-to-terminal.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
+import { effectiveDeadlineMs } from "../../providers/types.js";
 import { defineTool } from "../define-tool.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
@@ -776,6 +777,7 @@ export function createGeneratePlanTool(deps) {
                 ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
                 ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
             ].join("\n");
+            const planTimeoutMs = effectiveDeadlineMs(deps.conversation.provider, PLAN_TIMEOUT_MS);
             // Opens the invocation. Two things are only knowable here and both are
             // first-order suspects when a planner runs long and returns nothing: the size
             // of the seed it was handed, and which of its blocks made it that size. The
@@ -788,7 +790,7 @@ export function createGeneratePlanTool(deps) {
                 model: deps.conversation.model,
                 maxIterations: PLANNER_MAX_ITERATIONS,
                 salvageIterations: DEFAULT_SALVAGE_ITERATIONS,
-                timeoutMs: PLAN_TIMEOUT_MS,
+                timeoutMs: planTimeoutMs,
                 grounding: grounding.kind,
                 ...(input.parentPlanId ? { parentPlanId: input.parentPlanId } : {}),
                 seedChars: {
@@ -818,7 +820,7 @@ export function createGeneratePlanTool(deps) {
             };
             // Merge the outer abort signal with a wall-clock timeout — either
             // cancels the planner promptly.
-            const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(PLAN_TIMEOUT_MS)]);
+            const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(planTimeoutMs)]);
             let runError = null;
             let run = null;
             try {

package/dist/tools/sandbox/list-available-packages.js

@@ -27,12 +27,13 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { LIBS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
 /**
  * Where the list lives when the host mounts the library store at the same path
  * the sandbox does. Hosts that do not — the store is baked into the image and
  * never bind-mounted — inject their own path instead.
  */
-const DEFAULT_PACKAGES_FILE = "/mnt/libs/current/packages.txt";
+const DEFAULT_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/current/packages.txt`;
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
  * The shipped catalog is ~270 packages (~3 KB, well under a thousand tokens), so