@inflexa-ai/harness 0.39.2 → 0.40.0

package/dist/providers/reasoning.js

@@ -1,34 +1,23 @@
 /**
- * The reasoning depth of a run.
+ * The reasoning depth of a call.
  *
- * The harness states the depth one time, on `ChatRequest.reasoning`, with the
- * neutral names of the AI SDK. It names no vendor key. Each provider package
- * holds the table of what its own models accept, and it maps the neutral name
- * onto the wire. The Anthropic package also selects adaptive thinking there.
+ * The effort resolves in order: `ChatRequest.reasoning` (set only through
+ * `RunAgentOptions.reasoning`), the provider configuration's `reasoning`, then
+ * {@link DEFAULT_REASONING}. Anthropic discards its message cache when the
+ * top-level effort changes between calls.
  *
- * ## Why the harness names no vendor key
- *
- * The harness wrote `providerOptions.anthropic.effort` before. A value on that
- * key turns the per-model table of the Anthropic package off, thus the raw name
- * reached the wire. A model that accepts `high` but not `xhigh` answered 400.
- * The neutral field has no such hazard, because the package resolves the name
- * for the model that it is bound to.
- *
- * ## Where the policy belongs
- *
- * The policy rides on the run, not on the provider, for the same reason that the
- * cache policy does. A one-shot LLM call elsewhere in the harness has its own
- * depth needs, and it must not inherit the depth of an agent loop.
+ * Do not set `providerOptions.anthropic.effort` directly. It bypasses the
+ * per-model table, and a model that rejects the raw name answers 400.
  */
 /**
- * The default policy: the deepest name of the neutral ladder.
+ * The last source of the effort: the deepest rung of the neutral ladder.
  *
  * Each agent of the harness drives tools over many iterations. A shallow turn
  * there wastes more calls than a deeper turn costs in tokens. The Anthropic
  * package sends `xhigh` to a model that accepts it, and `max` to a model that
  * does not. The OpenAI-compatible package sends the name as it is.
  *
- * A host that wants a cheaper loop passes a lower name. A host on a model with
- * no reasoning support passes `"provider-default"`.
+ * A host that wants a cheaper role sets a lower name on that role's provider
+ * configuration. With no reasoning support, a host sets `"provider-default"`.
  */
 export const DEFAULT_REASONING = "xhigh";

package/dist/providers/types.d.ts

@@ -5,7 +5,7 @@
  * vendor-neutral interfaces. Every call carries an `AgentSession`; billing
  * attribution is resolved lazily at the provider wire boundary.
  */
-import type { FinishReason, LanguageModel, ModelMessage, ToolSet } from "ai";
+import type { FinishReason, LanguageModel, ModelMessage, SystemModelMessage, ToolSet } from "ai";
 import type { LanguageModelV4CallOptions } from "@ai-sdk/provider";
 import type { ProviderOptions } from "@ai-sdk/provider-utils";
 import type { ResultAsync } from "neverthrow";
@@ -32,19 +32,30 @@ export interface ProviderCapabilities {
      */
     readonly imageUserMessages?: boolean;
 }
+/**
+ * The request carries no free-form provider options. That would let a caller
+ * set a vendor key that bypasses the provider's per-model table.
+ */
 export interface ChatRequest {
-    readonly system: string;
+    /**
+     * The system prompt: a plain string, or a system message that carries the
+     * cache marker at its end (`withSystemPromptBreakpoint`).
+     */
+    readonly system: string | SystemModelMessage;
     readonly messages: readonly ModelMessage[];
     readonly tools: ToolSet;
     /**
      * A forced choice (`required`, or one named tool) is absent on purpose: some
      * Claude models reject it with a 400, and the model is chosen at run time.
+     *
+     * CAUTION: `@ai-sdk/anthropic` strips the tools when this is `"none"`, and
+     * Anthropic drops its cache on any `tool_choice` change — taking a signed
+     * thinking block with it. Use a tool mask instead of sending `"none"`.
      */
     readonly toolChoice?: "auto" | "none";
-    readonly providerOptions?: ProviderOptions;
     /**
-     * How deep the model reasons on this call. Absent sends no directive, thus
-     * the model applies its own default. Refer to `ReasoningPolicy`.
+     * How deep the model reasons. Absent, the effort falls back to the provider
+     * configuration's `reasoning`, then `DEFAULT_REASONING`.
      */
     readonly reasoning?: ReasoningPolicy;
 }
