@inflexa-ai/harness 0.19.2 → 0.21.0

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

@@ -9,68 +9,238 @@
  * page lives at `report-sessions/{threadId}/index.html` under the workspace root, which the preview writes.
  * A missed page means that no preview ran, and it is a typed outcome, not a throw.
  *
- * The `file://` URL resolves on the filesystem of the Chrome sidecar, because the connection is out of
- * process. Thus the sidecar must mount the workspace tree of the harness host at the same path. A sidecar
+ * The composition says where a browser comes from, and the eyes seam is that answer. One look acquires one
+ * lease, and the tool captures against the endpoint of that lease.
+ *
+ * The `file://` URL resolves on the filesystem of the browser, because the connection is out of process.
+ * Thus the browser of a lease must hold the workspace tree of the harness host at the same path. A browser
  * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
  *
- * A composition that names no browser and injects no capture seam has no eyes at all. The tool reports that
- * condition once, up front, and it stamps nothing. A per-attempt capture failure would instead read as a
- * transient fault and invite a repeat of a call that can never pass.
+ * The tool releases the lease after the look. The release runs on a pass and on a failed capture alike. That
+ * release is hygiene, and it is not the guarantee against a leak. A process can die between the acquire and
+ * the release, thus the realization bounds the life of what it provisions. As a result a failed release
+ * changes no outcome, and the log is its whole record.
+ *
+ * A composition with no capture seam, no eyes seam, and no configured endpoint has no eyes at all. The tool
+ * reports that condition one time, up front, and it stamps nothing. A per-attempt capture failure would
+ * instead read as a transient fault, and it would invite a repeat of a call that can never pass.
  *
  * On a capture the tool copies the rendered hash onto the seen hash through the gateway. Thus the look
  * counts, and the record tool lets the current draft record. The copy takes the rendered hash and never the
- * current one, thus a later edit makes the look stale and the record refuses.
+ * current one, thus a later edit makes the look stale and the record refuses. A picture of the window alone
+ * is a true picture of the current document, thus it stamps the same and the coverage of the result is what
+ * tells the agent what it saw.
  *
  * The gateway reports whether a rendered hash existed to copy. When the row holds none, no preview stamped
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The chrome navigation and the workspace-root seam each speak the throw protocol. The tool runs the capture
- * inside a guard, thus a genuine fault becomes a typed outcome and a control-flow exception propagates.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
+ * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ *
+ * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
+ * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
+ * and no outcome would ever arrive.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { hasBrowserUrl } from "../../lib/chrome.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
+import { createStaticEyes } from "../../lib/eyes.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { capturePage } from "../../lib/page-capture.js";
+import { reportSessionDir } from "../../workspace/paths.js";
 import { defineTool, withToolResultImage } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
 /** The empty input. The tool examines the current page of the thread, thus it needs no field. */
 const examinePageInput = z.object({});
