@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/state/schema.d.ts

@@ -54,6 +54,8 @@ export declare const RunStatus: z.ZodEnum<{
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
 export type RunStatus = z.infer<typeof RunStatus>;
+/** A status that a run keeps once it ended: every status but `running`. */
+export type TerminalRunStatus = Exclude<RunStatus, "running">;
 export declare const StepExecutionStatus: z.ZodEnum<{
     failed: "failed";
     pending: "pending";

package/dist/state/step-executions.d.ts

@@ -74,4 +74,13 @@ export declare function updateStepExecution(pool: Querier, runId: string, stepId
  * these steps never started.
  */
 export declare function sweepPendingStepExecutions(pool: Querier, runId: string): ResultAsync<void, DbError>;
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export declare function cancelRunningStepExecutions(pool: Querier, runId: string, reason: string): ResultAsync<void, DbError>;
 export declare function queryStepsByRun(pool: Querier, runId: string): ResultAsync<StepExecutionRow[], DbError>;

package/dist/state/step-executions.js

@@ -136,6 +136,28 @@ export function sweepPendingStepExecutions(pool, runId) {
         });
     });
 }
+/**
+ * Settle a run's still-`running` rows to `canceled` after an engine cancel.
+ * A canceled child re-raises before it writes a terminal row, so this is the
+ * only writer for a step that the cancel cut. `canceled`, not `skipped`: these
+ * steps started. The `status = 'running'` guard keeps a terminal row that a
+ * child wrote first. `started_at` and `completed_at` are ISO 8601 `TEXT`, so
+ * the duration casts both; it is NULL when `started_at` is NULL.
+ */
+export function cancelRunningStepExecutions(pool, runId, reason) {
+    const now = new Date().toISOString();
+    return tryMutation("stepExecutions.cancelRunningStepExecutions", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET status = 'canceled',
+              completed_at = $2::text,
+              duration_ms = (EXTRACT(EPOCH FROM ($2::text::timestamptz - started_at::timestamptz)) * 1000)::bigint,
+              error = $3
+          WHERE run_id = $1 AND status = 'running'`,
+            values: [runId, now, reason],
+        });
+    });
+}
 export function queryStepsByRun(pool, runId) {
     return tryQuery("stepExecutions.queryStepsByRun", async () => {
         const result = await pool.query({

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

@@ -103,5 +103,11 @@ export interface ProfileActivityFrame {
  * A failing write is swallowed and logged, never propagated: observation is a
  * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
  * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ *
+ * Each emission writes the reconciling activity part, so a late subscriber folds to the
+ * current activity, and then one `data-activity-entry`, so it also gets each earlier line.
+ * The two parts carry one time from `now`, which the body binds to the checkpointed clock of
+ * its workflow. The two writes fail alone. The sequence number of the entry advances before
+ * the clock read and the writes, thus a failure cannot shift a later id.
  */
-export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger): ProfileActivityEmitter;
+export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger, now: () => Promise<number>): ProfileActivityEmitter;

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

@@ -19,7 +19,7 @@
  * anything that throws on the way there reaches the failure path having emitted
  * no terminal at all.
  */
-import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.js";
+import { activityEmission, activityForTool } from "../sandbox/sandbox-step-translate.js";
 /**
  * Build the profile's activity channel over `write`.
  *
@@ -30,21 +30,30 @@ import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.j
  * A failing write is swallowed and logged, never propagated: observation is a
  * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
  * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ *
+ * Each emission writes the reconciling activity part, so a late subscriber folds to the
+ * current activity, and then one `data-activity-entry`, so it also gets each earlier line.
+ * The two parts carry one time from `now`, which the body binds to the checkpointed clock of
+ * its workflow. The two writes fail alone. The sequence number of the entry advances before
+ * the clock read and the writes, thus a failure cannot shift a later id.
  */
-export function createProfileActivityEmitter(write, frame, logger) {
-    // One reconciling id for the profile's single step, so the run-stream fold
-    // collapses every phase transition latest-wins onto one frame rather than
-    // accumulating them. Minted through the shared construction because that
-    // sameness across producers is what makes the fold correct.
-    const id = stepPartId("step-activity", frame.runId, frame.stepId);
-    const emit = async (phase, activity) => {
+export function createProfileActivityEmitter(write, frame, logger, now) {
+    let seq = 0;
+    const writeAlone = async (part, phase) => {
         try {
-            await write({ type: "data-step-activity", id, runId: frame.runId, stepId: frame.stepId, phase, activity });
+            await write(part);
         }
         catch (err) {
             logger.warn("run-event write failed (non-fatal)", { phase, ...logger.errorFields(err) });
         }
     };
+    const emit = async (phase, activity) => {
+        const position = seq++;
+        const at = new Date(await now()).toISOString();
+        const parts = activityEmission(frame, position, phase, activity, at);
+        await writeAlone(parts.activity, phase);
+        await writeAlone(parts.entry, phase);
+    };
     return {
         sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
         scanning: () => emit("executing", "Scanning input files"),

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

@@ -28,7 +28,7 @@ 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 GateRefusal, type NoticeFailure } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
@@ -38,6 +38,15 @@ import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type ProfileSubmission } from "../schemas/data-profile-schemas.js";
 import { type ProfileResolution } from "./data-profile-resolve.js";
 import { type DataProfileResult } from "../state/index.js";
+/** The settle of one profile claim: the ledger row left `running`, and the terminal write stamped it. */
+export interface DataProfileSettlement {
+    readonly analysisId: string;
+    readonly status: "completed" | "failed";
+    /** The `data_profile_completed_at` that the terminal write stamped, as an ISO 8601 string. */
+    readonly completedAt: string;
+}
+/** The notice of a profile settle. The workflow body calls it one time for each settled claim. */
+export type NotifyDataProfileSettled = (settlement: DataProfileSettlement) => ResultAsync<void, NoticeFailure>;
 /** The body's construction-time deps — closed over at registration. */
 export interface DataProfileDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
@@ -73,6 +82,11 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
      * Unbound keeps the current shape: no link tool, and no error.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
+    /**
+     * Notice of each profile settle, for the records of the embedder. Unbound, the
+     * body calls nothing. It is not a provenance hook.
+     */
+    readonly notifyDataProfileSettled?: NotifyDataProfileSettled;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -296,7 +296,7 @@ export async function runDataProfileBody(input, deps) {
     // ledger has no suspended state and the retry path takes a `failed` row again.
     const suspendProfile = async (suspension) => {
         logger.warn("profile suspended", { reason: suspension.reason });
-        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, suspension.reason)), "failed");
+        await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, suspension.reason)), "failed", deps.notifyDataProfileSettled);
         await revoke("data-profile-suspended");
         unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
         await activity.failed(suspension.reason);
@@ -310,7 +310,7 @@ export async function runDataProfileBody(input, deps) {
     // this capability, and a body that composed its own strings is a body they can drift from.
     // The frame is the workflow's synthetic one: both values are constants shared by every analysis,
     // so they identify nothing and consumers are required not to key on them.
-    const activity = createProfileActivityEmitter((part) => DBOS.writeStream("events", part), { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL }, logger);
+    const activity = createProfileActivityEmitter((part) => DBOS.writeStream("events", part), { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL }, logger, () => DBOS.now());
     try {
         // Record which workflow owns this profile before anything else, so a consumer that resolves
         // the id from the ledger can subscribe from the earliest possible moment. Guarded on a real
@@ -337,7 +337,7 @@ export async function runDataProfileBody(input, deps) {
             // catalogue's fit is measured, and a completion that emitted none would make the
             // empty-manifest path invisible to the same monitoring that watches every other.
             logProfileMonitoring(logger, { dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             // This is a terminal completion like any other, so it reports one — a consumer watching
             // an empty-manifest profile sees it settle rather than seeing the stream simply stop.
@@ -390,7 +390,7 @@ export async function runDataProfileBody(input, deps) {
             await activity.indexing();
             await indexProfile({ deps, analysisId, session: runSession, record, scan, logger });
             logProfileMonitoring(logger, { resolution, dimensions: [], probes: [], repairRounds: 0, absorb: "none" });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, record)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             await activity.complete();
             return;
@@ -416,7 +416,7 @@ export async function runDataProfileBody(input, deps) {
                 repairRounds: 0,
                 absorb: absorb.kind,
             });
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, absorbed)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             await activity.complete();
             return;
@@ -571,7 +571,7 @@ export async function runDataProfileBody(input, deps) {
             });
             // 6. Complete — store the FULL profiler finding plus the input signature for
             // staleness detection. The scratch tree is gone; this row is all that survives.
-            settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed");
+            await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, profileRecord)), "completed", deps.notifyDataProfileSettled);
             await revoke("data-profile-completed");
             // LAST statement of the success path, and that placement is the guarantee that exactly
             // one terminal activity is ever emitted. Everything that could still throw — the ledger
@@ -598,7 +598,7 @@ export async function runDataProfileBody(input, deps) {
             return await suspendProfile(suspension);
         logger.error("profile failed", logger.errorFields(err));
         const reason = profileFailureReason(err);
-        settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed");
+        await settleTerminalWrite(logger, analysisId, unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)), "failed", deps.notifyDataProfileSettled);
         await revoke("data-profile-failed");
         // The same bounded, user-safe line the ledger receives — never the raw error, whose paths and
         // stack frames stay in the log record above. This is the only other terminal emission, so
@@ -617,18 +617,23 @@ function logTerminalNoop(logger, analysisId, write) {
 }
 /**
  * Settle one terminal write of the profile ledger. A refused stamp is logged
- * (see `logTerminalNoop`). An accepted stamp records the profile's run outcome:
- * the CAS admits one write per `running` claim, so this is the exactly-once
+ * (see `logTerminalNoop`) and sends no notice. An accepted stamp records the
+ * profile's run outcome and then delivers the settle notice when the deps bind
+ * one: the CAS admits one write per `running` claim, so this is the exactly-once
  * point of the transition — a recovery replay of the body finds the row no
- * longer `running`, and records nothing again. The duration runs from the
+ * longer `running`, and does neither again. The duration runs from the
  * `data_profile_started_at` the claim stamped, never from a body-local clock.
+ * A crash between the stamp and the notice loses that one notice.
  */
-function settleTerminalWrite(logger, analysisId, write, status) {
+async function settleTerminalWrite(logger, analysisId, write, status, notify) {
     if (!write.stamped) {
         logTerminalNoop(logger, analysisId, status === "completed" ? "completion" : "failure");
         return;
     }
     recordRunCompleted({ workflow: "data_profile", status, durationMs: elapsedSinceIso(write.startedAt) });
+    if (notify === undefined)
+        return;
+    await deliverNotice(logger, "notifyDataProfileSettled", notify({ analysisId, status, completedAt: write.completedAt }));
 }
 /** A one-line, user-facing description of a `DataProfileStartError`. */
 export function describeDataProfileStartError(e) {

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

@@ -24,6 +24,8 @@ export interface AdHocRoute {
     readonly agentId: string;
     readonly resources: ResourceSpec;
     readonly rationale: string;
+    /** The capability phrase of the chosen agent, when the router copied one that the agent advertises. */
+    readonly capability?: string;
     /** The validated package entries of the step. Empty is a normal answer. */
     readonly packages: readonly string[];
     /** Every entry that the validation removed, with the reason for the caveat. */

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

@@ -1,6 +1,7 @@
 import { jsonSchema, tool as aiTool } from "ai";
 import { z } from "zod";
 import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.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";
@@ -24,6 +25,7 @@ const resourcesSchema = z.object({
 });
 const routeSchema = z.object({
     agentId: z.string().optional().describe("The id of one specialist from the eligible catalog, copied exactly."),
+    capability: z.string().optional().describe("The one capability phrase of that specialist which this request uses, copied exactly from its capabilities."),
     resources: resourcesSchema
         .optional()
         .describe("The sandbox resources of the step, inside the stated ranges. Omit to take the defaults; a value outside the ranges is replaced by the defaults."),
@@ -241,6 +243,20 @@ export async function routeAdHocRequest(deps, input) {
     // never becomes a `fallbackClass`, because that class describes the route
     // as a whole and a step agent reads it as "the routing itself fell back".
     const { packages, droppedPackages } = await routePackages(candidate.packages, deps.resolvePackages, logger);
-    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages });
-    return { agentId, resources, rationale, packages, droppedPackages, ...(failure ? { fallbackClass: failure } : {}) };
+    // Kept only when the chosen agent really advertises it. A phrase that no agent advertises
+    // resolves no data requirement anyway, and carrying it would put a fabricated capability into
+    // the step and into the run record. An absent phrase is a normal answer, not a fallback class:
+    // most requests use a capability that declares nothing.
+    const requestedCapability = typeof candidate.capability === "string" ? candidate.capability.trim() : "";
+    const capability = (SANDBOX_AGENT_META[agentId]?.capabilities ?? []).includes(requestedCapability) ? requestedCapability : undefined;
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages, ...(capability ? { capability } : {}) });
+    return {
+        agentId,
+        resources,
+        rationale,
+        packages,
+        droppedPackages,
+        ...(capability ? { capability } : {}),
+        ...(failure ? { fallbackClass: failure } : {}),
+    };
 }

package/dist/tools/approval/gateway.js

@@ -40,8 +40,11 @@ export function createAskGateway(deps) {
         // A standing grant this user holds for this ask's grant key — the command
         // unless the tool supplied a broader key — short-circuits the prompt: record
         // the invocation as `resolved` for the audit trail and return without pausing.
+        // The one part it emits is already settled, so no surface prompts, and the
+        // transcript still shows that a standing grant approved the call.
         if (unwrapOrThrow(await selectGrant(pool, ctx.analysisId, ctx.userId, request.grantKey ?? request.command))) {
             unwrapOrThrow(await insertGrantedAsk(pool, row, now));
+            await emitAskPart(ctx.emit, id, request, "resolved", "always");
             return { kind: "always" };
         }
         unwrapOrThrow(await insertPendingAsk(pool, row));
@@ -69,7 +72,7 @@ export function createAskGateway(deps) {
                 throw new AskRejectedError("approval request is no longer available");
             }
             if (resolution.status !== "pending") {
-                await emitAskPart(ctx.emit, id, request, resolution.status);
+                await emitAskPart(ctx.emit, id, request, resolution.status, replyKindOf(resolution.status, resolution.reply));
                 return settle(resolution.status, resolution.reply, ctx.signal);
             }
             await sleepUntil(POLL_INTERVAL_MS, ctx.signal);
@@ -88,7 +91,7 @@ export function createAskGateway(deps) {
     return { ask, answer, pending, sweepExpired };
 }
 /** Emit (or reconcile, under the same id) the ask's `data-ask` chat part. */
-function emitAskPart(emit, id, request, status) {
+function emitAskPart(emit, id, request, status, reply) {
     return emit({
         type: "data-ask",
         data: {
@@ -97,16 +100,36 @@ function emitAskPart(emit, id, request, status) {
             command: request.command,
             ...(request.detail !== undefined ? { detail: request.detail } : {}),
             status,
+            ...(reply !== undefined ? { reply } : {}),
         },
     });
 }
+/**
+ * The kind of reply the terminal part shows: the kind that `settle` acts on for a `resolved` or `rejected` row,
+ * and none for any other status. It never reads the feedback of a rejection, which is for the model.
+ */
+function replyKindOf(status, reply) {
+    switch (status) {
+        case "resolved":
+            return approvalOf(reply).kind;
+        case "rejected":
+            return "reject";
+        case "expired":
+        case "aborted":
+            return undefined;
+    }
+}
+/** The approval that a `resolved` row grants. */
+function approvalOf(reply) {
+    // Only `once` / `always` reach `resolved`; guard the JSONB round-trip and
+    // default to the narrowest approval if a malformed reply ever slipped in.
+    return reply && (reply.kind === "once" || reply.kind === "always") ? reply : { kind: "once" };
+}
 /** Resolve an approval or throw the terminal denial the ledger recorded. */
 function settle(status, reply, signal) {
     switch (status) {
         case "resolved":
-            // Only `once` / `always` reach `resolved`; guard the JSONB round-trip and
-            // default to the narrowest approval if a malformed reply ever slipped in.
-            return reply && (reply.kind === "once" || reply.kind === "always") ? reply : { kind: "once" };
+            return approvalOf(reply);
         case "rejected":
             throw new AskRejectedError(reply && reply.kind === "reject" ? reply.feedback : undefined);
         case "expired":

package/dist/tools/capability-data.d.ts

@@ -0,0 +1,36 @@
+/**
+ * inspectCapabilityData — the reference data a specialist capability cannot run without, and
+ * whether this store holds it.
+ *
+ * The method of a capability lives in a skill pack, and only a sandbox step agent reads a skill.
+ * Thus a conversation or planning surface knows a capability by its phrase alone, and it cannot
+ * name the datasets the method needs. It then does one of two wrong things: it calls the work
+ * impossible, or it designs a method around what it can see and substitutes for what it cannot.
+ *
+ * The declaration on the agent metadata is the one place a surface above the step can read, and
+ * this tool is how it reads it. The answer names an absent dataset by its CATALOG ID, because the
+ * id is what an install takes — a surface that can provision needs the identifier, not a
+ * description. Where the ids reach an agent matters: a prompt names no dataset, so the knowledge
+ * arrives through a tool, which carries its own description into the context at attach time.
+ */
+import type { EnvironmentStorePaths } from "../config/environment-stores.js";
+export type InspectCapabilityDataDeps = Pick<EnvironmentStorePaths, "refStorePath">;
+/** One capability, its declared datasets, and what the store holds of them. */
+export interface CapabilityDataRow {
+    readonly agentId: string;
+    readonly capability: string;
+    readonly installed: readonly string[];
+    readonly absent: readonly string[];
+}
+export interface CapabilityDataResult {
+    /** False when the store could not be answered for: every `absent` list is then unknown, not empty. */
+    readonly storeReadable: boolean;
+    readonly rows: readonly CapabilityDataRow[];
+    readonly content: string;
+}
+/**
+ * Build the tool. The store read happens per call, not at construction: a dataset installed during
+ * the conversation must show as installed on the next call, and a cached answer would have the
+ * agent offer a download the user already approved.
+ */
+export declare function createInspectCapabilityDataTool(deps?: InspectCapabilityDataDeps): import("./define-tool.js").Tool<Record<string, never>, CapabilityDataResult>;

package/dist/tools/capability-data.js

@@ -0,0 +1,73 @@
+/**
+ * inspectCapabilityData — the reference data a specialist capability cannot run without, and
+ * whether this store holds it.
+ *
+ * The method of a capability lives in a skill pack, and only a sandbox step agent reads a skill.
+ * Thus a conversation or planning surface knows a capability by its phrase alone, and it cannot
+ * name the datasets the method needs. It then does one of two wrong things: it calls the work
+ * impossible, or it designs a method around what it can see and substitutes for what it cannot.
+ *
+ * The declaration on the agent metadata is the one place a surface above the step can read, and
+ * this tool is how it reads it. The answer names an absent dataset by its CATALOG ID, because the
+ * id is what an install takes — a surface that can provision needs the identifier, not a
+ * description. Where the ids reach an agent matters: a prompt names no dataset, so the knowledge
+ * arrives through a tool, which carries its own description into the context at attach time.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { declaredDataRequirements } from "../agents/sandbox-catalog.js";
+import { defineTool } from "./define-tool.js";
+import { readInstalledDatasetIds } from "./sandbox/list-available-refs.js";
+const NO_DECLARATIONS = "No capability of this install declares reference data that it cannot run without.";
+const STORE_UNREADABLE = "The reference store could not be read, so whether these datasets are installed is UNKNOWN — not absent. " +
+    "Say that, and do not offer to install a dataset on this answer alone.";
+function renderRows(rows, storeReadable) {
+    if (rows.length === 0)
+        return NO_DECLARATIONS;
+    const lines = rows.map((row) => {
+        const state = storeReadable
+            ? [row.absent.length > 0 ? `absent: ${row.absent.join(", ")}` : null, row.installed.length > 0 ? `installed: ${row.installed.join(", ")}` : null]
+                .filter((part) => part !== null)
+                .join(" | ")
+            : `declared: ${[...row.installed, ...row.absent].sort().join(", ")}`;
+        return `- ${row.agentId} — "${row.capability}"\n  ${state}`;
+    });
+    const header = storeReadable
+        ? "Reference data a capability cannot run without, and what this store holds. An absent id is what an install takes."
+        : `Reference data a capability cannot run without. ${STORE_UNREADABLE}`;
+    return [header, "", ...lines].join("\n");
+}
+/**
+ * Build the tool. The store read happens per call, not at construction: a dataset installed during
+ * the conversation must show as installed on the next call, and a cached answer would have the
+ * agent offer a download the user already approved.
+ */
+export function createInspectCapabilityDataTool(deps = {}) {
+    return defineTool({
+        id: "inspect_capability_data",
+        description: "The reference data a specialist capability cannot run without, and whether this install holds it. " +
+            "Call it BEFORE you design a method yourself, and before you tell the user that something cannot be done — a capability whose data is absent is one install away, not impossible, and this is the only place that names WHICH datasets. " +
+            "Each entry names a catalog dataset id, which is exactly what an install takes; a surface with a way to provision can act on it directly. " +
+            "It takes no arguments and the whole set is small, so one call is the complete answer. " +
+            "An unreadable store answers UNKNOWN rather than absent, so a store that cannot be read never reads as a store that holds nothing.",
+        inputSchema: z.object({}),
+        describeCall: () => "declared capability data",
+        execute: async () => {
+            const declared = declaredDataRequirements();
+            if (declared.length === 0)
+                return ok({ storeReadable: true, rows: [], content: NO_DECLARATIONS });
+            const installedIds = await readInstalledDatasetIds(deps);
+            const storeReadable = installedIds !== undefined;
+            const rows = declared.map((requirement) => {
+                const datasets = [...requirement.datasets].sort();
+                return {
+                    agentId: requirement.agentId,
+                    capability: requirement.capability,
+                    installed: installedIds === undefined ? [] : datasets.filter((dataset) => installedIds.has(dataset)),
+                    absent: installedIds === undefined ? datasets : datasets.filter((dataset) => !installedIds.has(dataset)),
+                };
+            });
+            return ok({ storeReadable, rows, content: renderRows(rows, storeReadable) });
+        },
+    });
+}

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" | "echart" | "svg" | "table" | "structure";
+    kind: "code" | "echart" | "markdown" | "svg" | "table" | "structure";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

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

@@ -2,7 +2,9 @@
  * Unified async edge for approved plans and explicitly requested one-step ad
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
+import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
+import type { AgentSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
@@ -15,7 +17,7 @@ import { type AnalysisPlan } from "../schemas/workflow-state.js";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type AdHocRoute } from "./ad-hoc-router.js";
 type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
-export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> {
+export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory" | "refStorePath"> {
     readonly pool: Pool;
     readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
     readonly runAuthorizer: RunAuthorizer;
@@ -54,7 +56,84 @@ export declare class PlanPackagesMissingError extends Error {
     readonly unavailable?: string | undefined;
     constructor(missing: string[], collisions: string[], unavailable?: string | undefined);
 }
+/**
+ * A declared dataset that the reference store does not hold, found at the pre-launch pass. The
+ * message names the datasets and no remedy command — the remedy belongs to the embedder, and its
+ * wrapper appends it.
+ */
+export declare class PlanReferencesMissingError extends Error {
+    readonly missing: string[];
+    readonly unavailable?: string | undefined;
+    constructor(missing: string[], unavailable?: string | undefined);
+}
+/** The deps that start the run of a stored plan. */
+export type LaunchPlanRunDeps = Pick<ExecuteAnalysisToolDeps, "pool" | "executeAnalysisWorkflow" | "runAuthorizer" | "runLauncher" | "resourcePolicy" | "extendAnalysisFarm" | "refStorePath" | "logger">;
+/**
+ * The run of a stored plan. `started` is false when this call started nothing: `runId` then names the
+ * active run of the plan, or the newest run of the plan when the view of the caller was stale.
+ */
+export type PlanLaunch = {
+    runId: string;
+    started: boolean;
+};
+/**
+ * Why a stored plan did not start a run. `store_failed.cause` and `launch_failed.cause` are the
+ * values as the failing call gave them, thus a caller that must throw them keeps their class.
+ */
+export type LaunchPlanRunRefusal = {
+    type: "plan_not_found";
+    planId: string;
+} | {
+    type: "plan_invalid";
+    planId: string;
+    malformed: boolean;
+    errors: string[];
+} | {
+    type: "packages_missing";
+    missing: string[];
+    collisions: string[];
+    unavailable?: string;
+} | {
+    type: "references_missing";
+    missing: string[];
+    unavailable?: string;
+} | {
+    type: "run_not_found";
+    runId: string;
+} | {
+    type: "not_authorized";
+    reason: string;
+} | {
+    type: "suspended";
+    reason: string;
+} | {
+    type: "store_failed";
+    cause: unknown;
+} | {
+    type: "launch_failed";
+    cause: unknown;
+};
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
+/**
+ * `newestRunId` is the newest run of the plan that the caller saw, or `null` when the caller saw no run.
+ * Without it, the launch compares no run.
+ */
+export type LaunchPlanRunInput = {
+    session: AgentSession;
+    planId: string;
+    newestRunId?: string | null;
+};
+/**
+ * Start the run of a stored plan. It reads the plan under the analysis of the session, validates it,
+ * compares the newest run of the plan with `newestRunId`, links its packages, reserves a run,
+ * authorizes it, and starts the workflow. It gives the run id, or the refusal, and it emits no chat
+ * part. `started` is false when this call started nothing: a run of the plan was already active, or the
+ * newest run of the plan is not the run that the caller saw. `runId` then names that run.
+ *
+ * This is an API boundary: a host calls it outside a tool body, thus no outcome above rejects the
+ * promise.
+ */
+export declare function launchPlanRun(deps: LaunchPlanRunDeps, input: LaunchPlanRunInput): ResultAsync<PlanLaunch, LaunchPlanRunRefusal>;
 export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
     mode: "plan" | "adhoc";
     planId?: string | undefined;