@inflexa-ai/harness 0.48.2 → 0.48.4

package/dist/loop/test/unnamed-model.js

@@ -0,0 +1,24 @@
+/**
+ * One ChatProvider whose stream answers one text delta and one finish that carries the given input-token
+ * total and no output tokens. The usage suites feed it to the loop and read the counters back.
+ */
+import { convertArrayToReadableStream, MockLanguageModelV4 } from "ai/test";
+import { createAiSdkProvider } from "../../providers/ai-sdk.js";
+export function unnamedModel(inputTokens) {
+    const parts = [
+        { type: "stream-start", warnings: [] },
+        { type: "text-start", id: "p0" },
+        { type: "text-delta", id: "p0", delta: "done" },
+        { type: "text-end", id: "p0" },
+        {
+            type: "finish",
+            finishReason: { unified: "stop", raw: "stop" },
+            usage: {
+                inputTokens: { total: inputTokens, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                outputTokens: { total: undefined, text: undefined, reasoning: undefined },
+            },
+        },
+    ];
+    const model = new MockLanguageModelV4({ provider: "unnamed", doStream: () => Promise.resolve({ stream: convertArrayToReadableStream(parts) }) });
+    return createAiSdkProvider({ model, maxRetries: 0 });
+}

package/dist/memory/conversation-display-recorder.d.ts

@@ -17,6 +17,8 @@ export type ConversationDisplayRecorder = {
     takeOpening(): ConversationUIMessage[];
     /** The assistant message of one round, when the recorder got parts after the last take, and the divider of a marker of the round. */
     takeRound(messages: readonly ModelMessage[]): ConversationUIMessage[];
+    /** The `data-pause` parts of the open round, in one assistant message with the id of the round, or none. The round stays open. */
+    openRoundPauses(): ConversationUIMessage[];
     /** The whole turn in one projection. `runChatTurn` stores each round with `takeOpening` and `takeRound` instead. */
     finish(options?: {
         readonly fallbackText?: string;

package/dist/memory/conversation-display-recorder.js

@@ -8,7 +8,7 @@ function jsonCopy(value) {
     return structuredClone(value);
 }
 const DURABLE_CONVERSATION_PART_TYPES = new Set(Object.entries(PART_REGISTRY)
-    .filter(([, descriptor]) => descriptor.emitter === "conversation" && descriptor.consumer === "conversation" && !descriptor.transient)
+    .filter(([, descriptor]) => descriptor.consumer === "conversation" && !descriptor.transient)
     .map(([type]) => type));
 function durableConversationType(type) {
     return DURABLE_CONVERSATION_PART_TYPES.has(type);
@@ -167,6 +167,10 @@ export function createConversationDisplayRecorder(options) {
         }
         return taken;
     }
+    function openRoundPauses() {
+        const parts = displayParts(roundParts().filter((part) => part.type === "data-pause"));
+        return parts.length === 0 ? [] : [{ id: assistantMessageId, role: "assistant", parts: jsonCopy(parts) }];
+    }
     function finish(finishOptions) {
         if (!finished) {
             finished = true;
@@ -187,5 +191,5 @@ export function createConversationDisplayRecorder(options) {
         }
         return messages;
     }
-    return { emit, observe, assistantMessageId: () => assistantMessageId, userMessageId: () => userMessageId, takeOpening, takeRound, finish };
+    return { emit, observe, assistantMessageId: () => assistantMessageId, userMessageId: () => userMessageId, takeOpening, takeRound, openRoundPauses, finish };
 }

package/dist/memory/conversation-display-storage.d.ts

@@ -15,7 +15,7 @@
  * reconstruction.
  */
 import { type DataUIPart, type UIMessage } from "ai";
-import type { AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, PlanApprovalPart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart, SubAgentActivityEntry, SubAgentActivityPart } from "../contracts/chat-parts.js";
+import type { AnalogyReportPart, AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, ModelRefusal, ModelRefusalPart, PausePart, PlanApprovalPart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart, SubAgentActivityEntry, SubAgentActivityPart } from "../contracts/chat-parts.js";
 import type { ToolCallOutcome } from "../contracts/chat-events.js";
 import type { ChatMessage, MessagePart, ToolCallPart } from "../contracts/message.js";
 import type { Logger } from "../lib/logger.js";
@@ -35,6 +35,7 @@ export type ConversationUIData = {
         outcome: ToolCallOutcome;
     };
     presentation: Payload<PresentationPart>;
+    "analogy-report": Payload<AnalogyReportPart>;
     plan: Payload<PlanPart>;
     "run-card": Payload<RunCardPart>;
     "plan-approval": Payload<PlanApprovalPart>;
@@ -43,6 +44,8 @@ export type ConversationUIData = {
     "child-session-started": Payload<ChildSessionStartedPart>;
     "report-rendered": Payload<ReportRenderedPart>;
     compaction: Payload<CompactionPart>;
+    "model-refusal": ModelRefusal;
+    pause: Payload<PausePart>;
     "subagent-activity": Omit<Payload<SubAgentActivityPart>, "entries"> & {
         entries: (Omit<SubAgentActivityEntry, "outcome"> & {
             outcome: ToolCallOutcome;
@@ -65,7 +68,7 @@ export declare function parseStoredDisplayEnvelope(value: unknown, identity: str
 export type StoredSourcePart = Extract<Exclude<MessagePart, {
     type: "text";
 }>, {
-    type: ToolCallPart["type"] | PresentationPart["type"] | PlanPart["type"] | RunCardPart["type"] | PlanApprovalPart["type"] | FileReferencePart["type"] | AskPart["type"] | ChildSessionStartedPart["type"] | ReportRenderedPart["type"] | CompactionPart["type"] | SubAgentActivityPart["type"];
+    type: ToolCallPart["type"] | PresentationPart["type"] | AnalogyReportPart["type"] | PlanPart["type"] | RunCardPart["type"] | PlanApprovalPart["type"] | FileReferencePart["type"] | AskPart["type"] | ChildSessionStartedPart["type"] | ReportRenderedPart["type"] | CompactionPart["type"] | ModelRefusalPart["type"] | PausePart["type"] | SubAgentActivityPart["type"];
 }>;
 /** Whether `part` is an arm the stored vocabulary can hold; anything else cannot become a stored card. */
 export declare function isStoredSourcePart(part: Exclude<MessagePart, {

package/dist/memory/conversation-display-storage.js

@@ -19,7 +19,7 @@ import { textOf } from "../lib/unknown-text.js";
 import { isDataUIPart, validateUIMessages } from "ai";
 import { z } from "zod";
 import { parseUnknownRecord } from "../lib/unknown-containers.js";
-import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
+import { AnalogyReportPartSchema, AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, ModelRefusalPayloadSchema, PausePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
 import { ToolCallOutcomeSchema, ToolCallValueSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
 const DisplayEnvelopeHeaderSchema = z.object({
@@ -69,6 +69,7 @@ const ToolCallDisplaySchema = z.object({
 const dataSchemas = {
     "tool-call": ToolCallDisplaySchema,
     presentation: PresentationPartSchema.omit({ type: true }),
+    "analogy-report": AnalogyReportPartSchema.omit({ type: true }),
     plan: PlanPartSchema.omit({ type: true }),
     "run-card": RunCardPartSchema.omit({ type: true }),
     "plan-approval": PlanApprovalPartSchema.omit({ type: true }),
@@ -77,6 +78,8 @@ const dataSchemas = {
     "child-session-started": ChildSessionStartedPartSchema.omit({ type: true }),
     "report-rendered": ReportRenderedPartSchema.omit({ type: true }),
     compaction: CompactionPartSchema.omit({ type: true }),
+    "model-refusal": ModelRefusalPayloadSchema,
+    pause: PausePartSchema.omit({ type: true }),
     "subagent-activity": SubAgentActivityPartSchema.omit({ type: true }).extend({
         entries: z.array(SubAgentActivityEntrySchema.extend({ outcome: ToolCallOutcomeSchema })),
     }),
@@ -174,6 +177,7 @@ export async function parseStoredDisplayEnvelope(value, identity, logger) {
 const STORED_SOURCE_TYPES = [
     "tool-call",
     "data-presentation",
+    "data-analogy-report",
     "data-plan",
     "data-run-card",
     "data-plan-approval",
@@ -182,6 +186,8 @@ const STORED_SOURCE_TYPES = [
     "data-child-session-started",
     "data-report-rendered",
     "data-compaction",
+    "data-model-refusal",
+    "data-pause",
     "data-subagent-activity",
 ];
 const STORED_SOURCE_TYPE_SET = new Set(STORED_SOURCE_TYPES);
@@ -223,6 +229,10 @@ export function conversationDisplayPart(part) {
             const { type: _type, ...data } = part;
             return { type: "data-presentation", id, data };
         }
+        case "data-analogy-report": {
+            const { type: _type, ...data } = part;
+            return { type: "data-analogy-report", id, data };
+        }
         case "data-plan": {
             const { type: _type, ...data } = part;
             return { type: "data-plan", id, data };
@@ -255,6 +265,14 @@ export function conversationDisplayPart(part) {
             const { type: _type, ...data } = part;
             return { type: "data-compaction", id, data };
         }
+        case "data-model-refusal": {
+            const { type: _type, ...data } = part;
+            return { type: "data-model-refusal", id, data };
+        }
+        case "data-pause": {
+            const { type: _type, ...data } = part;
+            return { type: "data-pause", id, data };
+        }
         case "data-subagent-activity": {
             const { type: _type, ...payload } = part;
             return { type: "data-subagent-activity", id, data: { ...payload, entries: part.entries.map(closedEntry) } };
@@ -291,6 +309,9 @@ export function conversationUIToChatMessages(messages) {
                     case "data-presentation":
                         parts.push({ type: "data-presentation", ...part.data });
                         break;
+                    case "data-analogy-report":
+                        parts.push({ type: "data-analogy-report", ...part.data });
+                        break;
                     case "data-plan":
                         parts.push({ type: "data-plan", ...part.data });
                         break;
@@ -315,6 +336,12 @@ export function conversationUIToChatMessages(messages) {
                     case "data-compaction":
                         parts.push({ type: "data-compaction", ...part.data });
                         break;
+                    case "data-model-refusal":
+                        parts.push({ type: "data-model-refusal", ...part.data });
+                        break;
+                    case "data-pause":
+                        parts.push({ type: "data-pause", ...part.data });
+                        break;
                     case "data-subagent-activity":
                         parts.push({ type: "data-subagent-activity", ...part.data });
                         break;

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion of a bioinformatics analysis platform. You\nhelp researchers understand their data, run analyses, interpret results, and\ndevelop testable hypotheses.\n\nYour tool results stay in this conversation across turns. Reuse what you\nalready read or searched, and look again only for something new, for example\na run that completed since.\n\n## Data and Files\n\nYou can read the files of this analysis. `inspect_data_profile` is the record\nof what the dataset is. `workspace_search` finds files by their description,\nand `read_file` gives the values.\n\nWhen the user names data that is not yet an input of this analysis, add it with\nthe input tool if you hold one; its call asks the user. Without one, say that\nthe data must be added as an input. Never tell the user to copy files into a\nfolder to make them visible.\n\n## Analysis Runs\n\nA run starts a sandbox with a specialist agent, and it takes minutes to hours.\nStart one only for computation on the data that needs that environment:\nstatistics, models, R or Python packages, reference data, a table over 16 MiB.\nA lookup, a file read or write, a summary of results that you can read, and\nlight work on a table (a filter, a join, a count, a small test, a reshape, a\nderived file or chart) are not runs. Do them yourself, with `run_script` for\nthe tables.\n\n- **One sandbox computation that the user explicitly asks for** \u2192\n  `execute_analysis` in ad hoc mode, with the request in their words. The\n  request is the consent: do not plan it and do not ask again. Keep one request\n  in one call.\n- **Work of several dependent steps** \u2192 `generate_plan`. It shows the plan\n  card. Explain the plan, and ask for approval. On approval, call\n  `execute_analysis` in plan mode. A thread record that says that the person\n  approved a plan means that its run started already.\n- **A computation that only you suggest** \u2192 ask first.\n\nRuns are asynchronous. Read their results on a later turn with `inspect_run`.\n\n## Interpreting Results\n\nA completed run has one summary for each step. When the run had summaries and\nno blocker, it also has a run synthesis: conclusions, key findings, themes,\nlimitations, and references. `inspect_run` gives the `synthesisStatus` and\nthe `synthesisPath`. Start from the synthesis, and read a step summary for the\nevidence behind a finding. Without a synthesis, integrate the step summaries\nyourself. Group findings by biological theme, and keep well-supported findings\napart from speculation.\n\nFor a translational finding, give the landscape of existing drugs for a target,\nkeep predictive and prognostic biomarkers apart, name the validation that is\nmissing, and rest no claim on one source.\n\n## Literature and Biology\n\nA question about biology or the literature gets a lookup, not an answer from\nmemory. The lookups are cheap API calls in `run_script`: put independent\nlookups in one script, and print only what you need. When a source has nothing,\nsay so and continue with the others.\n\n## Hypotheses\n\nA hypothesis is grounded in data that you read, falsifiable, and specific: the\ngenes, pathways, comparisons, and expected effects. Make sure that the data can\ntest it, rank the candidates by impact, testability, novelty, and evidence, and\ndrop what cannot be tested. Analogies from `generate_analogy_report` are\ncandidate seeds; ground each one in the data before you use it. When the user\nasks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and\ngive the full updated list. To test a hypothesis, plan an analysis for it.\n\nThe analogy report renders as a card. Name the analogies that matter by their\n`analogyTitle`, say why they matter for this data, and end with one question\nabout which one to pursue. Keep analogies out of `generate_plan`,\n`execute_analysis`, and each other workflow input: the planner and the\nsandbox agents do not know analogy reports.\n\n## Reports\n\nWhen the user asks for a report, call `start_report_session` with no\nconfirmation, unless the scope is truly ambiguous: several analyses to choose\nfrom, or an audience that matters and is not known. Then tell the user that the\nreport takes shape in that chat. Do not compose the report here. A request to\nput content into a file, such as a markdown summary or a PDF, is a file that you\nwrite: `write_file` for text, and `export_pdf` in a script for a PDF. The user\nmay not know that report sessions exist: offer one when a structured, cited\nreport would serve them, for example after a run completes.\n\n## Ground Rules\n\n- Cite a value only from a synthesis, a step summary, or a file that you or a\n  script read. A `workspace_search` hit gives a description, not the values.\n  If you cannot find the data behind a claim, say so.\n- A constraint in the working memory binds the rest of the analysis. If a plan\n  or a choice would break one, raise the conflict with the user. Never just\n  proceed.\n- Data profiling runs each time the inputs change, thus a plan needs no step\n  that explores the data structure.\n- Before you call a package or a reference dataset unavailable, find out\n  whether a tool that you hold can provide it.\n- When a tool fails, say so briefly, name a cause that the user can act on, and\n  offer a retry or an alternative. Keep the internal details out.\n- When results conflict, give both sides.\n- Give a hypothesis with its ID, claim, rationale, test design, expected\n  outcomes, and priority.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion of a bioinformatics analysis platform. You\nhelp researchers understand their data, run analyses, interpret results, and\ndevelop testable hypotheses.\n\nYour tool results stay in this conversation across turns. Reuse what you\nalready read or searched, and look again only for something new, for example\na run that completed since.\n\n## Data and Files\n\nYou can read the files of this analysis. `inspect_data_profile` is the record\nof what the dataset is. `workspace_search` finds files by their description,\nand `read_file` gives the values.\n\nWhen the user names data that is not yet an input of this analysis, add it with\nthe input tool if you hold one; its call asks the user. Without one, say that\nthe data must be added as an input. Never tell the user to copy files into a\nfolder to make them visible.\n\n## Analysis Runs\n\nA run starts a sandbox with a specialist agent, and it takes minutes to hours.\nStart one only for computation on the data that needs that environment:\nstatistics, models, R or Python packages, reference data, a table over 16 MiB.\nA lookup, a file read or write, a summary of results that you can read, and\nlight work on a table (a filter, a join, a count, a small test, a reshape, a\nderived file or chart) are not runs. Do them yourself, with `run_script` for\nthe tables.\n\n- **One sandbox computation that the user explicitly asks for** \u2192\n  `execute_analysis` in ad hoc mode, with the request in their words. The\n  request is the consent: do not plan it and do not ask again. Keep one request\n  in one call.\n- **Work of several dependent steps** \u2192 `generate_plan`. It shows the plan\n  card. Explain the plan, and ask for approval. On approval, call\n  `execute_analysis` in plan mode. A thread record that says that the person\n  approved a plan means that its run started already.\n- **A computation that only you suggest** \u2192 ask first.\n\nRuns are asynchronous. Read their results on a later turn with `inspect_run`.\n\n## Interpreting Results\n\nA completed run has one summary for each step. When the run had summaries and\nno blocker, it also has a run synthesis: conclusions, key findings, themes,\nlimitations, and references. `inspect_run` gives the `synthesisStatus` and\nthe `synthesisPath`. Start from the synthesis, and read a step summary for the\nevidence behind a finding. Without a synthesis, integrate the step summaries\nyourself. Group findings by biological theme, and keep well-supported findings\napart from speculation.\n\nFor a translational finding, give the landscape of existing drugs for a target,\nkeep predictive and prognostic biomarkers apart, name the validation that is\nmissing, and rest no claim on one source.\n\n## Literature and Biology\n\nA question about biology or the literature gets a lookup, not an answer from\nmemory. The lookups are cheap API calls in `run_script`: put independent\nlookups in one script, and print only what you need. When a source has nothing,\nsay so and continue with the others.\n\n## Hypotheses\n\nA hypothesis is grounded in data that you read, falsifiable, and specific: the\ngenes, pathways, comparisons, and expected effects. Make sure that the data can\ntest it, rank the candidates by impact, testability, novelty, and evidence, and\ndrop what cannot be tested. Analogies from `generate_analogy_report` are\ncandidate seeds; ground each one in the data before you use it. When the user\nasks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and\ngive the full updated list. To test a hypothesis, plan an analysis for it.\n\nThe analogy block shows the full report to the user, thus do not copy the\nreport into your reply. Name the analogies that matter by their\n`analogyTitle`, say why they matter for this data, and end with one question\nabout which one to pursue. For an `extraction-failed` envelope, give\nthe message of the error and ask the user to narrow the problem. Keep\nanalogies out of `generate_plan`, `execute_analysis`, and each other workflow\ninput: the planner and the sandbox agents do not know analogy reports.\n\n## Reports\n\nWhen the user asks for a report, call `start_report_session` with no\nconfirmation, unless the scope is truly ambiguous: several analyses to choose\nfrom, or an audience that matters and is not known. Then tell the user that the\nreport takes shape in that chat. Do not compose the report here. A request to\nput content into a file, such as a markdown summary or a PDF, is a file that you\nwrite: `write_file` for text, and `export_pdf` in a script for a PDF. The user\nmay not know that report sessions exist: offer one when a structured, cited\nreport would serve them, for example after a run completes.\n\n## Ground Rules\n\n- Cite a value only from a synthesis, a step summary, or a file that you or a\n  script read. A `workspace_search` hit gives a description, not the values.\n  If you cannot find the data behind a claim, say so.\n- A constraint in the working memory binds the rest of the analysis. If a plan\n  or a choice would break one, raise the conflict with the user. Never just\n  proceed.\n- Data profiling runs each time the inputs change, thus a plan needs no step\n  that explores the data structure.\n- Before you call a package or a reference dataset unavailable, find out\n  whether a tool that you hold can provide it.\n- When a tool fails, say so briefly, name a cause that the user can act on, and\n  offer a retry or an alternative. Keep the internal details out.\n- When results conflict, give both sides.\n- Give a hypothesis with its ID, claim, rationale, test design, expected\n  outcomes, and priority.\n";

package/dist/prompts/conversation.js

@@ -72,11 +72,13 @@ candidate seeds; ground each one in the data before you use it. When the user
 asks to go deeper on a hypothesis, refine it into sharper sub-hypotheses and
 give the full updated list. To test a hypothesis, plan an analysis for it.
 
-The analogy report renders as a card. Name the analogies that matter by their
+The analogy block shows the full report to the user, thus do not copy the
+report into your reply. Name the analogies that matter by their
 \`analogyTitle\`, say why they matter for this data, and end with one question
-about which one to pursue. Keep analogies out of \`generate_plan\`,
-\`execute_analysis\`, and each other workflow input: the planner and the
-sandbox agents do not know analogy reports.
+about which one to pursue. For an \`extraction-failed\` envelope, give
+the message of the error and ask the user to narrow the problem. Keep
+analogies out of \`generate_plan\`, \`execute_analysis\`, and each other workflow
+input: the planner and the sandbox agents do not know analogy reports.
 
 ## Reports
 

package/dist/prompts/sandbox/mdv-preparation-agent.d.ts

@@ -0,0 +1 @@
+export declare const mdvPreparationAgentPrompt = "# MDV Preparation Agent\n\nYou prepare biological datasets as assets for MDV (Multi-Dimensional Viewer). You take\nscRNA-seq, snRNA-seq, scATAC-seq, multiome, spatial transcriptomics (CosMx, Xenium, Visium,\nMERFISH) and spatial proteomics (CODEX, IMC, MIBI) data, in raw or processed form. You deliver an\nMDV-ready AnnData that MDV's upload converts into readable tables, the context tables, and a\nREADME, so that a person who did not make them can use them in MDV.\n\n## Skills\n\nYour skills: `mdv-preparation`, `single-cell`, `spatial-omics`, `chromatin-regulation`,\n`shared/omics-general`.\n\nRead `mdv-preparation` first. Its workflow is the order of your work, and its references\nhold the code to copy: the asset helpers and the validator. Use the modality packs for QC,\nnormalisation, embedding, and clustering when the input is raw.\n\n## Workflow (Summary)\n\n1. **Inventory** \u2014 identify the modality, the platform, the input form (raw instrument output,\n   count matrix, processed AnnData, MuData, SpatialData), and the size. Estimate the memory\n   before you load a large matrix.\n2. **Build** \u2014 one analysis-ready AnnData: counts in, QC, log-normalised sparse X, UMAP,\n   clusters, and readable labels with their evidence.\n3. **Curate** \u2014 keep the columns a person needs, label each with words and units (the label is\n   the column name in MDV), keep grouping columns at 256 categories or fewer.\n4. **Write** \u2014 the asset, the context tables, and the README with a column glossary, the\n   processing record, and the first charts to make.\n5. **Validate** \u2014 run the validator of the pack. Zero errors before delivery.\n\n## Domain Standards\n\n- The deliverable is an asset, not an MDV project. You do not need mdvtools.\n- Spatial data: slide coordinates in micrometres as two columns, y flipped upwards. For raw CosMx\n  runs, measure the FOV orientation before you trust the layout.\n- Inferred labels are putative: say so in the column label and keep the evidence.\n- Fix every seed. The same input gives the same asset.\n\n## Figures\n\nThe asset is the deliverable. Write one preview PNG only if the step needs a figure for the\nreport: the tissue or the UMAP coloured by cell type.\n\n## Domain Anti-Patterns\n\n- Raw snake_case keys or bare cluster ids as the labels people see.\n- Dense or scaled matrices, extra layers, or PCA columns in the asset.\n- Grouping columns above 256 categories.\n- Skipping the validator because the file \"loads\".\n\n## Required Output Files\n\n- The asset `output/*.mdv.h5ad`, its context tables `output/*.tsv`, and `output/README.md`.\n- The validator report `output/*.mdv.validation.json`, with zero errors.\n- The analysis AnnData `output/*.h5ad` with standard keys and raw counts.\n";

package/dist/prompts/sandbox/mdv-preparation-agent.js

@@ -0,0 +1,56 @@
+export const mdvPreparationAgentPrompt = `# MDV Preparation Agent
+
+You prepare biological datasets as assets for MDV (Multi-Dimensional Viewer). You take
+scRNA-seq, snRNA-seq, scATAC-seq, multiome, spatial transcriptomics (CosMx, Xenium, Visium,
+MERFISH) and spatial proteomics (CODEX, IMC, MIBI) data, in raw or processed form. You deliver an
+MDV-ready AnnData that MDV's upload converts into readable tables, the context tables, and a
+README, so that a person who did not make them can use them in MDV.
+
+## Skills
+
+Your skills: \`mdv-preparation\`, \`single-cell\`, \`spatial-omics\`, \`chromatin-regulation\`,
+\`shared/omics-general\`.
+
+Read \`mdv-preparation\` first. Its workflow is the order of your work, and its references
+hold the code to copy: the asset helpers and the validator. Use the modality packs for QC,
+normalisation, embedding, and clustering when the input is raw.
+
+## Workflow (Summary)
+
+1. **Inventory** — identify the modality, the platform, the input form (raw instrument output,
+   count matrix, processed AnnData, MuData, SpatialData), and the size. Estimate the memory
+   before you load a large matrix.
+2. **Build** — one analysis-ready AnnData: counts in, QC, log-normalised sparse X, UMAP,
+   clusters, and readable labels with their evidence.
+3. **Curate** — keep the columns a person needs, label each with words and units (the label is
+   the column name in MDV), keep grouping columns at 256 categories or fewer.
+4. **Write** — the asset, the context tables, and the README with a column glossary, the
+   processing record, and the first charts to make.
+5. **Validate** — run the validator of the pack. Zero errors before delivery.
+
+## Domain Standards
+
+- The deliverable is an asset, not an MDV project. You do not need mdvtools.
+- Spatial data: slide coordinates in micrometres as two columns, y flipped upwards. For raw CosMx
+  runs, measure the FOV orientation before you trust the layout.
+- Inferred labels are putative: say so in the column label and keep the evidence.
+- Fix every seed. The same input gives the same asset.
+
+## Figures
+
+The asset is the deliverable. Write one preview PNG only if the step needs a figure for the
+report: the tissue or the UMAP coloured by cell type.
+
+## Domain Anti-Patterns
+
+- Raw snake_case keys or bare cluster ids as the labels people see.
+- Dense or scaled matrices, extra layers, or PCA columns in the asset.
+- Grouping columns above 256 categories.
+- Skipping the validator because the file "loads".
+
+## Required Output Files
+
+- The asset \`output/*.mdv.h5ad\`, its context tables \`output/*.tsv\`, and \`output/README.md\`.
+- The validator report \`output/*.mdv.validation.json\`, with zero errors.
+- The analysis AnnData \`output/*.h5ad\` with standard keys and raw counts.
+`;

package/dist/providers/ai-sdk.d.ts

@@ -118,6 +118,12 @@ export type AiSdkProviderConfig = {
      * Needs the `thinking-binding-controls-2026-08-01` beta header.
      */
     readonly thinkingBinding?: "drop_block" | "error" | "off";
+    /**
+     * `default`: when a safety classifier declines a request, the API sends it again to the model that it
+     * recommends for the category of the refusal, inside the same call. When the field is absent, a declined
+     * request ends with the content filter. A model with no fallback target keeps its refusal.
+     */
+    readonly fallbacks?: "default";
 } | {
     readonly kind: "openai";
     readonly baseURL?: string;
@@ -252,22 +258,19 @@ export declare function sessionKeyDigestOf(session: Pick<AgentSession, "scope" |
  * A model can refuse a request by category — a biology prompt is one such category —
  * and the API then re-serves it on another model. It reports the hop TWICE: as a
  * `fallback` content block inside the assistant turn, and on
- * `providerMetadata.anthropic.iterations`. `@ai-sdk/anthropic` keeps only the second,
- * because the AI SDK has no part for a model hop, and it drops the block from the
- * content it returns (`anthropic-messages-language-model`, the `content_block_start`
- * case). Thus the turn the harness holds is not the turn the API produced, and every
- * signed thinking block of that turn is rejected from the next request on.
+ * `providerMetadata.anthropic.iterations`. `@ai-sdk/anthropic` keeps the block as a
+ * custom part and sends it back on the next request, but it keeps each thinking block
+ * before it too. The API accepts no thinking block from before the hop, and a turn
+ * whose thinking blocks changed earns `thinking ... blocks in the latest assistant
+ * message cannot be modified`, which is a 400 that no retry can pass.
  *
- * The API holds the whole turn against the signature of each of its thinking blocks, so
- * echoing that turn earns `thinking ... blocks in the latest assistant message cannot be
- * modified`, which is a 400 that no retry can pass. A thinking block is optional on the
- * way back, thus the loop records the reply of a hop with no thinking block, and the next
- * request continues. The cost is the reasoning of this one turn and the cache write that
- * its new prefix pays for.
+ * A thinking block is optional on the way back, thus the loop records the reply of a
+ * hop with no thinking block, and the next request continues. The cost is the
+ * reasoning of this one turn and the cache write that its new prefix pays for.
  *
- * The response metadata of the package carries `message_start.message.model`, and that
- * field keeps the REQUESTED model across a hop. The iteration names the model that
- * answered, thus it wins for the usage record.
+ * The response metadata of the package carries `message_start.message.model`, and
+ * after a hop in the middle of a reply that field keeps the REQUESTED model. The
+ * iteration names the model that answered, thus it wins for the usage record.
  */
 export declare function fallbackModelOf(metadata: ProviderMetadata | undefined): string | undefined;
 /**

package/dist/providers/ai-sdk.js

@@ -108,22 +108,19 @@ function thinkingWithBinding(reasoning, mode) {
  * A model can refuse a request by category — a biology prompt is one such category —
  * and the API then re-serves it on another model. It reports the hop TWICE: as a
  * `fallback` content block inside the assistant turn, and on
- * `providerMetadata.anthropic.iterations`. `@ai-sdk/anthropic` keeps only the second,
- * because the AI SDK has no part for a model hop, and it drops the block from the
- * content it returns (`anthropic-messages-language-model`, the `content_block_start`
- * case). Thus the turn the harness holds is not the turn the API produced, and every
- * signed thinking block of that turn is rejected from the next request on.
+ * `providerMetadata.anthropic.iterations`. `@ai-sdk/anthropic` keeps the block as a
+ * custom part and sends it back on the next request, but it keeps each thinking block
+ * before it too. The API accepts no thinking block from before the hop, and a turn
+ * whose thinking blocks changed earns `thinking ... blocks in the latest assistant
+ * message cannot be modified`, which is a 400 that no retry can pass.
  *
- * The API holds the whole turn against the signature of each of its thinking blocks, so
- * echoing that turn earns `thinking ... blocks in the latest assistant message cannot be
- * modified`, which is a 400 that no retry can pass. A thinking block is optional on the
- * way back, thus the loop records the reply of a hop with no thinking block, and the next
- * request continues. The cost is the reasoning of this one turn and the cache write that
- * its new prefix pays for.
+ * A thinking block is optional on the way back, thus the loop records the reply of a
+ * hop with no thinking block, and the next request continues. The cost is the
+ * reasoning of this one turn and the cache write that its new prefix pays for.
  *
- * The response metadata of the package carries `message_start.message.model`, and that
- * field keeps the REQUESTED model across a hop. The iteration names the model that
- * answered, thus it wins for the usage record.
+ * The response metadata of the package carries `message_start.message.model`, and
+ * after a hop in the middle of a reply that field keeps the REQUESTED model. The
+ * iteration names the model that answered, thus it wins for the usage record.
  */
 export function fallbackModelOf(metadata) {
     const entries = metadata?.["anthropic"]?.["iterations"];
@@ -717,12 +714,13 @@ export function createConfiguredAiSdkProvider(deps) {
             maxRetries: config.maxRetries,
             requestTimeoutMs,
             reasoning: config.reasoning,
-            // The package sends the key as `metadata.user_id`, and the binding as
-            // `thinking.block_binding`.
+            // The package sends the key as `metadata.user_id`, the binding as
+            // `thinking.block_binding`, and the default fallback with its beta header.
             providerOptionsFor: ({ session, reasoning }) => ({
                 anthropic: {
                     metadata: { userId: sessionKeyDigestOf(session) },
                     thinking: binding === undefined ? undefined : thinkingWithBinding(reasoning, binding),
+                    fallbacks: config.fallbacks,
                 },
             }),
         });

package/dist/report-model/fixture-resolver.js

@@ -4,17 +4,9 @@
  * assertion rules without a host.
  */
 import { err, ok } from "neverthrow";
-import { asFiniteNumber, cellMatchesFilterValue, checkCitationAssertion, checkValueAssertion } from "./assert-rules.js";
-import { applyRowBound, columnsHeldByNoRow, fileTypeHoldsNoCell, snapshotEntry, snapshotRows, } from "./reference-resolver.js";
-/** Build an `Err` that carries the unresolved reference. The `detail` key is present only when there is a detail to carry. */
-function fail(reference, reason, detail) {
-    const failure = detail !== undefined ? { reference, reason, detail } : { reference, reason };
-    return err(failure);
-}
-/** A short account of a derivation input, for a detail that names which input broke the arithmetic. */
-function describeReference(reference) {
-    return `artifact value at ${reference.path} column ${reference.locator.column}`;
-}
+import { checkValueAssertion } from "./assert-rules.js";
+import { fail, readArtifactTable, resolveCitation, resolveDerivation, selectRow } from "./reference-read.js";
+import { fileTypeHoldsNoCell, snapshotEntry, snapshotRows } from "./reference-resolver.js";
 function resolveArtifactValue(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -35,53 +27,22 @@ function resolveArtifactValue(reference, snapshot) {
     if (readRows.isErr()) {
         return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
     }
-    const rows = readRows.value;
     const locator = reference.locator;
-    let selectedRow;
-    if (locator.row !== undefined) {
-        const row = rows[locator.row];
-        if (row === undefined) {
-            return fail(reference, "locator-out-of-range", `row ${locator.row} is outside the ${rows.length} rows`);
-        }
-        selectedRow = row;
-    }
-    else if (locator.rowFilter !== undefined) {
-        const filter = locator.rowFilter;
-        const matches = rows.filter((row) => cellMatchesFilterValue(row[filter.column], filter.value));
-        const match = matches[0];
-        if (match === undefined) {
-            return fail(reference, "locator-out-of-range", `no row where ${filter.column} equals ${String(filter.value)}`);
-        }
-        if (matches.length > 1) {
-            return fail(reference, "ambiguous-match", `${matches.length} rows where ${filter.column} equals ${String(filter.value)}`);
-        }
-        selectedRow = match;
-    }
-    else {
-        // The locator schema forbids a locator with neither selector. The resolver cannot depend on a
-        // prior parse, thus it treats a row that no selector addresses as out of range.
-        return fail(reference, "locator-out-of-range", "the locator selects no row");
+    const selection = selectRow(readRows.value, locator);
+    if (selection.isErr()) {
+        return fail(reference, selection.error.reason, selection.error.detail);
     }
     // A real table holds an empty cell, and the snapshot parser gives it back as an absent
     // key: `snapshotRows` drops a cell that parsed as `null` or `undefined`, so an absent key
     // is the only absence. It is not a value that a scalar reference can bind. An empty
     // string is a value, thus it stays valid.
-    const cell = selectedRow[locator.column];
+    const cell = selection.value[locator.column];
     if (cell === undefined) {
         return fail(reference, "locator-out-of-range", `column ${locator.column} holds no value in the selected row`);
     }
     const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, cell);
     return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: cell });
 }
-/**
- * Put one own data property on a projected row.
- *
- * A plain assignment at the key `__proto__` reaches the prototype setter, thus the projection loses a
- * column that the row holds. The definition makes an own data property for each key.
- */
-function defineOwn(target, key, value) {
-    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
-}
 function resolveArtifactTable(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
     if (artifact === undefined) {
@@ -94,46 +55,11 @@ function resolveArtifactTable(reference, snapshot) {
     if (fileTypeHoldsNoCell(tableFileType)) {
         return fail(reference, "unreadable-artifact", `the ${String(tableFileType)} at ${reference.path} holds no cell to read`);
     }
-    // The bound ranks the rows as the artifact holds them, thus a bound over a column that the subset
-    // below leaves out still ranks them. An unknown bound column addresses nothing, exactly as an unknown
-    // subset column does.
-    const bound = reference.rowBound;
     const readRows = snapshotRows(artifact);
     if (readRows.isErr()) {
         return fail(reference, "unreadable-artifact", `the artifact at ${reference.path} holds a malformed row: ${readRows.error}`);
     }
-    const allRows = readRows.value;
-    if (bound !== undefined && columnsHeldByNoRow(allRows, [bound.column]).length > 0) {
-        return fail(reference, "locator-out-of-range", `the row bound names column ${bound.column}, which the table at ${reference.path} does not hold`);
-    }
-    const rows = bound === undefined ? allRows : applyRowBound(allRows, bound);
-    // The page states the shown count against the count of the artifact. This read is the one place that
-    // holds both, thus a bounded table carries the pre-bound total out with its rows.
-    const total = bound === undefined ? {} : { total: allRows.length };
-    const columns = reference.columns;
-    if (columns === undefined) {
-        return ok({ type: "table", rows, ...total });
-    }
-    // A name that no row holds addresses nothing. Without this check a projection onto an invented column
-    // gives an empty cell for each row and still resolves, which is the fabrication that grounding exists
-    // to reject.
-    const absent = columnsHeldByNoRow(rows, columns);
-    if (absent.length > 0) {
-        return fail(reference, "locator-out-of-range", `the table at ${reference.path} holds no column ${absent.join(", ")}`);
-    }
-    // Project each row onto the requested columns. A table tolerates a ragged row, thus a column that a
-    // given row lacks is left out of that row and is not a failure.
-    const projectedRows = rows.map((row) => {
-        const projected = {};
-        for (const column of columns) {
-            const cell = row[column];
-            if (cell !== undefined) {
-                defineOwn(projected, column, cell);
-            }
-        }
-        return projected;
-    });
-    return ok({ type: "table", rows: projectedRows, columns, ...total });
+    return readArtifactTable(reference, readRows.value);
 }
 function resolveArtifactFile(reference, snapshot) {
     const artifact = snapshotEntry(snapshot, reference.path);
@@ -145,58 +71,6 @@ function resolveArtifactFile(reference, snapshot) {
     }
     return ok({ type: "file", path: reference.path, hash: artifact.hash });
 }
-async function resolveDerivation(reference, snapshot) {
-    const numbers = [];
-    for (const input of reference.inputs) {
-        const inputResult = await resolve(input, snapshot);
-        if (inputResult.isErr()) {
-            // Keep the inner reason so a reviewer sees the real cause, for example a missing artifact under
-            // the derivation. The derivation itself did not fail on its own terms.
-            return fail(reference, inputResult.error.reason, inputResult.error.detail);
-        }
-        const resolved = inputResult.value;
-        const numeric = resolved.type === "scalar" ? asFiniteNumber(resolved.value) : undefined;
-        if (numeric === undefined) {
-            // The arithmetic needs a finite number. A cell that holds text does not address a usable
-            // scalar, thus the closest reason is that the coordinate is out of range.
-            return fail(reference, "locator-out-of-range", `input ${describeReference(input)} did not resolve to a finite number`);
-        }
-        numbers.push(numeric);
-    }
-    const a = numbers[0];
-    const b = numbers[1];
-    if (a === undefined || b === undefined) {
-        return fail(reference, "locator-out-of-range", `operation ${reference.op} needs two inputs, and the derivation holds ${numbers.length}`);
-    }
-    let result;
-    switch (reference.op) {
-        case "ratio":
-            result = a / b;
-            break;
-        case "delta":
-            result = a - b;
-            break;
-        case "pctChange":
-            // A fraction, not a percent. A change of one half gives 0.5, thus an author asserts 0.5 and a
-            // `unit` of `%` only tells a renderer how to show it.
-            result = (a - b) / b;
-            break;
-    }
-    if (!Number.isFinite(result)) {
-        return fail(reference, "locator-out-of-range", `operation ${reference.op} does not yield a finite value, because the divisor is zero`);
-    }
-    const valueFailure = checkValueAssertion(reference, reference.assert?.value, reference.assert?.tolerance, result);
-    return valueFailure !== undefined ? err(valueFailure) : ok({ type: "scalar", value: result });
-}
-function resolveCitation(reference, snapshot) {
-    const key = `${reference.idKind}:${reference.id}`;
-    if (snapshot.citations === undefined || !snapshot.citations.includes(key)) {
-        return fail(reference, "artifact-missing", `the citation ${key} is not in the pinned evidence`);
-    }
-    const value = { type: "citation", id: key };
-    const citationFailure = checkCitationAssertion(reference, reference.assert?.value, key);
-    return citationFailure !== undefined ? err(citationFailure) : ok(value);
-}
 async function resolve(reference, snapshot) {
     switch (reference.kind) {
         case "artifact-value":
@@ -206,7 +80,7 @@ async function resolve(reference, snapshot) {
         case "artifact-file":
             return resolveArtifactFile(reference, snapshot);
         case "derivation":
-            return resolveDerivation(reference, snapshot);
+            return resolveDerivation(reference, snapshot, resolve);
         case "citation":
             return resolveCitation(reference, snapshot);
     }

package/dist/report-model/production-resolver.d.ts

@@ -13,9 +13,9 @@
  * holds the streamed hash and the parsed rows against a stat signature. Two tool calls of one analysis
  * share one cache.
  *
- * The realization calls the shared assert functions in `assert-rules.ts`, and it mirrors the locator walk
- * and the reason choices of `fixture-resolver.ts`. Thus one semantics exists, and the fixture stays the
- * executable specification of the value tier. The two realizations are substitutable behind the seam.
+ * The realization calls the shared assert functions in `assert-rules.ts` and the shared reference reads in
+ * `reference-read.ts`, as the fixture realization does. Thus one semantics exists, and the fixture stays
+ * the executable specification of the value tier. The two realizations are substitutable behind the seam.
  */
 import { type ReferenceResolver } from "./reference-resolver.js";
 /** One artifact row, as plain cells. A text-backed format holds a numeric column as a string. */