+/**
+ * Resolve the transport of the tool from its deps, one time.
+ *
+ * The precedence is `capture`, then `eyes`, then the chrome config as static eyes. An injected capture wins
+ * over the two others, because it replaces the whole transport and a test injects it.
+ *
+ * The chrome arm serves a direct construction alone, for example the tests of this file. The assembled
+ * runtime wraps the configured endpoint into the static realization at its composition root. Thus one wrap
+ * serves that runtime, and this arm never fires there.
+ */
+function resolveEyes(deps) {
+    if (deps.capture !== undefined) {
+        return { kind: "capture", capture: deps.capture };
+    }
+    if (deps.eyes !== undefined) {
+        return { kind: "lease", acquire: deps.eyes };
+    }
+    if (hasBrowserUrl(deps.chrome)) {
+        return { kind: "lease", acquire: createStaticEyes(deps.chrome) };
+    }
+    return { kind: "none" };
+}
+/** The log line of each stage. The outcome of the tool is one arm, thus the stage rides in the log alone. */
+const LOOK_FAULT_MESSAGE = {
+    acquire: "the eyes gave no browser for the look",
+    capture: "the page capture failed",
+};
+/**
+ * The deadline of one acquire, in milliseconds.
+ *
+ * A realization can start a container and boot a browser inside it, and that cold start costs seconds. The
+ * budget covers a slow cold start with a wide margin. It also ends a realization that hangs: one look sits
+ * inside one agent turn, and a hung acquire holds that whole turn with no outcome at all.
+ */
+const ACQUIRE_DEADLINE_MS = 60_000;
+/**
+ * The deadline of one release, in milliseconds.
+ *
+ * A release stops what one acquire started, and the look already holds its picture. Thus the budget is short.
+ * A release that runs past the budget costs nothing, because the realization bounds the life of what it
+ * provisions.
+ */
+const RELEASE_DEADLINE_MS = 10_000;
+/** The win of the timer arm. A symbol cannot collide with a value that the operation gives. */
+const EXPIRED = Symbol("expired");
+/**
+ * Run one operation against a deadline, and give the value, the cause, or the expiry.
+ *
+ * The eyes seam takes no abort signal, thus a race is the whole bound. The loser of the race stays in
+ * flight, and the caller of an expired operation owns whatever arrives late.
+ *
+ * Each path clears the timer. `sleep` of `async-utils.ts` holds a timer that nothing can clear. Thus an
+ * operation that wins its race would still keep the process alive for the rest of the budget.
+ */
+async function withDeadline(work, ms) {
+    let timer;
+    // The settled arm never rejects. Thus a fault that arrives after the expiry stays contained here, and it
+    // never reaches the process as an unhandled rejection.
+    const settled = work.then((value) => ok(value), (cause) => err({ kind: "threw", cause }));
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(EXPIRED), ms);
+    });
+    const winner = await Promise.race([settled, expiry]);
+    clearTimeout(timer);
+    return winner === EXPIRED ? err({ kind: "expired" }) : winner;
+}
+/** The cause of one such fault. An expiry names its budget, thus the detail of the outcome names it too. */
+function faultCause(fault, expiry, ms) {
+    return fault.kind === "threw" ? fault.cause : new Error(`${expiry} within ${ms} ms`);
+}
+/**
+ * Start one seam call, and give the promise of its outcome.
+ *
+ * A realization comes from the embedder, and one that is hand-written can throw before it gives its promise.
+ * The catch turns that throw into a rejection. Thus the deadline below reads one shape, and a look keeps the
+ * no-throw contract of the tool.
+ */
+function startSeamCall(call) {
+    try {
+        return call();
+    }
+    catch (cause) {
+        return Promise.reject(cause);
+    }
+}
+/**
+ * Release a lease that arrived after the deadline of its acquire.
+ *
+ * The acquire stays in flight past that deadline, thus a browser can still arrive with no owner. The
+ * realization bounds the life of that browser, and this release ends it sooner. The look already gave its
+ * outcome, thus a fault here reaches the log alone.
+ */
+function releaseLateLease(pending, logger) {
+    void pending
+        .then((lease) => lease.release())
+        .catch((cause) => {
+        logger.warn("the eyes lease did not release", logger.errorFields(cause));
+    });
+}
+/**
+ * Run one look over the resolved transport, and give the picture or the typed fault.
+ *
+ * The lease arm acquires one browser, captures against the endpoint of that lease, and releases in a
+ * `finally`. Thus a failed capture releases too. The shared capture takes a chrome config, thus the endpoint
+ * of the lease replaces the configured one and each other field of the composition stays.
+ *
+ * A failed release changes no outcome of the look. The capture already ran, and the realization bounds the
+ * life of what it provisions. Thus the log is the whole record of a failed release.
+ *
+ * The two seam calls each run against a deadline. An expired acquire reads as an acquire fault, thus a hung
+ * realization gives the same outcome as a refused one. An expired release reads as a failed release, thus it
+ * reaches the log and it changes no outcome.
+ */
+async function runLook(args) {
+    const { transport } = args;
+    if (transport.kind === "capture") {
+        try {
+            return ok(await transport.capture(args.url));
+        }
+        catch (cause) {
+            return err({ stage: "capture", cause });
+        }
+    }
+    // The pending acquire stays apart from its deadline. An expiry leaves the acquire in flight, and a lease
+    // that arrives late still gets a release.
+    const pending = startSeamCall(() => transport.acquire(args.scope));
+    const acquired = await withDeadline(pending, args.acquireMs);
+    if (acquired.isErr()) {
+        if (acquired.error.kind === "expired")
+            releaseLateLease(pending, args.logger);
+        return err({ stage: "acquire", cause: faultCause(acquired.error, "the eyes gave no browser", args.acquireMs) });
+    }
+    const lease = acquired.value;
+    try {
+        return ok(await capturePage({ ...args.chrome, browserUrl: lease.browserUrl }, args.url));
+    }
+    catch (cause) {
+        return err({ stage: "capture", cause });
+    }
+    finally {
+        const released = await withDeadline(startSeamCall(() => lease.release()), args.releaseMs);
+        if (released.isErr()) {
+            const cause = faultCause(released.error, "the eyes lease did not release", args.releaseMs);
+            args.logger.warn("the eyes lease did not release", args.logger.errorFields(cause));
+        }
+    }
+}
 /** The IANA media type of the screenshot. `page.screenshot` gives PNG bytes. */
 const SCREENSHOT_MEDIA_TYPE = "image/png";
 /** The line that the agent reads when the composition gives no browser. */
 const NO_BROWSER_DETAIL = "the composition gives no browser, thus this session cannot look at its page";
 /**
- * Make the eyes tool over the session-state gateway, the workspace-root seam, and the chrome config.
+ * Make the eyes tool over the session-state gateway, the workspace-root seam, and the eyes of the composition.
  *
  * The tool reads the thread id from the scope of the call, and it resolves the page path under the workspace
  * root. Thus one factory serves every thread. The tool holds no per-session value.
  */
 export function createExaminePageTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("examine-page");
