@inflexa-ai/harness 0.16.0 → 0.18.0

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

@@ -27,6 +27,7 @@ import { genePreclinicalProfileTool } from "../bio/gene-preclinical-profile.js";
 import { lookupAnnotationTool } from "../bio/lookup-annotation.js";
 import { searchGeneTool } from "../bio/search-gene.js";
 import { searchInteractionsTool } from "../bio/search-interactions.js";
+import { createResolveCitationTool } from "./resolve-citation.js";
 /** Sub-agent identity — appended to `callPath`, set as `agentId`. */
 const AGENT_ID = "literature-reviewer";
 /** Multi-tool research budget — search → read → synthesize over many genes. */
@@ -40,6 +41,7 @@ export function createLiteratureReviewerTool(deps) {
         lookupAnnotationTool,
         searchInteractionsTool,
         ncbi.pubmed,
+        createResolveCitationTool(deps.citationResolver),
         chemDb.drugGeneInteractions,
         genePreclinicalProfileTool,
     ];
@@ -66,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/resolve-citation.d.ts

@@ -0,0 +1,3 @@
+import { type CitationResolver } from "../../citations/types.js";
+import { type Tool } from "../define-tool.js";
+export declare function createResolveCitationTool(resolver: CitationResolver): Tool;

package/dist/tools/research/resolve-citation.js

@@ -0,0 +1,15 @@
+import { ok } from "neverthrow";
+import { CitationInputSchema } from "../../citations/types.js";
+import { defineTool } from "../define-tool.js";
+export function createResolveCitationTool(resolver) {
+    return defineTool({
+        id: "resolve_citation",
+        description: "Verify one supplied citation against applicable bibliographic authorities. " +
+            "Use this for 'does this reference exist and does its metadata agree?', not for topical literature discovery. " +
+            "Returns source-labelled records, field comparisons, conflicts, coverage, and one of verified, metadata_mismatch, " +
+            "not_found, unverifiable, or inconclusive. Source failure never becomes not_found.",
+        inputSchema: CitationInputSchema,
+        describeCall: ({ citation }) => `verify ${citation}`,
+        execute: async (input, ctx) => ok(await resolver.resolveOne(input, { signal: ctx.signal })),
+    });
+}

package/dist/tools/research/search-arxiv.d.ts