@@ -139,6 +150,11 @@ export interface ChatResponse {
      * diagnostics, never as an invariant.
      */
     readonly servedModelId?: string;
+    /**
+     * The AI SDK's `LanguageModel.provider` id, for example `anthropic.messages`.
+     * Absent for a bare model-id string, which names no provider.
+     */
+    readonly provider?: string;
 }
 export type ChatStreamEvent = {
     readonly type: "text-delta";

package/dist/report-model/authoring-grammar.d.ts

@@ -398,15 +398,15 @@ declare const AUTHORING_ATOM_SCHEMAS: readonly [z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    linear: "linear";
                     log: "log";
+                    linear: "linear";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    linear: "linear";
                     log: "log";
+                    linear: "linear";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

package/dist/runtime/assemble.d.ts

@@ -49,12 +49,13 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * here would let an embedder wire a recorder the workflows use and the
  * conversation agent does not — a half-wired ledger that reads as a complete
  * one. The protection has to hold on both sides of the assembly, not just the
- * conversation side.
+ * conversation side. Each bag omits `toolOutputStore` for the same reason: each
+ * loop must keep its texts in the one store that each read tool reads.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver">;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver">;
-    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
+    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder" | "toolOutputStore">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -66,21 +67,22 @@ export interface RegisteredWorkflows {
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, the
- * usage recorder, the report-session anchor, and the eyes.
+ * usage recorder, the report-session anchor, the eyes, and the tool output store.
  * `assembleCoreRuntime` supplies each of those itself. Thus a caller cannot wire
- * one of these five values:
+ * one of these six values:
  *
  * - a stale callable
  * - a policy that diverges from the one the workflows see
  * - a recorder that only half the agent tree reports to
  * - an anchor over a different session runtime
  * - a seam that only half the agent tree looks through
+ * - a store that only half the agent tree keeps its texts in
  *
  * The assembly resolves the eyes one time, from `CoreRuntimeDeps.eyes` and the
  * chrome config. A caller that bound the eyes here would give the conversation
  * agent a seam that the report agent never sees.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes" | "toolOutputStore">;
 /**
  * What binds one reference resolver: the analysis whose pinned artifacts it reads, and the auth of the tool
  * call that reads them. A resolver serves one analysis, thus the report tools build one for each call.

package/dist/runtime/assemble.js

@@ -30,6 +30,7 @@ import { createCitationResolver } from "../citations/resolve.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
 import { createReportVersionStore } from "../state/report-versions.js";
+import { createToolOutputStore } from "../state/tool-outputs.js";
 const _assertDomainError = true;
 /**
  * Wrap a type→agent registry as the resolution surface. Held apart from
@@ -83,9 +84,10 @@ export function assembleCoreRuntime(deps) {
             ? {}
             : { semanticScholarApiKey: conversation.bioKeys.semanticScholar }),
     });
-    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder });
-    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
-    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
+    const toolOutputStore = createToolOutputStore(conversation.pool);
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder, toolOutputStore });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder, toolOutputStore });
+    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder, toolOutputStore });
     // The extraction workflow shares the profile's sandbox and authorization rails, thus it draws the same
     // three seams from the profile deps. The report resolver factory binds the extraction arm over this
     // callable, thus a fall-through report reference reads its file out of process on the profile rails.
@@ -120,6 +122,7 @@ export function assembleCoreRuntime(deps) {
         anchorReportSession: reportSession.ensureSessionState,
         resourcePolicy,
         usageRecorder,
+        toolOutputStore,
         citationResolver,
         ...(eyes ? { eyes } : {}),
         // The start tool passes it to the spawn, which emits the creation of a
@@ -176,6 +179,7 @@ export function assembleCoreRuntime(deps) {
         ...(deps.resolveReportPageUrl ? { resolvePageUrl: deps.resolveReportPageUrl } : {}),
         ...(deps.provenance ? { provenance: deps.provenance } : {}),
         ...(conversation.logger ? { logger: conversation.logger } : {}),
+        toolOutputStore,
     });
     // The single registration point for every typed agent. A future thread type's
     // agent plugs in here at assembly with no embedder change. `conversation` is

package/dist/sandbox/create-sandbox.d.ts

@@ -49,8 +49,8 @@ export interface CreateSandboxClientConfig {
     /**
      * Per-stream retention budget sent with every exec, so the sandbox drops
      * output past it instead of shipping it. Defaults to `EXEC_STREAM_BYTE_CAP`,
-     * the same value the host truncates to on receipt — sending more than the
-     * host will keep buys nothing.
+     * the maximum of a kept tool output and the same value the host truncates to
+     * on receipt — sending more than the host will keep buys nothing.
      */
     execStreamByteCap?: number;
     /** Cluster resource ceilings; every sandbox request is clamped to these. */

package/dist/sandbox/submit-exec.d.ts

@@ -26,7 +26,7 @@ export interface SubmitExecDeps {
     }) => Promise<T>;
     /**
      * Per-stream retention budget to send when the body does not carry one.
-     * Defaults to `EXEC_STREAM_BYTE_CAP`.
+     * Defaults to `EXEC_STREAM_BYTE_CAP`, the maximum of a kept tool output.
      */
     execStreamByteCap?: number;
 }

