@inflexa-ai/harness 0.14.2 → 0.15.1

package/dist/tasks/data-profile-activity.d.ts

@@ -20,6 +20,7 @@
  * no terminal at all.
  */
 import type { Logger } from "../lib/logger.js";
+import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 /**
  * Writes one part to the run-event stream. Injected rather than imported so this
  * module stays free of the durability engine and so a test can record what a
@@ -51,8 +52,19 @@ export interface ProfileActivityEmitter {
     sandboxInit(): Promise<void>;
     /** Reported once the sandbox is ready, covering the gap before the agent's first tool call. */
     agentStarting(): Promise<void>;
-    /** Reported per tool call the profiler agent makes, phrased by the shared translator. */
-    forTool(name: string, input: unknown): Promise<void>;
+    /**
+     * Reported per tool call the profiler agent makes, phrased by the shared
+     * translator.
+     *
+     * `resolveDetail` is built over the profiler agent's own tool list, so the
+     * phrase comes from the called tool's `describeCall` hook. It is passed per
+     * call rather than held by the emitter because the emitter exists before the
+     * agent does — `sandboxInit` is reported before the sandbox the agent's tools
+     * are bound to. The call site supplies a RESOLVER, never a phrase: the
+     * phrases are this capability's observable contract, and a call site that
+     * composed its own is a call site that can drift from it.
+     */
+    forTool(name: string, input: unknown, resolveDetail?: ToolDetailResolver): Promise<void>;
     /** Reported for the vector-store pass that indexes per-file descriptions. */
     indexing(): Promise<void>;
     /** The success terminal. Emitted only after the terminal ledger write has landed. */

package/dist/tasks/data-profile-activity.js

