@inflexa-ai/harness 0.14.2 → 0.15.0

package/dist/state/purge-analysis.js

@@ -0,0 +1,205 @@
+/**
+ * purgeAnalysis — the single place that knows what an analysis's persisted
+ * Postgres footprint is.
+ *
+ * A host asks for it with an `analysisId` and nothing else: every keyed store,
+ * the analysis's dynamic vector-table name, and its workflow ids are all
+ * derivable from that id, so no caller enumerates tables or supplies a run list.
+ * The workflow ledger is part of the footprint, not a follow-on — the sandbox
+ * transcripts and run-event streams live there and are the dominant share of an
+ * analysis's stored bytes — and it is reached through the injected
+ * `WorkflowPurger` seam so the durability engine stays out of the state layer.
+ *
+ * There is no single transaction across the stages: the purge spans app tables, a
+ * DDL `DROP TABLE`, and the engine's system schema, so instead of faking atomicity
+ * every stage is idempotent and the whole operation is safe to re-run. A purge of
+ * an unknown or already-purged analysis therefore succeeds, reporting zeroes. Each
+ * stage carries the reason it sits where it does.
+ *
+ * A purge is NOT serialized against work still starting on the analysis. The
+ * mapping from an analysis to its workflows is read once, up front, out of
+ * `cortex_runs`; a run inserted after that read is outside the captured set, and
+ * the `cortex_runs` delete later in the same purge removes the only row that could
+ * ever have named it. Its workflow row and every byte cascading off it then belong
+ * to no analysis — no retry reaches them, because nothing is left that attributes
+ * them to one. Quiesce the analysis before purging it: no new runs, no new
+ * data-profile triggers. This module cannot observe a host's in-flight work, so it
+ * does not enforce that.
+ *
+ * What it does not reach, so that absent coverage is never read as delivered:
+ * scheduled operational workflows (they belong to no analysis and accumulate
+ * independently of any purge), target assessments and their annotations (a
+ * separate top-level entity), the shared regulatory corpus, `messages` rows whose
+ * thread row is already gone (nothing attributes them to an analysis), and
+ * workspace files on disk (the embedder owns their disposal).
+ */
+import { errAsync, okAsync } from "neverthrow";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { searchIndexName } from "../workspace/search-config.js";
+import { isSqlIdentifier } from "./vector-store.js";
+/**
+ * The shape an `analysisId` must take to be purgeable. It is load-bearing twice
+ * over, and neither job survives the other being dropped:
+ *
+ *  - Safe DDL interpolation. The analysis's vector-table name is derived from the
+ *    id and interpolated into `DROP TABLE`, because an identifier cannot be a bind
+ *    parameter. Confining the id to `[a-z0-9_-]` is what makes that derived name an
+ *    identifier at all.
+ *  - An unambiguous `dataprofile:` namespace. Profile workflows are found by the id
+ *    prefix `dataprofile:{analysisId}:`, matched with `starts_with` and no
+ *    delimiter check. An id holding a `:` makes analysis `a`'s prefix equally a
+ *    prefix of every workflow id of an analysis named `a:x` — and each id that
+ *    prefix returns is cancelled, then deleted with its descendants, taking another
+ *    analysis's ledger rows and everything cascading off them. Excluding `:` is the
+ *    only thing that keeps a purge inside the analysis it was asked for.
+ *
+ * Empty is outside the shape too: it derives the bare table prefix, which is a
+ * perfectly legal identifier and belongs to no analysis.
+ */
+const PURGEABLE_ANALYSIS_ID = /^[a-z0-9_-]+$/;
+/**
+ * The analysis-keyed deletes that follow the thread/message pair, in the order
+ * they run.
+ *
+ * `cortex_plans` carries its own statement, immediately ahead of the
+ * `cortex_analysis_state` row it hangs off. The foreign key between the two
+ * cascades, so on a schema that has the key the statement is redundant — but the
+ * table is provisioned with `CREATE TABLE IF NOT EXISTS`, which adds no
+ * constraint to a table that already exists, so a database whose `cortex_plans`
+ * predates the key never acquires one. Resting on the cascade alone would make
+ * the completeness of a purge contingent on a constraint being present, and would
+ * silently leave the plans behind wherever it is not. The statement removes the
+ * rows either way; the cascade stays a backstop behind it.
+ */
+const ANALYSIS_KEYED_DELETES = [
+    { op: "purgeAnalysis.artifacts", sql: "DELETE FROM cortex_artifacts WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.stepExecutions", sql: "DELETE FROM cortex_step_executions WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.runs", sql: "DELETE FROM cortex_runs WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.workingMemory", sql: "DELETE FROM cortex_working_memory WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.asks", sql: "DELETE FROM cortex_asks WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.askGrants", sql: "DELETE FROM cortex_ask_grants WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.plans", sql: "DELETE FROM cortex_plans WHERE analysis_id = $1" },
+    { op: "purgeAnalysis.analysisState", sql: "DELETE FROM cortex_analysis_state WHERE analysis_id = $1" },
+];
+/**
+ * A refusal raised before any stage runs, so nothing is cancelled, no workflow row
+ * and no `cortex_*` row is gone, and a retry answers the same way at the same cost.
+ * `op` names the check that raised it.
+ */
+function refuse(op, message) {
+    return errAsync({ type: "mutation_failed", op, cause: new Error(message) });
+}
+/** Run one delete on the transaction's client and report how many rows it took. */
+function deleteRows(client, op, text, analysisId) {
+    return tryMutation(op, async () => {
+        const { rowCount } = await client.query({ text, values: [analysisId] });
+        return rowCount ?? 0;
+    });
+}
+export function createAnalysisPurge({ pool, workflows, logger: injected }) {
+    const logger = (injected ?? createNoopLogger()).named("purge-analysis");
+    /**
+     * Every workflow id the analysis can still be traced to, read while the rows
+     * that record them are all still on disk. `cortex_runs.run_id` IS the parent
+     * workflow id, and those rows together with the `dataprofile:{analysisId}:` id
+     * namespace are the ONLY mapping from an analysis to its workflows: a delete
+     * of `cortex_runs` that lands before this read completes strands the largest
+     * part of the footprint permanently out of reach.
+     */
+    const collectWorkflowIds = (analysisId) => tryQuery("purgeAnalysis.runWorkflowIds", async () => {
+        const { rows } = await pool.query({
+            text: "SELECT run_id FROM cortex_runs WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        return rows.map((row) => row.run_id);
+    }).andThen((runIds) => workflows.findByIdPrefix(`dataprofile:${analysisId}:`).map((profileIds) => {
+        logger.debug("collected workflow identity", { analysisId, runs: runIds.length, dataProfiles: profileIds.length });
+        // The two id sources cannot overlap, but collapsing duplicates keeps a
+        // repeated id out of the reclaimed count regardless.
+        return [...new Set([...runIds, ...profileIds])];
+    }));
+    /**
+     * One transaction for the whole `cortex_*` stage, so a mid-stage failure leaves
+     * no half-deleted analysis behind.
+     */
+    const deleteCortexRows = (analysisId) => withTransaction(pool, "purgeAnalysis.cortexRows", (client) => 
+    // `messages` has no `analysis_id` column and no foreign key: the only
+    // route from an analysis to its messages is a join through its thread
+    // rows. So the messages go first and the thread rows that name them go
+    // second — reversed, the messages become unattributable and unreachable
+    // by any later reclamation. No `deleted_at` filter on either: an archived
+    // thread is still the analysis's, and a purge takes it too.
+    deleteRows(client, "purgeAnalysis.messages", `DELETE FROM messages
+                 WHERE thread_id IN (SELECT thread_id FROM cortex_analysis_threads WHERE analysis_id = $1)`, analysisId)
+        .andThen((messages) => deleteRows(client, "purgeAnalysis.threads", "DELETE FROM cortex_analysis_threads WHERE analysis_id = $1", analysisId).map((threads) => ({
+        threads,
+        messages,
+    })))
+        // Folded so the first failure short-circuits the rest. Submitting them
+        // together would not: the transaction is aborted the moment one raises,
+        // every statement behind it comes back `25P02`, and the `op` naming the
+        // delete that actually broke is buried under theirs.
+        .andThen((counts) => ANALYSIS_KEYED_DELETES.reduce((stage, { op, sql }) => stage.andThen(() => deleteRows(client, op, sql, analysisId).map(() => undefined)), okAsync(undefined)).map(() => counts)));
+    /**
+     * `vectorIndexDropped` is established by a `to_regclass` probe taken
+     * immediately before the drop, because `DROP TABLE IF EXISTS` reports nothing
+     * about whether it found anything. The probe resolves the name exactly as the
+     * drop does — both go through `search_path`, and the probe is handed the same
+     * double-quoted form the drop interpolates, since `to_regclass` parses its
+     * argument as an SQL identifier and would fold an unquoted one to lower case.
+     * The drop runs regardless of what the probe saw, so the window between them can
+     * at worst misreport the flag for an analysis already being destroyed, never
+     * leave a table behind.
+     *
+     * `indexName` arrives already accepted at the entry point; that is the whole
+     * warrant for interpolating it into the DDL below.
+     */
+    const dropVectorIndex = (indexName) => tryQuery("purgeAnalysis.vectorIndexPresent", async () => {
+        const { rows } = await pool.query({
+            text: "SELECT to_regclass($1::text) IS NOT NULL AS present",
+            values: [`"${indexName}"`],
+        });
+        return rows[0]?.present ?? false;
+    }).andThen((present) => tryMutation("purgeAnalysis.dropVectorIndex", async () => {
+        await pool.query(`DROP TABLE IF EXISTS "${indexName}"`);
+    }).map(() => present));
+    const purgeAnalysis = (analysisId) => {
+        if (!PURGEABLE_ANALYSIS_ID.test(analysisId)) {
+            return refuse("purgeAnalysis.analysisId", `purge-analysis: refusing unpurgeable analysis id "${analysisId}"`);
+        }
+        const indexName = searchIndexName(analysisId);
+        // The id's shape already settles the derived name's characters; what it cannot
+        // settle is how long the derivation makes it. This is the same guard the vector
+        // store applies to the same name on the write side, so the accepted shape
+        // cannot drift between the two, and a name Postgres would silently truncate
+        // onto another analysis's table is refused rather than dropped.
+        if (!isSqlIdentifier(indexName)) {
+            return refuse("purgeAnalysis.vectorIndexName", `purge-analysis: unsafe vector index name "${indexName}"`);
+        }
+        return (collectWorkflowIds(analysisId)
+            // Cancel before delete. Removing the status row of a running workflow
+            // does not stop the executor running it, and that executor goes on
+            // writing rows behind the delete — re-materializing exactly the orphans
+            // the purge exists to remove. A failed cancel leaves that risk in place,
+            // so it ends the purge rather than being absorbed into a completeness
+            // claim the operation can no longer make.
+            .andThen((ids) => workflows.cancel(ids).map(() => ids))
+            // Workflow rows go before the `cortex_*` ledger that names them: a failure
+            // here leaves the id mapping on disk and a retry finds it, whereas the
+            // reverse order turns one transient failure into a permanent orphan.
+            // Descendants are included because a run's child step workflows carry the
+            // sandbox transcripts and are reachable only through their parent.
+            .andThen((ids) => workflows.deleteWorkflows(ids, true))
+            .andThen((workflowsTargeted) => deleteCortexRows(analysisId).map((counts) => ({ ...counts, workflows: workflowsTargeted })))
+            // The vector table is dropped after the transaction rather than inside
+            // it: `DROP TABLE` takes an ACCESS EXCLUSIVE lock, and enlisting it would
+            // hold that lock for the duration of every row delete above.
+            .andThen((reclaimed) => dropVectorIndex(indexName).map((vectorIndexDropped) => ({ ...reclaimed, vectorIndexDropped })))
+            .map((outcome) => {
+            logger.info("purged analysis", { analysisId, ...outcome });
+            return outcome;
+        }));
+    };
+    return { purgeAnalysis };
+}

package/dist/state/vector-store.d.ts

@@ -15,6 +15,12 @@
 import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * Whether `name` may be interpolated into a statement as an identifier. Shared
+ * with the reclaim side, which guards the same derived names against the same
+ * shape — one invariant, one place to read it.
+ */
+export declare function isSqlIdentifier(name: string): boolean;
 export interface CreateIndexInput {
     readonly indexName: string;
     readonly dimension: number;

package/dist/state/vector-store.js

@@ -14,9 +14,29 @@
  */
 import { okAsync } from "neverthrow";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
-const IDENT = /^[a-z_][a-z0-9_]*$/;
+/**
+ * The identifier shape and length the harness may interpolate into a statement.
+ * An identifier cannot be a bind parameter, so a name reaching SQL has to be
+ * checked rather than bound, and lower-snake is the whole of what the harness ever
+ * derives. The bound is as load-bearing as the shape: Postgres keeps only the
+ * first 63 bytes of an identifier and truncates the rest silently, so two longer
+ * names sharing a 63-byte prefix resolve to one table — a write that lands in
+ * another resource's index, and a drop that takes it. The shape is ASCII-only, so
+ * a name that matches it has one byte per character and `length` is the byte count
+ * the limit is measured in.
+ */
+const SQL_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+const MAX_SQL_IDENTIFIER_BYTES = 63;
+/**
+ * Whether `name` may be interpolated into a statement as an identifier. Shared
+ * with the reclaim side, which guards the same derived names against the same
+ * shape — one invariant, one place to read it.
+ */
+export function isSqlIdentifier(name) {
+    return SQL_IDENTIFIER.test(name) && name.length <= MAX_SQL_IDENTIFIER_BYTES;
+}
 function assertIdent(name) {
-    if (!IDENT.test(name)) {
+    if (!isSqlIdentifier(name)) {
         throw new Error(`vector-store: unsafe index name "${name}"`);
     }
 }

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({