@inflexa-ai/harness 0.1.1 → 0.2.0

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

@@ -2,12 +2,19 @@
  * generatePlan — a loop-driving tool: a focused `runAgent` loop that builds
  * an analysis plan (a DAG of steps).
  *
- * The outer tool receives structured context from the conversation agent
- * (data profile, research question, prior runs, constraints) and drives an
- * internal "planner" agent that communicates outcomes EXCLUSIVELY via four
- * terminal tool calls:
+ * The dataset's facts are NOT an input. They are read here, server-side, from
+ * the analysis's persisted data profile — the one durable record of what the
+ * input data is — and projected into the planner's seed. The caller supplies
+ * only what the profile cannot hold: the research question, facts the user
+ * volunteered (`analystNotes`), prior run results, and plan constraints. A
+ * caller-typed dataset summary would be a model re-transcribing a record the
+ * database already holds, and it would lose fidelity at every hop.
  *
- *   - validate_plan(plan)       → non-terminal dry-run (Zod + semantic)
+ * The tool drives an internal "planner" agent that communicates outcomes
+ * EXCLUSIVELY via four terminal tool calls:
+ *
+ *   - validate_plan(plan)       → non-terminal dry-run: an any-shape candidate
+ *                                 in, {valid, issues} out (schema + semantic)
  *   - submit_plan(plan)         → terminal success: re-validates + persists
  *   - request_clarification(…)  → terminal: planner needs more context
  *   - report_blocker(reason)    → terminal: no viable plan
@@ -20,17 +27,21 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { formatAgentCatalog } from "../../agents/sandbox-catalog.js";
+import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { runToTerminal } from "../../loop/run-to-terminal.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
+import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
+import { isDataProfileStale } from "../../app/data-profile-policy.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../../config/resource-limits.js";
 import { plannerPrompt } from "../../prompts/planner.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { unwrapOrThrow } from "../../lib/result.js";
-import { insertPlan, loadPlan } from "../../state/index.js";
+import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
 const PLANNER_AGENT_ID = "planner";
@@ -75,6 +86,97 @@ function formatPriorPlan(parentPlanId, plan) {
             "references survive.",
     ].join("\n");
 }