@@ -1,10 +1,6 @@
-/**
- * Search arXiv for preprints. Returns Atom XML which we parse without a
- * dependency. arXiv is the primary source for ML / physics / math /
- * control-theory preprints; Semantic Scholar lags it by months.
- *
- * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
- */
+/** Search arXiv for preprints through the shared authority client. */
+import { type ArxivPaper } from "../../literature/sources/arxiv.js";
+export { parseArxivAtom, type ArxivPaper } from "../../literature/sources/arxiv.js";
 type SearchArxivOutput = {
     success: false;
     error: string;
@@ -13,20 +9,8 @@ type SearchArxivOutput = {
     success: true;
     papers: ArxivPaper[];
 };
-export interface ArxivPaper {
-    id: string;
-    title: string;
-    abstract: string;
-    authors: string[];
-    published: string;
-    categories: string[];
-    url: string;
-    pdfUrl?: string;
-}
-export declare function parseArxivAtom(xml: string): ArxivPaper[];
 export declare const searchArxivTool: import("../define-tool.js").Tool<{
     query: string;
     limit: number;
     categories?: string[] | undefined;
 }, SearchArxivOutput>;
-export {};

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

@@ -1,96 +1,10 @@
-/**
- * Search arXiv for preprints. Returns Atom XML which we parse without a
- * dependency. arXiv is the primary source for ML / physics / math /
- * control-theory preprints; Semantic Scholar lags it by months.
- *
- * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
- */
+/** Search arXiv for preprints through the shared authority client. */
 import { ok } from "neverthrow";
 import { z } from "zod";
+import { createArxivSource } from "../../literature/sources/arxiv.js";
 import { defineTool } from "../define-tool.js";
-import { apiFetch, describeApiError } from "../lib/api-utils.js";
-const BASE_URL = "https://export.arxiv.org/api/query";
-const stripCdata = (s) => s.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1");
-const decodeXmlEntities = (s) => s
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
-    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10)))
-    .replace(/&amp;/g, "&"); // amp last so we don't double-decode
-const collapseWs = (s) => decodeXmlEntities(stripCdata(s)).replace(/\s+/g, " ").trim();
-const extractEntries = (xml) => {
-    const re = /<entry\b[^>]*>([\s\S]*?)<\/entry>/g;
-    const out = [];
-    let m;
-    while ((m = re.exec(xml)) !== null)
-        out.push(m[1]);
-    return out;
-};
-const firstMatch = (entry, tag) => {
-    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`);
-    const m = entry.match(re);
-    return m?.[1];
-};
-const allMatches = (entry, tag) => {
-    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`, "g");
-    const out = [];
-    let m;
-    while ((m = re.exec(entry)) !== null)
-        out.push(m[1]);
-    return out;
-};
-const linkAttr = (entry, predicate) => {
-    const re = /<link\b([^>]*)\/>/g;
-    let m;
-    while ((m = re.exec(entry)) !== null) {
-        if (predicate(m[1])) {
-            const hrefMatch = m[1].match(/href="([^"]+)"/);
-            if (hrefMatch)
-                return hrefMatch[1];
-        }
-    }
-    return undefined;
-};
-const categoryTerms = (entry) => {
-    const re = /<category\b([^>]*)\/>/g;
-    const out = [];
-    let m;
-    while ((m = re.exec(entry)) !== null) {
-        const termMatch = m[1].match(/term="([^"]+)"/);
-        if (termMatch)
-            out.push(termMatch[1]);
-    }
-    return out;
-};
-export function parseArxivAtom(xml) {
-    return extractEntries(xml).flatMap((entry) => {
-        const idRaw = firstMatch(entry, "id");
-        const title = firstMatch(entry, "title");
-        if (!idRaw || !title)
-            return [];
-        const idMatch = idRaw.match(/abs\/(.+)$/);
-        const authors = allMatches(entry, "author")
-            .map((a) => firstMatch(a, "name"))
-            .filter((n) => !!n)
-            .map(collapseWs);
-        const htmlUrl = linkAttr(entry, (a) => /rel="alternate"/.test(a) && /type="text\/html"/.test(a));
-        const pdfUrl = linkAttr(entry, (a) => /title="pdf"/.test(a));
-        return [
-            {
-                id: idMatch?.[1] ?? collapseWs(idRaw),
-                title: collapseWs(title),
-                abstract: collapseWs(firstMatch(entry, "summary") ?? ""),
-                authors,
-                published: collapseWs(firstMatch(entry, "published") ?? ""),
-                categories: categoryTerms(entry),
-                url: htmlUrl ?? collapseWs(idRaw),
-                pdfUrl,
-            },
-        ];
-    });
-}
+export { parseArxivAtom } from "../../literature/sources/arxiv.js";
+const source = createArxivSource({ maxRetries: 3, retryDelayMs: 1_000, timeoutMs: 90_000 });
 export const searchArxivTool = defineTool({
     id: "search_arxiv",
     description: "Search arXiv for preprints in ML, physics, math, control theory, " +
@@ -104,20 +18,11 @@ 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)."),
     }),
-    execute: async ({ query, categories, limit }) => {
-        const catPart = categories && categories.length > 0 ? ` AND (${categories.map((c) => `cat:${c}`).join(" OR ")})` : "";
-        const params = new URLSearchParams({
-            search_query: `all:${query}${catPart}`,
-            max_results: String(limit),
-            sortBy: "relevance",
-            sortOrder: "descending",
-        });
-        const res = await apiFetch(`${BASE_URL}?${params}`, {
-            parseAs: "text",
-        });
-        if (res.isErr()) {
-            return ok({ success: false, error: describeApiError(res.error), papers: [] });
-        }
-        return ok({ success: true, papers: parseArxivAtom(res.value) });
+    describeCall: "none",
+    execute: async ({ query, categories, limit }, context) => {
+        const result = await source.search({ query, ...(categories === undefined ? {} : { categories }), limit }, context.signal);
+        if (result.status !== "ok")
+            return ok({ success: false, error: result.detail, papers: [] });
+        return ok({ success: true, papers: result.value });
     },
 });

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.d.ts

