@inflexa-ai/harness 0.39.1 → 0.40.0

package/dist/state/data-profile.js

@@ -225,9 +225,9 @@ export function expireStaleDataProfile(pool, analysisId, timeoutMs) {
  * Reset a ledger row wedged at `running` with no workflow behind it back to
  * `failed`, so the normal retry path can re-profile it.
  *
- * A start that rejects after the CAS already flipped the row to `running`
+ * A start that fails after the CAS already flipped the row to `running`
  * compensates itself (`triggerDataProfile`/`runDataProfile` fail the ledger in
- * their catch). This covers the residual case that compensation cannot: a host
+ * their dispatch). This covers the residual case that compensation cannot: a host
  * that dies in the window between the CAS and the `DBOS.startWorkflow` insert
  * leaves a `running` row with no workflow for recovery to resume — nothing
  * would ever move it off `running`, and every later trigger reports

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

@@ -17,7 +17,7 @@
  * triggers dedup via the ledger CAS (only one `tryStart/tryRerun/tryRetry`
  * UPDATE wins); each winning attempt starts a workflow under a per-attempt id.
  */
-import { type ResultAsync } from "neverthrow";
+import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
@@ -26,6 +26,8 @@ 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";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
@@ -62,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
@@ -149,9 +153,25 @@ export declare function runDataProfileBody(input: DataProfileWorkflowInput, deps
  * - `"already_running"`: a workflow already owns the row, and nothing new ran.
  * - `"completed"`: the analysis has no input files, so the row is `completed` at once
  *   with no result. No workflow ran (see {@link completeEmptyDataProfile}).
- * - `"failed"`: the trigger refused the call or faulted, and the row is unchanged.
+ * - `"failed"`: the trigger refused the call, and the row is unchanged.
  */
 export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "completed" | "failed";
+/**
+ * Why the dispatch of a claimed profile started no workflow. The dispatch writes `failed` to the claimed
+ * row before a caller reads the `err`:
+ * - `refused`: `RunAuthorizer.authorize` gave an `err`. `reason` and `suspend` are the values of the host.
+ * - `start_failed`: DBOS did not start the workflow. `cause` is the throw of DBOS.
+ */
+export type DataProfileStartError = {
+    readonly type: "refused";
+    readonly reason: string;
+    readonly suspend: boolean;
+} | {
+    readonly type: "start_failed";
+    readonly cause: unknown;
+};
+/** A one-line, user-facing description of a `DataProfileStartError`. */
+export declare function describeDataProfileStartError(e: DataProfileStartError): string;
 /**
  * Route-side deps for triggering the data-profile workflow: the ledger pool,
  * the run authorizer, and the registered workflow callable. The body's
@@ -213,16 +233,17 @@ export declare function dataProfileWorkflowId(analysisId: string, nonce: string)
  * `"completed"`. An empty manifest against a seed that names files is a divergence
  * between the caller and the ledger, and the trigger refuses it.
  *
- * Returns what happened, so the caller can surface it (e.g. in the seed response).
+ * Returns what happened, so the caller can surface it (e.g. in the seed response). A
+ * failed ledger read or claim is the `err`. The dispatch settles its own row, thus a
+ * refusal or a failed start after a claim shows on the ledger only.
  */
-export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<DataProfileTriggerResult>;
+export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): ResultAsync<DataProfileTriggerResult, DbError>;
 /**
  * Start the data-profile workflow for an already-claimed analysis (the retry
  * route claims via `tryRetryDataProfile`, then calls this). The caller does not
- * await the workflow's completion, but a start that rejects compensates the
- * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
- * own `.catch` still observes the error and the row never wedges at `running`.
- * A refused authorization fails the row with the reason of the host, and the
- * promise resolves: the row is where a caller reads the outcome.
+ * wait for the completion of the workflow. A refused authorization and a failed
+ * start each settle the row as `failed` before the `err` (see
+ * {@link dispatchClaimedProfile}), thus a caller that minted an authorization
+ * can revoke it.
  */
-export declare function runDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<void>;
+export declare function runDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): ResultAsync<void, DataProfileStartError>;

package/dist/tasks/data-profile.js