+/**
+ * Read the profile ledger row into a grounding variant.
+ *
+ * Staleness is `isDataProfileStale` — the single definition in
+ * `app/data-profile-policy.ts` that the embedder's re-trigger policy and
+ * `inspect_data_profile` also use, so the planner and the conversation agent can
+ * never disagree about whether a profile still describes the data.
+ */
+function classifyGrounding(status) {
+    // `loadDataProfileStatus` collapses "no analysis row" and "profile cleared"
+    // into one null, deliberately — both mean "no profile" to a consumer.
+    if (!status)
+        return { kind: "absent" };
+    const result = status.result;
+    if (!result) {
+        if (status.status === "failed")
+            return { kind: "failed", error: status.error };
+        // `completed` with no result is the empty-manifest path: there were no
+        // input files to profile. "Nothing is known about the data" is the honest
+        // reading of that, not a failure.
+        if (status.status === "completed")
+            return { kind: "absent" };
+        return { kind: "pending" };
+    }
+    // A result outlives the attempt that superseded it: `tryRerun` / `tryRetry`
+    // preserve `data_profile_result` on purpose, so a non-`completed` status
+    // carrying a result means what is on the row is the PREVIOUS profile.
+    const reasons = [];
+    if (isDataProfileStale(status.seedInputFileIds ?? [], result.inputFileIds)) {
+        reasons.push("the analysis's input file set changed after this profile was taken");
+    }
+    if (status.status === "pending" || status.status === "running") {
+        reasons.push("a re-profile is in progress — this is the previous profile");
+    }
+    if (status.status === "failed") {
+        reasons.push(`the most recent profiling attempt failed (${status.error ?? "no reason recorded"}) — this is the previous profile`);
+    }
+    return reasons.length > 0 ? { kind: "provisional", result, reasons } : { kind: "ready", result };
+}
+/** What a seed says when it has no dataset facts to give the planner. */
+const NO_FACTS_GUIDANCE = "Plan from the research question alone, do not invent dataset specifics, and call " +
+    "`request_clarification` if a specific fact about the data is essential to the plan.";
+/**
+ * Render the seed's `## Data Context` from the grounding.
+ *
+ * The facts come from `buildDataProfileOrientation` — the same bounded projector
+ * the sandbox step seed uses, so a step and the plan that produced it are oriented
+ * by identical text. It is not re-derived here, and the planner cannot reach past
+ * it: the planner has no `inspect_data_profile` tool, so what this section does not
+ * say is simply not known to it.
+ *
+ * An absent profile renders NOTHING — no heading, no apology. Planning without
+ * dataset facts is worse-grounded but entirely possible, and a section announcing
+ * its own emptiness is an invitation to fill it. Every other state renders,
+ * including the two that carry no facts either: a planner told that its record is
+ * still being built, or that its facts may have moved, can act on that; one handed
+ * stale facts silently cannot.
+ *
+ * Pure — the same grounding renders the same string.
+ */
+function renderDataContext(grounding) {
+    switch (grounding.kind) {
+        case "absent":
+            return "";
+        case "pending":
+            return ["## Data Context", "", `This analysis is still being profiled — no dataset facts are available yet. ${NO_FACTS_GUIDANCE}`].join("\n");
+        case "failed":
+            return [
+                "## Data Context",
+                "",
+                `Data profiling failed (${grounding.error ?? "no reason recorded"}) and no earlier profile exists, ` +
+                    `so no dataset facts are available. ${NO_FACTS_GUIDANCE}`,
+            ].join("\n");
+        case "ready":
+        case "provisional": {
+            const lines = [
+                "## Data Context",
+                "",
+                "From this analysis's persisted data profile — the authoritative record of what the input data " +
+                    "is, derived by profiling the files themselves. Nobody typed it; ground your plan in it.",
+                "",
+                buildDataProfileOrientation(grounding.result, DATA_PROFILE_ORIENTATION_MAX_CHARS),
+            ];
+            if (grounding.kind === "provisional") {
+                lines.push("", `PROVISIONAL — this profile may not describe the analysis's current inputs: ${grounding.reasons.join("; ")}. ` +
+                    "Plan on it, but keep the plan robust to any fact above having moved.");
+            }
+            return lines.join("\n");
+        }
+    }
+}
 // ── Persistence ─────────────────────────────────────────────────────
 /**
  * Persist a validated plan. Returns the planId, or an outcome-ready error
@@ -146,14 +248,24 @@ function fullyValidate(candidate, resourcePolicy) {
  * loop finishes.
  */
 function buildInnerTools(holder, persistCtx, pool, resourcePolicy) {
-    const candidatePlan = z.object({ plan: z.unknown() });
     const validatePlanTool = defineTool({
         id: "validate_plan",
-        description: "Dry-run a candidate plan against the schema and semantic checks " +
-            "(agent IDs, DAG cycles, dependency references, unique step IDs, " +
-            "resources). Returns {valid, issues}. Non-terminal — call as many " +
-            "times as needed to iterate toward a clean plan before submit_plan.",
-        inputSchema: candidatePlan,
+        description: "Dry-run a candidate plan and get back everything that is wrong with it. " +
+            "Takes the plan in ANY shape: a malformed, partial, or wrong-typed " +
+            "candidate is REPORTED, not rejected. Returns {valid, issues[]} covering " +
+            "both schema problems (missing / wrong-typed fields) and the semantic " +
+            "checks a schema cannot express (unknown agent IDs, DAG cycles, dangling " +
+            "depends_on references, duplicate step IDs, resource ceilings). The " +
+            "authoritative field-by-field plan schema is the arg schema of " +
+            "submit_plan — this tool deliberately does not restate it. Non-terminal: " +
+            "call as often as needed to iterate toward a clean plan, then submit_plan.",
+        // Deliberately permissive: a structurally-invalid candidate must reach
+        // `execute` so the model gets a structured {valid:false, issues} result —
+        // including semantic issues — instead of a bare Zod rejection at the loop's
+        // input boundary. `execute` re-parses against PlannerPlanSchema itself.
+        inputSchema: z.object({
+            plan: z.unknown().describe("The candidate plan, in any shape. Field-by-field schema: see submit_plan."),
+        }),
         execute: async (input) => {
             const result = fullyValidate(input.plan, resourcePolicy);
             return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
@@ -164,8 +276,11 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy) {
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
             "success returns {accepted: true, planId} — STOP after this. On " +
             "rejection returns {accepted: false, issues} — fix and call again, " +
-            "or switch to report_blocker if the plan cannot be made valid.",
-        inputSchema: candidatePlan,
+            "or switch to report_blocker if the plan cannot be made valid. This " +
+            "arg schema is the authoritative plan contract.",
+        // Strict: a malformed plan must not reach submission. `execute` still
+        // re-validates (schema + semantic) — it does not lean on this boundary.
+        inputSchema: z.object({ plan: PlannerPlanSchema }),
         execute: async (input) => {
             if (holder.outcome !== null) {
                 return ok({
@@ -226,18 +341,15 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy) {
             return ok({ recorded: true });
         },
     });
-    const reportBlockerTool = defineTool({
-        id: "report_blocker",
-        description: "Terminal. Use when no valid plan can be produced (out of scope, " +
-            "data incompatible with every available agent, etc.). Pass a short " +
-            "reason. Stop after calling.",
-        inputSchema: z.object({ reason: z.string().min(1) }),
-        execute: async (input) => {
-            if (holder.outcome === null) {
-                holder.outcome = { kind: "blocker", reason: input.reason };
-            }
-            return ok({ recorded: true });
+    const reportBlockerTool = createReportBlockerToolFor({
+        record: (outcome) => {
+            if (holder.outcome === null)
+                holder.outcome = outcome;
         },
+        blockedWhen: "Ends plan generation with no plan saved. Use it when no valid plan can " +
+            "be produced for this data and research question (out of scope, data " +
+            "incompatible with every available agent, etc.) — not for a plan you " +
+            "could fix and submit.",
     });
     const terminal = [submitPlanTool, requestClarificationTool, reportBlockerTool];
     return { all: [validatePlanTool, ...terminal], terminal };
@@ -288,16 +400,26 @@ function shapeOutcome(args) {
 export function createGeneratePlanTool(deps) {
     return defineTool({
         id: "generate_plan",
-        description: "Generate an analysis plan (DAG of steps) for the given data context " +
-            "and research question. Pass all relevant context: data profile " +
-            "summary, omics type, experimental design, prior run results, and " +
-            "user constraints. Returns a structured plan ready for show_plan and " +
-            "execute_plan, or a clarification question if context is insufficient.",
+        description: "Generate an analysis plan (DAG of steps) for this analysis's data and the user's research question. " +
+            "The dataset's own facts — domain, organism, experimental design, condition names, quality concerns, " +
+            "per-file data types and dimensions — are read server-side from the persisted data profile and handed " +
+            "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
+            "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
+            "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
+            "Returns a structured plan ready for show_plan and execute_plan, or a clarification question if " +
+            "the planner is missing something it cannot infer.",
         inputSchema: z.object({
-            dataContext: z
-                .string()
-                .describe("Data profile summary: data type, modality, file descriptions, " + "feature/sample counts, experimental design, condition names."),
             researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
+            analystNotes: z
+                .string()
+                .optional()
+                .describe("Facts about the data that ONLY the user could have told you and the data profile cannot know — " +
+                'e.g. "samples 3 and 7 were re-sequenced", "treat batch B as the reference", ' +
+                '"the tumor/normal labels in column 4 are swapped". ' +
+                "This is NOT a place to restate the data profile: organism, omics type, experimental design, " +
+                "condition names, file names and dimensions are already loaded server-side and given to the " +
+                "planner — repeating them here only risks contradicting the record. Omit entirely unless the " +
+                "user has told you something the profile does not already hold."),
             priorRuns: z
                 .string()
                 .optional()
@@ -338,13 +460,22 @@ export function createGeneratePlanTool(deps) {
                     });
                 }
             }
+            // The dataset's facts come from the ledger, not from a string a model
+            // typed: the profile is the only durable record of what the input data
+            // is, and every re-transcription of it loses fidelity.
+            //
+            // A read failure degrades to "no profile" rather than throwing. Planning
+            // without dataset facts is a real, supported state (see `renderDataContext`),
+            // so a ledger read that fails must cost the planner its grounding — never
+            // the user their plan.
+            const profileStatus = await loadDataProfileStatus(deps.pool, analysisId).unwrapOr(null);
+            const dataContextBlock = renderDataContext(classifyGrounding(profileStatus));
             const prompt = [
                 ...(priorPlanBlock ? [priorPlanBlock, ""] : []),
-                "## Data Context",
-                input.dataContext,
-                "",
+                ...(dataContextBlock ? [dataContextBlock, ""] : []),
                 "## Research Question",
                 input.researchQuestion,
+                ...(input.analystNotes ? ["", "## Analyst Notes (from the user — facts about the data the profile does not record)", input.analystNotes] : []),
                 ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
                 ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
             ].join("\n");
@@ -356,7 +487,7 @@ export function createGeneratePlanTool(deps) {
             const innerTools = buildInnerTools(holder, persistCtx, deps.pool, deps.resourcePolicy);
             const planner = {
                 id: PLANNER_AGENT_ID,
-                systemPrompt: plannerInstructions(deps.resourcePolicy),
+                systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
                 model: deps.model,
                 tools: innerTools.all,
                 maxIterations: PLANNER_MAX_ITERATIONS,

package/dist/tools/research/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from "./generate-plan.js";
 export * from "./inspect-run.js";
+export * from "./inspect-data-profile.js";
 export * from "./literature-reviewer.js";
 export * from "./generate-analogy-report.js";
 export * from "./context7-docs.js";

package/dist/tools/research/index.js

@@ -7,6 +7,7 @@
  */
 export * from "./generate-plan.js";
 export * from "./inspect-run.js";
+export * from "./inspect-data-profile.js";
 export * from "./literature-reviewer.js";
 export * from "./generate-analogy-report.js";
 export * from "./context7-docs.js";

package/dist/tools/research/inspect-data-profile.d.ts

@@ -0,0 +1,85 @@
+/**
+ * inspectDataProfile — read the analysis's data profile.
+ *
+ * Dependency-bearing: the database `Pool` is captured by the factory (see the
+ * harness-durable-runtime spec). The analysis id is read from the request-scoped
+ * `Session`, not an ambient request context — the same shape as `inspectRun`.
+ *
+ * **There is no data-profile file.** The profiler's `runs/data-profile/` scratch tree
+ * is deleted when profiling completes; the profile's only durable home is the
+ * `cortex_analysis_state` row this tool reads. That makes this the single authoritative
+ * source for dataset facts (organism, domain, design, per-file type/format/dimensions),
+ * and it is why the record is served in full rather than summarized: an agent that
+ * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
+ *
+ * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
+ * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
+ * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
+ * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
+ * never a silent truncation.
+ *
+ * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
+ * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
+ * able to reason about, so each returns in the ok channel.
+ */
+import type { Pool } from "pg";
+import { type DataProfileFile, type DataProfileResult } from "../../state/index.js";
+/**
+ * Whether the served profile can be trusted to describe the analysis's CURRENT inputs.
+ * `"stale"` still carries the full profile — a stale profile is far better than none —
+ * but says plainly why it may be wrong.
+ */
+type Freshness = "ready" | "stale";
+interface ProfileEnvelope {
+    readonly state: Freshness;
+    /** Why the profile may not describe the current inputs. Present only when `state` is `"stale"`. */
+    readonly staleReason?: string;
+    readonly profiledAt: string;
+}
+interface OverviewOutput extends ProfileEnvelope {
+    readonly scope: "overview";
+    readonly summary: string;
+    readonly domain?: string;
+    readonly subtype?: string;
+    readonly organism?: DataProfileResult["organism"];
+    readonly tissue?: string | null;
+    readonly cellType?: string | null;
+    readonly condition?: string | null;
+    readonly experimentalDesign?: string;
+    readonly qualityAssessment?: DataProfileResult["qualityAssessment"];
+    readonly accessions?: string[];
+    /** How many per-file records `scope:"files"` would page through. */
+    readonly fileCount: number;
+}
+interface FilesOutput extends ProfileEnvelope {
+    readonly scope: "files";
+    readonly page: number;
+    readonly pageSize: number;
+    /** Every per-file record the profile holds — not just this page. */
+    readonly total: number;
+    /** True when records remain past this page. Truncation is always stated, never silent. */
+    readonly hasMore: boolean;
+    readonly files: DataProfileFile[];
+}
+/** No profile to serve — the honest lifecycle states, in the ok channel. */
+interface AbsentOutput {
+    readonly state: "absent";
+    readonly message: string;
+}
+interface PendingOutput {
+    readonly state: "pending";
+    readonly status: "pending" | "running";
+    readonly message: string;
+}
+interface FailedOutput {
+    readonly state: "failed";
+    readonly error: string | null;
+    readonly message: string;
+}
+export type InspectDataProfileOutput = OverviewOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;
+export declare function createInspectDataProfileTool(pool: Pool): import("../define-tool.js").Tool<{
+    scope?: "files" | "overview" | undefined;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+}, InspectDataProfileOutput>;
+export {};

package/dist/tools/research/inspect-data-profile.js

@@ -0,0 +1,161 @@
+/**
+ * inspectDataProfile — read the analysis's data profile.
+ *
+ * Dependency-bearing: the database `Pool` is captured by the factory (see the
+ * harness-durable-runtime spec). The analysis id is read from the request-scoped
+ * `Session`, not an ambient request context — the same shape as `inspectRun`.
+ *
+ * **There is no data-profile file.** The profiler's `runs/data-profile/` scratch tree
+ * is deleted when profiling completes; the profile's only durable home is the
+ * `cortex_analysis_state` row this tool reads. That makes this the single authoritative
+ * source for dataset facts (organism, domain, design, per-file type/format/dimensions),
+ * and it is why the record is served in full rather than summarized: an agent that
+ * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
+ *
+ * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
+ * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
+ * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
+ * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
+ * never a silent truncation.
+ *
+ * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
+ * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
+ * able to reason about, so each returns in the ok channel.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { isDataProfileStale } from "../../app/data-profile-policy.js";
+import { scopeResource } from "../../auth/types.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { loadDataProfileStatus } from "../../state/index.js";
+import { defineTool } from "../define-tool.js";
+/** Per-file records returned per page when the caller names none. */
+const DEFAULT_PAGE_SIZE = 20;
+/** Ceiling on `pageSize` — a page is a context-window budget, not a dump. */
+const MAX_PAGE_SIZE = 100;
+/**
+ * Name every reason the served profile may not describe the current inputs.
+ *
+ * Two independent things make a profile stale, and both are ordinary. The input set can
+ * change under a completed profile (`isDataProfileStale` — the same predicate the
+ * embedder's re-trigger policy uses; staleness is defined once, in
+ * `app/data-profile-policy.ts`, not re-derived here). And the ledger can have moved off
+ * `completed` while an older result is still on the row: `tryRerun`/`tryRetry` preserve
+ * `data_profile_result` precisely so a prior profile stays servable while the next
+ * attempt runs or after it fails.
+ */
+function stalenessReasons(status, result) {
+    const reasons = [];
+    if (isDataProfileStale(status.seedInputFileIds ?? [], result.inputFileIds)) {
+        reasons.push("the analysis's input file set changed after this profile was taken");
+    }
+    if (status.status === "running" || status.status === "pending") {
+        reasons.push("a re-profile is in progress — this is the previous profile");
+    }
+    if (status.status === "failed") {
+        reasons.push(`the most recent profiling attempt failed (${status.error ?? "no reason recorded"}) — this is the previous profile`);
+    }
+    return reasons;
+}
+export function createInspectDataProfileTool(pool) {
+    return defineTool({
+        id: "inspect_data_profile",
+        description: "Read this analysis's data profile — the AUTHORITATIVE record of what the input dataset is: " +
+            "organism and taxon id, scientific domain and subtype, tissue, cell type, condition, experimental design, " +
+            "dataset-wide quality concerns and strengths, public accessions, and per-file data type, format, " +
+            "row/column dimensions, tags, warnings, and profiling metrics. " +
+            "There is NO data-profile file in the workspace — this tool is the only way to read it. Do not search for one, " +
+            "and do not rediscover these facts by listing or reading the raw input files. " +
+            "Call it before you reason about the data (planning, writing analysis code, interpreting results). " +
+            "scope:'overview' (the default) returns the dataset-level orientation plus the number of profiled files. " +
+            "scope:'files' returns the per-file records, paged: page (1-based, default 1) and pageSize (default 20, max 100), " +
+            "always with the true total and hasMore, so you can see exactly what you have not read yet. " +
+            "The state field says what you got: 'ready'; 'stale' (a profile is returned but may not describe the current " +
+            "inputs — staleReason says why); 'pending' (profiling is still running); 'failed'; or 'absent' (never profiled, " +
+            "or the analysis has no input files).",
+        inputSchema: z.object({
+            scope: z
+                .enum(["overview", "files"])
+                .optional()
+                .describe("'overview' (default): dataset-level facts + file count. 'files': paged per-file records."),
+            page: z.number().int().min(1).optional().describe("1-based page of per-file records. Only used when scope is 'files'. Default 1."),
+            pageSize: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_PAGE_SIZE)
+                .optional()
+                .describe(`Per-file records per page. Only used when scope is 'files'. Default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}.`),
+        }),
+        execute: async (input, ctx) => {
+            const resourceId = scopeResource(ctx.session.scope).resourceId;
+            const status = unwrapOrThrow(await loadDataProfileStatus(pool, resourceId));
+            // `loadDataProfileStatus` collapses "no analysis row" and "profile cleared"
+            // into the same null, on purpose — both mean "no profile" to a consumer.
+            if (!status) {
+                return ok({
+                    state: "absent",
+                    message: "No data profile exists for this analysis. It has not been profiled, or its input files were removed.",
+                });
+            }
+            const result = status.result;
+            if (!result) {
+                if (status.status === "failed") {
+                    return ok({
+                        state: "failed",
+                        error: status.error,
+                        message: `Data profiling failed and no earlier profile exists: ${status.error ?? "no reason recorded"}.`,
+                    });
+                }
+                if (status.status === "completed") {
+                    // A completed profile with no result is the empty-manifest path: there
+                    // were no input files to profile. "Absent" is the honest reading.
+                    return ok({
+                        state: "absent",
+                        message: "Data profiling completed with no result — this analysis has no input files.",
+                    });
+                }
+                return ok({
+                    state: "pending",
+                    status: status.status,
+                    message: "Data profiling is still running; no profile is available yet. Proceed without it or ask the user to wait.",
+                });
+            }
+            const reasons = stalenessReasons(status, result);
+            const envelope = reasons.length > 0
+                ? { state: "stale", staleReason: reasons.join("; "), profiledAt: result.profiledAt }
+                : { state: "ready", profiledAt: result.profiledAt };
+            if ((input.scope ?? "overview") === "overview") {
+                return ok({
+                    ...envelope,
+                    scope: "overview",
+                    summary: result.summary,
+                    domain: result.domain,
+                    subtype: result.subtype,
+                    organism: result.organism,
+                    tissue: result.tissue,
+                    cellType: result.cellType,
+                    condition: result.condition,
+                    experimentalDesign: result.experimentalDesign,
+                    qualityAssessment: result.qualityAssessment,
+                    accessions: result.accessions,
+                    fileCount: result.files.length,
+                });
+            }
+            const pageSize = input.pageSize ?? DEFAULT_PAGE_SIZE;
+            const page = input.page ?? 1;
+            const total = result.files.length;
+            const start = (page - 1) * pageSize;
+            const files = result.files.slice(start, start + pageSize);
+            return ok({
+                ...envelope,
+                scope: "files",
+                page,
+                pageSize,
+                total,
+                hasMore: start + files.length < total,
+                files,
+            });
+        },
+    });
+}

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

@@ -19,6 +19,7 @@ import { z } from "zod";
 import { finalText, runAgent } from "../../loop/run-agent.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { literatureReviewerPrompt } from "../../prompts/literature-reviewer.js";
+import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
 import { createNcbiTools } from "../bio/keys.js";
@@ -41,16 +42,14 @@ export function createLiteratureReviewerTool(deps) {
         searchPathwayTool,
         lookupGoTermTool,
         searchInteractionsTool,
-        ncbi.searchPubMed,
-        ncbi.getArticleDetails,
-        ncbi.getArticleFullText,
+        ncbi.pubmed,
         searchDgidbTool,
         searchBgeeExpressionTool,
         getImpcKoProfileTool,
     ];
     const agent = {
         id: AGENT_ID,
-        systemPrompt: literatureReviewerPrompt,
+        systemPrompt: composeSystemPrompt(literatureReviewerPrompt),
         model: deps.model,
         tools: reviewerTools,
         maxIterations: REVIEWER_MAX_ITERATIONS,