-    // An injected seam is the eyes of a test. A named browser is the eyes of a deployment. With neither, the
-    // composition has no eyes, and that answer is fixed at construction.
-    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
-    const capture = deps.capture ?? ((url) => capturePage(deps.chrome, url));
+    // The eyes of the composition are fixed here, thus one look reads one resolved transport and never the
+    // precedence again.
+    const transport = resolveEyes(deps);
+    const acquireMs = deps.deadlines?.acquireMs ?? ACQUIRE_DEADLINE_MS;
+    const releaseMs = deps.deadlines?.releaseMs ?? RELEASE_DEADLINE_MS;
     return defineTool({
         id: "examine_page",
         description: "Open the rendered report page in a real headless browser, and report what you see. " +
-            "Give back a screenshot, the console errors, and the failed requests. " +
+            "Give back a screenshot, the coverage of that screenshot, the console errors, and the failed requests. " +
+            "The coverage says whether the picture holds the whole page, or the top window alone. " +
             "Run it after the preview to look at the current page, and to confirm that the layout and the charts read clean. " +
             "The report tool records a version only after you look at the current page. " +
             "If the page has no confirmed render, run the preview again first.",
         inputSchema: examinePageInput,
         executionMode: "inline",
         describeCall: "none",
+        // A look gives a picture, and a picture has no one-line form. Thus the outcome of the look is the
+        // whole line: a watcher reads that the eyes saw the page, or that the page was absent, or that the
+        // capture failed.
+        describeResult: (_input, result) => result.outcome,
         execute: async (_input, ctx) => {
             // The check runs before every read, thus one clear signal replaces a capture failure for each
-            // page. The arm stamps no seen hash, because no eyes saw the page.
-            if (!eyesAvailable) {
+            // page. The arm stamps no seen hash, because no eyes saw the page. It also narrows the transport
+            // for the look below, thus the acquire needs no assertion.
+            if (transport.kind === "none") {
                 logger.warn("the composition gives no browser, thus no look can run");
                 return ok({ outcome: "no-browser", detail: NO_BROWSER_DETAIL });
             }
@@ -87,7 +257,7 @@ export function createExaminePageTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the workspace root did not resolve" });
             }
-            const relativePagePath = join("report-sessions", threadId, "index.html");
+            const relativePagePath = join(reportSessionDir(threadId), "index.html");
             const pagePath = join(root, relativePagePath);
             try {
                 await access(pagePath);
@@ -100,14 +270,23 @@ export function createExaminePageTool(deps) {
                 logger.warn("the session page could not be read", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the session page could not be read" });
             }
-            let captured;
-            try {
-                captured = await capture(pathToFileURL(pagePath).href);
-            }
-            catch (cause) {
-                logger.warn("the page capture failed", { threadId, analysisId, ...defaultErrorFields(cause) });
+            // The scope of the acquire carries the analysis and the root that this call resolved. Thus a
+            // realization that starts a browser mounts the same tree, and it holds no second resolver.
+            const looked = await runLook({
+                transport,
+                chrome: deps.chrome,
+                scope: { analysisId, workspaceRoot: root },
+                url: pathToFileURL(pagePath).href,
+                acquireMs,
+                releaseMs,
+                logger,
+            });
+            if (looked.isErr()) {
+                const { stage, cause } = looked.error;
+                logger.warn(LOOK_FAULT_MESSAGE[stage], { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: cause instanceof Error ? cause.message : String(cause) });
             }
+            const captured = looked.value;
             const stamped = await deps.gateway.stampSeen(threadId);
             if (stamped.outcome === "no-rendered") {
                 // The row holds no rendered hash, thus no preview stamped one and the look cannot count. A
@@ -127,6 +306,7 @@ export function createExaminePageTool(deps) {
             // JSON keeps the faults and the page path only, thus the JSON text holds no bytes.
             return ok(withToolResultImage({
                 outcome: "examined",
+                coverage: captured.coverage,
                 consoleErrors: captured.consoleErrors,
                 failedRequests: captured.failedRequests,
                 pagePath: relativePagePath,

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

@@ -8,3 +8,5 @@
 export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, } from "./preview-report.js";
 export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, } from "./examine-page.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
+export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";
+export { createListPinnedArtifactsTool, type ListPinnedArtifactsInput, type ListPinnedArtifactsResult, type ListPinnedArtifactsToolDeps, type PinnedArtifact, type PinnedCitation, } from "./list-artifacts.js";

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

@@ -8,3 +8,5 @@
 export { createPreviewReportTool, } from "./preview-report.js";
 export { createExaminePageTool, } from "./examine-page.js";
 export { createRecordVersionTool } from "./record-version.js";
+export { createDeriveTableTool } from "./derive-table.js";
+export { createListPinnedArtifactsTool, } from "./list-artifacts.js";

package/dist/tools/report-session/list-artifacts.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The pinned-artifact listing tool of a report session.
+ *
+ * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the content
+ * hash, the file type, and the header columns of a tabular artifact, plus the pinned citations with the
+ * short citation of each. Thus one call orients the agent, and a reference binds to a path or to a
+ * citation key of that set.
+ *
+ * The order is the code-unit order of the path. Two calls over one snapshot give one listing, thus the
+ * agent reads a stable set. A snapshot can pin many thousands of staged inputs, thus the listing stops at
+ * a cap and it carries the total count and a truncation marker.
+ *
+ * The columns come from a bounded header read of a listed entry. The path of a snapshot entry is
+ * untrusted, thus the read contains it with the one workspace-path resolver first. The extension gates
+ * the read, because a file type states a role and not a data format.
+ *
+ * An absent file, an unreadable file, and an unresolvable workspace root each give no columns and no
+ * error. Absence is a normal condition here: the listing is orientation, and the hash is the evidence.
+ */
+import { z } from "zod";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Logger } from "../../lib/logger.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool lists the pinned set of the thread, thus it needs no field. */
+declare const listPinnedArtifactsInput: z.ZodObject<{}, z.core.$strip>;
+export type ListPinnedArtifactsInput = z.infer<typeof listPinnedArtifactsInput>;
+/**
+ * One pinned artifact of the listing.
+ *
+ * `fileType` states a role, and it does not state a data format. `columns` is present only for a header
+ * that the read recovered, thus an absent `columns` says nothing about the content of the file.
+ */
+export interface PinnedArtifact {
+    path: string;
+    hash: string;
+    fileType?: string;
+    columns?: string[];
+}
+/**
+ * One pinned citation of the listing: the key, and the short citation of its pinned record.
+ *
+ * `citation` names which paper the key is, thus the agent binds a citation block with no guess. A key that
+ * the pin recorded no citation for carries none, because absence is a normal condition. The description of
+ * the record stays out, because the listing is an orientation surface.
+ */
+export interface PinnedCitation {
+    key: string;
+    citation?: string;
+}
+/**
+ * The typed outcome of the listing tool. Each arm is ok-channel data, thus the tool never throws for one
+ * of them.
+ *
+ * `total` counts the whole pinned set, and `truncated` says that the set holds more entries than
+ * `artifacts` names. Thus the agent reads a partial listing as a partial listing.
+ *
+ * `citations` gives the pinned citations in the code-unit order of the keys that the pin stored. A citation
+ * reference binds to one of those keys, thus the agent reads a key here and never out of a refusal.
+ */
+export type ListPinnedArtifactsResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "listed";
+    artifacts: PinnedArtifact[];
+    total: number;
+    truncated: boolean;
+    citations: PinnedCitation[];
+};
+/**
+ * The construction deps of the listing 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.
+ */
+export interface ListPinnedArtifactsToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly logger?: Logger;
+}
+/**
+ * The header columns of a file on disk, or `undefined` when the file gives none.
+ *
+ * `path` decides whether the file carries a header at all, and `absolute` is where the bytes sit. The
+ * derivation tool reads the columns of its own output the same way, thus the two surfaces describe a table
+ * with one rule.
+ */
+export declare function readHeaderColumns(path: string, absolute: string): Promise<string[] | undefined>;
+/**
+ * Make the pinned-artifact listing tool over the session-state gateway.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the snapshot through the gateway.
+ * Thus one factory serves every thread, and the tool holds no per-session value.
+ */
+export declare function createListPinnedArtifactsTool(deps: ListPinnedArtifactsToolDeps): Tool<ListPinnedArtifactsInput, ListPinnedArtifactsResult>;
+export {};

package/dist/tools/report-session/list-artifacts.js

@@ -0,0 +1,197 @@
+/**
+ * The pinned-artifact listing tool of a report session.
+ *
+ * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the content
+ * hash, the file type, and the header columns of a tabular artifact, plus the pinned citations with the
+ * short citation of each. Thus one call orients the agent, and a reference binds to a path or to a
+ * citation key of that set.
+ *
+ * The order is the code-unit order of the path. Two calls over one snapshot give one listing, thus the
+ * agent reads a stable set. A snapshot can pin many thousands of staged inputs, thus the listing stops at
+ * a cap and it carries the total count and a truncation marker.
+ *
+ * The columns come from a bounded header read of a listed entry. The path of a snapshot entry is
+ * untrusted, thus the read contains it with the one workspace-path resolver first. The extension gates
+ * the read, because a file type states a role and not a data format.
+ *
+ * An absent file, an unreadable file, and an unresolvable workspace root each give no columns and no
+ * error. Absence is a normal condition here: the listing is orientation, and the hash is the evidence.
+ */
+import { ok } from "neverthrow";
+import { open } from "node:fs/promises";
+import { extname } from "node:path";
+import { z } from "zod";
+import { resolveWorkspacePath } from "../../workspace/paths.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { tryFs } from "../../lib/fs-result.js";
+import { defaultErrorFields } from "../../lib/logger.js";
+import { citationRecordOf, fileTypeHoldsNoCell } from "../../report-model/reference-resolver.js";
+import { defineTool } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool lists the pinned set of the thread, thus it needs no field. */
+const listPinnedArtifactsInput = z.object({});
+/**
+ * The cap of the header read. A header line of an analysis output sits far under it, and a file with no
+ * newline at all costs this many bytes and no more.
+ */
+const HEADER_CAP_BYTES = 16 * 1024;
+/**
+ * The cap of the listing. A snapshot pins each staged input of the analysis, and such a set can hold
+ * many thousands of entries. One entry costs one file read, thus the cap bounds both the reply and the
+ * work of the call.
+ */
+const LISTING_CAP = 200;
+/**
+ * The two extensions that carry a header line, each with its delimiter.
+ *
+ * The extension decides, because the bytes carry no declaration and a file type states a role alone. A
+ * minified JSON under `output/` splits into hundreds of names that address nothing, and a binary splits
+ * into unreadable text. Thus an entry with another extension reads no header.
+ */
+const HEADER_DELIMITERS = new Map([
+    [".csv", ","],
+    [".tsv", "\t"],
+]);
+/** The header delimiter of a path, or `undefined` when the extension carries no header. */
+function delimiterOf(path) {
+    return HEADER_DELIMITERS.get(extname(path).toLowerCase());
+}
+/**
+ * Read the first line of a file under the cap, or give `undefined` when the bytes do not come back.
+ *
+ * The read takes a bounded byte window, thus a file of any size costs the cap. An absent file and a
+ * genuine read fault both give `undefined`, because the listing reports no error for a header.
+ */
+async function readHeaderLine(absolute) {
+    const head = await tryFs("listPinnedArtifacts.readHeader", async () => {
+        const handle = await open(absolute, "r");
+        try {
+            const buffer = Buffer.alloc(HEADER_CAP_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, HEADER_CAP_BYTES, 0);
+            return { text: buffer.subarray(0, bytesRead).toString("utf8"), filled: bytesRead === HEADER_CAP_BYTES };
+        }
+        finally {
+            await handle.close();
+        }
+    }, { path: absolute, onAbsent: () => undefined }).unwrapOr(undefined);
+    if (head === undefined) {
+        return undefined;
+    }
+    const line = head.text.split(/\r?\n/, 1)[0];
+    if (line.length === 0) {
+        return undefined;
+    }
+    return { line, cut: head.filled && !head.text.includes("\n") };
+}
+/**
+ * Split a header line into column names on the delimiter, or give `undefined` when no whole name comes
+ * out of it.
+ *
+ * A double quote makes a field that can hold the delimiter itself, thus the naive split gives wrong
+ * names. A cut line ends inside its last name, and an agent writes a column name into a locator. Both
+ * conditions give no columns, because a wrong name is worse than an absent one.
+ */
+function columnsOf(read, delimiter) {
+    if (read.line.includes('"')) {
+        return undefined;
+    }
+    const names = read.line.split(delimiter).map((name) => name.trim());
+    const whole = read.cut ? names.slice(0, -1) : names;
+    return whole.length > 0 ? whole : undefined;
+}
+/**
+ * The header columns of a file on disk, or `undefined` when the file gives none.
+ *
+ * `path` decides whether the file carries a header at all, and `absolute` is where the bytes sit. The
+ * derivation tool reads the columns of its own output the same way, thus the two surfaces describe a table
+ * with one rule.
+ */
+export async function readHeaderColumns(path, absolute) {
+    const delimiter = delimiterOf(path);
+    if (delimiter === undefined) {
+        return undefined;
+    }
+    const read = await readHeaderLine(absolute);
+    return read === undefined ? undefined : columnsOf(read, delimiter);
+}
+/**
+ * Make the pinned-artifact listing tool over the session-state gateway.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the snapshot through the gateway.
+ * Thus one factory serves every thread, and the tool holds no per-session value.
+ */
+export function createListPinnedArtifactsTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("list-pinned-artifacts");
+    return defineTool({
+        id: "list_pinned_artifacts",
+        description: "List the pinned evidence of this session. Each entry gives the path of an artifact, its content hash, its file type, " +
+            "and the header columns of a .csv or a .tsv file. Another extension, a header line that holds a double quote, and a " +
+            "file whose bytes do not read each give no columns. " +
+            `The listing gives a maximum of ${LISTING_CAP} entries: "total" gives the size of the pinned set, and "truncated" says that the ` +
+            "set holds more artifacts than this listing names. " +
+            '"citations" gives the pinned literature of this session. Each entry carries "key", the citation id in the "idKind:id" form, and ' +
+            '"citation", the short citation of the paper. A key that the pin recorded no citation for carries no "citation". A citation block ' +
+            "binds to a key of this list, thus take a key from here and never from a refusal. " +
+            "The pin freezes at the start of the session, thus a reference binds to an artifact of this pinned set. " +
+            "Read it to orient before you bind a block, and to choose the column that a locator names. " +
+            "A reference names the path alone: the session stamps the hash from this evidence.",
+        inputSchema: listPinnedArtifactsInput,
+        executionMode: "inline",
+        describeCall: "none",
+        // The size of the listing is what a watcher reads, and the cap makes that size differ from the
+        // pinned set. Thus a truncated listing names the total beside the count, and a whole listing names
+        // the count alone, because a total that equals the count says the same thing two times.
+        describeResult: (_input, result) => {
+            if (result.outcome !== "listed") {
+                return result.outcome;
+            }
+            const count = result.artifacts.length;
+            const listed = `${count} ${count === 1 ? "artifact" : "artifacts"}`;
+            return result.truncated ? `${listed} of ${result.total}` : listed;
+        },
+        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 paths = Object.keys(state.snapshot.artifacts).sort();
+            // The cap cuts the tail of the same order, thus a truncated listing is a prefix of the whole
+            // listing and a second call over one snapshot names the same entries.
+            const listed = paths.slice(0, LISTING_CAP);
+            // The seam signals an unresolvable resource by a throw. The listing still serves the path and
+            // the hash of each entry, thus the fault costs the columns alone and never the whole call.
+            let root;
+            try {
+                root = deps.resolveWorkspaceRoot(analysisId);
+            }
+            catch (cause) {
+                logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+            }
+            const artifacts = [];
+            for (const path of listed) {
+                const entry = state.snapshot.artifacts[path];
+                const fileType = entry.fileType;
+                const artifact = { path, hash: entry.hash, ...(typeof fileType === "string" ? { fileType } : {}) };
+                if (root !== undefined && !fileTypeHoldsNoCell(fileType)) {
+                    const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId, path });
+                    if (resolved.kind === "ok") {
+                        const columns = await readHeaderColumns(path, resolved.absolute);
+                        if (columns !== undefined) {
+                            artifact.columns = columns;
+                        }
+                    }
+                }
+                artifacts.push(artifact);
+            }
+            // The pin stores the citation keys sorted, thus the listing keeps that order. A snapshot that
+            // pinned no citation gives an empty list, and an empty list is a complete answer. A key with no
+            // pinned record lists bare, thus a stored pin that holds no record map still orients the agent.
+            const citations = (state.snapshot.citations ?? []).map((key) => {
+                const record = citationRecordOf(state.snapshot.citationRecords, key);
+                return record === undefined ? { key } : { key, citation: record.citation };
+            });
+            return ok({ outcome: "listed", artifacts, total: paths.length, truncated: paths.length > listed.length, citations });
+        },
+    });
+}

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

@@ -6,6 +6,12 @@
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
  * and renders the page.
  *
+ * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
+ * them beside the figures. It also writes the script of each derivation that the document references, from
+ * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
+ * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
+ * wrote stays, and each other file goes.
+ *
  * The page and its staged 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.