@@ -19,7 +19,7 @@
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { randomUUID } from "node:crypto";
-import { err, ok } from "neverthrow";
+import { ResultAsync, err, ok } from "neverthrow";
 import { forStep, forSubAgent } from "../auth/types.js";
 import { createDataProfilerAgent } from "../agents/sandbox/data-profiler.js";
 import { runToTerminal } from "../loop/run-to-terminal.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,
     };
@@ -345,14 +346,14 @@ export async function runDataProfileBody(input, deps) {
             return;
         }
         // 2. Register staged files in cortex_artifacts
-        await upsertArtifacts(deps.pool, stagedInputs.map((f) => ({
+        unwrapOrThrow(await upsertArtifacts(deps.pool, stagedInputs.map((f) => ({
             resourceId: analysisId,
             path: inputArtifactPath(f),
             hash: f.hash,
             size: f.size,
             role: "input",
             fileId: f.fileId,
-        })));
+        }))));
         const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
         const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
@@ -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],
@@ -636,6 +638,15 @@ function settleTerminalWrite(logger, analysisId, write, status) {
     }
     recordRunCompleted({ workflow: "data_profile", status, durationMs: elapsedSinceIso(write.startedAt) });
 }
+/** A one-line, user-facing description of a `DataProfileStartError`. */
+export function describeDataProfileStartError(e) {
+    switch (e.type) {
+        case "refused":
+            return `the profile run was not authorized: ${e.reason}`;
+        case "start_failed":
+            return `the profile workflow did not start: ${profileFailureReason(e.cause)}`;
+    }
+}
 /**
  * Resolve the `RunSession` the workflow runs under. Whether the authorization
  * is freshly minted (Cortex-owned) or reused (caller-owned) is decided by the
@@ -667,18 +678,14 @@ export function dataProfileWorkflowId(analysisId, nonce) {
     return `dataprofile:${analysisId}:${nonce}`;
 }
 /**
- * Authorize the run via the `RunAuthorizer` and start the data-profile workflow
- * under a per-attempt id `dataprofile:{analysisId}:{nonce}` — concurrent
- * triggers are already serialized by the ledger CAS. The caller has already
- * staged the inputs and supplied the manifest in `params.stagedInputs`; this
- * forwards it into the workflow input. Fire-and-forget: the handle result is
- * not awaited.
+ * Start the data-profile workflow under the authorization and a per-attempt id
+ * `dataprofile:{analysisId}:{nonce}` — concurrent triggers are already
+ * serialized by the ledger CAS. The caller has already staged the inputs and
+ * supplied the manifest in `params.stagedInputs`; this forwards it into the
+ * workflow input. The handle result is not awaited.
  */
