@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/report-render/views/values.d.ts

@@ -1,16 +1,57 @@
 /**
- * The value markup: the metric card, the data table, the figure, and the inline citation.
+ * The value markup: the metric card, the data table, the figure, and the citation card.
+ *
+ * The citation card is the bibliography entry of its source. It carries the one link of the page body,
+ * which is a navigation to PubMed, thus the page loads nothing from a remote host.
  *
  * The caller resolves each value, and it narrows the value to the shape that the block needs. The runtime
  * escapes every interpolated string, thus a hostile label, a hostile cell, a hostile caption, or a
- * hostile source reaches the page as text.
+ * hostile source reaches the page as text. The `title` attribute takes the same escape as every other
+ * attribute value, thus the full digits cannot break out of their slot.
+ *
+ * A number reaches the page through the number format. A table cell takes the meaning that the binding
+ * declares for its column, and the column name answers for a column that declares none. A metric takes its
+ * label, because a value locator declares no column-wide meaning.
+ *
+ * A table card carries the grid mount and the download of the raw pinned bytes. The rows and the display of
+ * each column ride a data asset beside the page, and the page script builds the grid over them. Thus the
+ * markup carries no row, and `tableDisplay` gives the page what the server resolved for each column.
+ *
+ * Each card marks its binding in the shared ledger, thus every evidentiary block carries a marker and an
+ * appendix entry. A reference that two blocks share keeps one number and one entry.
  *
  * Each data card carries the `corner-accents` class. Thus the card keeps square corners with the L-shaped
  * accents, which is the geometric identity of the report.
  */
 import type { CitationBlock, FigureBlock, MetricBlock, TableBlock } from "../../contracts/report-blocks.js";
-import type { ReferenceLedger } from "../references.js";
+import { type ArtifactTableReference } from "../../contracts/report-reference.js";
+import type { CitationRecord } from "../../report-model/reference-resolver.js";
+import { type ReferenceLedger } from "../references.js";
+import type { ColumnDisplay } from "../table-data.js";
 import type { RenderValue } from "../types.js";
