@inflexa-ai/harness 0.17.0 → 0.19.0

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

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

package/dist/tools/research/context7-docs.js

@@ -25,6 +25,7 @@ export const resolveLibraryIdTool = defineTool({
         libraryName: z.string().describe("Package or library name to search for (e.g., 'scanpy', 'pysam', 'lifelines')."),
         query: z.string().describe("What you need help with — used to rank results by relevance (e.g., 'how to run differential expression')."),
     }),
+    describeCall: "none",
     execute: async ({ libraryName, query }) => {
         const result = await apiFetchValidated(`${CONTEXT7_BASE}/search?query=${encodeURIComponent(libraryName)}&topic=${encodeURIComponent(query)}`, Context7SearchResponseSchema, { maxRetries: 1 });
         if (result.isErr())
@@ -48,6 +49,7 @@ export const queryDocsTool = defineTool({
         libraryId: z.string().describe("Context7 library ID from resolve-library-id (e.g., '/scverse/scanpy')."),
         query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),
     }),
+    describeCall: "none",
     execute: async ({ libraryId, query }) => {
         const result = await apiFetchValidated(`${CONTEXT7_BASE}/docs?libraryId=${encodeURIComponent(libraryId)}&query=${encodeURIComponent(query)}`, Context7DocsResponseSchema, { maxRetries: 1 });
         if (result.isErr())

package/dist/tools/research/generate-analogy-report.js

@@ -193,6 +193,7 @@ export function createGenerateAnalogyReportTool(deps) {
             "latency on the same failure). Surface the message and ask the user to " +
             "narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
+        describeCall: "none",
         execute: async (input, ctx) => {
             const childSession = forSubAgent(ctx.session, AGENT_ID);
             // Phase 1+2: drive the research agent over the cross-domain toolset.

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

@@ -30,6 +30,7 @@ import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { DEFAULT_SALVAGE_ITERATIONS, runToTerminal } from "../../loop/run-to-terminal.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
+import { effectiveDeadlineMs } from "../../providers/types.js";
 import { defineTool } from "../define-tool.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
@@ -344,6 +345,7 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
             // structured issue reporting.
             plan: z.union([PlannerPlanSchema, z.unknown()]).describe("Candidate plan; malformed values are reported in issues."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             if (holder.outcome !== null) {
                 trace.duplicateTerminalCalls++;
@@ -416,6 +418,7 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
             question: z.string().min(1),
             questionContext: z.string().optional(),
         }),
+        describeCall: "none",
         execute: async (input) => {
             if (holder.outcome !== null) {
                 trace.duplicateTerminalCalls++;
@@ -670,6 +673,7 @@ export function createGeneratePlanTool(deps) {
                 .optional()
                 .describe("The planId of the prior plan being iterated on. Set only when " + "the user is asking for modifications to an existing plan."),
         }),
+        describeCall: ({ researchQuestion }) => researchQuestion,
         execute: async (input, ctx) => {
             const analysisId = scopeResource(ctx.session.scope).resourceId;
             // Bound per invocation: `analysisId` comes from the call-time session, not from
@@ -773,6 +777,7 @@ export function createGeneratePlanTool(deps) {
                 ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
                 ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
             ].join("\n");
+            const planTimeoutMs = effectiveDeadlineMs(deps.conversation.provider, PLAN_TIMEOUT_MS);
             // Opens the invocation. Two things are only knowable here and both are
             // first-order suspects when a planner runs long and returns nothing: the size
             // of the seed it was handed, and which of its blocks made it that size. The
@@ -785,7 +790,7 @@ export function createGeneratePlanTool(deps) {
                 model: deps.conversation.model,
                 maxIterations: PLANNER_MAX_ITERATIONS,
                 salvageIterations: DEFAULT_SALVAGE_ITERATIONS,
-                timeoutMs: PLAN_TIMEOUT_MS,
+                timeoutMs: planTimeoutMs,
                 grounding: grounding.kind,
                 ...(input.parentPlanId ? { parentPlanId: input.parentPlanId } : {}),
                 seedChars: {
@@ -815,7 +820,7 @@ export function createGeneratePlanTool(deps) {
             };
             // Merge the outer abort signal with a wall-clock timeout — either
             // cancels the planner promptly.
-            const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(PLAN_TIMEOUT_MS)]);
+            const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(planTimeoutMs)]);
             let runError = null;
             let run = null;
             try {

package/dist/tools/research/inspect-data-profile.js

@@ -98,6 +98,10 @@ export function createInspectDataProfileTool(pool) {
                 .optional()
                 .describe(`Per-file records per page. Only used when scope is 'files'. Default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}.`),
         }),
+        // `execute` defaults both fields internally, and the hook applies the same
+        // defaults. Without them the ordinary call, which names no field at all,
+        // gives no detail. `page` acts only on the `files` scope, as in `execute`.
+        describeCall: ({ scope, page }) => ((scope ?? "overview") === "files" ? `files (page ${page ?? 1})` : "overview"),
         execute: async (input, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;
             const status = unwrapOrThrow(await loadDataProfileStatus(pool, resourceId));

package/dist/tools/research/literature-reviewer.js

@@ -68,6 +68,7 @@ export function createLiteratureReviewerTool(deps) {
                 "biological features to investigate and the experimental " +
                 "context. The reviewer sees only this — include everything it needs."),
         }),
+        describeCall: "none",
         execute: async ({ brief }, ctx) => {
             const { messages: transcript } = await runAgent(agent, [{ role: "user", content: brief }], forSubAgent(ctx.session, AGENT_ID), {
                 provider: deps.provider,

package/dist/tools/research/search-arxiv.js

@@ -18,6 +18,7 @@ export const searchArxivTool = defineTool({
             .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). ' + "Combined with the query using AND."),
         limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
     }),
+    describeCall: "none",
     execute: async ({ query, categories, limit }, context) => {
         const result = await source.search({ query, ...(categories === undefined ? {} : { categories }), limit }, context.signal);
         if (result.status !== "ok")

package/dist/tools/research/search-github-repos.js

@@ -61,6 +61,7 @@ export function createSearchGithubReposTool(deps) {
             language: z.string().optional().describe('Optional language filter (e.g., "python").'),
             limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
         }),
+        describeCall: "none",
         execute: async ({ query, language, limit }) => {
             const q = language ? `${query} language:${language}` : query;
             const params = new URLSearchParams({

package/dist/tools/research/search-semantic-scholar.js

@@ -24,6 +24,7 @@ export function createSearchSemanticScholarTool(options = {}) {
                 '"reinforcement learning for control" or "feedback stabilisation in oscillators".'),
             limit: z.number().int().min(1).max(20).default(10).describe("Maximum number of results to return (1–20, default 10)."),
         }),
+        describeCall: "none",
         execute: async ({ query, limit }, context) => {
             const result = await source.search(query, limit, context.signal);
             if (result.status !== "ok")

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

@@ -26,6 +26,7 @@ import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 /**
  * Where the list lives when the host mounts the library store at the same path
  * the sandbox does. Hosts that do not — the store is baked into the image and
@@ -187,6 +188,28 @@ export function createListAvailablePackagesTool(deps = {}) {
                 .optional()
                 .describe(`Cap the packages listed. Omit to get the whole set — the store fits well within the ${DEFAULT_LIMIT} ceiling. Ignored when \`names\` is given.`),
         }),
+        // `queryPackages` returns on `names` before it reads another field, thus
+        // the presence check comes first. An empty array is not a presence check.
+        // `names` are exact identifiers a caller checks for, thus they name the
+        // call as they are. A blank query counts as absent, because `queryPackages`
+        // trims the needle and applies no filter when nothing is left.
+        //
+        // A needle rides behind `matching "…"`, because a bare needle reads as a
+        // package name. The needle takes its own bound, thus the emit-site cap
+        // cannot cut inside the mark and leave the quote open. `language` stays a
+        // trailing qualifier, exactly as `execute` treats it.
+        describeCall: ({ names, query, language }) => {
+            if (names !== undefined && names.length > 0)
+                return names.join(", ");
+            const needle = query?.trim();
+            if (needle !== undefined && needle !== "") {
+                const marked = `matching "${capCodePoints(needle, DETAIL_NEEDLE_MAX_LENGTH)}"`;
+                return language === undefined ? marked : `${marked} (${language})`;
+            }
+            if (language !== undefined)
+                return `${language} packages`;
+            return "full package list";
+        },
         execute: async (input) => {
             // An unreadable inventory is an expected environment state — model it as an
             // `available: false` data variant telling the caller the set is UNKNOWN.

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

@@ -27,6 +27,7 @@ import { lstat, readFile, readdir } from "node:fs/promises";
 import { join as hostJoin, posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
+import { capCodePoints, DETAIL_MAX_LENGTH, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { REFERENCE_DATA_CATALOG } from "../../reference-data/catalog.js";
 import { parseReferenceInstallReceipt } from "../../reference-data/receipt.js";
 import { defineTool } from "../define-tool.js";
@@ -510,6 +511,41 @@ export function createListAvailableRefsTool(deps) {
             "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path, and whatever is added shows up on a later call. " +
             "So before you report a gap as permanent, check whether any tool you hold reaches that provisioning path — offer that route if one exists, and call the gap permanent only when none does.",
         inputSchema: ListAvailableRefsInputSchema,
+        // `execute` resolves `path ?? category` for the subtree it inspects, and
+        // it ignores `category` when `path` is present. `query` is an ADDITIVE
+        // filter over that subtree, thus the target keeps naming the call and the
+        // filter rides beside it.
+        //
+        // A needle rides behind `matching "…"`: a bare needle reads as a path, and
+        // a filtered subtree must name both halves, not the target alone. The two
+        // halves join with a space and a word, as `grep` joins its own two halves.
+        // A separator glyph belongs to a host, which owns its line and its own
+        // vocabulary; the harness renders nothing and thus borrows nothing.
+        //
+        // Each half carries its own bound. The emit-site cap cuts the TAIL, and
+        // `path` admits 4096 bytes, thus one long target would swallow the very
+        // filter this detail exists to state. The needle takes a fixed budget, and
+        // the target takes what the bounded filter leaves. Then both halves reach
+        // a reader, and each one marks its own cut.
+        //
+        // A blank value counts as absent, because `execute` treats it that way: it
+        // browses the store root for a blank target, and it applies no filter for a
+        // blank needle. The precedence stays `??` and never `||`, thus a blank
+        // `path` still suppresses `category` exactly as `execute` does.
+        describeCall: ({ path, category, query }) => {
+            const target = path ?? category;
+            const named = target !== undefined && target.trim() !== "" ? target : undefined;
+            const needle = query?.trim();
+            const filter = needle === undefined || needle === "" ? undefined : `matching "${capCodePoints(needle, DETAIL_NEEDLE_MAX_LENGTH)}"`;
+            if (named === undefined)
+                return filter ?? "full reference store";
+            if (filter === undefined)
+                return named;
+            // The budget comes off the rendered filter, never off a count of its
+            // parts, thus it cannot drift from the template above. One code point
+            // pays for the joining space.
+            return `${capCodePoints(named, DETAIL_MAX_LENGTH - [...filter].length - 1)} ${filter}`;
+        },
         execute: async ({ path, category, query, limit }) => {
             // `category` is shorthand for a top-level path; an explicit `path` wins.
             const requestedInput = path ?? category;

package/dist/tools/sandbox/report-blocker.js

@@ -33,6 +33,7 @@ export function createReportBlockerToolFor(deps) {
         id: "report_blocker",
         description: `Terminal. ${deps.blockedWhen} Pass a clear reason. Stop immediately after calling — take no further actions.`,
         inputSchema: ReportBlockerInputSchema,
+        describeCall: "none",
         execute: async (input) => {
             deps.record({ kind: "blocker", reason: input.reason });
             return ok({

package/dist/tools/sandbox/skills.js

@@ -54,6 +54,7 @@ export function createSkillTools(deps) {
             query: z.string().min(1).describe("Keywords to match (e.g. 'PyDESeq2 contrast syntax')."),
             topK: z.number().int().min(1).max(MAX_TOP_K).optional().describe(`Max results to return. Defaults to ${DEFAULT_TOP_K}.`),
         }),
+        describeCall: "none",
         execute: async ({ query, topK }) => {
             if (allowed.size === 0) {
                 return ok({ status: "no_skills" });
@@ -114,6 +115,7 @@ export function createSkillTools(deps) {
             skill: z.string().min(1).describe("Skill name (one of your declared skills)."),
             path: z.string().min(1).describe("File path within the skill, e.g. 'SKILL.md' or 'references/pydeseq2-api.md'."),
         }),
+        describeCall: "none",
         execute: async ({ skill, path }) => {
             if (!allowed.has(skill)) {
                 return ok({ status: "skill_not_declared", skill });

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

@@ -22,6 +22,7 @@ export function createFileStatTool(fs, workingDir) {
             "in bytes. Use before reading to size a file. Missing and out-of-scope " +
             "paths return a data variant, not an error.",
         inputSchema: FileStatInputSchema,
+        describeCall: "none",
         execute: async ({ path }, ctx) => {
             const result = unwrapOrThrow(await fs.stat({ session: ctx.session, path, workingDir }));
             switch (result.kind) {

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

@@ -38,6 +38,8 @@ export const showFileTool = defineTool({
         "Cards render in call order, so to interleave figures with prose alternate `show_user(markdown)` and `show_file` calls " +
         "(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.
+    describeCall: ({ files }) => (files.length === 1 ? files[0].path : `${files.length} files`),
     execute: async (input, ctx) => {
         const card = buildFileReferenceCardData(input);
         // A malformed/traversal path yields no card — an expected outcome the model can self-correct

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

@@ -32,6 +32,7 @@ export function createShowPlanTool(pool) {
                 .describe("Plan ID (`pln-<8hex>`) from `generate_plan` (newly created) or `inspect_run` (each run carries the planId it ran)"),
             title: z.string().optional().describe("Optional card heading; defaults to the plan's own title"),
         }),
+        describeCall: ({ planId }) => planId,
         execute: async ({ planId, title }, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;
             // "Plan not found" / "plan no longer parses" are expected outcomes —

package/dist/workflows/execute-analysis.d.ts

@@ -298,8 +298,12 @@ export interface ExecuteAnalysisDeps {
      * point. Idempotency is the consumer's job, achieved via the deterministic
      * identifiers the events carry, not via step caching. Every call site is
      * guarded so a throwing observer never fails the run.
+     *
+     * Events arrive with the run's `RunSession` from durable workflow input — a
+     * persisting realization needs its credential, scope, and identity.
+     * Implementations may ignore the parameter.
      */
-    readonly emitProvenance?: (event: RunProvenanceEvent) => void;
+    readonly emitProvenance?: (event: RunProvenanceEvent, session: RunSession) => void;
     /**
      * Optional, fire-and-forget observation of the run's live shape, for a host driving a UI.
      *

package/dist/workflows/execute-analysis.js

@@ -87,12 +87,12 @@ function emitStreamPart(part) {
  * swallowed, never corrupt run state — integrity enforcement lives at the
  * host's own ledger, not here.
  */
-function emitProvenanceGuarded(deps, event) {
+function emitProvenanceGuarded(deps, event, session) {
     const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
     if (!deps.emitProvenance)
         return;
     try {
-        deps.emitProvenance(event);
+        deps.emitProvenance(event, session);
     }
     catch (err) {
         logger.error("emitProvenance threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
@@ -437,7 +437,7 @@ export async function runExecuteAnalysisBody(input, deps) {
         planSummary: input.planSummary,
         stepCount: input.steps.length,
         atMs: startedAtMs,
-    });
+    }, input.runSession);
     // Opening snapshot: every step pending. The scheduler's own map does not exist yet, and an
     // empty one yields exactly that — so a host has the run's full shape before the first dispatch
     // rather than learning the step list from whichever transition happens to land first.
@@ -930,7 +930,7 @@ async function runSchedulerLoop(args) {
             status: stepStatus,
             ...(stepDurationMs !== undefined ? { durationMs: stepDurationMs } : {}),
             atMs: settledAtMs,
-        });
+        }, input.runSession);
     }
     await drainBudgetExceededNotifications(budgetExceededChildIds);
     return {
@@ -1000,7 +1000,7 @@ async function collectAndComplete(args) {
         status,
         atMs: terminalAtMs,
         durationMs: terminalAtMs - startedAtMs,
-    });
+    }, input.runSession);
     try {
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateRunStatus(deps.pool, runId, status, failureReason ?? (status === "canceled" && !budgetExceeded ? "external_cancel" : null)));

package/dist/workflows/execute-target-assessment.d.ts

@@ -6,13 +6,16 @@
  *
  *  Phase 0   `phase0Resolve`               — only step allowed to throw
  *                                            (terminates → `target-unresolved`)
- *  Phase 1   14 collectors in parallel     — coverage-envelope failures
+ *  Phase 1   15 collectors in parallel     — coverage-envelope failures
  *  Progress  `emitProgress("deciding")`
  *  Phase 2   2 decisions in parallel       — LLM calls, attempt-numbered
  *  Progress  `emitProgress("fanning_out")`
  *  Phase 3   4 fan-out blocks in parallel  — per-item HTTP, withHost semaphore
  *  Progress  `emitProgress("assembling")`
- *  Phase 4   `phase4Assemble`              — deterministic
+ *  Phase 4   `phase4Assemble`              — aggregation + cached annotator
+ *  Phase 4a  `ta-approval-precedents`      — one openFDA lookup, two projections
+ *  Phase 4b  `assembleSafetyCorroboration` — pure fold, no step of its own
+ *  Phase 4c  `investigateClaims`           — propose / critique / re-verify / converge
  *  Progress  `emitProgress("synthesizing")`
  *  Phase 5a  3 per-section syntheses in parallel
  *  Phase 5b  `dossierRecommendation` sequential
@@ -38,6 +41,7 @@ import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { AgentChat } from "../providers/types.js";
 import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
+import { type ClaimInvestigationConfig } from "./target-assessment/investigation/index.js";
 import { type ProgressPhase } from "./target-assessment/progress.js";
 export declare const ExecuteTargetAssessmentInputSchema: z.ZodObject<{
     assessmentId: z.ZodString;
@@ -91,6 +95,13 @@ export interface ExecuteTargetAssessmentDeps {
     readonly synthesisModel: string;
     /** LLM usage-accounting seam for the assessment's agent loops; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /**
+     * Bounds the claim-investigation phase runs under. Omitted falls back to
+     * `DEFAULT_CLAIM_INVESTIGATION_CONFIG` — the values are cost and termination
+     * bounds, not domain constants, so an embedder wanting a deeper pass sets
+     * its own and the dossier reports what was in force.
+     */
+    readonly claimInvestigation?: Partial<ClaimInvestigationConfig>;
 }
 /**
  * Register the executeTargetAssessment workflow with DBOS. Caller is