@@ -48,7 +48,7 @@ export function createProfileActivityEmitter(write, frame, logger) {
     return {
         sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
         agentStarting: () => emit("executing", "Running data-profiler"),
-        forTool: (name, input) => emit("executing", activityForTool(name, input)),
+        forTool: (name, input, resolveDetail) => emit("executing", activityForTool(name, input, resolveDetail)),
         indexing: () => emit("indexing", "Indexing input descriptions for search"),
         complete: () => emit("complete", "Profile complete"),
         failed: (reason) => emit("failed", reason),

package/dist/tasks/data-profile.d.ts

@@ -23,6 +23,7 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { SandboxClient } from "../sandbox/client.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
@@ -53,6 +54,8 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
     readonly embedding: EmbeddingProvider;
     /** Absolute path to the skills tree (one subdirectory per skill). */
     readonly skillsDir: string;
+    /** LLM usage-accounting seam for the profiler agent loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -26,6 +26,7 @@ import { durableStep } from "../loop/run-step.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { defineTool } from "../tools/define-tool.js";
+import { createDetailResolver } from "../tools/detail-resolver.js";
 import { renderWorkspace } from "../prompts/briefing.js";
 import { toSandboxPath } from "../workspace/paths.js";
 import { estimateDataProfileResources } from "../sandbox/estimate-data-profile-resources.js";
@@ -36,8 +37,9 @@ import { ProfilerOutputSchema } from "../schemas/data-profile-schemas.js";
 import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
 import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
-/** Synthetic run/step literal for the data-profile workflow. */
-const DATA_PROFILE_RUN_LITERAL = "data-profile";
+// The run literal is declared in `contracts/` — a consumer reads it back off recorded usage, and this
+// module is unimportable to one that only wants the string (see the constant's own doc).
+import { DATA_PROFILE_RUN_LITERAL } from "../contracts/data-profile.js";
 const DATA_PROFILE_STEP_LITERAL = "profile";
 const DATA_PROFILE_AGENT_ID = "data-profiler";
 /** Sandbox-server exec budget for the profile run. */
@@ -277,6 +279,9 @@ export async function runDataProfileBody(input, deps) {
             });
             const baseAgent = createDataProfilerAgent(sandboxAgentDeps);
             const agentDef = { ...baseAgent, tools: [...baseAgent.tools, submitProfileTool] };
+            // The profiler's own roster, `submit_profile` included, so every call it
+            // makes is phrased by the tool that was called.
+            const resolveDetail = createDetailResolver(agentDef.tools, logger);
             const signal = new AbortController().signal;
             // Covers the gap between a ready sandbox and the agent's first tool call, which would
             // otherwise still read as `Starting sandbox` long after the container was up. The run
@@ -294,10 +299,11 @@ export async function runDataProfileBody(input, deps) {
                 // counter and desynchronise the recorded sequence on replay.
                 emit: async (event) => {
                     if (event.type === "tool-started")
-                        await activity.forTool(event.name, event.input);
+                        await activity.forTool(event.name, event.input, resolveDetail);
                 },
                 runStep: durableStep,
                 resolved: () => capturedProfile !== null,
+                usageRecorder: deps.usageRecorder,
             }, {
                 tools: [submitProfileTool],
                 nudge: "You stopped without calling submit_profile, so no profile was " +

package/dist/tools/bio/pubmed.js

@@ -125,6 +125,21 @@ export function createPubMedTool(deps) {
             "`outline` from the first call and re-request the specific `sections` you need rather than raising maxChars. " +
             "available: false is an expected outcome, not an error — do not retry it.",
         inputSchema,
+        // One tool, three jobs. The action alone would still render three
+        // different searches identically, so each action names its own subject:
+        // the query, how many articles, or which article.
+        describeCall: (input) => {
+            switch (input.action) {
+                case "search":
+                    return `search ${input.query ?? ""}`;
+                case "details": {
+                    const count = input.pmids?.length ?? 0;
+                    return `details for ${count} ${count === 1 ? "article" : "articles"}`;
+                }
+                case "fulltext":
+                    return `fulltext ${input.pmcId ?? ""}`;
+            }
+        },
         execute: async (input) => {
             switch (input.action) {
                 case "search":

package/dist/tools/bio/search-gene.js

@@ -5,6 +5,12 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { lookupGenes } from "../lib/ensembl-client.js";
+/**
+ * How many symbols a detail names before it switches to a count plus a sample.
+ * Eight symbols of typical length stay well inside the emit-site cap, so the
+ * listed form is never the thing that trips it.
+ */
+const SYMBOLS_LISTED_IN_FULL = 8;
 export const searchGeneTool = defineTool({
     id: "search_gene",
     description: "Resolve gene symbols against Ensembl — the identifier step other tools depend on. Per symbol: Ensembl gene ID (ENSG…), coordinates, strand, " +
@@ -14,5 +20,11 @@ export const searchGeneTool = defineTool({
         symbols: z.array(z.string()).min(1).max(200).describe("Gene symbols to look up (e.g. ['BRCA1', 'TP53'])"),
         species: z.string().default("homo_sapiens").describe("Species name (e.g. 'homo_sapiens', 'mus_musculus')"),
     }),
+    // The symbols are the call. A large batch is summarized here rather than
+    // left to the emit-site cap: that cap cuts at a character, so a 200-symbol
+    // join arrives ending in `TP5` — a fragment that reads as a real symbol and
+    // says nothing about how many were dropped. The count leads, so a batch is
+    // legible as a batch even when the sample after it is itself trimmed.
+    describeCall: ({ symbols }) => symbols.length <= SYMBOLS_LISTED_IN_FULL ? symbols.join(", ") : `${symbols.length} genes: ${symbols.slice(0, SYMBOLS_LISTED_IN_FULL).join(", ")}, …`,
     execute: async ({ symbols, species }) => ok(await lookupGenes(symbols, { species })),
 });

package/dist/tools/define-tool.d.ts

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`, `turnUsage`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
@@ -18,6 +18,7 @@
 import type { Result } from "neverthrow";
 import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
+import type { AgentRunUsage } from "../loop/metrics.js";
 import type { EmitFn, RunStep } from "../loop/types.js";
 import type { AskApproval, AskRequest } from "./approval/contract.js";
 export type { EmitFn };
@@ -42,7 +43,8 @@ export declare function isToolError(value: unknown): value is ToolError;
  * dependencies (see the harness-durable-runtime spec) — invocation identity,
  * `session`, `signal`, `emit`, the `runStep`
  * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows) a
- * tool uses to wrap its own durable work, and the `ask` user-approval seam.
+ * tool uses to wrap its own durable work, the `ask` user-approval seam, and the
+ * turn's usage accumulator a sub-agent-running tool hands to its child loop.
  */
 export interface ToolContext {
     /** Stable identity of this AI SDK tool call. Redelivery preserves it; a new
@@ -64,10 +66,18 @@ export interface ToolContext {
      * waiting on a surface that cannot answer.
      */
     readonly ask: (request: AskRequest) => Promise<AskApproval>;
+    /**
+     * The turn's usage accumulator — the mutable total every loop under this
+     * turn folds its LLM calls into. A tool that drives a child `runAgent`
+     * passes it straight into that run's options, which is what puts the
+     * child's tokens in the turn total its root loop reports. A tool that runs
+     * no child agent ignores it.
+     */
+    readonly turnUsage?: AgentRunUsage;
 }
 /**
  * A packaged tool: identity, the Zod input contract, the emitted AI SDK input
- * schema, execution mode, and the executor.
+ * schema, execution mode, the optional call-description hook, and the executor.
  */
 export interface Tool<Input = unknown, Output = unknown> {
     readonly id: string;
@@ -75,6 +85,8 @@ export interface Tool<Input = unknown, Output = unknown> {
     readonly inputSchema: z.ZodType;
     readonly jsonSchema: Record<string, unknown>;
     readonly executionMode: ToolExecutionMode;
+    /** See {@link ToolDefinition.describeCall}. Absent when the tool declares none. */
+    describeCall?(input: Input): string;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 export interface ToolDefinition<Schema extends z.ZodType, Output> {
@@ -82,6 +94,32 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
     readonly description: string;
     readonly inputSchema: Schema;
     readonly executionMode?: ToolExecutionMode;
+    /**
+     * One line naming what THIS call is doing — the call-time counterpart of
+     * `description`. `description` self-describes the tool at attach time, so an
+     * agent knows what it holds; `describeCall` self-describes one invocation, so
+     * a surface can render four `update_working_memory` calls as four distinct
+     * lines instead of four identical chips.
+     *
+     * It lives here, beside `inputSchema`, because that is the one place the
+     * compiler checks the two against each other. A host-side formatter reading
+     * `input.path` by string key breaks silently the day the schema moves; this
+     * one fails to build. The tool author writes it because the tool author knows
+     * which field matters.
+     *
+     * Synchronous and pure — no I/O, no ambient state. Dispatch is what the user
+     * waits on, and a description must never be able to fail a call: the loop
+     * validates the input against `inputSchema` first, guards the call, and drops
+     * the detail on any failure (see the tool-call-detail capability).
+     *
+     * Return whatever reads best. Normalization — one line, control characters
+     * removed, secrets redacted, length capped — happens once at the emit site,
+     * never here.
+     *
+     * OPTIONAL, and absence is a normal state: a tool without it is observable
+     * exactly as it is today. The hook never reaches the model.
+     */
+    describeCall?(input: z.infer<Schema>): string;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`, `turnUsage`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
@@ -44,6 +44,9 @@ export function defineTool(def) {
         inputSchema: def.inputSchema,
         jsonSchema,
         executionMode,
+        // Spread rather than assigned: a tool that declares no hook carries no
+        // `describeCall` key at all, so "has a hook" is one property check.
+        ...(def.describeCall === undefined ? {} : { describeCall: def.describeCall }),
         execute: def.execute,
     };
 }

package/dist/tools/detail-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The name-plus-input detail resolver.
+ *
+ * The live loop holds the resolved `Tool` at dispatch and needs nothing. Every
+ * other surface — the reload converter, a workflow's live-activity line — has a
+ * tool NAME and a persisted input, so it needs a way back to the tool. This is
+ * that way, and it is deliberately built over a tool list the CALLER supplies:
+ *
+ * - A name map internal to the harness could never see an embedder's tools. A
+ *   host contributes tools through the host-tools seam, and those calls are as
+ *   ambiguous in a transcript as any other.
+ * - Two harness tools legitimately share one id (`write_file` exists in both the
+ *   workspace surface and the report version store). A resolver built from one
+ *   agent's list cannot hold both, because a tool list rejects a duplicate id at
+ *   registry construction.
+ *
+ * It resolves through the same `computeDetail` the loop uses, so a reloaded
+ * thread cannot show a different detail from the one the live turn showed.
+ * Nothing is persisted: storage stays the pure model transcript.
+ */
+import { type ToolCallDetail } from "../loop/tool-detail.js";
+import type { Logger } from "../lib/logger.js";
+import type { Tool } from "./define-tool.js";
+/**
+ * Maps a tool name plus a call's input to that call's detail. Yields
+ * `undefined` for an unknown tool, a tool with no hook, and an input the tool's
+ * schema rejects.
+ */
+export type ToolDetailResolver = (toolName: string, input: unknown) => ToolCallDetail | undefined;
+/**
+ * Build a resolver over `tools`. A duplicate id resolves to the first tool
+ * declaring it; callers pass one agent's composed list, which a registry has
+ * already rejected duplicates from.
+ */
+export declare function createDetailResolver(tools: readonly Tool[], logger?: Logger): ToolDetailResolver;

package/dist/tools/detail-resolver.js

@@ -0,0 +1,39 @@
+/**
+ * The name-plus-input detail resolver.
+ *
+ * The live loop holds the resolved `Tool` at dispatch and needs nothing. Every
+ * other surface — the reload converter, a workflow's live-activity line — has a
+ * tool NAME and a persisted input, so it needs a way back to the tool. This is
+ * that way, and it is deliberately built over a tool list the CALLER supplies:
+ *
+ * - A name map internal to the harness could never see an embedder's tools. A
+ *   host contributes tools through the host-tools seam, and those calls are as
+ *   ambiguous in a transcript as any other.
+ * - Two harness tools legitimately share one id (`write_file` exists in both the
+ *   workspace surface and the report version store). A resolver built from one
+ *   agent's list cannot hold both, because a tool list rejects a duplicate id at
+ *   registry construction.
+ *
+ * It resolves through the same `computeDetail` the loop uses, so a reloaded
+ * thread cannot show a different detail from the one the live turn showed.
+ * Nothing is persisted: storage stays the pure model transcript.
+ */
+import { computeDetail } from "../loop/tool-detail.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+/**
+ * Build a resolver over `tools`. A duplicate id resolves to the first tool
+ * declaring it; callers pass one agent's composed list, which a registry has
+ * already rejected duplicates from.
+ */
+export function createDetailResolver(tools, logger) {
+    const log = (logger ?? createNoopLogger()).named("tool-detail");
+    const byId = new Map();
+    for (const tool of tools) {
+        if (!byId.has(tool.id))
+            byId.set(tool.id, tool);
+    }
+    return (toolName, input) => {
+        const tool = byId.get(toolName);
+        return tool === undefined ? undefined : computeDetail(tool, input, log);
+    };
+}

package/dist/tools/execute-analysis.js

@@ -152,6 +152,9 @@ export function createExecuteAnalysisTool(deps) {
             "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
             "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn.",
         inputSchema,
+        // The mode is what a user most needs to see here — an approved plan
+        // running is a different event from an ad hoc request being routed.
+        describeCall: (input) => (input.mode === "plan" ? `plan ${input.planId ?? ""}` : `ad hoc: ${input.request ?? ""}`),
         execute: async (input, ctx) => {
             if (ctx.session.scope.kind !== "analysis")
                 throw new Error("execute_analysis requires an analysis-scoped session");

package/dist/tools/iterate-report.d.ts

@@ -48,6 +48,7 @@ import { type StagedAsset } from "./lib/report-preflight.js";
 import type { PreviewPublisher } from "./report/preview-publisher.js";
 import type { ChromeConfig } from "../lib/chrome.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 /**
  * The report brief the conversation agent composes: title/audience + sources +
  * the section union. This is the ~12k-char schema that `plan_report` hands back
@@ -209,6 +210,8 @@ export interface SubmitReportDeps {
         previewId: string;
         ttlSeconds: number;
     }) => Promise<PreviewPublisher>;
+    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /**
  * `submit_report` — takes the composed brief and drives the report iteration.

package/dist/tools/iterate-report.js

@@ -654,6 +654,7 @@ export function createReportSubmitTool(deps) {
                 templatesDir: deps.templatesDir,
                 skillsDir: deps.skillsDir,
                 chrome: deps.chrome,
+                usageRecorder: deps.usageRecorder,
             }, {
                 resourceId,
                 workspaceRoot: analysisRoot,
@@ -665,6 +666,8 @@ export function createReportSubmitTool(deps) {
                 session: ctx.session,
                 signal: ctx.signal,
                 emit: ctx.emit,
+                turnUsage: ctx.turnUsage,
+                invocationId: ctx.invocationId,
             });
             if (!result.ok) {
                 await ctx.emit({

package/dist/tools/memory/update-working-memory.js

@@ -149,6 +149,14 @@ export function createUpdateWorkingMemoryTool(workingMemory, pool) {
             "user's last message, run contents (tables, gene lists, file paths), or anything you can retrieve " +
             "again with inspect_run, read_file, or search.",
         inputSchema,
+        // Four writes in one turn are four identical chips without this. The
+        // entry id rides along on revise/retire because it is the only thing
+        // separating two retirements from the same section.
+        describeCall: (input) => {
+            const operation = input.section === "goal" ? "set" : (input.operation ?? "add");
+            const target = input.id === undefined ? "" : ` ${input.id}`;
+            return `${operation} ${input.section}${target}`;
+        },
         execute: async (input, ctx) => {
             const analysisId = scopeResource(ctx.session.scope).resourceId;
             switch (input.section) {

package/dist/tools/research/generate-analogy-report.d.ts

@@ -15,6 +15,7 @@
 import { z } from "zod";
 import { type AnalogicalReasonerOutput } from "@inflexa-ai/harness/contracts/analogy-report.js";
 import type { ChatProvider } from "../../providers/types.js";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
 export declare const generateAnalogyReportInputSchema: z.ZodObject<{
@@ -39,6 +40,8 @@ export interface GenerateAnalogyReportDeps {
     readonly model: string;
     /** API keys for the bio/chem + GitHub data sources the reasoner searches. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
 export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps): Tool;

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

@@ -203,6 +203,12 @@ export function createGenerateAnalogyReportTool(deps) {
                     signal: ctx.signal,
                     emit: ctx.emit,
                     runStep: passthroughStep,
+                    usageRecorder: deps.usageRecorder,
+                    // Fold the child's calls into the turn total the root loop reports.
+                    turnUsage: ctx.turnUsage,
+                    // Keeps the usage record keys of two parallel dispatches disjoint —
+                    // same frame, same call path, same loop-local step names.
+                    invocationId: ctx.invocationId,
                 });
                 rawText = finalText(transcript);
             }

package/dist/tools/research/generate-plan.d.ts

@@ -25,6 +25,7 @@
  */
 import type { Pool } from "pg";
 import { type ChatProvider } from "../../providers/types.js";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import { type ResourcePolicy } from "../../config/resource-limits.js";
@@ -49,6 +50,8 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly resourcePolicy?: ResourcePolicy;
     /** Diagnostic sink. Absent, the tool runs silently — see `RunAgentOptions.logger`. */
     readonly logger?: Logger;
+    /** LLM usage-accounting seam for the planner loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;

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

@@ -830,6 +830,12 @@ export function createGeneratePlanTool(deps) {
                     // as soon as one is recorded.
                     toolChoice: "required",
                     logger,
+                    usageRecorder: deps.usageRecorder,
+                    // Fold the planner's calls into the turn total the root loop reports.
+                    turnUsage: ctx.turnUsage,
+                    // Keeps the usage record keys of two parallel dispatches disjoint —
+                    // same frame, same call path, same loop-local step names.
+                    invocationId: ctx.invocationId,
                 }, {
                     tools: innerTools.terminal,
                     nudge: "You ended without a terminal outcome. Call submit_plan with " +

package/dist/tools/research/inspect-run.js

@@ -102,6 +102,10 @@ export function createInspectRunTool(pool, clock = systemClock) {
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
         inputSchema,
+        // The two calls do different work: one inspects a named run, the other
+        // pages the list. Naming the run id is what separates repeated polls of
+        // the same run from polls of different ones.
+        describeCall: (input) => (input.runId === undefined ? `run list (page ${input.page ?? 1})` : input.runId),
         execute: async (input, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;
             const verbose = input.includeDiagnostics === true;

package/dist/tools/research/literature-reviewer.d.ts

@@ -18,6 +18,7 @@ import { type ChatProvider } from "../../providers/types.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
 import type { Logger } from "../../lib/logger.js";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 export interface LiteratureReviewerDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -27,6 +28,8 @@ export interface LiteratureReviewerDeps {
     readonly model: string;
     /** API keys for the bio/chem data sources the reviewer searches. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `literature_reviewer` delegation tool bound to its provider. */
 export declare function createLiteratureReviewerTool(deps: LiteratureReviewerDeps): Tool;

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

@@ -72,6 +72,12 @@ export function createLiteratureReviewerTool(deps) {
                 signal: ctx.signal,
                 emit: ctx.emit,
                 runStep: passthroughStep,
+                usageRecorder: deps.usageRecorder,
+                // Fold the child's calls into the turn total the root loop reports.
+                turnUsage: ctx.turnUsage,
+                // Keeps the usage record keys of two parallel reviews disjoint —
+                // same frame, same call path, same loop-local step names.
+                invocationId: ctx.invocationId,
             });
             return ok({ report: finalText(transcript) });
         },

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

@@ -65,6 +65,8 @@ export function createEditFileTool(deps) {
             "/ `out_of_scope` / `file_not_found` / `not_found` / `not_unique` data " +
             "variants — never throws on expected outcomes.",
         inputSchema: EditFileInputSchema,
+        // The path only. The replaced text is file content, not a description.
+        describeCall: ({ path }) => path,
         execute: async ({ path, old_string, new_string, replace_all }, ctx) => {
             const read = unwrapOrThrow(await deps.workspaceFilesystem.readFile({
                 session: ctx.session,

package/dist/tools/workspace/execute-command.js

@@ -42,6 +42,12 @@ const ExecuteCommandInputSchema = z.object({
     env: z.record(z.string(), z.string()).optional().describe("Extra environment variables for this command."),
     timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds; capped by the step deadline."),
 });
+/** Extensions that mark an argv token as the thing being run, not a flag or a data path. */
+const SCRIPT_EXTENSIONS = /\.(py|R|r|sh|js|ts|ipynb)$/;
+/** The first script-like token in an argv, or `undefined` when none looks like one. */
+function scriptToken(command) {
+    return command.find((arg) => SCRIPT_EXTENSIONS.test(arg));
+}
 export function createExecuteCommandTool(deps) {
     const { sandboxClient, sandbox, workflowId, stepId, nextFunctionId, deadlineMs, defaultCwd, markExecActive, lineageCollector, mountRoot } = deps;
     return defineTool({
@@ -58,6 +64,25 @@ export function createExecuteCommandTool(deps) {
             "analysis results via 'python -c' / inline one-liners and read them from " +
             "stdout; that work is lost. Write a script and persist its outputs to output/.",
         inputSchema: ExecuteCommandInputSchema,
+        // The script is what a reader recognises, and it survives a long
+        // invocation whose flags would otherwise push it past the length cap.
+        // When nothing in the argv looks like a script, the joined argv is the
+        // best account of the call there is.
+        //
+        // `env` never rides along. It is the channel this tool documents for
+        // secrets, so it is the one field guaranteed to hold them. An argv can
+        // hold one too (`--password …` is a real habit), and the emit-site
+        // redaction only matches the structured, prefixed formats — so the join
+        // is a deliberate trade, not a claim of safety.
+        //
+        // Know what the trade costs. This tool is sandbox-gated, so the only
+        // surface that reads its detail is a workflow's live-activity line — and
+        // that line goes to the run-event stream through `DBOS.writeStream`. The
+        // detail is therefore DURABLE, and every history read replays it. It
+        // stays inside the session's own analysis and never reaches the model,
+        // but display-only does not mean transient. A secret typed into an argv
+        // outlives the turn that ran it.
+        describeCall: ({ command }) => scriptToken(command) ?? command.join(" "),
         execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
             const execId = `${workflowId}:${stepId}:${nextFunctionId()}`;
             const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);

package/dist/tools/workspace/grep.js

@@ -38,6 +38,9 @@ export function createGrepTool(fs, workingDir) {
             "bytes per line — narrow your path or pattern if you hit the cap. " +
             "No matches and out-of-scope paths return data variants, not errors.",
         inputSchema: GrepInputSchema,
+        // Both fields, because either alone loses the call: the same pattern over
+        // two trees and two patterns over one tree are both ordinary sequences.
+        describeCall: ({ pattern, path }) => `${pattern} in ${path}`,
         execute: async ({ pattern, path, ignoreCase }, ctx) => {
             let regex;
             try {

package/dist/tools/workspace/list-files.js

@@ -24,6 +24,8 @@ export function createListFilesTool(fs, workingDir) {
             "else: it never reaches a directory outside the analysis, including the host process's current " +
             "working directory. Missing and out-of-scope paths return a data variant, not an error.",
         inputSchema: ListFilesInputSchema,
+        // The directory IS the call — two listings differ by nothing else.
+        describeCall: ({ path }) => path,
         execute: async ({ path }, ctx) => {
             const result = unwrapOrThrow(await fs.list({ session: ctx.session, path, workingDir }));
             switch (result.kind) {

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

@@ -62,6 +62,13 @@ export function createReadFileTool(fs, workingDir) {
             "back as a `binary` data variant rather than decoded garbage. Missing " +
             "paths and paths outside the analysis tree return a data variant — not an error.",
         inputSchema: ReadFileInputSchema,
+        describeCall: ({ path, headLines, tailLines }) => {
+            if (headLines !== undefined)
+                return `${path} (first ${headLines} lines)`;
+            if (tailLines !== undefined)
+                return `${path} (last ${tailLines} lines)`;
+            return path;
+        },
         execute: async ({ path, headLines, tailLines }, ctx) => {
             if (headLines !== undefined && tailLines !== undefined) {
                 return ok({

package/dist/tools/workspace/workspace-search.js

@@ -47,6 +47,7 @@ export function createWorkspaceSearchTool(pool, embedding) {
                 .describe('Restrict results to one entry type: "input", "output", "summary", or "synthesis"'),
             limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
         }),
+        describeCall: ({ query, type }) => (type === undefined ? query : `${query} (${type})`),
         execute: async ({ query, type, limit }, ctx) => {
             const [vector] = unwrapOrThrow(await embedding.embed([query], ctx.session));
             if (!vector)

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

@@ -28,6 +28,9 @@ export function createWriteFileTool(deps) {
             "variant (no I/O), and one escaping the analysis tree returns " +
             "`out_of_scope`.",
         inputSchema: WriteFileInputSchema,
+        // The path only. `content` is a whole file and must never ride a display
+        // channel, which the emit-site length cap enforces regardless.
+        describeCall: ({ path }) => path,
         execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({ path, content, toolName: "write_file", emit: ctx.emit })),
     });
 }

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

@@ -63,6 +63,7 @@ import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 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 { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
@@ -280,6 +281,12 @@ export interface ExecuteAnalysisDeps {
     readonly runCharge: RunCharge;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;
+    /**
+     * LLM usage-accounting seam for the in-body synthesizer loop (and the
+     * literature reviewer it delegates to); omitted falls back to the no-op
+     * recorder.
+     */
+    readonly usageRecorder?: UsageRecorder;
     /**
      * Optional, fire-and-forget provenance observation of the run lifecycle.
      * Deliberately invoked directly in the workflow body (NOT wrapped in