-async function startDataProfileWorkflow(deps, params) {
-    const authorized = await authorizeDataProfile(deps, params);
-    if (authorized.isErr())
-        return err(authorized.error);
-    const { runSession, ownsMandate } = authorized.value; // oss-core-managed-ok
+async function startDataProfileWorkflow(deps, params, authorization) {
+    const { runSession, ownsMandate } = authorization; // oss-core-managed-ok
     const attemptNonce = randomUUID();
     await DBOS.startWorkflow(deps.workflow, {
         workflowID: dataProfileWorkflowId(params.analysisId, attemptNonce),
@@ -688,20 +695,29 @@ async function startDataProfileWorkflow(deps, params) {
         ownsMandate, // oss-core-managed-ok
         stagedInputs: params.stagedInputs,
     });
-    return ok(undefined);
 }
 /**
- * Dispatch a claimed profile, fire-and-forget. The claim already flipped the
- * row to `running`, thus a refused authorization and a rejected start each
- * settle the row as `failed`, and it never wedges at `running`.
+ * Authorize and start a claimed profile. The claim already flipped the row to
+ * `running`, thus a refused authorization and a failed start each settle the
+ * row as `failed` before the `err`, and the row never wedges at `running`. A
+ * rejected `authorize` promise is a defect of the host: the row is settled the
+ * same way, and the rejection passes through.
  */
 async function dispatchClaimedProfile(deps, params, phase) {
-    const started = await startDataProfileWorkflow(deps, params).catch(async (cause) => {
-        await compensateStartFailure(deps, params.analysisId, phase, cause);
-        return undefined;
+    const authorized = await Promise.resolve(authorizeDataProfile(deps, params)).catch(async (defect) => {
+        await compensateStartFailure(deps, params.analysisId, phase, defect);
+        throw defect;
     });
-    if (started?.isErr())
-        await refuseClaimedProfile(deps, params.analysisId, phase, started.error);
+    if (authorized.isErr()) {
+        await refuseClaimedProfile(deps, params.analysisId, phase, authorized.error);
+        return err({ type: "refused", reason: authorized.error.reason, suspend: authorized.error.kind === "suspended" });
+    }
+    const started = await ResultAsync.fromPromise(startDataProfileWorkflow(deps, params, authorized.value), (cause) => cause);
+    if (started.isErr()) {
+        await compensateStartFailure(deps, params.analysisId, phase, started.error);
+        return err({ type: "start_failed", cause: started.error });
+    }
+    return ok(undefined);
 }
 /**
  * Attempt to claim and run data profiling for an analysis, then start the workflow
@@ -720,70 +736,85 @@ async function dispatchClaimedProfile(deps, params, phase) {
  * `"completed"`. An empty manifest against a seed that names files is a divergence
  * between the caller and the ledger, and the trigger refuses it.
  *
- * Returns what happened, so the caller can surface it (e.g. in the seed response).
+ * Returns what happened, so the caller can surface it (e.g. in the seed response). A
+ * failed ledger read or claim is the `err`. The dispatch settles its own row, thus a
+ * refusal or a failed start after a claim shows on the ledger only.
  */
-export async function triggerDataProfile(deps, params) {
+export function triggerDataProfile(deps, params) {
+    return new ResultAsync(claimAndDispatchProfile(deps, params));
+}
+async function claimAndDispatchProfile(deps, params) {
     const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId: params.analysisId });
     const { analysisId } = params;
-    try {
-        // ADVISORY pre-check, not the enforcement — the claim CAS carries the same seed
-        // conjunct (see `SEEDED` in state/data-profile.ts) and is what actually makes a
-        // seedless `running` row impossible. This read exists only to name the cause: on
-        // the ordinary non-racing path it turns an opaque "no claim matched" into a
-        // precise reason. An empty array is not a seed — it names zero files. Reads via
-        // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
-        // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
-        const seeded = unwrapOrThrow(await loadSeedInputFileIds(deps.pool, analysisId));
-        if (params.stagedInputs.length === 0) {
-            // The trigger validates the manifest it is about to dispatch against the ledger
-            // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
-            // then hit the body's empty-manifest path, and complete with a NULL result while
-            // the seed still names files. Refuse the divergence before any claim.
-            if (seeded !== null && seeded.length > 0) {
-                logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
-                return "failed";
-            }
-            // The analysis has no input files, so there is nothing to profile. The row is
-            // `completed` at once, with no workflow. The CAS carries the same seed
-            // predicate as this pre-read, so a seed upsert that lands in between cannot be
-            // hidden behind a finished profile: the stamp refuses, and the status read
-            // below names the cause.
-            if (unwrapOrThrow(await completeEmptyDataProfile(deps.pool, analysisId)))
-                return "completed";
-            const current = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
-            if (current?.status === "running")
-                return "already_running";
-            logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
-            return "failed";
-        }
-        // A non-empty manifest against a seed that names no file: the caller skipped the
-        // seed, or the analysis row is missing. Name the cause before any claim.
-        if (seeded === null || seeded.length === 0) {
-            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
-            return "failed";
-        }
-        const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));
-        if (started) {
-            void dispatchClaimedProfile(deps, params, "Run");
-            return "started";
+    // ADVISORY pre-check, not the enforcement — the claim CAS carries the same seed
+    // conjunct (see `SEEDED` in state/data-profile.ts) and is what actually makes a
+    // seedless `running` row impossible. This read exists only to name the cause: on
+    // the ordinary non-racing path it turns an opaque "no claim matched" into a
+    // precise reason. An empty array is not a seed — it names zero files. Reads via
+    // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
+    // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
+    const seedRead = await loadSeedInputFileIds(deps.pool, analysisId);
+    if (seedRead.isErr())
+        return err(seedRead.error);
+    const seeded = seedRead.value;
+    if (params.stagedInputs.length === 0) {
+        // The trigger validates the manifest it is about to dispatch against the ledger
+        // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
+        // then hit the body's empty-manifest path, and complete with a NULL result while
+        // the seed still names files. Refuse the divergence before any claim.
+        if (seeded !== null && seeded.length > 0) {
+            logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+            return ok("failed");
         }
-        const restarted = unwrapOrThrow(await tryRerunDataProfile(deps.pool, analysisId));
-        if (restarted) {
-            void dispatchClaimedProfile(deps, params, "Re-run");
-            return "restarted";
-        }
-        const status = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
-        if (status?.status === "running")
-            return "already_running";
-        return "failed";
+        // The analysis has no input files, so there is nothing to profile. The row is
+        // `completed` at once, with no workflow. The CAS carries the same seed
+        // predicate as this pre-read, so a seed upsert that lands in between cannot be
+        // hidden behind a finished profile: the stamp refuses, and the status read
+        // below names the cause.
+        const completed = await completeEmptyDataProfile(deps.pool, analysisId);
+        if (completed.isErr())
+            return err(completed.error);
+        if (completed.value)
+            return ok("completed");
+        const current = await loadDataProfileStatus(deps.pool, analysisId);
+        if (current.isErr())
+            return err(current.error);
+        if (current.value?.status === "running")
+            return ok("already_running");
+        logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
+        return ok("failed");
     }
-    catch (err) {
-        logger.error("trigger error", logger.errorFields(err));
-        return "failed";
+    // A non-empty manifest against a seed that names no file: the caller skipped the
+    // seed, or the analysis row is missing. Name the cause before any claim.
+    if (seeded === null || seeded.length === 0) {
+        logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
+        return ok("failed");
+    }
+    const started = await tryStartDataProfile(deps.pool, analysisId);
+    if (started.isErr())
+        return err(started.error);
+    if (started.value) {
+        dispatchInBackground(deps, params, "Run");
+        return ok("started");
+    }
+    const restarted = await tryRerunDataProfile(deps.pool, analysisId);
+    if (restarted.isErr())
+        return err(restarted.error);
+    if (restarted.value) {
+        dispatchInBackground(deps, params, "Re-run");
+        return ok("restarted");
     }
+    const status = await loadDataProfileStatus(deps.pool, analysisId);
+    if (status.isErr())
+        return err(status.error);
+    return ok(status.value?.status === "running" ? "already_running" : "failed");
+}
+/** The dispatch settles the row on each arm and logs a defect, thus the trigger keeps no outcome of it. */
+function dispatchInBackground(deps, params, phase) {
+    void dispatchClaimedProfile(deps, params, phase).catch(() => undefined);
 }
 /**
- * Compensate a fire-and-forget start that rejected. The ledger CAS in
+ * Compensate a start that failed after the claim. The ledger CAS in
  * `tryStart`/`tryRerun`/`tryRetry` already flipped the row to `running`; if the
  * dispatch never landed a workflow, DBOS has nothing to recover, so without
  * this the row would sit at `running` forever and every later trigger would
@@ -827,23 +858,13 @@ async function failClaimedProfile(deps, analysisId, phase, reason) {
 /**
  * Start the data-profile workflow for an already-claimed analysis (the retry
  * route claims via `tryRetryDataProfile`, then calls this). The caller does not
- * await the workflow's completion, but a start that rejects compensates the
- * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
- * own `.catch` still observes the error and the row never wedges at `running`.
- * A refused authorization fails the row with the reason of the host, and the
- * promise resolves: the row is where a caller reads the outcome.
+ * wait for the completion of the workflow. A refused authorization and a failed
+ * start each settle the row as `failed` before the `err` (see
+ * {@link dispatchClaimedProfile}), thus a caller that minted an authorization
+ * can revoke it.
  */
-export async function runDataProfile(deps, params) {
-    let started;
-    try {
-        started = await startDataProfileWorkflow(deps, params);
-    }
-    catch (cause) {
-        await compensateStartFailure(deps, params.analysisId, "Retry", cause);
-        throw cause;
-    }
-    if (started.isErr())
-        await refuseClaimedProfile(deps, params.analysisId, "Retry", started.error);
+export function runDataProfile(deps, params) {
+    return new ResultAsync(dispatchClaimedProfile(deps, params, "Retry"));
 }
 /**
  * Concise, UI-safe failure reason. `data_profile_error` is surfaced verbatim

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