@inflexa-ai/harness 0.1.1 → 0.2.0

package/dist/reference-data/receipt.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { ReferenceArtifactPathSchema, ReferenceDatasetSchema, ReferenceSha256Schema } from "./catalog.js";
+/** Schema version for installation receipts shared by all embedders. */
+export const REFERENCE_INSTALL_RECEIPT_VERSION = 1;
+/**
+ * What was actually written to disk for one artifact. The size and digest are
+ * *observed at install*, never copied from the catalog — for a `pinned`
+ * artifact they equal the catalog's (the install would have failed otherwise),
+ * and for an `unpinned` one they are the only record of what the mutable
+ * upstream served, which is what `verify` later checks the files against.
+ */
+const ReferenceReceiptArtifactSchema = z.object({
+    path: ReferenceArtifactPathSchema,
+    bytes: z.number().int().nonnegative(),
+    sha256: ReferenceSha256Schema,
+    integrity: z.enum(["pinned", "unpinned"]),
+});
+/** Optional metadata describing one activated reference dataset version. */
+export const ReferenceInstallReceiptSchema = z
+    .object({
+    version: z.literal(REFERENCE_INSTALL_RECEIPT_VERSION),
+    datasetId: ReferenceDatasetSchema.shape.id,
+    datasetVersion: ReferenceDatasetSchema.shape.version,
+    activatedAt: z.iso.datetime({ offset: true }),
+    artifacts: z.array(ReferenceReceiptArtifactSchema).min(1),
+})
+    .superRefine((receipt, ctx) => {
+    const paths = new Set();
+    for (const [index, artifact] of receipt.artifacts.entries()) {
+        if (paths.has(artifact.path)) {
+            ctx.addIssue({ code: "custom", message: `Duplicate receipt artifact path: ${artifact.path}`, path: ["artifacts", index, "path"] });
+        }
+        paths.add(artifact.path);
+    }
+});
+/** Parse optional/untrusted receipt metadata; invalid receipts are ignored. */
+export function parseReferenceInstallReceipt(input) {
+    const result = ReferenceInstallReceiptSchema.safeParse(input);
+    return result.success ? result.data : undefined;
+}

package/dist/schemas/data-profile-schemas.js

