@inflexa-ai/harness 0.41.1 → 0.42.0

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

@@ -1,10 +1,14 @@
 /**
  * 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 tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the file type,
+ * and the count of 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. A call with a path gives the header columns of that one artifact.
+ *
+ * A wide table can have hundreds of columns, and the listing stays in the context of each later request.
+ * Thus the listing counts the columns, and the agent reads the names of one artifact when it binds to it.
+ * A reference names the path alone and the session stamps the hash, thus the tool gives no hash.
  *
  * 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
@@ -28,8 +32,14 @@ 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({});
+/** No path lists the pinned set. A path gives the header columns of that one pinned artifact. */
+const listPinnedArtifactsInput = z.object({
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The path of one pinned artifact, as the listing gives it. The result then gives the header columns of that artifact."),
+});
 /**
  * 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.
@@ -124,24 +134,29 @@ 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. " +
+        description: "List the pinned evidence of this session. With no path, each entry gives the path of an artifact, its file type, " +
+            'and "columnCount", the count of the header columns of a .csv or a .tsv file. ' +
+            'Give "path" to get that one artifact with "columns", the names of its header columns. A path that the pin does not hold gives not-pinned. ' +
+            "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.",
+            "Read the listing to orient before you bind a block. Read the columns of one artifact to choose the column that a locator names. " +
+            "A reference names the path alone: the session stamps the hash from this evidence, thus the tool gives no hash.",
         inputSchema: listPinnedArtifactsInput,
         executionMode: "inline",
-        describeCall: "none",
+        describeCall: (input) => input.path ?? "the pinned set",
         // 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 === "artifact") {
+                const count = result.artifact.columnCount;
+                return count === undefined ? "no columns" : `${count} ${count === 1 ? "column" : "columns"}`;
+            }
             if (result.outcome !== "listed") {
                 return result.outcome;
             }
@@ -149,18 +164,14 @@ export function createListPinnedArtifactsTool(deps) {
             const listed = `${count} ${count === 1 ? "artifact" : "artifacts"}`;
             return result.truncated ? `${listed} of ${result.total}` : listed;
         },
-        execute: async (_input, ctx) => {
+        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.
+            // the file type of each entry, thus the fault costs the columns alone and never the whole call.
             let root;
             try {
                 root = deps.resolveWorkspaceRoot(analysisId);
@@ -168,21 +179,30 @@ export function createListPinnedArtifactsTool(deps) {
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
             }
+            const describe = async (path) => {
+                const fileType = state.snapshot.artifacts[path].fileType;
+                const artifact = { path, ...(typeof fileType === "string" ? { fileType } : {}) };
+                if (root === undefined || fileTypeHoldsNoCell(fileType)) {
+                    return { artifact };
+                }
+                const resolved = resolveWorkspacePath({ workspaceRoot: root, analysisId, path });
+                const columns = resolved.kind === "ok" ? await readHeaderColumns(path, resolved.absolute) : undefined;
+                return columns === undefined ? { artifact } : { artifact: { ...artifact, columnCount: columns.length }, columns };
+            };
+            if (input.path !== undefined) {
+                if (!Object.hasOwn(state.snapshot.artifacts, input.path)) {
+                    return ok({ outcome: "not-pinned", path: input.path });
+                }
+                const { artifact, columns } = await describe(input.path);
+                return ok({ outcome: "artifact", artifact: columns === undefined ? artifact : { ...artifact, columns } });
+            }
+            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);
             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);
+                artifacts.push((await describe(path)).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

package/dist/tools/report-session/page-faults.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The digest of the faults of one look. A blocked inline font logs its whole base64 body, often many times,
+ * thus the raw lists can cost more context than the pictures of the look.
+ */
+import type { FailedRequest } from "../../lib/page-capture.js";
+/** One distinct console error of a look, and how many times the page logged it. */
+export interface ConsoleErrorEntry {
+    text: string;
+    count: number;
+}
+/** One distinct failed request of a look, and how many times the page made it. */
+export interface FailedRequestEntry {
+    url: string;
+    reason: string;
+    count: number;
+}
+/** The digest of one look. `omittedFaults` counts the distinct entries that the cap left out, thus a cut is never silent. */
+export interface PageFaults {
+    consoleErrors: ConsoleErrorEntry[];
+    failedRequests: FailedRequestEntry[];
+    omittedFaults?: {
+        consoleErrors: number;
+        failedRequests: number;
+    };
+}
+/** Shorten one fault text: the inline data becomes placeholders, and the text stops at the cap. */
+export declare function shortenFaultText(text: string): string;
+/** Digest the raw faults of one capture into the short lists that the agent reads. */
+export declare function digestPageFaults(consoleErrors: readonly string[], failedRequests: readonly FailedRequest[]): PageFaults;

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