@@ -1,33 +1,8 @@
-/**
- * Search Semantic Scholar Graph API for academic papers across all
- * sciences. No API key required; rate-limited but reasonable for agent
- * use. Used by the analogical-reasoner for cross-domain analogical search.
- *
- * Same wire call and envelope as the legacy tool, packaged as `defineTool`.
- * Stateless HTTP; no deps.
- */
-export interface SemanticScholarPaper {
-    id: string;
-    title: string;
-    abstract?: string;
-    year?: number;
-    venue?: string;
-    citationCount?: number;
-    url?: string;
-    authors: string[];
-    externalIds?: Record<string, string>;
-}
-type SearchSemanticScholarOutput = {
-    success: false;
-    error: string;
-    papers: SemanticScholarPaper[];
-} | {
-    success: true;
-    papers: SemanticScholarPaper[];
-};
-export declare function parseSemanticScholarResponse(raw: unknown): SemanticScholarPaper[];
-export declare const searchSemanticScholarTool: import("../define-tool.js").Tool<{
-    query: string;
-    limit: number;
-}, SearchSemanticScholarOutput>;
-export {};
+/** Search Semantic Scholar through the shared authority client. */
+import { type SemanticScholarSearchPaper } from "../../literature/sources/semantic-scholar.js";
+import { type Tool } from "../define-tool.js";
+export { parseSemanticScholarResponse } from "../../literature/sources/semantic-scholar.js";
+export type SemanticScholarPaper = SemanticScholarSearchPaper;
+export declare function createSearchSemanticScholarTool(options?: {
+    readonly apiKey?: string;
+}): Tool;

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

@@ -1,93 +1,35 @@
-/**
- * Search Semantic Scholar Graph API for academic papers across all
- * sciences. No API key required; rate-limited but reasonable for agent
- * use. Used by the analogical-reasoner for cross-domain analogical search.
- *
- * Same wire call and envelope as the legacy tool, packaged as `defineTool`.
- * Stateless HTTP; no deps.
- */
+/** Search Semantic Scholar through the shared authority client. */
 import { ok } from "neverthrow";
 import { z } from "zod";
+import { createSemanticScholarSource } from "../../literature/sources/semantic-scholar.js";
 import { defineTool } from "../define-tool.js";