@@ -15,7 +15,7 @@ export const ProfilerFileSchema = z.object({
         .describe("Semantic data type: count-matrix, normalized-expression, variants, alignments, " +
         "clinical-metadata, clinical-sdtm, clinical-adam, clinical-response, " +
         "pharmacokinetic-data, adverse-events, safety-labs, " +
-        "molecular-structures, annotations"),
+        "molecular-structures, annotations, document (paper PDF, README, methods doc)"),
     format: z.string().describe("File format (e.g. CSV, TSV, h5ad, MTX, VCF, BAM, SDF, FASTQ)"),
     rows: z.number().nullish(),
     cols: z.number().nullish(),
@@ -43,7 +43,7 @@ export const OrganismSchema = z.object({
     source: SubjectSourceEnum,
     confidence: z
         .enum(["high", "medium", "low"])
-        .describe("high: explicit organism column or paper/README statement. " +
+        .describe("high: explicit user-context statement, an organism column, or a paper/README statement. " +
         "medium: filename convention or accession lookup. " +
         "low: inferred from gene IDs or other indirect signals, OR sources disagree (in which case also record the conflict in qualityAssessment.concerns)."),
     notes: z.string().optional().describe("Brief note when source is 'inferred' or confidence is 'low' (one sentence)."),
@@ -51,7 +51,9 @@ export const OrganismSchema = z.object({
 export const ProfilerOutputSchema = z.object({
     files: z.array(ProfilerFileSchema),
     analysisSummary: z.string().describe("Narrative overview of the dataset — structure, content, analytical potential, and limitations"),
-    domain: z.string().describe("Scientific domain (e.g. transcriptomics, proteomics, genomics, chemistry, clinical, imaging, metabolomics, multi-omics)"),
+    domain: z
+        .string()
+        .describe("Scientific domain (e.g. transcriptomics, proteomics, genomics, cheminformatics, clinical, imaging, metabolomics, multi-omics)"),
     subtype: z.string().optional().describe("Specific subtype within domain (e.g. bulk-rna-seq, single-cell, LC-MS/MS, whole-genome-sequencing)"),
     organism: OrganismSchema.nullable().describe("Subject organism, identified from any input (metadata files, paper PDFs, READMEs, filenames, accession patterns). " +
         "Set to null ONLY when no input identifies the organism — never guess. " +

package/dist/schemas/plan-schemas.d.ts

@@ -11,6 +11,13 @@ export declare const PlanStepSchema: z.ZodObject<{
     id: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    track: z.ZodString;
+    step_type: z.ZodString;
+    question: z.ZodString;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance_criteria: z.ZodArray<z.ZodString>;
+    caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    depends_on: z.ZodArray<z.ZodString>;
     resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
         cpu: z.ZodNumber;
         memoryGb: z.ZodNumber;
@@ -18,13 +25,6 @@ export declare const PlanStepSchema: z.ZodObject<{
             count: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
-    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    track: z.ZodString;
-    step_type: z.ZodString;
-    question: z.ZodString;
-    acceptance_criteria: z.ZodArray<z.ZodString>;
-    caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    depends_on: z.ZodArray<z.ZodString>;
     agent: z.ZodEnum<{
         [x: string]: string;
     }>;
@@ -43,6 +43,13 @@ export declare const PlannerPlanSchema: z.ZodObject<{
         id: z.ZodString;
         context: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        track: z.ZodString;
+        step_type: z.ZodString;
+        question: z.ZodString;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        acceptance_criteria: z.ZodArray<z.ZodString>;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        depends_on: z.ZodArray<z.ZodString>;
         resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
             cpu: z.ZodNumber;
             memoryGb: z.ZodNumber;
@@ -50,13 +57,6 @@ export declare const PlannerPlanSchema: z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
-        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        track: z.ZodString;
-        step_type: z.ZodString;
-        question: z.ZodString;
-        acceptance_criteria: z.ZodArray<z.ZodString>;
-        caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        depends_on: z.ZodArray<z.ZodString>;
         agent: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -84,6 +84,13 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
             id: z.ZodString;
             context: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            track: z.ZodString;
+            step_type: z.ZodString;
+            question: z.ZodString;
+            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            acceptance_criteria: z.ZodArray<z.ZodString>;
+            caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            depends_on: z.ZodArray<z.ZodString>;
             resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
                 cpu: z.ZodNumber;
                 memoryGb: z.ZodNumber;
@@ -91,13 +98,6 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
                     count: z.ZodNumber;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
-            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            track: z.ZodString;
-            step_type: z.ZodString;
-            question: z.ZodString;
-            acceptance_criteria: z.ZodArray<z.ZodString>;
-            caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            depends_on: z.ZodArray<z.ZodString>;
             agent: z.ZodEnum<{
                 [x: string]: string;
             }>;

package/dist/schemas/plan-schemas.js

@@ -19,13 +19,19 @@ export const PlanStepSchema = AnalysisStepSchema.omit({
 })
     .required({ agent: true, resources: true })
     .extend({
-    agent: z.enum(plannableAgentIds).describe("Sandbox agent ID from the available agents list"),
+    agent: z.enum(plannableAgentIds).describe("Sandbox agent ID, routed by the step's primary data object. Must be one of the available agents."),
 });
 /** Plan schema for planner output — uses PlanStepSchema for steps and requires
  *  a concise title (optional on the persistence schema for historical plans). */
 export const PlannerPlanSchema = AnalysisPlanSchema.extend({
-    title: z.string().min(1).max(80).describe("Concise human-readable plan name (3–8 words)"),
-    steps: z.array(PlanStepSchema),
+    title: z
+        .string()
+        .min(1)
+        .max(80)
+        .describe('Concise plan name (3–8 words) naming the analysis by what it does — e.g. "AD lesional vs control DE + pathways", ' +
+        '"scRNA immune deconvolution". Ground it in the actual research question and conditions; it is shown as the run\'s heading in chat. ' +
+        'Not a generic name like "Transcriptomics analysis".'),
+    steps: z.array(PlanStepSchema).describe("The steps of the plan, as a DAG wired by depends_on."),
 });
 /** Hydrate slim planner output into a full AnalysisPlan with execution-time defaults. */
 export function hydratePlanSteps(plannerPlan) {

package/dist/schemas/run-synthesis.d.ts

@@ -4,6 +4,10 @@
  * Produced by the synthesis step after all sandbox steps complete.
  * Combines computational findings from step summaries with literature
  * evidence from the literature-reviewer agent.
+ *
+ * This schema is the synthesizer's output contract: it is emitted as the
+ * `submit_synthesis` tool's arg schema, so every field's meaning must live in
+ * `.describe()` — a JSDoc comment here reaches no model.
  */
 import { z } from "zod";
 export declare const LiteratureReferenceSchema: z.ZodObject<{
@@ -27,11 +31,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
-        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
+        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
     references: z.ZodArray<z.ZodObject<{
@@ -53,7 +57,6 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "clinical-evidence": "clinical-evidence";
         }>;
         actionType: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             "therapeutic-target": "therapeutic-target";
             "predictive-biomarker": "predictive-biomarker";
             "prognostic-biomarker": "prognostic-biomarker";
@@ -62,6 +65,7 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "resistance-mechanism": "resistance-mechanism";
             "patient-stratification": "patient-stratification";
             "mechanism-of-action": "mechanism-of-action";
+            none: "none";
         }>>;
         rationale: z.ZodString;
     }, z.core.$strip>>;
@@ -88,11 +92,11 @@ export declare const RunSynthesisSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
-            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
+            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
         references: z.ZodArray<z.ZodObject<{
@@ -114,7 +118,6 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "clinical-evidence": "clinical-evidence";
             }>;
             actionType: z.ZodOptional<z.ZodEnum<{
-                none: "none";
                 "therapeutic-target": "therapeutic-target";
                 "predictive-biomarker": "predictive-biomarker";
                 "prognostic-biomarker": "prognostic-biomarker";
@@ -123,6 +126,7 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "resistance-mechanism": "resistance-mechanism";
                 "patient-stratification": "patient-stratification";
                 "mechanism-of-action": "mechanism-of-action";
+                none: "none";
             }>>;
             rationale: z.ZodString;
         }, z.core.$strip>>;

package/dist/schemas/run-synthesis.js

@@ -4,35 +4,51 @@
  * Produced by the synthesis step after all sandbox steps complete.
  * Combines computational findings from step summaries with literature
  * evidence from the literature-reviewer agent.
+ *
+ * This schema is the synthesizer's output contract: it is emitted as the
+ * `submit_synthesis` tool's arg schema, so every field's meaning must live in
+ * `.describe()` — a JSDoc comment here reaches no model.
  */
 import { z } from "zod";
 export const LiteratureReferenceSchema = z.object({
-    pmid: z.string(),
-    citation: z.string(),
-    relevance: z.string(),
-    concordance: z.enum(["supports", "contradicts", "extends", "contextualizes"]),
+    pmid: z.string().describe("Numeric PubMed ID. Must come from a literature_reviewer response — never invented."),
+    citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+    relevance: z.string().describe("Why this paper matters to the finding — what it establishes, challenges, or contextualizes."),
+    concordance: z
+        .enum(["supports", "contradicts", "extends", "contextualizes"])
+        .describe("How the paper relates to the finding. " +
+        "supports: the paper directly supports the finding. " +
+        "contradicts: the paper reports a conflicting result. " +
+        "extends: the paper builds on the finding in another context. " +
+        "contextualizes: the paper provides background but does not directly address the finding."),
 });
 export const SynthesizedFindingSchema = z.object({
-    /** Which step produced this finding. */
-    stepId: z.string(),
-    /** Finding title from the step summary. */
-    title: z.string(),
-    /** Finding description from the step summary. */
-    description: z.string(),
-    /** Confidence from the step summary. */
-    confidence: z.enum(["high", "medium", "low"]),
-    /** Novelty assessment based on literature review. */
-    noveltyStatus: z.enum(["novel", "confirmed", "partially_confirmed", "contradicted", "expected"]),
-    /** How this finding relates to existing literature. */
-    literatureInterpretation: z.string(),
-    /** Supporting or contradicting references. */
-    references: z.array(LiteratureReferenceSchema),
-    /** Translational proximity and actionability assessment. */
+    stepId: z.string().describe("Which step produced this finding. Must be a stepId present in the input summaries."),
+    title: z.string().describe("Finding title from the step summary."),
+    description: z.string().describe("Finding description from the step summary."),
+    confidence: z
+        .enum(["high", "medium", "low"])
+        .describe("Confidence from the step summary — reflect the summary's own stated confidence, not a re-assessment. " +
+        "If the summary states none, use medium; use high only for findings the summary treats as robust."),
+    noveltyStatus: z
+        .enum(["novel", "confirmed", "partially_confirmed", "contradicted", "expected"])
+        .describe("Novelty assessment based on literature review. " +
+        "novel: the literature does not describe this result in this context. " +
+        "confirmed: the literature independently establishes this result. " +
+        "partially_confirmed: the literature supports related but not identical claims (e.g. same gene, different tissue). " +
+        "contradicted: the literature reports the opposite direction or effect. " +
+        "expected: a standard, well-known result (housekeeping genes, canonical QC outcomes) — not a discovery."),
+    literatureInterpretation: z.string().describe("How this finding relates to existing literature."),
+    references: z.array(LiteratureReferenceSchema).describe("Supporting or contradicting references."),
     translationalRelevance: z
         .object({
-        /** How close this finding is to clinical application. */
-        stage: z.enum(["discovery", "preclinical-validation", "biomarker-candidate", "clinical-evidence"]),
-        /** What type of translational action this finding supports. */
+        stage: z
+            .enum(["discovery", "preclinical-validation", "biomarker-candidate", "clinical-evidence"])
+            .describe("How close this finding is to clinical application. " +
+            "discovery: novel biology with no direct clinical path yet. " +
+            "preclinical-validation: known target/pathway with existing preclinical evidence but no clinical data in this context. " +
+            "biomarker-candidate: measurable, differential, with a biologically plausible mechanism linking it to outcome. " +
+            "clinical-evidence: supported by or directly relevant to clinical trial data or approved therapeutics."),
         actionType: z
             .enum([
             "therapeutic-target",
@@ -45,43 +61,63 @@ export const SynthesizedFindingSchema = z.object({
             "mechanism-of-action",
             "none",
         ])
-            .optional(),
-        /** Brief rationale for the stage and action type. */
-        rationale: z.string(),
+            .optional()
+            .describe("What type of translational action this finding supports. " +
+            "therapeutic-target: gene/protein/pathway suitable for drug intervention. " +
+            "predictive-biomarker: differentiates treatment responders from non-responders (requires treatment x marker interaction evidence). " +
+            "prognostic-biomarker: predicts outcome regardless of treatment. " +
+            "pharmacodynamic-biomarker: measures target engagement or drug effect over time. " +
+            "safety-signal: suggests potential toxicity, adverse effect, or off-target liability. " +
+            "resistance-mechanism: explains non-response or acquired resistance. " +
+            "patient-stratification: enables subgroup identification for enrichment strategies. " +
+            "mechanism-of-action: illuminates how a drug or intervention works. " +
+            "none: biological value but no direct translational path."),
+        rationale: z
+            .string()
+            .describe("ONE sentence on why this stage and action type were assigned. " +
+            "Must reference specific evidence (existing drugs, clinical trials, biomarker properties, literature)."),
     })
-        .optional(),
+        .optional()
+        .describe("Translational proximity and actionability. Populate only for findings with genuine translational implications — " +
+        "omit for purely technical or methodological findings."),
 });
 export const BiologicalThemeSchema = z.object({
-    /** Theme name, e.g. "Immune dysregulation", "Metabolic reprogramming". */
-    name: z.string(),
-    /** Findings that contribute to this theme (by stepId + title). */
-    findings: z.array(z.object({ stepId: z.string(), title: z.string() })),
-    /** How these findings connect into a coherent biological story. */
-    narrative: z.string(),
+    name: z
+        .string()
+        .describe('Theme name — a conclusion, not a topic label. "ECM remodeling drives the NAFLD-to-NASH transition" is a theme; ' +
+        '"Differential expression results" is not.'),
+    findings: z
+        .array(z.object({ stepId: z.string(), title: z.string() }))
+        .describe("Findings that contribute to this theme. Each entry must match an entry in findings[] by stepId + title."),
+    narrative: z.string().describe("How these findings connect into a coherent biological story — 3-5 sentences connecting them, not restating them."),
 });
 export const RunSynthesisSchema = z.object({
-    runId: z.string(),
-    /** Brief (2-4 sentence) summary of the run's scope and top-line result. */
-    overview: z.string(),
-    /**
-     * Integrated interpretation: what the run establishes, what is novel,
-     * what is actionable from a translational perspective. This is the
-     * primary interpretive section — the "so what" of the analysis.
-     */
-    conclusions: z.string(),
-    /**
-     * Selective findings — only novel, contradicted, or high-impact results
-     * that warrant individual attention. NOT a per-step catalog.
-     */
-    findings: z.array(SynthesizedFindingSchema),
-    /** Cross-step biological themes. */
-    themes: z.array(BiologicalThemeSchema),
-    /** Methodological and translational caveats. */
-    limitations: z.array(z.string()),
-    /** Key references across all findings. */
-    keyReferences: z.array(z.object({
-        pmid: z.string(),
-        citation: z.string(),
-        description: z.string(),
-    })),
+    runId: z.string().describe("The run being synthesized. Must equal the runId given in the prompt."),
+    overview: z
+        .string()
+        .describe("2-4 sentences: the run's scope, the top-line result, and the most important takeaway. " +
+        "An abstract's conclusion, not its body — do NOT enumerate counts, gene lists, or per-step results."),
+    conclusions: z
+        .string()
+        .describe("The PRIMARY interpretive section — the 'so what' — as connected prose (3-5 paragraphs). " +
+        "What the run establishes and what is novel vs confirmatory; what is actionable translationally (therapeutic-target candidates, " +
+        "biomarker candidates, safety signals, resistance mechanisms); how findings connect into a biological story; where computational " +
+        "predictions agree or disagree with clinical evidence; and an honest assessment of the translational distance."),
+    findings: z
+        .array(SynthesizedFindingSchema)
+        .describe("SELECTIVE — only novel, contradicted, high-impact, or unexpected results that warrant individual attention. " +
+        "NOT a per-step catalog. Target 3-7 for a typical run."),
+    themes: z
+        .array(BiologicalThemeSchema)
+        .describe("Cross-step biological themes. Target 2-4. Return fewer (or zero) rather than forcing findings that do not converge."),
+    limitations: z
+        .array(z.string())
+        .describe("Concrete methodological and translational caveats — not generic disclaimers. " + "Each names what it affects and why it matters. Target 3-6."),
+    keyReferences: z
+        .array(z.object({
+        pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
+        citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+        description: z.string().describe("What the paper establishes and why it is key to this run."),
+    }))
+        .describe("The 5-10 most important papers across all findings. Prioritize those that directly validate, contradict, or extend the findings — do not pad with background citations."),
 });

package/dist/schemas/validate-plan.js

@@ -26,7 +26,7 @@ export function deriveOutputPrefix(stepId) {
     return stepId
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
+        .replace(/^-|-$/g, "");
 }
 /**
  * Validate an analysis plan for structural correctness.

package/dist/schemas/workflow-state.d.ts

@@ -5,6 +5,12 @@
  * and the completion schemas that validate LLM structured output.
  */
 import { z } from "zod";
+/**
+ * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
+ * this into the planner's output contract and emits it as the `validate_plan` /
+ * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * not in a comment the model never sees.
+ */
 export declare const AnalysisStepSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -220,8 +226,8 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
     message: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodEnum<{
         error: "error";
-        warning: "warning";
         info: "info";
+        warning: "warning";
     }>>;
     content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"markdown">;

package/dist/schemas/workflow-state.js

@@ -6,17 +6,27 @@
  */
 import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
+/**
+ * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
+ * this into the planner's output contract and emits it as the `validate_plan` /
+ * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * not in a comment the model never sees.
+ */
 export const AnalysisStepSchema = z.object({
-    id: z.string().describe("Step ID in format T{track}S{step}"),
-    name: z.string(),
-    track: z.string(),
-    step_type: z.string(),
-    question: z.string(),
-    context: z.string().optional(),
-    constraints: z.array(z.string()).optional(),
-    acceptance_criteria: z.array(z.string()),
-    caveats: z.array(z.string()).optional(),
-    depends_on: z.array(z.string()),
+    id: z.string().describe("Step ID in format T{track}S{step} (e.g. T1S1, T1S2, T2S1). Unique within the plan and usable as a directory-name segment."),
+    name: z.string().describe("Short human-readable step name."),
+    track: z.string().describe("The track this step belongs to. Steps in the same track share a logical theme; steps in different tracks are independent."),
+    step_type: z.string().describe('Short label for the kind of work the step does (e.g. "analysis").'),
+    question: z
+        .string()
+        .describe("The specific question this step answers, framed with the actual condition names and comparisons from the experimental design."),
+    context: z.string().optional().describe("Background the sandbox agent needs to do the work."),
+    constraints: z.array(z.string()).optional().describe("Requirements the sandbox agent must follow exactly — not suggestions."),
+    acceptance_criteria: z.array(z.string()).describe("What the result must satisfy for the step to count as successful."),
+    caveats: z.array(z.string()).optional().describe("Pitfalls the sandbox agent should watch for."),
+    depends_on: z
+        .array(z.string())
+        .describe("IDs of steps in this plan that must complete before this one runs. Empty when the step has no prerequisites. The graph must be acyclic."),
     status: z.enum(["pending", "running", "completed", "failed", "skipped"]).default("pending"),
     // Optional on the persistence schema so historical plans (pre-resources)
     // still parse on the read side. `PlanStepSchema` re-requires it for planner
@@ -24,16 +34,17 @@ export const AnalysisStepSchema = z.object({
     // resources (no silent default) and clamps to cluster limits before use.
     resources: z
         .object({
-        cpu: z.number(),
-        memoryGb: z.number(),
-        gpu: z.object({ count: z.number() }).optional(),
+        cpu: z.number().describe("CPU cores the step needs."),
+        memoryGb: z.number().describe("Memory in GB the step needs."),
+        gpu: z.object({ count: z.number() }).optional().describe("GPUs the step needs. Omit unless the step genuinely requires one."),
     })
-        .optional(),
+        .optional()
+        .describe("Resources the step needs. Ground the estimate in the actual data size — see the resource-estimation rules."),
     // Execution fields
     agent: z.string().optional().describe("Assigned sandbox agent name from registry"),
     timeout: z.number().optional().describe("Execution timeout in seconds (falls back to image default)"),
     maxSteps: z.number().describe("Max LLM agentic steps for sandbox agent"),
-    description: z.string().optional().describe("Human-readable description of what the step does"),
+    description: z.string().optional().describe("Human-readable description of what the step produces."),
     // Step result fields (populated during execution)
     summary: z.string().optional().describe("Execution result summary"),
     artifactIds: z.array(z.string()).optional().describe("Artifact IDs produced by this step"),
@@ -43,11 +54,14 @@ export const AnalysisPlanSchema = z.object({
     // Optional on the persistence schema so historical plans (pre-title) still
     // parse on the read side. `PlannerPlanSchema` re-requires it for new plans.
     title: z.string().optional().describe("Concise human-readable plan name"),
-    analytical_narrative: z.string(),
+    analytical_narrative: z
+        .string()
+        .describe("Brief narrative of the logical flow: why these steps, in this order, address the research question. " +
+        "Reference the data characteristics that informed the choices."),
     steps: z.array(AnalysisStepSchema),
-    created_at: z.string(),
-    omicsType: z.string().optional().describe("Detected omics data type (e.g., transcriptomics, proteomics)"),
-    omicsSubtype: z.string().optional().describe("Detected subtype (e.g., bulk-rna-seq, single-cell)"),
+    created_at: z.string().describe("ISO-8601 timestamp for when the plan was created."),
+    omicsType: z.string().optional().describe("Omics data type detected from the data context (e.g. transcriptomics, proteomics, metabolomics)."),
+    omicsSubtype: z.string().optional().describe("Subtype detected from the data context (e.g. bulk-rna-seq, single-cell, microarray)."),
 });
 // ── Suspension Payload ──────────────────────────────────────────────
 /**

package/dist/state/artifacts.d.ts

@@ -44,6 +44,19 @@ export interface InputArtifactMeta {
  */
 export declare function queryInputArtifacts(pool: Querier, analysisId: string, paths: string[]): Promise<InputArtifactMeta[]>;
 export declare function queryUnsyncedStepArtifacts(pool: Querier, resourceId: string, runId: string, stepId: string): Promise<ArtifactRow[]>;
+/** One registered step output, as a downstream consumer needs to name it. */
+export interface StepArtifactRef {
+    /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
+    path: string;
+    fileType: string | null;
+}
+/**
+ * The artifacts a completed step registered, most consequential first. Ordered
+ * by artifact kind (outputs, then figures, notebooks, scripts, logs) and then by
+ * path, so a `limit` truncates the tail of the list rather than an arbitrary
+ * slice of it — and so the same call replays to the same rows.
+ */
+export declare function queryStepArtifactPaths(pool: Querier, resourceId: string, runId: string, stepId: string, limit: number): Promise<StepArtifactRef[]>;
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): Promise<number>;
 export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): Promise<void>;

package/dist/state/artifacts.js

@@ -121,6 +121,33 @@ export async function queryUnsyncedStepArtifacts(pool, resourceId, runId, stepId
     });
     return result.rows.map(mapArtifactRow);
 }
+/**
+ * The artifacts a completed step registered, most consequential first. Ordered
+ * by artifact kind (outputs, then figures, notebooks, scripts, logs) and then by
+ * path, so a `limit` truncates the tail of the list rather than an arbitrary
+ * slice of it — and so the same call replays to the same rows.
+ */
+export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, limit) {
+    if (limit <= 0)
+        return [];
+    const result = await pool.query({
+        text: `SELECT path, file_type
+          FROM cortex_artifacts
+          WHERE analysis_id = $1 AND source_run = $2 AND source_step = $3
+            AND role = 'step_output'
+          ORDER BY CASE file_type
+                     WHEN 'output' THEN 0
+                     WHEN 'figure' THEN 1
+                     WHEN 'notebook' THEN 2
+                     WHEN 'script' THEN 3
+                     ELSE 4
+                   END,
+                   path
+          LIMIT $4`,
+        values: [resourceId, runId, stepId, limit],
+    });
+    return result.rows.map((r) => ({ path: r.path, fileType: r.file_type ?? null }));
+}
 /** Count step-output artifacts produced by a run — for the run-completed card. */
 export async function countArtifactsForRun(pool, analysisId, runId) {
     const result = await pool.query({