package/dist/schemas/artifact-manifest.d.ts

@@ -8,9 +8,9 @@ import { z } from "zod";
 /** Artifact type inferred from the step subdirectory. */
 export declare const ArtifactTypeSchema: z.ZodEnum<{
     output: "output";
-    log: "log";
-    figure: "figure";
     script: "script";
+    figure: "figure";
+    log: "log";
     notebook: "notebook";
 }>;
 export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
@@ -22,9 +22,9 @@ export declare const ArtifactManifestEntrySchema: z.ZodObject<{
     size: z.ZodNumber;
     type: z.ZodEnum<{
         output: "output";
-        log: "log";
-        figure: "figure";
         script: "script";
+        figure: "figure";
+        log: "log";
         notebook: "notebook";
     }>;
     hash: z.ZodOptional<z.ZodString>;

package/dist/state/init.js

@@ -242,8 +242,8 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- the JSON operators retractLastTurn uses work the same on either type.
 --
 -- reported_usage holds a whole turn's TokenUsageRollup — what providers reported
--- for the turn this row completed — and is written only on the LAST assistant row
--- of a turn, so a reloaded transcript can show the figure the live turn showed.
+-- for the turn this row completed — on the LAST assistant row of an older turn
+-- only. cortex_thread_turns holds the figures of each later turn.
 -- It is NOT the tokens column beside it, and the two must never be read for
 -- each other: tokens is an offline js-tiktoken estimate stamped on EVERY row so
 -- the read path can window by budget without a provider round trip, and it exists
@@ -283,8 +283,8 @@ CREATE TABLE IF NOT EXISTS messages (
   role          TEXT,
   content_jsonb JSONB,
   message_envelope JSON,
-  -- Versioned AI SDK UIMessage projection for the whole turn. Present only
-  -- on the genuine-user-start row. Model-history reads never select it.
+  -- Versioned AI SDK UIMessage projection of one written group, on the first
+  -- row of that group. Model-history reads never select it.
   display_envelope JSONB,
   tokens        INTEGER NOT NULL,
   reported_usage JSONB,
@@ -294,6 +294,24 @@ CREATE TABLE IF NOT EXISTS messages (
   PRIMARY KEY (thread_id, seq)
 );
 
+-- The state of one chat turn, and no message: a close never changes a row of
+-- messages. messages.reported_usage and messages.turn_duration_ms hold the
+-- figures of the older turns, which have no record here.
+CREATE TABLE IF NOT EXISTS cortex_thread_turns (
+  thread_id        TEXT NOT NULL,
+  -- The seq of the user row that opens the turn.
+  start_seq        BIGINT NOT NULL,
+  status           TEXT NOT NULL CHECK (status IN ('open', 'done', 'aborted', 'failed')),
+  -- A short text from the class of the error, never its message, because each later turn sends the note.
+  reason           TEXT,
+  -- Absent when no provider reported a quantity, the same as messages.reported_usage.
+  reported_usage   JSONB,
+  turn_duration_ms BIGINT,
+  opened_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  closed_at        TIMESTAMPTZ,
+  PRIMARY KEY (thread_id, start_seq)
+);
+
 -- Conversation thread metadata — the harness ThreadStore module's table,
 -- one row per conversation thread. Holds the analysis-scope, title, and
 -- soft-delete tombstone the harness messages table deliberately lacks.
@@ -413,6 +431,23 @@ CREATE TABLE IF NOT EXISTS cortex_ask_grants (
   created_at   TEXT NOT NULL,
   PRIMARY KEY (analysis_id, user_id, grant_key)
 );
+
+-- The kept text of each cut tool result. thread_id is null for a text of a run, thus purgeThread removes
+-- only the texts of chat turns, and purgeAnalysis removes each row by analysis_id.
+CREATE TABLE IF NOT EXISTS cortex_tool_outputs (
+  analysis_id  TEXT NOT NULL,
+  ref          TEXT NOT NULL,
+  tool_name    TEXT NOT NULL,
+  tool_call_id TEXT NOT NULL,
+  thread_id    TEXT,
+  content      TEXT NOT NULL,
+  total_length INTEGER NOT NULL,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (analysis_id, ref)
+);
+
+CREATE INDEX IF NOT EXISTS cortex_tool_outputs_thread_idx
+  ON cortex_tool_outputs (thread_id) WHERE thread_id IS NOT NULL;
 `;
 /**
  * Initialize Cortex state tables. Safe to call on every startup and across

package/dist/state/purge-analysis.js

@@ -78,6 +78,8 @@ const ANALYSIS_KEYED_DELETES = [
     { 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" },
+    // By its own analysis id, not through the thread rows: a kept text of a run names no thread.
+    { op: "purgeAnalysis.toolOutputs", sql: "DELETE FROM cortex_tool_outputs WHERE analysis_id = $1" },
     { op: "purgeAnalysis.plans", sql: "DELETE FROM cortex_plans WHERE analysis_id = $1" },
     { op: "purgeAnalysis.reportVersions", sql: "DELETE FROM cortex_report_versions WHERE analysis_id = $1" },
     { op: "purgeAnalysis.reportSessionState", sql: "DELETE FROM cortex_report_session_state WHERE analysis_id = $1" },
@@ -133,6 +135,8 @@ export function createAnalysisPurge({ pool, workflows, logger: injected }) {
     // 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.turnRecords", `DELETE FROM cortex_thread_turns
+                 WHERE thread_id IN (SELECT thread_id FROM cortex_analysis_threads WHERE analysis_id = $1)`, analysisId).map(() => messages))
         .andThen((messages) => deleteRows(client, "purgeAnalysis.threads", "DELETE FROM cortex_analysis_threads WHERE analysis_id = $1", analysisId).map((threads) => ({
         threads,
         messages,

package/dist/state/tool-outputs.d.ts

@@ -0,0 +1,4 @@
+/** The Postgres realization of the tool output store of the loop, over `cortex_tool_outputs`. */
+import type { Pool } from "pg";
+import type { ToolOutputStore } from "../loop/tool-output.js";
+export declare function createToolOutputStore(pool: Pool): ToolOutputStore;

package/dist/state/tool-outputs.js

@@ -0,0 +1,30 @@
+/** The Postgres realization of the tool output store of the loop, over `cortex_tool_outputs`. */
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+function toKeptToolOutput(row) {
+    return {
+        analysisId: row.analysis_id,
+        ref: row.ref,
+        toolName: row.tool_name,
+        toolCallId: row.tool_call_id,
+        ...(row.thread_id === null ? {} : { threadId: row.thread_id }),
+        content: row.content,
+        totalLength: row.total_length,
+    };
+}
+export function createToolOutputStore(pool) {
+    return {
+        put: (output) => tryMutation("toolOutputs.put", () => pool.query(
+        // The update sets no `created_at`, thus the row keeps the time of its first put.
+        `INSERT INTO cortex_tool_outputs (analysis_id, ref, tool_name, tool_call_id, thread_id, content, total_length)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         ON CONFLICT (analysis_id, ref) DO UPDATE SET
+           tool_name = EXCLUDED.tool_name,
+           tool_call_id = EXCLUDED.tool_call_id,
+           thread_id = EXCLUDED.thread_id,
+           content = EXCLUDED.content,
+           total_length = EXCLUDED.total_length`, [output.analysisId, output.ref, output.toolName, output.toolCallId, output.threadId ?? null, output.content, output.totalLength])).map(() => undefined),
+        get: (analysisId, ref) => tryQuery("toolOutputs.get", () => pool.query(`SELECT analysis_id, ref, tool_name, tool_call_id, thread_id, content, total_length
+         FROM cortex_tool_outputs
+         WHERE analysis_id = $1 AND ref = $2`, [analysisId, ref])).map(({ rows }) => (rows[0] === undefined ? null : toKeptToolOutput(rows[0]))),
+    };
+}

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

@@ -26,6 +26,7 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { DbError } from "../lib/db-result.js";
 import { type GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
@@ -63,6 +64,8 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
     readonly skillsDir: string;
     /** LLM usage-accounting seam for the profiler agent loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** The store of the profiler loop and of its read tool. */
+    readonly toolOutputStore?: ToolOutputStore;
     /**
      * The farm-extension seam of the embedder. Bound, it rides into the
      * profiler agent deps, and the substrate attaches `link_packages`. Thus

package/dist/tasks/data-profile.js

@@ -271,6 +271,7 @@ export function profilerSandboxAgentDeps(deps, step) {
         ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
         ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
         ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
+        ...(deps.toolOutputStore ? { toolOutputStore: deps.toolOutputStore } : {}),
         bioKeys: deps.bioKeys,
         step,
     };
@@ -548,6 +549,7 @@ export async function runDataProfileBody(input, deps) {
                 runStep: durableStep,
                 resolved: () => accepted !== null,
                 usageRecorder: deps.usageRecorder,
+                toolOutputStore: deps.toolOutputStore,
                 isFatalLoopError: (err) => err instanceof DBOSErrors.DBOSWorkflowCancelledError,
             }, {
                 tools: [submitProfileTool],

package/dist/tools/ad-hoc-router.d.ts

@@ -1,7 +1,9 @@
 import type { Pool } from "pg";
 import { type AgentSession } from "../auth/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy, ResourceSpec } from "../config/resource-limits.js";
 import type { Logger } from "../lib/logger.js";
+import { type AgentRunUsage } from "../loop/metrics.js";
 import { type ChatProvider } from "../providers/types.js";
 import type { CheckedPackage } from "./sandbox/list-available-packages.js";
 export declare const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
@@ -48,6 +50,8 @@ export interface AdHocRouterDeps {
      * the entries reach the link pass as the model wrote them.
      */
     readonly resolvePackages?: (names: readonly string[]) => Promise<readonly CheckedPackage[] | null>;
+    /** Falls back to the no-op recorder when omitted. */
+    readonly usageRecorder?: UsageRecorder;
 }
 export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;
 export declare function validAdHocResources(value: unknown, policy?: ResourcePolicy): ResourceSpec | null;
@@ -56,4 +60,8 @@ export declare function routeAdHocRequest(deps: AdHocRouterDeps, input: {
     request: string;
     session: AgentSession;
     signal: AbortSignal;
+    /** The router call folds its usage into this, so the turn total includes it. */
+    readonly turnUsage?: AgentRunUsage;
+    /** Carried into the record key of the router usage entry. */
+    readonly invocationId?: string;
 }): Promise<AdHocRoute>;

package/dist/tools/ad-hoc-router.js

@@ -3,8 +3,11 @@ import { z } from "zod";
 import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
 import { forSubAgent } from "../auth/types.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
+import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
+import { countChatTokens } from "../loop/metrics.js";
+import { accountForChatCall } from "../loop/run-agent.js";
 import { packagesSection, resourceEstimationSection } from "../prompts/planner.js";
 import { effectiveDeadlineMs } from "../providers/types.js";
 import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
@@ -12,6 +15,8 @@ import { loadDataProfileStatus } from "../state/index.js";
 export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
 export const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
+/** Must differ from a loop step name such as `llm-0`, since both share the usage-record key space. */
+const AD_HOC_ROUTE_CALL_NAME = "adhoc-route";
 const resourcesSchema = z.object({
     cpu: z.number().positive(),
     memoryGb: z.number().positive(),
@@ -152,6 +157,7 @@ function routeTool() {
 }
 export async function routeAdHocRequest(deps, input) {
     const logger = (deps.logger ?? createNoopLogger()).named("adhoc-router").with({ analysisId: input.analysisId, model: deps.model });
+    const routerSession = forSubAgent(input.session, AD_HOC_ROUTER_AGENT_ID);
     const catalog = PLANNABLE_AGENT_CATALOG.map((agent) => `- ${agent.id}: capabilities [${agent.capabilities.join(", ")}]; suitable for [${agent.suitableFor.join(", ")}]`).join("\n");
     const orientation = await profileOrientation(deps.pool, input.analysisId, logger);
     const controller = new AbortController();
@@ -160,7 +166,8 @@ export async function routeAdHocRequest(deps, input) {
     let raw;
     let failure;
     try {
-        const response = unwrapOrThrow(await deps.provider.chat({
+        const response = unwrapOrThrow(await deps.provider
+            .chat({
             system: [
                 "Select exactly one specialist for a targeted one-step analysis, estimate its sandbox resources, and name the packages that the step imports.",
                 "Choose only from the supplied catalog. Do not create a plan, reject the request, or select scientific-executor.",
@@ -179,7 +186,19 @@ export async function routeAdHocRequest(deps, input) {
             // No forced tool choice: some Claude models reject it with a
             // 400. A reply without the call falls back below as `malformed`.
             tools: routeTool(),
-        }, forSubAgent(input.session, AD_HOC_ROUTER_AGENT_ID), signal));
+        }, routerSession, signal)
+            .map(countChatTokens(AD_HOC_ROUTER_AGENT_ID)));
+        // A failed call throws at unwrapOrThrow above, so no usage is recorded.
+        accountForChatCall(response, {
+            session: routerSession,
+            agentId: AD_HOC_ROUTER_AGENT_ID,
+            callPath: routerSession.provenance.callPath,
+            stepName: AD_HOC_ROUTE_CALL_NAME,
+            ...(input.invocationId === undefined ? {} : { invocationId: input.invocationId }),
+            usageRecorder: deps.usageRecorder ?? createNoopUsageRecorder(),
+            logger,
+            rollups: input.turnUsage === undefined ? [] : [input.turnUsage],
+        });
         const call = Array.isArray(response.message.content)
             ? response.message.content.find((part) => part.type === "tool-call" && part.toolName === "submit_route")
             : undefined;

package/dist/tools/display/show-user.d.ts

@@ -26,7 +26,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "markdown" | "table" | "echart" | "svg" | "structure";
+    kind: "code" | "markdown" | "echart" | "svg" | "table" | "structure";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

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

@@ -3,6 +3,7 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import type { Pool } from "pg";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
@@ -29,6 +30,8 @@ export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "fa
      * run reserves anything. Without it, the link pass returns at once.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
+    /** Falls back to the no-op recorder when omitted. */
+    readonly usageRecorder?: UsageRecorder;
 }
 export declare class PlanNotFoundError extends Error {
     constructor(planId: string);

package/dist/tools/execute-analysis.js

@@ -296,7 +296,15 @@ async function persistedAdHocPlan(deps, args) {
         resourcePolicy: deps.resourcePolicy,
         logger: deps.logger,
         ...(resolvePackages ? { resolvePackages } : {}),
-    }, { analysisId: args.analysisId, request: args.request, session: args.ctx.session, signal: args.ctx.signal });
+        ...(deps.usageRecorder ? { usageRecorder: deps.usageRecorder } : {}),
+    }, {
+        analysisId: args.analysisId,
+        request: args.request,
+        session: args.ctx.session,
+        signal: args.ctx.signal,
+        ...(args.ctx.turnUsage ? { turnUsage: args.ctx.turnUsage } : {}),
+        invocationId: args.ctx.invocationId,
+    });
     const candidate = buildAdHocPlan(args.request, route);
     unwrapOrThrow(await upsertPlan(deps.pool, { planId: args.planId, analysisId: args.analysisId, plan: candidate }));
     const stored = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));

package/dist/tools/read-tool-output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `read_tool_output` — reads the kept text of a tool result that the loop cut, by a window or by a pattern.
+ * Each result stays under the cap of the loop, thus the loop never cuts a result of this tool.
+ */
+import { type ToolOutputStore } from "../loop/tool-output.js";
+import { type Tool } from "./define-tool.js";
+export declare function createReadToolOutputTool(store: ToolOutputStore): Tool;