-import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
-const BASE_URL = "https://api.semanticscholar.org/graph/v1";
-const DEFAULT_FIELDS = "paperId,title,abstract,year,venue,citationCount,url,authors,externalIds";
-// Raw Semantic Scholar wire shape, validated at the fetch boundary. Every field
-// is optional — `parseSemanticScholarResponse` already filters/coerces defensively,
-// so a partial-but-valid response must still parse; `externalIds` values stay
-// unconstrained (`z.unknown`) since the mapper only checks the container is an object.
-// The scalar fields are also `.nullable()`: Semantic Scholar sends an explicit
-// `null` for a missing abstract/year/venue/url/externalIds (very common), which a
-// bare `.optional()` would reject — failing the whole `data` array on one such paper.
-const SemanticScholarResponseSchema = z.object({
-    data: z
-        .array(z.object({
-        paperId: z.string().optional(),
-        title: z.string().optional(),
-        abstract: z.string().nullable().optional(),
-        year: z.number().nullable().optional(),
-        venue: z.string().nullable().optional(),
-        citationCount: z.number().nullable().optional(),
-        url: z.string().nullable().optional(),
-        authors: z.array(z.object({ name: z.string().nullable().optional() })).optional(),
-        externalIds: z.record(z.string(), z.unknown()).nullable().optional(),
-    }))
-        .optional(),
-});
-export function parseSemanticScholarResponse(raw) {
-    const data = raw?.data;
-    if (!Array.isArray(data))
-        return [];
-    return data
-        .filter((p) => typeof p === "object" && p !== null && "paperId" in p && "title" in p)
-        .map((p) => {
-        const authors = Array.isArray(p.authors)
-            ? p.authors.map((a) => a?.name).filter((n) => typeof n === "string")
-            : [];
-        return {
-            id: String(p.paperId),
-            title: String(p.title),
-            abstract: typeof p.abstract === "string" ? p.abstract : undefined,
-            year: typeof p.year === "number" ? p.year : undefined,
-            venue: typeof p.venue === "string" ? p.venue : undefined,
-            citationCount: typeof p.citationCount === "number" ? p.citationCount : undefined,
-            url: typeof p.url === "string" ? p.url : undefined,
-            authors,
-            externalIds: p.externalIds && typeof p.externalIds === "object" ? p.externalIds : undefined,
-        };
+export { parseSemanticScholarResponse } from "../../literature/sources/semantic-scholar.js";
+export function createSearchSemanticScholarTool(options = {}) {
+    const source = createSemanticScholarSource({
+        maxRetries: 3,
+        retryDelayMs: 1_000,
+        timeoutMs: 90_000,
+        ...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+    });
+    return defineTool({
+        id: "search_semantic_scholar",
+        description: "Search Semantic Scholar for academic papers across all sciences " +
+            "(biology, ML, physics, math, economics, engineering, etc.). Returns " +
+            "paper id, title, abstract, year, venue, citation count, authors, and " +
+            "external IDs (DOI, ArXiv). Best for cross-domain analogical search.",
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("Free-text query. Use natural language phrases such as " +
+                '"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")
+                return ok({ success: false, error: result.detail, papers: [] });
+            return ok({ success: true, papers: result.value });
+        },
     });
 }
-export const searchSemanticScholarTool = defineTool({
-    id: "search_semantic_scholar",
-    description: "Search Semantic Scholar for academic papers across all sciences " +
-        "(biology, ML, physics, math, economics, engineering, etc.). Returns " +
-        "paper id, title, abstract, year, venue, citation count, authors, and " +
-        "external IDs (DOI, ArXiv). Best for cross-domain analogical search.",
-    inputSchema: z.object({
-        query: z
-            .string()
-            .describe("Free-text query. Use natural language phrases such as " + '"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)."),
-    }),
-    execute: async ({ query, limit }) => {
-        const params = new URLSearchParams({
-            query,
-            limit: String(limit),
-            fields: DEFAULT_FIELDS,
-        });
-        const apiKey = process.env.SEMANTIC_SCHOLAR_API_KEY;
-        const headers = {};
-        if (apiKey)
-            headers["x-api-key"] = apiKey;
-        const res = await apiFetchValidated(`${BASE_URL}/paper/search?${params}`, SemanticScholarResponseSchema, {
-            headers,
-        });
-        if (res.isErr()) {
-            return ok({ success: false, error: describeApiError(res.error), papers: [] });
-        }
-        return ok({
-            success: true,
-            papers: parseSemanticScholarResponse(res.value),
-        });
-    },
-});

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";
@@ -318,9 +319,8 @@ async function scanStore(root, relative, recursive = false) {
     const entries = [];
     let scanned = 0;
     let pathBytes = 0;
-    let truncated = false;
     const { values: children, cut } = await cappedEntries(target, Math.min(MAX_ENTRIES + 2, MAX_SCANNED_ENTRIES));
-    truncated = cut;
+    let truncated = cut;
     for (const child of children) {
         const childRelative = relative === "." ? child.name : `${relative}/${child.name}`;
         if (childRelative === ".inflexa" || childRelative.startsWith(".inflexa/") || childRelative === "registry.json")
@@ -511,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

@@ -64,6 +64,7 @@ import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { CitationResolver } from "../citations/types.js";
 import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
@@ -277,6 +278,8 @@ export interface ExecuteAnalysisDeps {
     readonly synthesisModel: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** Shared resolver for the literature reviewer used during synthesis. */
+    readonly citationResolver: CitationResolver;
     /** Run-level billing-bracket seam (managed: external bracket; OSS: no-op). */
     readonly runCharge: RunCharge;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
@@ -295,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) });
@@ -320,6 +320,7 @@ export function synthesizeFindings(args) {
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
         synthesisModel: deps.synthesisModel,
         bioKeys: deps.bioKeys,
+        citationResolver: deps.citationResolver,
         usageRecorder: deps.usageRecorder,
     }, {
         analysisId,
@@ -436,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.
@@ -929,7 +930,7 @@ async function runSchedulerLoop(args) {
             status: stepStatus,
             ...(stepDurationMs !== undefined ? { durationMs: stepDurationMs } : {}),
             atMs: settledAtMs,
-        });
+        }, input.runSession);
     }
     await drainBudgetExceededNotifications(budgetExceededChildIds);
     return {
@@ -999,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)));