@inflexa-ai/harness 0.18.0 → 0.19.1

package/dist/report-model/reference-resolver.d.ts

@@ -17,7 +17,7 @@ import type { Reference, UnresolvedReference } from "../contracts/report-referen
  *
  * `rows` is optional because an image is pinned by its hash alone and holds no cells. An empty array in
  * that position would say that the artifact holds zero rows, which is a different and false claim. The
- * mint never populates `rows`. `rows` serves the fixture realization only, and that realization resolves
+ * pin never populates `rows`. `rows` serves the fixture realization only, and that realization resolves
  * from the snapshot itself. A production snapshot pins identity, and a value comes from a read of the
  * artifact.
  *
@@ -71,9 +71,15 @@ export type ResolvedValue = {
  * The `Ok` channel carries the resolved value. The `Err` channel carries the `UnresolvedReference`,
  * which names the reason and the detail that a reference did not bind. The validator collects each such
  * `Err` into its report, thus a caller reads the reason as data and resolution never throws.
+ *
+ * `prepare` is an optional batch step that runs one time before the per-reference loop. A realization
+ * that reads storage groups the references by artifact, reads each file one time, and fills a cache.
+ * `resolve` then answers from the cache. The method is optional, thus a realization without it keeps the
+ * per-reference behavior and the extension breaks no caller.
  */
 export interface ReferenceResolver {
     resolve(reference: Reference, snapshot: ReportSnapshot): Promise<Result<ResolvedValue, UnresolvedReference>>;
+    prepare?(references: readonly Reference[], snapshot: ReportSnapshot): Promise<void>;
 }
 /**
  * Give back each name in `columns` that no row holds, in the order of `columns`.

package/dist/report-model/validate.d.ts

@@ -8,9 +8,16 @@
  * each reference against the pinned evidence, and it warns about a free numeral in prose.
  */
 import type { UnresolvedReference } from "../contracts/report-reference.js";
-import { type ReportWarning } from "./block-walk.js";
-import { type ReferenceResolver, type ReportSnapshot } from "./reference-resolver.js";
+import { type AnyBlock, type CollectedReference, type ReportWarning } from "./block-walk.js";
+import { type ReferenceResolver, type ReportSnapshot, type ResolvedValue } from "./reference-resolver.js";
 export type { ReportWarning };
+/**
+ * The cap on how many references resolve at the same time.
+ *
+ * A production resolver reads storage for each reference, and a large report holds hundreds of them. An
+ * unbounded fan-out would open one read for each reference at the same moment.
+ */
+export declare const RESOLUTION_CONCURRENCY = 8;
 /** One schema conformance problem, reduced to a path and a message. */
 export interface SchemaIssue {
     path: string;
@@ -36,5 +43,30 @@ export type ReportValidation = {
     resolutionFailures?: ResolutionFailure[];
     warnings: ReportWarning[];
 };
+/**
+ * Match each column that a chart encoding names against the table that its binding resolved to.
+ *
+ * The binding schema admits a table reference only, thus a resolved value of another type means that the
+ * bound resolver broke its own contract. That is reported and never ignored, because a chart with no
+ * table behind it renders nothing and a silent skip would pass it as grounded.
+ */
+export declare function checkChartEncoding(entry: CollectedReference, value: ResolvedValue): UnresolvedReference | undefined;
+/** The resolved values and the failures of one resolution pass over the references of a block tree. */
+export interface ReferenceResolution {
+    /** The resolved value of each block whose reference resolved, keyed by its block id. */
+    resolvedByBlock: Map<string, ResolvedValue>;
+    /** Each reference that did not resolve, or whose chart encoding named an absent column. */
+    failures: ResolutionFailure[];
+}
+/**
+ * Resolve each reference of a block tree under the concurrency bound, and run the chart-encoding match.
+ *
+ * The walk collects each reference one time, `allWithConcurrency` bounds the fan-out, and
+ * `checkChartEncoding` catches a chart that plots a column which the bound table does not hold. The record
+ * gate and the preview share this one pass, thus the two refuse the same references. A value-bearing block
+ * whose reference resolved carries its value in the map. A claim or a citation reference reads no value
+ * from the map. The walk collects every failure, thus a reviewer sees each block that broke.
+ */
+export declare function resolveDocumentReferences(sections: readonly AnyBlock[], snapshot: ReportSnapshot, resolver: ReferenceResolver): Promise<ReferenceResolution>;
 /** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
 export declare function validateReport(document: unknown, snapshot: ReportSnapshot, resolver: ReferenceResolver): Promise<ReportValidation>;

package/dist/report-model/validate.js

@@ -17,7 +17,7 @@ import { columnsHeldByNoRow } from "./reference-resolver.js";
  * A production resolver reads storage for each reference, and a large report holds hundreds of them. An
  * unbounded fan-out would open one read for each reference at the same moment.
  */
-const RESOLUTION_CONCURRENCY = 8;
+export const RESOLUTION_CONCURRENCY = 8;
 /**
  * Match each column that a chart encoding names against the table that its binding resolved to.
  *
@@ -25,7 +25,7 @@ const RESOLUTION_CONCURRENCY = 8;
  * bound resolver broke its own contract. That is reported and never ignored, because a chart with no
  * table behind it renders nothing and a silent skip would pass it as grounded.
  */
-function checkChartEncoding(entry, value) {
+export function checkChartEncoding(entry, value) {
     const encodingColumns = entry.encodingColumns;
     if (encodingColumns === undefined || encodingColumns.length === 0) {
         return undefined;
@@ -43,31 +43,51 @@ function checkChartEncoding(entry, value) {
         detail: `the encoding names column ${absent.join(", ")}, which the bound table does not hold`,
     };
 }
-/** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
-export async function validateReport(document, snapshot, resolver) {
-    const parsed = ReportDocumentSchema.safeParse(document);
-    if (!parsed.success) {
-        const schemaIssues = parsed.error.issues.map((issue) => ({
-            path: issue.path.map((segment) => String(segment)).join("."),
-            message: issue.message,
-        }));
-        return { valid: false, schemaIssues, warnings: [] };
+/**
+ * Resolve each reference of a block tree under the concurrency bound, and run the chart-encoding match.
+ *
+ * The walk collects each reference one time, `allWithConcurrency` bounds the fan-out, and
+ * `checkChartEncoding` catches a chart that plots a column which the bound table does not hold. The record
+ * gate and the preview share this one pass, thus the two refuse the same references. A value-bearing block
+ * whose reference resolved carries its value in the map. A claim or a citation reference reads no value
+ * from the map. The walk collects every failure, thus a reviewer sees each block that broke.
+ */
+export async function resolveDocumentReferences(sections, snapshot, resolver) {
+    const { references } = walkBlocks(sections);
+    // A realization that reads storage batches its reads here, one time before the loop. It fills a cache
+    // that each `resolve` then answers from. A realization without `prepare` keeps the per-reference read.
+    if (resolver.prepare !== undefined) {
+        await resolver.prepare(references.map((entry) => entry.reference), snapshot);
     }
-    const { references, repeatedIds, warnings } = walkBlocks(parsed.data.sections);
     const resolved = await allWithConcurrency(references.map((entry) => () => resolver.resolve(entry.reference, snapshot).then((result) => ({ entry, result }))), RESOLUTION_CONCURRENCY);
-    // Collect every failure. A reviewer must see each block that broke, thus the walk does not stop at
-    // the first unresolved reference. The `Err` channel carries the unresolved reference itself.
-    const resolutionFailures = [];
+    const failures = [];
+    const resolvedByBlock = new Map();
     for (const { entry, result } of resolved) {
         if (result.isErr()) {
-            resolutionFailures.push({ blockId: entry.blockId, failure: result.error });
+            failures.push({ blockId: entry.blockId, failure: result.error });
             continue;
         }
         const encodingFailure = checkChartEncoding(entry, result.value);
         if (encodingFailure !== undefined) {
-            resolutionFailures.push({ blockId: entry.blockId, failure: encodingFailure });
+            failures.push({ blockId: entry.blockId, failure: encodingFailure });
+            continue;
         }
+        resolvedByBlock.set(entry.blockId, result.value);
+    }
+    return { resolvedByBlock, failures };
+}
+/** Resolve each reference, collect the schema conformance and the resolution outcomes, and warn on prose. */
+export async function validateReport(document, snapshot, resolver) {
+    const parsed = ReportDocumentSchema.safeParse(document);
+    if (!parsed.success) {
+        const schemaIssues = parsed.error.issues.map((issue) => ({
+            path: issue.path.map((segment) => String(segment)).join("."),
+            message: issue.message,
+        }));
+        return { valid: false, schemaIssues, warnings: [] };
     }
+    const { repeatedIds, warnings } = walkBlocks(parsed.data.sections);
+    const { failures: resolutionFailures } = await resolveDocumentReferences(parsed.data.sections, snapshot, resolver);
     if (repeatedIds.length > 0 || resolutionFailures.length > 0) {
         return {
             valid: false,

package/dist/report-render/page.d.ts

@@ -118,10 +118,33 @@ export declare const ECHARTS_THEME: {
         };
     };
 };
+/**
+ * The name of the readiness event, and the name of the window sentinel that guards a late listener. The
+ * bootstrap below emits both names, thus this module owns them. A capture that waits for the page reads the
+ * same two constants, thus the emitter and the waiter cannot disagree over a rename.
+ */
+export declare const THEME_READY_EVENT = "inflexa-theme-ready";
+export declare const THEME_READY_SENTINEL = "__inflexaThemeReady";
+/**
+ * The navigation budget and the readiness budget of one page capture, in milliseconds. The readiness budget
+ * bounds the wait for the event that the bootstrap dispatches. Every capture of this page reads the same two
+ * budgets, thus two capture sites cannot drift apart.
+ */
+export declare const PAGE_NAV_TIMEOUT_MS = 20000;
+export declare const PAGE_READY_TIMEOUT_MS = 8000;
 /**
  * The page-side script that wires each chart. It finds every chart container, reads the option JSON from
  * the sibling `<script type="application/json">` element, and initializes ECharts with the registered
  * theme. The skeleton registers the theme before this script runs. A resize handler keeps each chart
  * fit to the window.
+ *
+ * The script signals readiness when the bootstrap completes, and immediately when no chart exists. It sets
+ * the `window.__inflexaThemeReady` sentinel and dispatches the `inflexa-theme-ready` event on the document.
+ * A reader that captures the page keys on this signal, thus the capture returns when the page is ready and
+ * not at a timeout. The sentinel guards a listener that registers after the dispatch, thus a late listener
+ * still resolves.
+ *
+ * Each chart initializes inside a guard. One malformed option is exactly the fault that a look must
+ * diagnose, thus it must never stop a sibling chart and it must never withhold the readiness signal.
  */
 export declare const CHART_BOOTSTRAP: string;

package/dist/report-render/page.js

@@ -274,14 +274,42 @@ export const ECHARTS_THEME = {
         splitLine: { lineStyle: { color: "#f1f5f9", type: "dashed" } },
     },
 };
+/**
+ * The name of the readiness event, and the name of the window sentinel that guards a late listener. The
+ * bootstrap below emits both names, thus this module owns them. A capture that waits for the page reads the
+ * same two constants, thus the emitter and the waiter cannot disagree over a rename.
+ */
+export const THEME_READY_EVENT = "inflexa-theme-ready";
+export const THEME_READY_SENTINEL = "__inflexaThemeReady";
+/**
+ * The navigation budget and the readiness budget of one page capture, in milliseconds. The readiness budget
+ * bounds the wait for the event that the bootstrap dispatches. Every capture of this page reads the same two
+ * budgets, thus two capture sites cannot drift apart.
+ */
+export const PAGE_NAV_TIMEOUT_MS = 20_000;
+export const PAGE_READY_TIMEOUT_MS = 8_000;
 /**
  * The page-side script that wires each chart. It finds every chart container, reads the option JSON from
  * the sibling `<script type="application/json">` element, and initializes ECharts with the registered
  * theme. The skeleton registers the theme before this script runs. A resize handler keeps each chart
  * fit to the window.
+ *
+ * The script signals readiness when the bootstrap completes, and immediately when no chart exists. It sets
+ * the `window.__inflexaThemeReady` sentinel and dispatches the `inflexa-theme-ready` event on the document.
+ * A reader that captures the page keys on this signal, thus the capture returns when the page is ready and
+ * not at a timeout. The sentinel guards a listener that registers after the dispatch, thus a late listener
+ * still resolves.
+ *
+ * Each chart initializes inside a guard. One malformed option is exactly the fault that a look must
+ * diagnose, thus it must never stop a sibling chart and it must never withhold the readiness signal.
  */
 export const CHART_BOOTSTRAP = `(function () {
+  function signalReady() {
+    window.${THEME_READY_SENTINEL} = true;
+    document.dispatchEvent(new Event(${JSON.stringify(THEME_READY_EVENT)}));
+  }
   if (typeof echarts === "undefined") {
+    signalReady();
     return;
   }
   var containers = document.querySelectorAll("[data-echarts-id]");
@@ -291,9 +319,13 @@ export const CHART_BOOTSTRAP = `(function () {
     if (!optionScript || optionScript.getAttribute("type") !== "application/json") {
       continue;
     }
-    var option = JSON.parse(optionScript.textContent || "{}");
-    var chart = echarts.init(container, ${JSON.stringify(ECHARTS_THEME_NAME)});
-    chart.setOption(option);
+    try {
+      var option = JSON.parse(optionScript.textContent || "{}");
+      var chart = echarts.init(container, ${JSON.stringify(ECHARTS_THEME_NAME)});
+      chart.setOption(option);
+    } catch (cause) {
+      console.error("chart bootstrap failed for " + (container.getAttribute("data-echarts-id") || "(no id)") + ": " + (cause && cause.message ? cause.message : cause));
+    }
   }
   window.addEventListener("resize", function () {
     var nodes = document.querySelectorAll("[data-echarts-id]");
@@ -304,4 +336,5 @@ export const CHART_BOOTSTRAP = `(function () {
       }
     }
   });
+  signalReady();
 })();`;

package/dist/report-render/value-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { type Result } from "neverthrow";
+import type { ResolvedValue } from "../report-model/reference-resolver.js";
+import type { RenderValues } from "./types.js";
+/** The block kinds that carry no render value. Each one renders from the block and the ledger alone. */
+type NoValueKind = "text" | "claim" | "citation" | "section";
+/** The block kinds that carry one render value under the block id in the map. */
+type ValueBearingKind = "metric" | "table" | "chart" | "figure";
+/** The file echo that a figure binding resolves to: a whole-file pin of a path and a hash. */
+export type ResolvedFile = Extract<ResolvedValue, {
+    type: "file";
+}>;
+/** The policy that turns a resolved file echo into a figure `src` string. The caller owns the policy. */
+export type FigureSourcePolicy = (file: ResolvedFile) => string;
+/**
+ * The resolution result of one block: the block id, the block kind, and the resolved value of its binding.
+ *
+ * A value-bearing kind carries the resolved value. A no-value kind carries none, thus a text block with
+ * no binding is representable and a value on it is not.
+ */
+export type BlockResolution = {
+    blockId: string;
+    kind: NoValueKind;
+} | {
+    blockId: string;
+    kind: ValueBearingKind;
+    resolved: ResolvedValue;
+};
+/**
+ * One typed mismatch between a block kind and a resolved value type. `blockId` names the block, and
+ * `blockKind` names the kind that sets the expectation. `expected` names the resolved type that the kind
+ * needs, and `actual` names the resolved type that arrived.
+ */
+export interface BridgeMismatch {
+    blockId: string;
+    blockKind: ValueBearingKind;
+    expected: ResolvedValue["type"];
+    actual: ResolvedValue["type"];
+}
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export declare function bridgeValues(resolutions: readonly BlockResolution[], figureSrc: FigureSourcePolicy): Result<RenderValues, BridgeMismatch[]>;
+export {};

package/dist/report-render/value-bridge.js

@@ -0,0 +1,82 @@
+/**
+ * The value bridge: a resolved value maps onto a render value, keyed by block id.
+ *
+ * The resolver gives one `ResolvedValue` for each reference. The renderer takes a `RenderValues` map. The
+ * two models agree on a scalar, a table, and a citation, but they part on a figure. A `ResolvedValue`
+ * file echo carries a path and a hash, and a page needs a source string. Thus the bridge takes a
+ * caller-supplied policy that turns a file echo into a `src` string. The preview tool gives the concrete
+ * policy, because the page directory and its asset access are a session concern.
+ *
+ * The bridge is pure. It reads no file, it resolves no reference, and it imports nothing from the state
+ * layer or the tool layer. A block kind that carries no render value maps to no entry. A block kind whose
+ * resolved value has the wrong type becomes one typed mismatch. The bridge collects every mismatch, thus
+ * one call reports each fault at one time.
+ */
+import { err, ok } from "neverthrow";
+/**
+ * Map the resolved values of the blocks onto a `RenderValues` map.
+ *
+ * The bridge walks each resolution in order. A no-value kind adds no entry. A value-bearing kind whose
+ * resolved type matches adds one entry. A value-bearing kind whose resolved type does not match adds one
+ * mismatch. A run with a mismatch returns the mismatch list and no map. A run with no mismatch returns the
+ * complete map.
+ */
+export function bridgeValues(resolutions, figureSrc) {
+    const values = {};
+    const mismatches = [];
+    for (const resolution of resolutions) {
+        switch (resolution.kind) {
+            case "text":
+            case "claim":
+            case "citation":
+            case "section":
+                break;
+            case "metric": {
+                const value = resolution.resolved;
+                if (value.type !== "scalar") {
+                    mismatches.push(mismatch(resolution.blockId, "metric", "scalar", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "scalar", value: value.value };
+                break;
+            }
+            case "table":
+            case "chart": {
+                const value = resolution.resolved;
+                if (value.type !== "table") {
+                    mismatches.push(mismatch(resolution.blockId, resolution.kind, "table", value.type));
+                    break;
+                }
+                values[resolution.blockId] = tableValue(value);
+                break;
+            }
+            case "figure": {
+                const value = resolution.resolved;
+                if (value.type !== "file") {
+                    mismatches.push(mismatch(resolution.blockId, "figure", "file", value.type));
+                    break;
+                }
+                values[resolution.blockId] = { type: "figure", src: figureSrc(value) };
+                break;
+            }
+        }
+    }
+    if (mismatches.length > 0) {
+        return err(mismatches);
+    }
+    return ok(values);
+}
+/**
+ * Map a resolved table onto a render table. The explicit column order carries through when it is present,
+ * and it stays absent otherwise, thus the renderer keeps its first-row order as the default.
+ */
+function tableValue(value) {
+    if (value.columns !== undefined) {
+        return { type: "table", rows: value.rows, columns: value.columns };
+    }
+    return { type: "table", rows: value.rows };
+}
+/** Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that arrived. */
+function mismatch(blockId, blockKind, expected, actual) {
+    return { blockId, blockKind, expected, actual };
+}

package/dist/runtime/assemble.d.ts

@@ -16,6 +16,7 @@
  */
 import { type Result } from "neverthrow";
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import { type ReportSessionRuntime } from "../app/report-session-runtime.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
@@ -24,8 +25,11 @@ import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalys
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
+import { type ExtractValuesResult, type ExtractValuesWorkflowInput } from "../tasks/extract-values.js";
 import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
+import type { AuthContext } from "../auth/types.js";
+import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
@@ -53,6 +57,7 @@ export interface RegisteredWorkflows {
     readonly sandboxStep: SandboxStepCallable;
     readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
+    readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, and
@@ -61,6 +66,19 @@ export interface RegisteredWorkflows {
  * workflows see, or a recorder that only half the agent tree reports to.
  */
 export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver">;
+/**
+ * What binds one reference resolver: the analysis whose pinned artifacts it reads, and the auth of the tool
+ * call that reads them. A resolver serves one analysis, thus the report tools build one for each call.
+ */
+export interface ReportResolverScope {
+    readonly analysisId: string;
+    readonly auth: AuthContext;
+}
+/**
+ * The factory that gives the reference resolver of one report tool call. The harness wires the production
+ * realization, and an embedder can bind its own at its composition root.
+ */
+export type MakeReportReferenceResolver = (scope: ReportResolverScope) => ReferenceResolver;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -78,6 +96,20 @@ export interface CoreRuntimeDeps {
     readonly usageRecorder?: UsageRecorder;
     /** Harness-owned citation capability configuration; no ambient lookup occurs. */
     readonly citationResolverConfig?: CitationResolverConfig;
+    /**
+     * The byte cap on the in-process host read of a report reference. A file over the
+     * cap falls through to the extraction arm. Absent, the resolver uses its 16 MiB
+     * default. The embedder tunes it here, thus a host changes it with no harness change.
+     */
+    readonly reportHostReadCapBytes?: number;
+    /**
+     * The report reference resolver of an embedder. A managed host reads its pinned
+     * artifacts from its own store, thus it binds a realization of the seam here and the
+     * report tools resolve through it. Absent, the harness wires the production resolver
+     * over the workspace tree and the extraction arm, which is the whole OSS path. A bound
+     * factory replaces that wiring, thus `reportHostReadCapBytes` then governs nothing.
+     */
+    readonly makeReportReferenceResolver?: MakeReportReferenceResolver;
 }
 /**
  * The refusal a thread type carries no agent yet. `report` is a valid
@@ -120,6 +152,13 @@ export interface CoreRuntime {
      * on the `Result` channel.
      */
     readonly agents: ThreadAgentResolver;
+    /**
+     * The turn-start anchor of a report session. A serving path runs it at the
+     * turn start, thus a report tool call never arrives before the session state
+     * exists. The gateway stays behind the tool boundary, thus the runtime exposes
+     * the anchor operation alone here, and a later change wires it at the turn start.
+     */
+    readonly reportSession: Pick<ReportSessionRuntime, "ensureSessionState">;
     readonly workflows: RegisteredWorkflows;
     readonly citationResolver: CitationResolver;
 }

package/dist/runtime/assemble.js

@@ -16,12 +16,18 @@
  */
 import { err, ok } from "neverthrow";
 import { createConversationAgent } from "../agents/conversation-agent.js";
+import { createReportSessionAgent } from "../agents/report-session-agent.js";
+import { createReportSessionRuntime } from "../app/report-session-runtime.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
+import { bindExtractionTrigger, createExtractionArm, registerExtractValuesWorkflow, } from "../tasks/extract-values.js";
 import { createCitationResolver } from "../citations/resolve.js";
+import { createThreadStore } from "../memory/thread-store.js";
+import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
+import { createReportVersionStore } from "../state/report-versions.js";
 const _assertDomainError = true;
 /**
  * Wrap a type→agent registry as the resolution surface. Held apart from
@@ -60,6 +66,14 @@ export function assembleCoreRuntime(deps) {
     const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
     const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
     const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
+    // The extraction workflow shares the profile's sandbox and authorization rails, thus it draws the same
+    // three seams from the profile deps. The report resolver factory binds the extraction arm over this
+    // callable, thus a fall-through report reference reads its file out of process on the profile rails.
+    const extractValues = registerExtractValuesWorkflow({
+        sandboxClient: wf.dataProfile.sandboxClient,
+        runAuthorizer: wf.dataProfile.runAuthorizer,
+        ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
+    });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
@@ -67,22 +81,69 @@ export function assembleCoreRuntime(deps) {
         usageRecorder,
         citationResolver,
     });
-    // The single registration point for every typed agent. One entry today; a
-    // future thread type's agent plugs in here at assembly with no embedder
-    // change. `conversation` is required at the type level because boot resolves
-    // it unconditionally (`boot.ts` backfill) — a dropped registration must fail
-    // tsc here, not surface only as a boot-time throw. The `Partial` over the
-    // rest keeps the compiler honest that `report` has no agent yet.
+    // The report agent is a singleton over the conversation deps. The session
+    // runtime binds the per-session state to the thread behind the tool boundary,
+    // thus one definition serves every report thread. Its preview tool writes the
+    // page into the analysis tree and returns the path, thus the page write reaches
+    // no host seam.
+    const reportSession = createReportSessionRuntime({ pool: conversation.pool, ...(conversation.logger ? { logger: conversation.logger } : {}) });
+    const reportVersionStore = createReportVersionStore({ pool: conversation.pool, ...(conversation.logger ? { logger: conversation.logger } : {}) });
+    const reportThreads = createThreadStore(conversation.pool);
+    // The read cache of the production report path, one for each recent analysis. A preview
+    // and the record that follows it are two tool calls over one draft, thus they meet the
+    // same artifacts. The store carries the streamed hash and the extracted rows between
+    // them, and each resolver still binds its own extraction arm below. Thus the auth of a
+    // call never outlives the call, and one unchanged file costs one hash and one container.
+    const reportArtifactReads = createArtifactReadStore();
+    // The reference resolver of the report path, and its production wiring. A resolver reads
+    // the pinned artifacts of one analysis, thus the factory binds one analysis and one auth
+    // for each tool call. The extraction arm falls through to the registered extract-values
+    // callable for an over-cap file or a host parse fault. The cap gates the host read, and
+    // the resolver defaults it to 16 MiB.
+    const makeProductionReportResolver = (scope) => {
+        const arm = createExtractionArm(bindExtractionTrigger({ runAuthorizer: conversation.runAuthorizer, workflow: extractValues }, { auth: scope.auth, analysisId: scope.analysisId }));
+        return createProductionResolver({
+            workspaceRoot: conversation.resolveWorkspaceRoot(scope.analysisId),
+            analysisId: scope.analysisId,
+            extractionArm: arm,
+            readCache: reportArtifactReads.forAnalysis(scope.analysisId),
+            ...(deps.reportHostReadCapBytes !== undefined ? { cap: deps.reportHostReadCapBytes } : {}),
+        });
+    };
+    const makeReportResolver = deps.makeReportReferenceResolver ?? makeProductionReportResolver;
+    const reportAgent = createReportSessionAgent({
+        model: conversation.model,
+        pool: conversation.pool,
+        embedding: conversation.embedding,
+        workspaceFs: conversation.workspaceFs,
+        gateway: reportSession.gateway,
+        resolveWorkspaceRoot: conversation.resolveWorkspaceRoot,
+        store: reportVersionStore,
+        threads: reportThreads,
+        chrome: conversation.chrome,
+        makeResolver: makeReportResolver,
+        ...(conversation.logger ? { logger: conversation.logger } : {}),
+    });
+    // The single registration point for every typed agent. A future thread type's
+    // agent plugs in here at assembly with no embedder change. `conversation` is
+    // required at the type level because boot resolves it unconditionally
+    // (`boot.ts` backfill). `report` is required now that its agent registers here,
+    // so a dropped registration fails tsc, and it does not surface only as a
+    // resolution refusal. The `Partial` over the rest keeps the compiler honest
+    // about a type that has no agent yet.
     const agents = {
         conversation: conversationAgent,
+        report: reportAgent,
     };
     return {
         agents: createThreadAgentResolver(agents),
+        reportSession: { ensureSessionState: reportSession.ensureSessionState },
         workflows: {
             executeAnalysis,
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
+            extractValues,
         },
         citationResolver,
     };

package/dist/sandbox/mount-plan.d.ts

@@ -17,6 +17,13 @@
  * (see {@link buildSessionSubPaths}).
  */
 export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "logs", "notebooks"];
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export declare const LIBS_CONTAINER_PATH = "/mnt/libs";
+export declare const REFS_CONTAINER_PATH = "/mnt/refs";
 export interface MountPlanCoords {
     analysisId: string;
     runId: string;

package/dist/sandbox/mount-plan.js

@@ -18,8 +18,13 @@
  */
 import { assertSafeId } from "../workspace/paths.js";
 export const STEP_SUBDIRS = ["output", "scripts", "figures", "logs", "notebooks"];
-const LIBS_CONTAINER_PATH = "/mnt/libs";
-const REFS_CONTAINER_PATH = "/mnt/refs";
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export const LIBS_CONTAINER_PATH = "/mnt/libs";
+export const REFS_CONTAINER_PATH = "/mnt/refs";
 /**
  * The step tail beneath an analysis's workspace root, in both container and
  * PVC-relative space. The harness owns this layout (workspace-layout spec).