@inflexa-ai/harness 0.17.0 → 0.18.0

package/dist/tools/report-authoring/authoring-tools.js

@@ -0,0 +1,352 @@
+/**
+ * The authoring tool surface over the draft operations.
+ *
+ * The factory closes over a private draft holder and the pinned snapshot. It gives eight tools and a
+ * read of the current draft. The tools read no ambient state, thus two factories hold two independent
+ * drafts.
+ *
+ * Each tool maps its flat input onto a core operation, and it applies the pure operation. The holder
+ * swaps only on a landed operation. A refused operation returns typed data in the ok channel, and the
+ * error channel stays for an unexpected failure.
+ *
+ * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
+ * nested union. A conflict between the flat fields refuses before the core runs.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
+import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
+import { finishDraft } from "../../report-model/draft-finish.js";
+import { DraftBlockSchema } from "../../report-model/draft.js";
+import { defineTool } from "../define-tool.js";
+/**
+ * The block payload.
+ *
+ * The published JSON Schema carries the whole draft grammar, because a tool is self-describing at attach
+ * time and the schema is the only place where the model learns the shape of the eight block kinds. A bare
+ * `z.unknown()` emits the empty schema, which tells the model nothing and leaves it to discover each
+ * required field through one refusal at a time.
+ *
+ * The `z.unknown()` member keeps the runtime parse permissive. Thus a malformed payload still reaches the
+ * core, which parses it with the same grammar and refuses `malformed-block` as typed data in the ok
+ * channel. A strict input schema would turn that designed refusal into a hard input-validation error from
+ * the loop.
+ */
+const blockPayload = z.union([DraftBlockSchema, z.unknown()]);
+/**
+ * A flat field that the model can leave out.
+ *
+ * Nullish, and not optional. A model that must choose one of four destination fields routinely sends
+ * `null` for the three it does not use, and strict function calling requires every declared key to be
+ * present. Under `.optional()` each of those nulls fails the input parse, and the block never lands.
+ */
+const absentable = (schema) => schema.nullish();
+/** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
+const addBlockInput = z.object({
+    block: blockPayload,
+    parentId: absentable(z.string()),
+    place: absentable(z.enum(["start", "end"])),
+    before: absentable(z.string()),
+    after: absentable(z.string()),
+});
+/**
+ * The change payload is a title for a section target, or a block for an atom target, and exactly one of
+ * the two. Both fields are absentable, because a section retitle names no block. Zod 4 treats a bare
+ * `z.unknown()` as a required key, thus an optional marker is what makes the retitle call representable.
+ */
+const changeBlockInput = z.object({
+    targetId: z.string(),
+    title: absentable(z.string()),
+    block: blockPayload.optional(),
+});
+const removeBlockInput = z.object({
+    targetId: z.string(),
+});
+const moveBlockInput = z.object({
+    targetId: z.string(),
+    parentId: absentable(z.string()),
+    place: absentable(z.enum(["start", "end"])),
+    before: absentable(z.string()),
+    after: absentable(z.string()),
+});
+const readOutlineInput = z.object({});
+/** The read names its target with the same field name as each mutation, thus one id key serves them all. */
+const readBlockInput = z.object({
+    targetId: z.string(),
+});
+const setTitleInput = z.object({
+    title: z.string().min(1),
+});
+const finishDraftInput = z.object({});
+/** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
+function given(value) {
+    return value ?? undefined;
+}
+/**
+ * Map the flat destination fields onto the core destination.
+ *
+ * Two anchors, or an anchor beside a place, name two places at one time. Thus the map refuses with
+ * `conflicting-destination`, and the detail names the conflict. An anchor implies its own parent, thus a
+ * place beside an anchor is a contradiction and not a refinement.
+ *
+ * The reason is not `unknown-target`, which means that no block holds a named id. A conflict is a fault in
+ * the shape of the call, and the repair is to drop one field. An agent that reads `unknown-target` instead
+ * goes back to the outline for a better id, finds the ids were already correct, and sends the same
+ * conflicting pair again.
+ */
+function toDestination(input) {
+    const parentId = given(input.parentId);
+    const place = given(input.place);
+    const before = given(input.before);
+    const after = given(input.after);
+    if (before !== undefined && after !== undefined) {
+        return err({ reason: "conflicting-destination", detail: "a destination names `before` or `after`, not both" });
+    }
+    const hasAnchor = before !== undefined || after !== undefined;
+    if (hasAnchor && place !== undefined) {
+        return err({ reason: "conflicting-destination", detail: "a destination names an anchor or a `place`, not both" });
+    }
+    let resolvedPlace;
+    if (before !== undefined) {
+        resolvedPlace = { before };
+    }
+    else if (after !== undefined) {
+        resolvedPlace = { after };
+    }
+    else {
+        resolvedPlace = place;
+    }
+    return ok({ parentId, place: resolvedPlace });
+}
+/**
+ * Map the flat change fields onto the core change operation.
+ *
+ * A change names a title or a block, and exactly one of the two. Neither field and both fields each name
+ * an ambiguous change. Thus the map refuses with `payload-kind-mismatch`.
+ */
+function toChangeOperation(input) {
+    const title = given(input.title);
+    const block = given(input.block);
+    if (title !== undefined && block !== undefined) {
+        return err({ reason: "payload-kind-mismatch", detail: "a change names a `title` or a `block`, not both" });
+    }
+    if (title !== undefined) {
+        return ok({ targetId: input.targetId, title });
+    }
+    if (block !== undefined) {
+        return ok({ targetId: input.targetId, block: decodeBlockPayload(block) });
+    }
+    return err({ reason: "payload-kind-mismatch", detail: "a change names a `title` or a `block`" });
+}
+/**
+ * Give the block payload as the core expects it, and decode a double-encoded one.
+ *
+ * A model routinely sends a nested object as a `JSON.stringify` string. The loop repairs that at its own
+ * input boundary, but only for a schema that rejects the string, and this payload accepts any value so
+ * that a malformed block can come back as a typed refusal. Thus the decode happens here. A string that is
+ * not JSON passes through as it is, and the core refuses it as a malformed block.
+ */
+function decodeBlockPayload(block) {
+    if (typeof block !== "string") {
+        return block;
+    }
+    try {
+        return JSON.parse(block);
+    }
+    catch {
+        return block;
+    }
+}
+/** Read the `kind` of an untyped block payload, or `undefined` when the payload names none. */
+function readKind(block) {
+    return readStringField(block, "kind");
+}
+/** Read the `id` of an untyped block payload, or `undefined` when the payload names none. */
+function readId(block) {
+    return readStringField(block, "id");
+}
+function readStringField(block, field) {
+    if (block !== null && typeof block === "object") {
+        const value = block[field];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * The id of the section that holds a block, or `undefined` when the block sits at the root.
+ *
+ * The two cases are not distinguishable from the value alone, thus a caller that needs to tell "the root"
+ * from "no such block" tests the block itself first.
+ */
+function holderIdOf(document, blockId) {
+    return locate(document, blockId)?.parent?.id;
+}
+/** Read the child order of one container out of a document. */
+function containerIn(document, parentId) {
+    if (parentId === undefined) {
+        return { children: childOutline(document.sections, 0) };
+    }
+    const located = locate(document, parentId);
+    // A parent id reaches here only from a landed operation, which already resolved it to a section. The
+    // empty fall-back keeps the read total rather than asserting that.
+    const children = located !== undefined && located.block.kind === "section" ? located.block.blocks : [];
+    return { parentId, children: childOutline(children, located?.path.length ?? 0) };
+}
+/**
+ * Every tool of this surface runs inline.
+ *
+ * The draft is closure memory with no durable backing. A step-mode tool goes through `DBOS.runStep`, which
+ * caches the result of a step and replays it without running the body. A replay after a host restart would
+ * hand the agent the cached `applied: true` outline of each landed operation while the rebuilt closure
+ * holds an empty draft, and the finish would then report an empty document for a report that the
+ * transcript shows as complete. Inline mode keeps the tool result and the draft in one lifetime.
+ */
+const AUTHORING_EXECUTION_MODE = "inline";
+/**
+ * Make the eight authoring tools over one draft.
+ *
+ * The holder is a private `let`. Each tool reads the holder at call time, thus a landing through one tool
+ * shows in the next call of every tool. The holder swaps only inside `land`, thus a refused operation
+ * leaves the draft as it was.
+ */
+export function createReportAuthoringTools(state) {
+    const snapshot = state.snapshot;
+    let draft = state.initialDraft ?? { title: "", sections: [] };
+    /**
+     * Swap the holder on a landing, and report the containers that the operation changed.
+     *
+     * `holders` names them by id, and it reads the draft as it was and the draft as it becomes, because a
+     * removed block has a holder only in the first and an added block has one only in the second. The
+     * child order comes out of `next` in either case.
+     */
+    const land = (result, holders) => result.match((next) => {
+        const previous = draft;
+        draft = next;
+        // A move inside one container names the same holder two times.
+        const unique = [...new Set(holders(previous, next))];
+        return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
+    }, (refusal) => ({ applied: false, refusal }));
+    const refuse = (refusal) => ({ applied: false, refusal });
+    const add_block = defineTool({
+        id: "add_block",
+        description: "Add one block to the draft. The `block` schema gives the eight kinds and the fields of each one. " +
+            "You choose the `id` of the block, and it must be unique in the draft. " +
+            "Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
+            "The root admits a section only, and an atom needs a section as its parent.",
+        inputSchema: addBlockInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => {
+            const kind = readKind(decodeBlockPayload(input.block));
+            return kind !== undefined ? `add ${kind}` : "add a block";
+        },
+        execute: async (input) => {
+            const destination = toDestination(input);
+            if (destination.isErr()) {
+                return ok(refuse(destination.error));
+            }
+            const block = decodeBlockPayload(input.block);
+            const addedId = readId(block);
+            return ok(land(addBlock(draft, { block, destination: destination.value }, snapshot), (_previous, next) => [
+                addedId === undefined ? undefined : holderIdOf(next, addedId),
+            ]));
+        },
+    });
+    const change_block = defineTool({
+        id: "change_block",
+        description: "Change one block by its id. Give a `title` to retitle a section, or a `block` to replace an atom, and never both. " +
+            "The change keeps the id of the target, thus the `id` of the payload does not matter. A kind change is permitted.",
+        inputSchema: changeBlockInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => `change ${input.targetId}`,
+        execute: async (input) => {
+            const operation = toChangeOperation(input);
+            if (operation.isErr()) {
+                return ok(refuse(operation.error));
+            }
+            return ok(land(changeBlock(draft, operation.value, snapshot), (_previous, next) => [holderIdOf(next, input.targetId)]));
+        },
+    });
+    const remove_block = defineTool({
+        id: "remove_block",
+        description: "Remove one block by its id. A removed section takes its whole subtree with it, and the id is free for a later add.",
+        inputSchema: removeBlockInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => `remove ${input.targetId}`,
+        execute: async (input) => ok(land(removeBlock(draft, { targetId: input.targetId }, snapshot), (previous) => [holderIdOf(previous, input.targetId)])),
+    });
+    const move_block = defineTool({
+        id: "move_block",
+        description: "Move one block by its id to a new destination. Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
+            "A section cannot move into its own subtree.",
+        inputSchema: moveBlockInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => `move ${input.targetId}`,
+        execute: async (input) => {
+            const destination = toDestination(input);
+            if (destination.isErr()) {
+                return ok(refuse(destination.error));
+            }
+            return ok(land(moveBlock(draft, { targetId: input.targetId, destination: destination.value }, snapshot), (previous, next) => [
+                holderIdOf(previous, input.targetId),
+                holderIdOf(next, input.targetId),
+            ]));
+        },
+    });
+    const set_title = defineTool({
+        id: "set_title",
+        description: "Set the title of the report document. A draft starts with no title, and a document needs one. " +
+            "The title names the whole report, and it is not the title of a section.",
+        inputSchema: setTitleInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => `title the report ${input.title}`,
+        // The title sits on the document, thus no container changes its child order.
+        execute: async (input) => ok(land(ok(setTitle(draft, input.title)), () => [])),
+    });
+    const read_outline = defineTool({
+        id: "read_outline",
+        description: "Read the outline of the draft. Each entry gives the id, the kind, the nesting depth, and a short label. " +
+            "A label that ends with the character … is clipped. Use the outline as the primary view of the draft, " +
+            "and read one block when the label is not enough.",
+        inputSchema: readOutlineInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        // The input carries no field, thus a hook can only restate the name of the tool.
+        describeCall: "none",
+        execute: async () => ok({ outline: buildOutline(draft) }),
+    });
+    const read_block = defineTool({
+        id: "read_block",
+        description: "Read one block by its id. An atom gives the full block with its bindings. A section gives its title and the id of each child, " +
+            "because the outline already names every block under it. Use it when the outline label is not enough.",
+        inputSchema: readBlockInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        describeCall: (input) => `read ${input.targetId}`,
+        execute: async (input) => {
+            const block = readBlock(draft, input.targetId);
+            const result = block !== undefined ? { found: true, block } : { found: false };
+            return ok(result);
+        },
+    });
+    const finish_draft = defineTool({
+        id: "finish_draft",
+        description: "Finish the draft. The result gives each completeness gap, or the valid report document, and each advisory warning. " +
+            "Use it to make sure that the draft passes the whole document schema, the id rule, and the structural tier.",
+        inputSchema: finishDraftInput,
+        executionMode: AUTHORING_EXECUTION_MODE,
+        // The input carries no field, thus a hook can only restate the name of the tool.
+        describeCall: "none",
+        execute: async () => ok(finishDraft(draft, snapshot)),
+    });
+    return {
+        add_block,
+        change_block,
+        remove_block,
+        move_block,
+        set_title,
+        read_outline,
+        read_block,
+        finish_draft,
+        currentDraft: () => draft,
+    };
+}

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

@@ -344,6 +344,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 +417,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 +672,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

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)));