@@ -0,0 +1,48 @@
+/**
+ * The digest of the faults of one look. A blocked inline font logs its whole base64 body, often many times,
+ * thus the raw lists can cost more context than the pictures of the look.
+ */
+import { capCodePoints } from "../../loop/tool-detail.js";
+/** The most code points of one fault text, after the placeholders replace the inline data. */
+const MAX_FAULT_TEXT = 300;
+/** The most distinct entries of one list. */
+const MAX_FAULT_ENTRIES = 20;
+/** A data URI. A fault text quotes a URI in quotes or parentheses, thus those characters end the data. */
+const DATA_URI = /data:([a-z0-9.+-]+\/[a-z0-9.+-]+)?((?:;[^,;\s'"()<>]*)*),([^\s'"()<>]*)/gi;
+/** A base64 run of 100 characters or more. A content hash in hex is 64 characters, thus a hash stays. */
+const BASE64_RUN = /[A-Za-z0-9+/]{100,}={0,2}/g;
+/** Shorten one fault text: the inline data becomes placeholders, and the text stops at the cap. */
+export function shortenFaultText(text) {
+    const inlined = text.replace(DATA_URI, (_uri, mediaType, _parameters, data) => {
+        return `[inline ${mediaType ?? "text/plain"} data, ${data.length} chars]`;
+    });
+    const unrun = inlined.replace(BASE64_RUN, (run) => `[base64 data, ${run.length} chars]`);
+    return capCodePoints(unrun, MAX_FAULT_TEXT);
+}
+/** Collapse each repeat of one list into one entry with a count. A `Map` keeps the first occurrence order. */
+function collapse(items, keyOf) {
+    const byKey = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        const held = byKey.get(key);
+        if (held === undefined) {
+            byKey.set(key, { item, count: 1 });
+        }
+        else {
+            held.count += 1;
+        }
+    }
+    return [...byKey.values()];
+}
+/** Digest the raw faults of one capture into the short lists that the agent reads. */
+export function digestPageFaults(consoleErrors, failedRequests) {
+    const errors = collapse(consoleErrors.map(shortenFaultText), (text) => text).map(({ item, count }) => ({ text: item, count }));
+    const requests = collapse(failedRequests.map((request) => ({ url: shortenFaultText(request.url), reason: shortenFaultText(request.reason) })), (request) => `${request.url}\n${request.reason}`).map(({ item, count }) => ({ ...item, count }));
+    const omittedErrors = Math.max(0, errors.length - MAX_FAULT_ENTRIES);
+    const omittedRequests = Math.max(0, requests.length - MAX_FAULT_ENTRIES);
+    return {
+        consoleErrors: errors.slice(0, MAX_FAULT_ENTRIES),
+        failedRequests: requests.slice(0, MAX_FAULT_ENTRIES),
+        ...(omittedErrors + omittedRequests > 0 ? { omittedFaults: { consoleErrors: omittedErrors, failedRequests: omittedRequests } } : {}),
+    };
+}

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

@@ -4,7 +4,8 @@
  * The tool renders the current draft of a thread. It runs the finish first, because a mid-composition
  * draft is not a `ReportDocument`. A gap list returns as data, and no render runs. On a pass the tool
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
- * and renders the page.
+ * and renders the page. The gap list and the rendered page each carry the advisory warnings of the finish,
+ * thus the agent reads them with no separate finish.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
  * them beside the figures. The tool asks the optional provenance source for the frozen document of the
@@ -40,6 +41,8 @@ import { z } from "zod";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import type { AuthContext } from "../../auth/types.js";
 import { type Logger } from "../../lib/logger.js";
+import type { ThreadStore } from "../../memory/thread-store.js";
+import { type ReportWarning } from "../../report-model/block-walk.js";
 import { type FinishGap } from "../../report-model/draft-finish.js";
 import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
 import { type ResolutionFailure } from "../../report-model/validate.js";
@@ -68,7 +71,7 @@ export type SessionPageAccess = {
 /**
  * The typed outcome of the preview tool. Each arm is ok-channel data, thus the tool never throws for a
  * degraded condition. `rendered` carries the absolute page path, and the access grant of the hosted view
- * when the composition binds the publisher.
+ * when the composition binds the publisher. `gaps` and `rendered` carry the advisory warnings of the finish.
  */
 export type PreviewReportResult = {
     outcome: "refused";
@@ -76,6 +79,7 @@ export type PreviewReportResult = {
 } | {
     outcome: "gaps";
     gaps: FinishGap[];
+    warnings: ReportWarning[];
 } | {
     outcome: "resolver-unavailable";
 } | {
@@ -105,6 +109,7 @@ export type PreviewReportResult = {
     outcome: "rendered";
     pagePath: string;
     access?: SessionPageAccess;
+    warnings: ReportWarning[];
 };
 /**
  * The lookup of the source file of one staged asset. It maps the module specifier of a manifest entry
@@ -144,6 +149,8 @@ export interface PreviewReportToolDeps {
      * then carries no provenance asset.
      */
     readonly provenance?: ProvenanceSeam;
+    /** Names the report thread after the rendered document. Omitted, the thread keeps its title. */
+    readonly threads?: Pick<ThreadStore, "setAutoTitle">;
     readonly logger?: Logger;
 }
 /**

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

@@ -4,7 +4,8 @@
  * The tool renders the current draft of a thread. It runs the finish first, because a mid-composition
  * draft is not a `ReportDocument`. A gap list returns as data, and no render runs. On a pass the tool
  * resolves each reference through the injected resolver, bridges the resolved values into the render model,
- * and renders the page.
+ * and renders the page. The gap list and the rendered page each carry the advisory warnings of the finish,
+ * thus the agent reads them with no separate finish.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
  * them beside the figures. The tool asks the optional provenance source for the frozen document of the
@@ -396,6 +397,7 @@ export function createPreviewReportTool(deps) {
         description: "Render the current draft to an HTML page in the session directory, and give back the page path. " +
             "The page loads its figures, table data, and libraries from an assets directory that the tool stages beside it. " +
             "The tool finishes the draft first: an incomplete draft gives back the gap list, and no page renders. " +
+            "The gap list and the rendered page each carry the advisory warnings of the finish, for example a number typed into the prose. " +
             "On a pass it resolves each reference, stages each bound image beside the page, and writes the page. " +
             "An unresolved reference gives back the block and the binding to repair. " +
             "The outcome resolver-unavailable means that this host gives no reference resolver, and a repeat gives the same outcome. " +
@@ -419,7 +421,7 @@ export function createPreviewReportTool(deps) {
             const { document: draft, snapshot } = state;
             const finished = finishDraft(draft, snapshot, derivations);
             if (!finished.valid) {
-                return ok({ outcome: "gaps", gaps: finished.gaps });
+                return ok({ outcome: "gaps", gaps: finished.gaps, warnings: finished.warnings });
             }
             const document = finished.document;
             if (deps.makeResolver === undefined) {
@@ -498,6 +500,14 @@ export function createPreviewReportTool(deps) {
                 logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
                 return ok({ outcome: "stamp-failed", pagePath: written.value, detail });
             }
+            // Before the part, thus a client that reads the thread list on the part reads the new title.
+            const title = document.title.trim();
+            if (deps.threads && title.length > 0) {
+                const named = await deps.threads.setAutoTitle(threadId, title);
+                if (named.isErr()) {
+                    logger.warn("the report title did not reach the thread", { threadId, analysisId, ...defaultErrorFields(named.error.cause) });
+                }
+            }
             // The part rides the rendered arm only. Each degraded arm shows no
             // fresh page, thus it emits nothing.
             await ctx.emit({
@@ -508,7 +518,7 @@ export function createPreviewReportTool(deps) {
             // the draft that the page shows, thus a consumer ties the page to the document that made it.
             observe({ type: "preview", analysisId, threadId, pagePath: written.value, documentHash: renderedHash });
             const access = await mintAccess(deps.makeSessionPages, analysisId, threadId, ctx.session.auth, logger);
-            return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}) });
+            return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}), warnings: finished.warnings });
         },
     });
 }

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

@@ -32,6 +32,7 @@ import { z } from "zod";
 import type { AuthContext } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import type { ThreadStore } from "../../memory/thread-store.js";
+import { type ReportWarning } from "../../report-model/block-walk.js";
 import { type FinishGap } from "../../report-model/draft-finish.js";
 import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
 import { type ResolutionFailure, type SchemaIssue } from "../../report-model/validate.js";
@@ -47,7 +48,8 @@ export type RecordVersionInput = z.infer<typeof recordVersionInput>;
  * The typed outcome of the record tool. Each arm is ok-channel data, thus the tool never throws for a
  * degraded condition.
  *
- * `gaps` names each completeness gap of the draft. `never-seen` means that no eyes ran on the current draft.
+ * `gaps` names each completeness gap of the draft. `gaps` and `recorded` carry the advisory warnings of the
+ * finish. `never-seen` means that no eyes ran on the current draft.
  * `stale-look` means that the eyes ran, and the agent then changed the draft. `root-unresolvable` means that
  * the resolver construction cannot resolve the workspace root. `invalid` names each gate failure, and a
  * resolution failure carries the block that holds it. `recorded` carries the version id, and `replaced` is
@@ -59,6 +61,7 @@ export type RecordVersionResult = {
 } | {
     outcome: "gaps";
     gaps: FinishGap[];
+    warnings: ReportWarning[];
 } | {
     outcome: "never-seen";
 } | {
@@ -80,6 +83,7 @@ export type RecordVersionResult = {
     outcome: "recorded";
     versionId: string;
     replaced: boolean;
+    warnings: ReportWarning[];
 };
 /**
  * The construction deps of the record tool.

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

@@ -128,7 +128,8 @@ export function createRecordVersionTool(deps) {
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
             "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
-            "and a failed reference gives back the block that broke. The tool records a version only after examine_page looked at the page of the current draft: " +
+            "and a failed reference gives back the block that broke. The gap list and the recorded version each carry the advisory warnings of the finish. " +
+            "The tool records a version only after examine_page looked at the page of the current draft: " +
             "with no look it gives back never-seen, and after an edit since the look it gives back stale-look. " +
             "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
             "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
@@ -152,7 +153,7 @@ export function createRecordVersionTool(deps) {
             const { document: draft, snapshot } = state;
             const finished = finishDraft(draft, snapshot, derivations);
             if (!finished.valid) {
-                return ok({ outcome: "gaps", gaps: finished.gaps });
+                return ok({ outcome: "gaps", gaps: finished.gaps, warnings: finished.warnings });
             }
             // The look-before-record rule runs before the resolver and the validation, on the state that the
             // load already read. The preview stamps the rendered hash, and the eyes copy it onto the seen
@@ -220,7 +221,7 @@ export function createRecordVersionTool(deps) {
                     logger,
                 });
             }
-            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId, replaced: ref.outcome === "replaced" }), (error) => {
+            return recorded.match((ref) => ok({ outcome: "recorded", versionId: ref.versionId, replaced: ref.outcome === "replaced", warnings: finished.warnings }), (error) => {
                 logger.warn("the version did not record", { threadId, analysisId, reason: error.type });
                 return ok({ outcome: "record-failed", detail: describeRecordFailure(error) });
             });

package/dist/tools/workspace/show-file.js

@@ -25,7 +25,7 @@ const ShowFileInputSchema = z.object({
     }))
         .min(1)
         .max(MAX_FILES)
-        .describe(`The related set of files to show together, 1 to ${MAX_FILES} per call; multiple render as ONE gallery card. Pass a related set in a single call — do not make one call per figure.`),
+        .describe(`The files to show together, 1 to ${MAX_FILES} per call; multiple render as ONE gallery card. Pass all the figures that one prose section discusses in a single call. Figures for different sections go in separate calls.`),
 });
 export const showFileTool = defineTool({
     id: "show_file",
@@ -36,8 +36,9 @@ export const showFileTool = defineTool({
         "Paths are analysis-rooted (no leading slash, no `..`); discover them with `workspace_search` or `list_files`. " +
         "The tool checks the shape of each path only, not that the file exists, so a wrong path fails only when the user views the card; " +
         "`shown: false` with `invalid_path` means a path has a leading slash or a `..` segment. " +
-        "Up to 10 files per call — pass a related set in ONE call and they render as a gallery, rather than one call per figure. " +
-        "Cards render in call order, so to interleave figures with prose alternate `show_user(markdown)` and `show_file` calls " +
+        "Up to 10 files per call, rendered as one gallery — pass all the figures that one prose section discusses in ONE call. " +
+        "Cards render in call order, so to put figures next to their prose, emit `show_user(markdown)` sections and `show_file` " +
+        "calls in one batch, in reading order: a section, then the `show_file` for its figures, then the next section " +
         "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",
     inputSchema: ShowFileInputSchema,
     // `.min(1)` on `files` makes index 0 total after the parse.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.41.1",
+    "version": "0.42.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -77,6 +77,7 @@
         "hono": "^4.12.34",
         "hyparquet": "^1.28.1",
         "js-tiktoken": "^1.0.21",
+        "kysely": "^0.29.6",
         "mime": "^4.1.0",
         "nanoid": "^5.1.16",
         "neverthrow": "^8.2.0",