+/**
+ * The attribute that marks the grid mount of a table card, and that names the block of its data.
+ *
+ * The page script reads the same attribute, thus the card and the boot cannot disagree over a rename.
+ */
+export declare const GRID_MOUNT_ATTRIBUTE = "data-report-grid";
+/**
+ * The class of the print note of a table card.
+ *
+ * The note is empty on the screen. The page script writes the bound of a truncated print form into it at
+ * print time, and it clears the text after. The page script reads the same class, thus the card and the
+ * boot cannot disagree over a rename.
+ */
+export declare const GRID_NOTE_CLASS = "report-grid-note";
+/**
+ * The class of the row count of a table card.
+ *
+ * The renderer writes the count of the resolved rows, and the page script writes it again after each filter.
+ * The page script reads the same class, thus the card and the boot cannot disagree over a rename.
+ */
+export declare const GRID_COUNT_CLASS = "report-table-count";
+/** The word that follows a row count, in the status line of the card and in the print note alike. */
+export declare const GRID_ROWS_WORD = "rows";
 /** The scalar value that a metric renders from. */
 type ScalarValue = Extract<RenderValue, {
     type: "scalar";
@@ -23,8 +64,20 @@ type TableValue = Extract<RenderValue, {
 type FigureValue = Extract<RenderValue, {
     type: "figure";
 }>;
-/** Render a metric block as a stat card with the mono value and the mono label. */
-export declare function renderMetric(block: MetricBlock, value: ScalarValue): string;
+/**
+ * Render a metric block as a stat card with the mono value and the mono label.
+ *
+ * The label names the value, thus it selects the number kind. The full digits ride the `title` attribute
+ * when the shown form hides one, and no attribute appears at any other time.
+ *
+ * A metric reads one cell and it has no column, thus no neighbor bounds a zero here. A zero under a
+ * p-value label reads as the near-zero form.
+ *
+ * The value binding joins the reference ladder, thus the label line carries the marker and the appendix
+ * names the cell. The marker sits on the label and never on the value, because the value line is the one
+ * figure that a reader takes from the card.
+ */
+export declare function renderMetric(block: MetricBlock, ledger: ReferenceLedger, value: ScalarValue): string;
 /**
  * Wrap a run of stat cards in one responsive grid. The caller renders each card first, and it passes the
  * markup as one already-escaped string, thus `raw()` inserts it byte for byte. The grid carries its own
@@ -32,20 +85,82 @@ export declare function renderMetric(block: MetricBlock, value: ScalarValue): st
  */
 export declare function renderMetricGrid(cardsHtml: string): string;
 /**
- * Render a table block. The header holds one cell for each column, and the body holds one row for each
- * resolved row. A zero-row table renders the header alone. The title and the caption render only when the
- * block carries one. An absent cell renders as an empty cell, thus a ragged row keeps its shape.
+ * The column order of a table. The value columns win when they are present. The keys of the first row
+ * give the order otherwise, in first-appearance order.
+ *
+ * The header of the card and the payload of the data asset both read this order. Thus the position of a
+ * cell in an encoded row names the column of its header.
+ */
+export declare function tableColumns(value: TableValue): string[];
+/**
+ * The display of each column of a table, in the column order of the header.
+ *
+ * The renderer resolves the label, the number kind, the filter, and the bound of a stored zero one time for
+ * each column, and the data asset ships them. Thus the page formats a cell with no read of a declaration
+ * and no second pass over a column.
+ *
+ * The argument is the binding and not the block, because a chart binds the same whole-table reference. A
+ * chart that reads the shared payload then resolves its columns through this one helper.
+ *
+ * The filter reads the cells and not the kind. A column of gene names carries no number, thus it takes the
+ * text filter and a reader finds a gene by its name. A column where one cell parses takes the number filter.
+ *
+ * A probability column carries the smallest positive value of its own rows as the bound. A column with no
+ * positive value takes no bound, and its zero then reads as the near-zero form.
+ */
+export declare function tableDisplay(binding: ArtifactTableReference, value: TableValue, columns: readonly string[]): ColumnDisplay[];
+/**
+ * The status of a table card: the shown count against the pre-bound total of the artifact.
+ *
+ * A bound cut the rows, thus the shown count and the total differ and the line names both. A whole table
+ * shows every row that it holds, thus the line states the one count. The page script writes the same two
+ * forms after each filter, thus the first paint and every later one read alike.
  */
-export declare function renderTable(block: TableBlock, value: TableValue): string;
+export declare function tableStatusText(shown: number, total: number): string;
+/**
+ * Render a table block as the grid mount and the download of its raw bytes.
+ *
+ * The rows ride a data asset beside the page. A page that stamped 14,201 rows into its markup weighed
+ * megabytes, and each row was a copy of the column names. Thus the markup holds one empty mount, and the
+ * page script builds the grid over the payload that registers under the block id.
+ *
+ * The mount names its block in the mount attribute. A mount whose block the registry does not hold stays
+ * empty, thus the card keeps its title, its status, and its download, and the page throws nothing.
+ *
+ * The footer holds one status line and the download button. The status states the count of the resolved
+ * rows against the pre-bound total of the artifact, and the row bound of the binding beside it. The page
+ * script writes the count again after each filter, thus a reader of a narrowed table sees what the grid
+ * shows and what the artifact holds.
+ *
+ * The note under the status stays empty on the screen. A print of a table that passes the print bound writes
+ * the bound into it, thus the paper states what it shows and what it leaves out.
+ *
+ * The download names the staged copy of the pinned artifact. The link is relative and the browser saves
+ * the file, thus the page fetches nothing when it opens and the reader still gets the whole table.
+ *
+ * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
+ * appendix names the artifact. Every evidentiary block ledgers this way, and a card with no title still
+ * shows its marker on the same line.
+ */
+export declare function renderTable(block: TableBlock, ledger: ReferenceLedger, rowCount: number, total?: number): string;
 /**
  * Render a figure block as a corner-accent card. The source rides the `src` attribute, and the caption
  * renders below the image. The caption also fills the `alt` attribute, thus the escape keeps a hostile
  * source and a hostile caption inside their slots.
+ *
+ * The whole-file binding joins the reference ladder, thus the caption line carries the marker and the
+ * appendix names the image. A figure with no caption still shows its marker on that line. The marker stays
+ * out of the `alt` text, because a screen reader reads the alt as the picture and not as a footnote.
  */
-export declare function renderFigure(block: FigureBlock, value: FigureValue): string;
+export declare function renderFigure(block: FigureBlock, ledger: ReferenceLedger, value: FigureValue): string;
 /**
- * Render a citation block as a card in the reference form. The binding joins the ledger like a claim
- * binding, thus one shared source keeps one number. The optional note renders after the marker.
+ * Render a citation block as a bibliography card. The binding joins the one reference ladder like a claim
+ * binding, thus one shared source keeps one bracket number. The card shows the marker, the short citation
+ * of the pinned record, the optional note, and the citation key.
+ *
+ * The short citation of a `pmid:` record carries the PubMed link of its identifier. A key of another
+ * identifier space shows the citation as text. A key with no pinned record shows the key and the note
+ * alone, because absence is a normal condition and no text stands in for the paper.
  */
-export declare function renderCitation(block: CitationBlock, ledger: ReferenceLedger): string;
+export declare function renderCitation(block: CitationBlock, ledger: ReferenceLedger, record?: CitationRecord): string;
 export {};

package/dist/report-render/views/values.js

@@ -1,19 +1,77 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "hono/jsx/jsx-runtime";
 /**
- * The value markup: the metric card, the data table, the figure, and the inline citation.
+ * The value markup: the metric card, the data table, the figure, and the citation card.
+ *
+ * The citation card is the bibliography entry of its source. It carries the one link of the page body,
+ * which is a navigation to PubMed, thus the page loads nothing from a remote host.
  *
  * The caller resolves each value, and it narrows the value to the shape that the block needs. The runtime
  * escapes every interpolated string, thus a hostile label, a hostile cell, a hostile caption, or a
- * hostile source reaches the page as text.
+ * hostile source reaches the page as text. The `title` attribute takes the same escape as every other
+ * attribute value, thus the full digits cannot break out of their slot.
+ *
+ * A number reaches the page through the number format. A table cell takes the meaning that the binding
+ * declares for its column, and the column name answers for a column that declares none. A metric takes its
+ * label, because a value locator declares no column-wide meaning.
+ *
+ * A table card carries the grid mount and the download of the raw pinned bytes. The rows and the display of
+ * each column ride a data asset beside the page, and the page script builds the grid over them. Thus the
+ * markup carries no row, and `tableDisplay` gives the page what the server resolved for each column.
+ *
+ * Each card marks its binding in the shared ledger, thus every evidentiary block carries a marker and an
+ * appendix entry. A reference that two blocks share keeps one number and one entry.
  *
  * Each data card carries the `corner-accents` class. Thus the card keeps square corners with the L-shaped
  * accents, which is the geometric identity of the report.
  */
 import { raw } from "hono/html";
+import { declaredForColumn } from "../../contracts/report-reference.js";
+import { stagedSource, tableSidecarName } from "../assets.js";
 import { Marker } from "./references-view.js";
-/** Render a metric block as a stat card with the mono value and the mono label. */
-export function renderMetric(block, value) {
-    return String(_jsxs("div", { class: "stat-card corner-accents", children: [_jsx("div", { class: "stat-card-value", children: value.value }), _jsx("div", { class: "stat-card-label", children: block.label })] }));
+import { formatNumberCell, formatTableCell, holdsANumber, selectColumnKind, selectNumberKind, smallestPositiveValue } from "../number-format.js";
+import { citationKeyOf } from "../references.js";
+/**
+ * The attribute that marks the grid mount of a table card, and that names the block of its data.
+ *
+ * The page script reads the same attribute, thus the card and the boot cannot disagree over a rename.
+ */
+export const GRID_MOUNT_ATTRIBUTE = "data-report-grid";
+/**
+ * The class of the print note of a table card.
+ *
+ * The note is empty on the screen. The page script writes the bound of a truncated print form into it at
+ * print time, and it clears the text after. The page script reads the same class, thus the card and the
+ * boot cannot disagree over a rename.
+ */
+export const GRID_NOTE_CLASS = "report-grid-note";
+/**
+ * The class of the row count of a table card.
+ *
+ * The renderer writes the count of the resolved rows, and the page script writes it again after each filter.
+ * The page script reads the same class, thus the card and the boot cannot disagree over a rename.
+ */
+export const GRID_COUNT_CLASS = "report-table-count";
+/** The word that follows a row count, in the status line of the card and in the print note alike. */
+export const GRID_ROWS_WORD = "rows";
+/** The label of the download button of a table card, without the format of the file. */
+const DOWNLOAD_LABEL = "Download";
+/**
+ * Render a metric block as a stat card with the mono value and the mono label.
+ *
+ * The label names the value, thus it selects the number kind. The full digits ride the `title` attribute
+ * when the shown form hides one, and no attribute appears at any other time.
+ *
+ * A metric reads one cell and it has no column, thus no neighbor bounds a zero here. A zero under a
+ * p-value label reads as the near-zero form.
+ *
+ * The value binding joins the reference ladder, thus the label line carries the marker and the appendix
+ * names the cell. The marker sits on the label and never on the value, because the value line is the one
+ * figure that a reader takes from the card.
+ */
+export function renderMetric(block, ledger, value) {
+    const n = ledger.mark(block.value);
+    const shown = formatNumberCell(value.value, selectNumberKind(block.label, value.value));
+    return String(_jsxs("div", { class: "stat-card corner-accents", children: [_jsx("div", { class: "stat-card-value", title: shown.full, children: shown.text }), _jsxs("div", { class: "stat-card-label", children: [block.label, _jsx(Marker, { n: n })] })] }));
 }
 /**
  * Wrap a run of stat cards in one responsive grid. The caller renders each card first, and it passes the
@@ -26,8 +84,11 @@ export function renderMetricGrid(cardsHtml) {
 /**
  * The column order of a table. The value columns win when they are present. The keys of the first row
  * give the order otherwise, in first-appearance order.
+ *
+ * The header of the card and the payload of the data asset both read this order. Thus the position of a
+ * cell in an encoded row names the column of its header.
  */
-function tableColumns(value) {
+export function tableColumns(value) {
     if (value.columns !== undefined) {
         return value.columns;
     }
@@ -35,28 +96,148 @@ function tableColumns(value) {
     return first !== undefined ? Object.keys(first) : [];
 }
 /**
- * Render a table block. The header holds one cell for each column, and the body holds one row for each
- * resolved row. A zero-row table renders the header alone. The title and the caption render only when the
- * block carries one. An absent cell renders as an empty cell, thus a ragged row keeps its shape.
+ * The header label of one column.
+ *
+ * A declared label names what the column measures. A column with no label prettifies, thus an underscore
+ * reads as a space. The page compares the label against the raw name, and it puts the raw name on the
+ * header hover where the two differ.
+ */
+function columnLabel(column, labels) {
+    return declaredForColumn(labels, column) ?? column.replaceAll("_", " ");
+}
+/**
+ * The display of each column of a table, in the column order of the header.
+ *
+ * The renderer resolves the label, the number kind, the filter, and the bound of a stored zero one time for
+ * each column, and the data asset ships them. Thus the page formats a cell with no read of a declaration
+ * and no second pass over a column.
+ *
+ * The argument is the binding and not the block, because a chart binds the same whole-table reference. A
+ * chart that reads the shared payload then resolves its columns through this one helper.
+ *
+ * The filter reads the cells and not the kind. A column of gene names carries no number, thus it takes the
+ * text filter and a reader finds a gene by its name. A column where one cell parses takes the number filter.
+ *
+ * A probability column carries the smallest positive value of its own rows as the bound. A column with no
+ * positive value takes no bound, and its zero then reads as the near-zero form.
+ */
+export function tableDisplay(binding, value, columns) {
+    return columns.map((column) => {
+        // One pass over the column serves the filter and the bound alike, thus a wide table reads no column
+        // twice.
+        const cells = value.rows.map((row) => row[column]);
+        const kind = selectColumnKind(column, declaredForColumn(binding.columnMeanings, column));
+        const label = columnLabel(column, binding.columnLabels);
+        const filter = holdsANumber(cells) ? "number" : "text";
+        if (kind !== "scientific") {
+            return { label, kind, filter };
+        }
+        const bound = smallestPositiveValue(cells);
+        return bound === undefined ? { label, kind, filter } : { label, kind, filter, bound };
+    });
+}
+/**
+ * The label of the download button: the word and the format of the pinned file, for example `Download CSV`.
+ *
+ * The extension of the path names the format, thus the label states what the reader gets. A path with no
+ * extension gives the word alone, because a made-up format would be a claim about bytes that nobody read.
+ */
+function downloadLabel(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    const format = dot > 0 ? base.slice(dot + 1).toUpperCase() : "";
+    return format === "" ? DOWNLOAD_LABEL : `${DOWNLOAD_LABEL} ${format}`;
+}
+/**
+ * The row bound of a binding as text, for example `top 20 by padj`, or `undefined` where the binding carries
+ * none.
+ *
+ * The bound is what the resolution kept, thus the status line states it beside the count and a reader never
+ * reads a cut table as the whole artifact. The rank direction names the end that the bound kept.
  */
-export function renderTable(block, value) {
-    const columns = tableColumns(value);
-    return String(_jsxs("div", { class: "report-table", children: [block.title !== undefined ? _jsx("div", { class: "report-table-title", children: block.title }) : null, _jsx("div", { class: "corner-accents", children: _jsx("div", { class: "data-table-scroll", children: _jsxs("table", { class: "data-table", children: [_jsx("thead", { children: _jsx("tr", { children: columns.map((column) => (_jsx("th", { children: column }))) }) }), _jsx("tbody", { children: value.rows.map((row) => (_jsx("tr", { class: "report-row", children: columns.map((column) => (_jsx("td", { children: row[column] }))) }))) })] }) }) }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
+function boundText(binding) {
+    const bound = binding.rowBound;
+    if (bound === undefined) {
+        return undefined;
+    }
+    const end = bound.order === "asc" ? "lowest" : "top";
+    const count = formatTableCell(bound.count, "compact-scientific");
+    return `${end} ${count} by ${columnLabel(bound.column, binding.columnLabels)}`;
+}
+/**
+ * The status of a table card: the shown count against the pre-bound total of the artifact.
+ *
+ * A bound cut the rows, thus the shown count and the total differ and the line names both. A whole table
+ * shows every row that it holds, thus the line states the one count. The page script writes the same two
+ * forms after each filter, thus the first paint and every later one read alike.
+ */
+export function tableStatusText(shown, total) {
+    const whole = `${formatTableCell(total, "compact-scientific")} ${GRID_ROWS_WORD}`;
+    return shown === total ? whole : `${formatTableCell(shown, "compact-scientific")} of ${whole}`;
+}
+/**
+ * Render a table block as the grid mount and the download of its raw bytes.
+ *
+ * The rows ride a data asset beside the page. A page that stamped 14,201 rows into its markup weighed
+ * megabytes, and each row was a copy of the column names. Thus the markup holds one empty mount, and the
+ * page script builds the grid over the payload that registers under the block id.
+ *
+ * The mount names its block in the mount attribute. A mount whose block the registry does not hold stays
+ * empty, thus the card keeps its title, its status, and its download, and the page throws nothing.
+ *
+ * The footer holds one status line and the download button. The status states the count of the resolved
+ * rows against the pre-bound total of the artifact, and the row bound of the binding beside it. The page
+ * script writes the count again after each filter, thus a reader of a narrowed table sees what the grid
+ * shows and what the artifact holds.
+ *
+ * The note under the status stays empty on the screen. A print of a table that passes the print bound writes
+ * the bound into it, thus the paper states what it shows and what it leaves out.
+ *
+ * The download names the staged copy of the pinned artifact. The link is relative and the browser saves
+ * the file, thus the page fetches nothing when it opens and the reader still gets the whole table.
+ *
+ * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
+ * appendix names the artifact. Every evidentiary block ledgers this way, and a card with no title still
+ * shows its marker on the same line.
+ */
+export function renderTable(block, ledger, rowCount, total) {
+    const binding = block.binding;
+    const n = ledger.mark(binding);
+    const download = tableSidecarName(binding.hash, binding.path);
+    const bound = boundText(binding);
+    return String(_jsxs("div", { class: "report-table", children: [_jsxs("div", { class: "report-table-title", children: [block.title, _jsx(Marker, { n: n })] }), _jsxs("div", { class: "corner-accents", children: [_jsx("div", { class: "report-grid", [GRID_MOUNT_ATTRIBUTE]: block.id }), _jsxs("div", { class: "report-table-footer", children: [_jsxs("div", { class: "report-table-footer-row", children: [_jsxs("span", { class: "report-table-status", children: [_jsx("span", { class: GRID_COUNT_CLASS, children: tableStatusText(rowCount, total ?? rowCount) }), bound !== undefined ? _jsx("span", { class: "report-table-bound", children: bound }) : null] }), _jsx("a", { class: "report-table-download", href: stagedSource(download), download: download, children: downloadLabel(binding.path) })] }), _jsx("div", { class: GRID_NOTE_CLASS })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
 }
 /**
  * Render a figure block as a corner-accent card. The source rides the `src` attribute, and the caption
  * renders below the image. The caption also fills the `alt` attribute, thus the escape keeps a hostile
  * source and a hostile caption inside their slots.
+ *
+ * The whole-file binding joins the reference ladder, thus the caption line carries the marker and the
+ * appendix names the image. A figure with no caption still shows its marker on that line. The marker stays
+ * out of the `alt` text, because a screen reader reads the alt as the picture and not as a footnote.
  */
-export function renderFigure(block, value) {
+export function renderFigure(block, ledger, value) {
+    const n = ledger.mark(block.binding);
     const caption = block.caption;
-    return String(_jsxs("figure", { class: "report-figure corner-accents", children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), caption !== undefined ? _jsx("figcaption", { class: "report-caption", children: caption }) : null] }));
+    return String(_jsxs("figure", { class: "report-figure corner-accents", children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), _jsxs("figcaption", { class: "report-caption", children: [caption, _jsx(Marker, { n: n })] })] }));
 }
 /**
- * Render a citation block as a card in the reference form. The binding joins the ledger like a claim
- * binding, thus one shared source keeps one number. The optional note renders after the marker.
+ * The PubMed address of one identifier. The address is deterministic, and an anchor loads nothing, thus a
+ * page with such a link still stands alone.
+ */
+const PUBMED_BASE = "https://pubmed.ncbi.nlm.nih.gov/";
+/**
+ * Render a citation block as a bibliography card. The binding joins the one reference ladder like a claim
+ * binding, thus one shared source keeps one bracket number. The card shows the marker, the short citation
+ * of the pinned record, the optional note, and the citation key.
+ *
+ * The short citation of a `pmid:` record carries the PubMed link of its identifier. A key of another
+ * identifier space shows the citation as text. A key with no pinned record shows the key and the note
+ * alone, because absence is a normal condition and no text stands in for the paper.
  */
-export function renderCitation(block, ledger) {
+export function renderCitation(block, ledger, record) {
     const n = ledger.mark(block.binding);
-    return String(_jsxs("div", { class: "report-citation corner-accents", children: [_jsx(Marker, { n: n }), block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null] }));
+    const binding = block.binding;
+    const key = citationKeyOf(binding);
+    return String(_jsxs("div", { class: "report-citation corner-accents", children: [_jsx(Marker, { n: n }), record !== undefined ? (_jsxs(_Fragment, { children: [" ", binding.idKind === "pmid" ? (_jsx("a", { class: "report-citation-source", href: `${PUBMED_BASE}${encodeURIComponent(binding.id)}/`, children: record.citation })) : (_jsx("span", { class: "report-citation-source", children: record.citation }))] })) : null, block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null, " ", _jsx("span", { class: "report-citation-key", children: key })] }));
 }

package/dist/runtime/assemble.d.ts

@@ -20,6 +20,8 @@ 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";
+import { type ChromeConfig } from "../lib/chrome.js";
+import { type AcquireEyes } from "../lib/eyes.js";
 import type { ThreadType } from "../memory/thread-store.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
@@ -61,12 +63,22 @@ export interface RegisteredWorkflows {
     readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
 }
 /**
- * Conversation-agent deps minus the workflow callable, the resource policy, and
- * the usage recorder — `assembleCoreRuntime` supplies those itself so a caller
- * cannot wire a stale callable, a policy that diverges from the one the
- * workflows see, or a recorder that only half the agent tree reports to.
+ * Conversation-agent deps minus the workflow callable, the resource policy, the
+ * usage recorder, the report-session anchor, and the eyes.
+ * `assembleCoreRuntime` supplies each of those itself. Thus a caller cannot wire
+ * one of these five values:
+ *
+ * - a stale callable
+ * - a policy that diverges from the one the workflows see
+ * - a recorder that only half the agent tree reports to
+ * - an anchor over a different session runtime
+ * - a seam that only half the agent tree looks through
+ *
+ * The assembly resolves the eyes one time, from `CoreRuntimeDeps.eyes` and the
+ * chrome config. A caller that bound the eyes here would give the conversation
+ * agent a seam that the report agent never sees.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes">;
 /**
  * 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.
@@ -120,6 +132,15 @@ export interface CoreRuntimeDeps {
      * materializes them to disk and binds its own lookup here.
      */
     readonly resolveReportPageAsset?: ResolvePageAsset;
+    /**
+     * The eyes of a report session — where a browser comes from for one look at the rendered
+     * page. A host with no standing sidecar starts a browser for one look. Thus it binds its own
+     * realization here, and the harness keeps every page behavior. Absent, the assembly wraps a
+     * chrome config that names a browser into the static realization. Thus a composition that
+     * names a standing sidecar changes nothing. A composition with neither route has no eyes, and
+     * the eyes tool of a report session then reports that condition.
+     */
+    readonly eyes?: AcquireEyes;
 }
 /**
  * The refusal a thread type carries no agent yet. `report` is a valid
@@ -172,4 +193,17 @@ export interface CoreRuntime {
     readonly workflows: RegisteredWorkflows;
     readonly citationResolver: CitationResolver;
 }
+/**
+ * The eyes of the composition, or none.
+ *
+ * A seam that the embedder bound answers first. Otherwise a chrome config that names a browser
+ * becomes the static realization. Thus a composition with a standing sidecar keeps its endpoint,
+ * and it changes nothing. A config that names no browser gives no eyes at all, and the eyes tool
+ * then gives the no-browser outcome.
+ *
+ * `createStaticEyes` refuses a config with no endpoint, thus the gate on the config runs before
+ * the construction. The resolution stays apart from `assembleCoreRuntime`, the same as the thread
+ * resolver above. Thus a test drives the precedence with no DBOS registration.
+ */
+export declare function resolveCompositionEyes(seam: AcquireEyes | undefined, chrome: ChromeConfig): AcquireEyes | undefined;
 export declare function assembleCoreRuntime(deps: CoreRuntimeDeps): CoreRuntime;

package/dist/runtime/assemble.js

@@ -19,6 +19,8 @@ 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 { hasBrowserUrl } from "../lib/chrome.js";
+import { createStaticEyes } from "../lib/eyes.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
@@ -52,6 +54,25 @@ export function createThreadAgentResolver(registry) {
         },
     };
 }
+/**
+ * The eyes of the composition, or none.
+ *
+ * A seam that the embedder bound answers first. Otherwise a chrome config that names a browser
+ * becomes the static realization. Thus a composition with a standing sidecar keeps its endpoint,
+ * and it changes nothing. A config that names no browser gives no eyes at all, and the eyes tool
+ * then gives the no-browser outcome.
+ *
+ * `createStaticEyes` refuses a config with no endpoint, thus the gate on the config runs before
+ * the construction. The resolution stays apart from `assembleCoreRuntime`, the same as the thread
+ * resolver above. Thus a test drives the precedence with no DBOS registration.
+ */
+export function resolveCompositionEyes(seam, chrome) {
+    if (seam !== undefined)
+        return seam;
+    if (hasBrowserUrl(chrome))
+        return createStaticEyes(chrome);
+    return undefined;
+}
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
     const usageRecorder = deps.usageRecorder ?? createNoopUsageRecorder();
@@ -74,19 +95,32 @@ export function assembleCoreRuntime(deps) {
         runAuthorizer: wf.dataProfile.runAuthorizer,
         ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
     });
+    // The session runtime binds the per-session state to the thread behind the
+    // tool boundary, thus one instance serves every report thread. It comes before
+    // the conversation agent, because `start_report_session` takes its anchor
+    // operation and pins the snapshot of a new session at the spawn.
+    // The runtime takes the same root resolver as the session tools, because the pin reads the citation
+    // evidence out of the run tree of the analysis.
+    const reportSession = createReportSessionRuntime({
+        pool: conversation.pool,
+        resolveWorkspaceRoot: conversation.resolveWorkspaceRoot,
+        ...(conversation.logger ? { logger: conversation.logger } : {}),
+    });
+    // The eyes of the composition resolve one time here. Thus the agent that looks at a page and
+    // the tool that starts a session read one answer. No tool reads the precedence again.
+    const eyes = resolveCompositionEyes(deps.eyes, conversation.chrome);
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
+        anchorReportSession: reportSession.ensureSessionState,
         resourcePolicy,
         usageRecorder,
         citationResolver,
+        ...(eyes ? { eyes } : {}),
     });
-    // 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 } : {}) });
+    // The report agent is a singleton over the conversation deps, the same way the
+    // session runtime is. Its preview tool writes the page into the analysis tree
+    // and returns the path, thus the page write reaches no host seam.
     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
@@ -121,7 +155,14 @@ export function assembleCoreRuntime(deps) {
         store: reportVersionStore,
         threads: reportThreads,
         chrome: conversation.chrome,
+        // The derivation tool draws the rails of the value tier: the same sandbox client
+        // and the same run authorizer. Thus a session derivation and an extraction run on
+        // one substrate, and neither one mints a run of the analysis.
+        derivations: reportSession.derivations,
+        sandboxClient: wf.dataProfile.sandboxClient,
+        runAuthorizer: conversation.runAuthorizer,
         makeResolver: makeReportResolver,
+        ...(eyes ? { eyes } : {}),
         ...(deps.resolveReportPageAsset ? { resolvePageAsset: deps.resolveReportPageAsset } : {}),
         ...(conversation.logger ? { logger: conversation.logger } : {}),
     });

package/dist/sandbox/client.d.ts

@@ -20,8 +20,17 @@
  * `awaitExec` runs in the workflow body (not as a DBOS step) because
  * `DBOS.recv` and `DBOS.writeStream` are body-only.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, SubmitExecBody } from "./types.js";
 export interface SandboxClient {
+    /**
+     * The result transport this client awaits under, fixed at construction. A caller that runs outside a
+     * workflow body reads it: `callback` awaits through `DBOS.recv`, which is body-only, thus such a caller
+     * must refuse before it starts a container it can never await.
+     *
+     * Optional, because a hand-written realization states nothing here. Absent means unknown, and a caller
+     * treats it as the poll default rather than refusing every composition that omits it.
+     */
+    readonly transport?: SandboxTransport;
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the