@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/prompts/briefing.d.ts

@@ -24,14 +24,20 @@
 import { type WorkingMemory } from "../memory/working-memory.js";
 import type { DataProfileResult } from "../state/data-profile.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
+import type { TemplateParameter } from "../tools/knowledge/client.js";
+import type { TemplateBindingValue } from "../tools/knowledge/template.js";
 /** Completed dependencies rendered as upstream blocks; the tail is counted, not rendered. */
 export declare const MAX_UPSTREAM_DEPS = 5;
 /** Characters of each dependency's summary carried in the seed — the gist, not the document. */
 export declare const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export declare const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export declare const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export declare const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
-export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats"];
+export declare const STEP_TASK_FIELDS: readonly ["name", "question", "description", "context", "constraints", "acceptance_criteria", "caveats", "grounding"];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
  * threaded separately through the workflow input, execution knobs, and result
@@ -41,7 +47,7 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * {@link renderResources} section, because the budget is an execution bound,
  * not a task instruction.
  */
-export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages"];
+export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages", "capability"];
 /**
  * The step's own instructions. Only `question` is guaranteed present; the
  * remaining task fields are appended as dedicated sections when populated, so a
@@ -50,7 +56,7 @@ export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type",
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export declare function renderTask(step: AnalysisStep): string;
+export declare function renderTask(step: AnalysisStep, contract?: Pick<StepBriefing, "template" | "templateNotRetrieved">): string;
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
  * prompt names this same text, thus a test pins the two together.
@@ -75,6 +81,46 @@ export declare function emptyStepMemory(): StepMemory;
  * entry — it has no memory tool.
  */
 export declare function renderMemory(memory: StepMemory): string;
+/** A file the script of the template reads. `path` names the slot that gives it, for example `{{counts_path}}`. */
+export interface TemplateBriefInput {
+    readonly name: string;
+    readonly path: string;
+    readonly description?: string;
+}
+/** One plan setting bound to an adaptable slot of the template. */
+export interface TemplateBoundSetting {
+    readonly name: string;
+    readonly value: TemplateBindingValue;
+    /** The source of the value (a doi or a document), or `plan` when the procedure names none. */
+    readonly source: string;
+}
+/**
+ * The contract of the template a step renders, projected for the seed. The
+ * parent fetches it at dispatch and binds the plan settings to it; the
+ * section is what lets an agent that has never seen the template make one
+ * valid render call.
+ */
+export interface TemplateBrief {
+    /** The template reference of the plan step, with its version when the plan names one. */
+    readonly ref: string;
+    /** The version the service serves. Differs from the version of `ref` when the snapshot moved on. */
+    readonly version_served: string;
+    /** The adaptable slots of the contract, in the order the template declares them. A pinned slot is never rendered. */
+    readonly slots: readonly TemplateParameter[];
+    readonly inputs: readonly TemplateBriefInput[];
+    /** The plan settings bound to a slot, in plan order. Empty when the served version differs from the plan. */
+    readonly bound: readonly TemplateBoundSetting[];
+    /** The plan settings no bound slot carries, one line each with the reason. */
+    readonly unbound_settings: readonly string[];
+}
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export declare function renderTemplateContract(brief: TemplateBrief | undefined): string;
 /**
  * What anchors every path the agent writes or reads: the id the tree is mounted
  * at, and the step's writable directory.
@@ -136,6 +182,14 @@ export interface StepBriefing {
     readonly upstream: readonly UpstreamHandoff[];
     /** The goal and the constraints of the analysis, read from the working memory at dispatch. */
     readonly memory: StepMemory;
+    /** The contract of the template the step renders, with the plan settings bound to it. Absent when none was retrieved. */
+    readonly template?: TemplateBrief;
+    /**
+     * Why the seed carries no template contract for a step whose grounding
+     * names one: no client is bound, the service did not answer, or the
+     * service does not hold the template. Read only when `template` is absent.
+     */
+    readonly templateNotRetrieved?: string;
 }
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step

package/dist/prompts/briefing.js

@@ -30,6 +30,10 @@ export const MAX_UPSTREAM_DEPS = 5;
 export const UPSTREAM_SUMMARY_MAX_CHARS = 500;
 /** Artifact paths listed per dependency; the rest are reachable from its output directory. */
 export const MAX_UPSTREAM_ARTIFACTS = 8;
+/** Adaptable slots rendered in the Template contract section; the tail is counted, not rendered. */
+export const MAX_TEMPLATE_SLOTS = 24;
+/** Characters of one slot description carried in the seed — the constraint, not the manual. */
+export const TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS = 160;
 // ── Field partition (the coverage guard's two halves) ─────────────────
 /** Fields whose content is agent-facing and MUST appear in the rendered task. */
 export const STEP_TASK_FIELDS = [
@@ -40,6 +44,9 @@ export const STEP_TASK_FIELDS = [
     "constraints",
     "acceptance_criteria",
     "caveats",
+    // The step agent reads the template id and the claim identifiers from the
+    // step, not from prose: the grounding renders beside the task fields.
+    "grounding",
 ];
 /**
  * Fields deliberately excluded from the task section: identity/DAG structure
@@ -70,6 +77,11 @@ export const STEP_NON_TASK_FIELDS = [
     // the agent does need to know about them — a dropped entry, or a step that
     // declares none — rides in `caveats`.
     "packages",
+    // Withheld for the same reason as `packages`, one layer up: the phrase is how the router and
+    // the planner name what they routed on, and the launch has already resolved the reference data
+    // it declares. The step agent learns the work from its skill pack, which names each dataset by
+    // what it is. Handing it a routing phrase would invite it to treat that phrase as the method.
+    "capability",
 ];
 // ── Formatting primitives ─────────────────────────────────────────────
 function section(heading, body) {
@@ -95,7 +107,7 @@ function clamp(text, max) {
  * folded in here — otherwise the agent runs against the bare question and
  * improvises the rest.
  */
-export function renderTask(step) {
+export function renderTask(step, contract = {}) {
     const parts = [`# ${step.name}`, section("Task", step.question)];
     if (step.description?.trim()) {
         parts.push(section("What this step produces", step.description.trim()));
@@ -112,8 +124,46 @@ export function renderTask(step) {
     if (step.caveats && step.caveats.length > 0) {
         parts.push(section("Caveats", bullets(step.caveats)));
     }
+    if (step.grounding) {
+        parts.push(section("Grounding", renderGrounding(step.grounding, contract)));
+    }
     return parts.join("\n\n");
 }
+/**
+ * The grounding as data lines. The template id is the one value the agent
+ * acts on (it names it to `knowledge_template`), thus it renders first after
+ * the status. The claim identifiers and the digest are for the record.
+ *
+ * A grounding that names a template promises a Template contract section.
+ * When the seed carries none, one line says so with the reason, thus the
+ * agent knows the contract was not fetched rather than guessing at slots.
+ *
+ * The settings of the procedure ride here as vetted values, not as
+ * constraints: the agent uses each one unless the data gives a reason for
+ * another value, and then it states the reason. They render only when the
+ * seed carries no template contract, because the bound and the unbound
+ * lists of the contract hold every setting already.
+ */
+function renderGrounding(grounding, contract) {
+    const lines = [`- Status: ${grounding.status}`];
+    if (grounding.template) {
+        lines.push(`- Template: \`${grounding.template}\``);
+        if (!contract.template)
+            lines.push(`- Template contract: not retrieved (${contract.templateNotRetrieved ?? "no contract was fetched for this step"})`);
+    }
+    lines.push(`- Snapshot: ${grounding.snapshot}`);
+    lines.push(`- Claims: ${grounding.claims.length > 0 ? grounding.claims.join(", ") : "none"}`);
+    lines.push(`- Reason: ${grounding.reason}`);
+    const settings = grounding.settings ?? [];
+    if (settings.length > 0 && !contract.template) {
+        lines.push("- Settings (the vetted values of the procedure; another value is permitted when your summary states the reason):");
+        for (const setting of settings) {
+            const value = Array.isArray(setting.value) ? setting.value.join(", ") : String(setting.value);
+            lines.push(`  - ${setting.step}: ${setting.name} = ${value}${setting.source ? ` (${setting.source})` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
 // ── (1b) Analysis memory ──────────────────────────────────────────────
 /**
  * The heading of the analysis-memory section. The orient core of the sandbox
@@ -155,6 +205,82 @@ export function renderMemory(memory) {
     }
     return section(ANALYSIS_MEMORY_HEADING, parts.join("\n\n"));
 }
+/** A value as the render request carries it: JSON, thus `"apeglm"` and `10` cannot be confused. */
+function slotValue(value) {
+    return JSON.stringify(value);
+}
+/** The version of a template reference (`tpl-x@1.0.0` gives `1.0.0`), or `undefined` when the reference has none. */
+function versionOfRef(ref) {
+    const at = ref.indexOf("@");
+    return at < 0 ? undefined : ref.slice(at + 1);
+}
+/**
+ * One adaptable slot as a bullet: the name, the type, the default with its
+ * source or the required state, the description, and the constraints the
+ * render enforces. A slot without a default is required unless the contract
+ * says otherwise, which is the rule of the renderer.
+ */
+function renderSlot(slot) {
+    const facts = [slot.type];
+    // A local slot is bound on this machine: the agent sends it as any other slot, and the value never leaves.
+    if (slot.local)
+        facts.push("local");
+    if (slot.default !== undefined) {
+        facts.push(`default ${slotValue(slot.default)}${slot.default_source ? ` [${slot.default_source}]` : ""}`);
+    }
+    else {
+        facts.push(slot.required === false ? "optional" : "required");
+    }
+    if (slot.minimum !== undefined)
+        facts.push(`min ${slot.minimum}`);
+    if (slot.maximum !== undefined)
+        facts.push(`max ${slot.maximum}`);
+    const tail = [];
+    if (slot.enum && slot.enum.length > 0)
+        tail.push(`Permitted: ${slot.enum.map(slotValue).join(", ")}.`);
+    if (slot.pattern)
+        tail.push(`Pattern: \`${slot.pattern}\`.`);
+    const description = clamp(slot.description.trim(), TEMPLATE_SLOT_DESCRIPTION_MAX_CHARS);
+    return `\`${slot.name}\` (${facts.join("; ")})${description ? `: ${description}` : ""}${tail.length > 0 ? ` ${tail.join(" ")}` : ""}`;
+}
+/**
+ * The Template contract section. Only the adaptable slots render, bounded by
+ * {@link MAX_TEMPLATE_SLOTS} and the description clamp, so a wide template
+ * cannot blow the seed. A served version that differs from the plan renders
+ * as a caveat: the render refuses the plan version, and the settings are not
+ * bound to a version the plan did not name.
+ */
+export function renderTemplateContract(brief) {
+    if (!brief)
+        return "";
+    const refVersion = versionOfRef(brief.ref);
+    const lead = [
+        `\`${brief.ref}\` (the service serves version ${brief.version_served}). Send only the slots listed here to \`knowledge_template\`; a slot not listed is pinned or unknown, and the render refuses it.`,
+    ];
+    if (refVersion !== undefined && refVersion !== brief.version_served) {
+        lead.push(`Caveat: the plan names version ${refVersion}, and the service serves version ${brief.version_served}. The plan settings are not bound to this render. Render the served version, and state each plan value yourself.`);
+    }
+    const blocks = [lead.join("\n")];
+    const adaptable = brief.slots.filter((slot) => slot.adaptable);
+    if (adaptable.length > 0) {
+        const shown = adaptable.slice(0, MAX_TEMPLATE_SLOTS);
+        const lines = [bullets(shown.map(renderSlot))];
+        const omitted = adaptable.length - shown.length;
+        if (omitted > 0)
+            lines.push(`(+${omitted} more adaptable ${omitted === 1 ? "slot" : "slots"} not listed. The render answer names a required one that is absent.)`);
+        blocks.push(`Slots:\n${lines.join("\n")}`);
+    }
+    if (brief.inputs.length > 0) {
+        blocks.push(`Inputs the script reads:\n${bullets(brief.inputs.map((input) => `${input.name}: \`${input.path}\`${input.description ? ` — ${input.description}` : ""}`))}`);
+    }
+    if (brief.bound.length > 0) {
+        blocks.push(`Bound by the plan (send each value as it is, or add an \`overrides\` entry with the slot and the reason for the change; a changed value without an override is refused):\n${bullets(brief.bound.map((setting) => `\`${setting.name}\` = ${slotValue(setting.value)} (${setting.source})`))}`);
+    }
+    if (brief.unbound_settings.length > 0) {
+        blocks.push(`Unbound settings (the plan states them, and no bound slot carries them):\n${bullets(brief.unbound_settings)}`);
+    }
+    return section("Template contract", blocks.join("\n\n"));
+}
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export function analysisRootOf(frame) {
     return `/${frame.analysisId}`;
@@ -240,7 +366,8 @@ function renderHandoff(handoff) {
  */
 export function composeStepBriefing(briefing) {
     return [
-        renderTask(briefing.step),
+        renderTask(briefing.step, briefing),
+        renderTemplateContract(briefing.template),
         renderMemory(briefing.memory),
         renderWorkspace(briefing.workspace),
         renderResources(briefing.step.resources),

package/dist/prompts/planner.js

@@ -120,7 +120,8 @@ leaves open:
 - An inventory block that reports a failed lookup. Absence in it proves
   nothing, so read that inventory through its tool.
 - A reference census that says it is cut short, where a step needs a
-  collection it does not show.
+  collection it does not show. A bounded listing is not evidence of absence,
+  so confirm through the tool before you call that data missing.
 - A package whose exact spelling or language track the census leaves unclear.
 
 Batch the lookups. \`names\` takes every package you are unsure of in one call,
@@ -212,10 +213,18 @@ ${agentCatalog}
 ### Routing Rules
 - Route by primary data object: if the step works on a count matrix, assign
   the transcriptomics agent; if on a gene list, assign the enrichment agent.
+- A gene list does not settle the assignment by itself. Read what the step
+  asks of the list. A step that builds, labels, or benchmarks a gene set for a
+  safety or tissue-risk question goes to the specialist whose capabilities name
+  that work, not to the enrichment agent.
 - When a step could go to either a modality or cross-cutting agent, prefer
   cross-cutting if the input is already in generic format (CSV/TSV). Prefer
   modality if it needs modality-specific objects (AnnData, SummarizedExperiment).
 - If no agent is an exact fit, pick the closest specialist from the list.
+- Name the capability you routed on. Copy one phrase out of that agent's
+  capabilities into the step's \`capability\` field, spelled exactly as the
+  catalog spells it. The launch resolves what reference data that capability
+  needs before the run starts, so a paraphrase costs the step that check.
 
 ## Grounding
 
@@ -287,7 +296,9 @@ safety, toxicity, or treatment outcomes:
 5. **Route safety data correctly.** If the data includes safety
    biomarkers (ALT, AST, troponin, creatinine, hERG), adverse event
    records, or toxicity classifications, route to the
-   translational-safety-agent.
+   translational-safety-agent. Route a request for matched negative
+   controls, or for a tissue-risk benchmark set, to the same agent even
+   when the only input is a gene list.
 
 6. **Route immune profiling correctly.** If the research question
    involves immune cell composition, tumor microenvironment

package/dist/provenance/seam.d.ts

@@ -8,14 +8,16 @@
  *
  * One surface carries the three, and each member is optional alone. Thus a composition binds the members
  * that it records, and the harness reads an absent member as absence and never as an error. The run emit
- * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
- * its credential. A session act carries no session, thus the session emit takes the event alone.
+ * takes an `AgentSession`, because a persisting realization needs the credential of the actor. The
+ * workflow body passes the `RunSession` of its durable input, and the run canceler passes the session of
+ * the cancel. A session act carries no session, thus the session emit takes the event alone.
  *
- * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
- * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
- * happened.
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. The writer
+ * that wins the conditional terminal write of the run row emits `run_completed`. The body emits it before
+ * its status write commits, or after a refused or failed write. The canceler emits it only when its write
+ * changes the row, thus a refused cancel emits nothing.
  */
-import type { RunSession } from "../auth/types.js";
+import type { AgentSession } from "../auth/types.js";
 import type { Logger } from "../lib/logger.js";
 import type { ProvenanceExport } from "../report-render/provenance-data.js";
 import type { AuthoringBlock } from "../report-model/authoring-grammar.js";
@@ -26,14 +28,19 @@ export type { ProvenanceExport } from "../report-render/provenance-data.js";
  * Harness-owned plain union — the harness stays tsprov-free and bus-free; the
  * host maps these execution facts onto its own ledger vocabulary.
  *
- * Every `atMs` is epoch milliseconds read via `await DBOS.now()`, a checkpointed
- * step: a body re-executed by DBOS recovery reads the recorded value, so a
+ * In the workflow body, every `atMs` is epoch milliseconds read via `await DBOS.now()`, a
+ * checkpointed step: a body re-executed by DBOS recovery reads the recorded value, so a
  * re-emitted event carries the identical timestamp and merges on the host's
- * ledger without a value conflict. Never source these from a wall clock
+ * ledger without a value conflict. The body never sources these from a wall clock
  * (`Date.now()`) — that would diverge across replays and defeat the merge.
  *
- * `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
- * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span.
+ * The run canceler is the second emit site of `step_completed` and `run_completed`, and it emits only
+ * when its write of the run row changes the row. It is not a workflow, thus no replay fires its emits,
+ * and it reads the wall clock one time for all of them.
+ *
+ * In the body, `run_completed.durationMs` is the terminal `atMs` minus the `run_started`
+ * `atMs` (both `DBOS.now()` reads) — the true workflow-observed run span. The canceler holds no
+ * `run_started` time, thus it measures from the `started_at` of the run row.
  *
  * `step_completed` fires once at EVERY scheduler-loop settlement — the only site
  * that observes every executed step (registration sees only artifact-producing
@@ -192,11 +199,12 @@ export type ProvenanceSeam = {
      * The run engine emits the facts of one run here.
      *
      * Synchronous by signature (`void`, never a promise): a host that needs input and output dispatches
-     * the work rather than making a workflow body wait behind it. The `RunSession` rides from the durable
-     * workflow input, because a persisting realization needs the credential, the scope, and the identity
-     * of the run. A realization can ignore the parameter.
+     * the work rather than making a workflow body wait behind it. The session rides beside the event,
+     * because a persisting realization needs the credential, the scope, and the identity of the actor.
+     * The body passes the `RunSession` of its durable workflow input. The run canceler passes the
+     * session of the cancel, because it holds no `RunSession`. A realization can ignore the parameter.
      */
-    readonly emitRunEvent?: (event: RunProvenanceEvent, session: RunSession) => void;
+    readonly emitRunEvent?: (event: RunProvenanceEvent, session: AgentSession) => void;
     /**
      * A session emits one act here. A session act runs under no authorized run, thus this member takes
      * the event alone. It is synchronous by signature for the same reason as the run emit.

package/dist/provenance/seam.js

@@ -8,12 +8,14 @@
  *
  * One surface carries the three, and each member is optional alone. Thus a composition binds the members
  * that it records, and the harness reads an absent member as absence and never as an error. The run emit
- * takes the `RunSession` of the run, because a durable run carries one and a persisting realization needs
- * its credential. A session act carries no session, thus the session emit takes the event alone.
+ * takes an `AgentSession`, because a persisting realization needs the credential of the actor. The
+ * workflow body passes the `RunSession` of its durable input, and the run canceler passes the session of
+ * the cancel. A session act carries no session, thus the session emit takes the event alone.
  *
- * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. A site emits
- * after its act lands, thus a refused act and a failed act each emit nothing and the record states what
- * happened.
+ * Both emit members are fire-and-forget. Neither gives a result, and the harness reads none. The writer
+ * that wins the conditional terminal write of the run row emits `run_completed`. The body emits it before
+ * its status write commits, or after a refused or failed write. The canceler emits it only when its write
+ * changes the row, thus a refused cancel emits nothing.
  */
 /**
  * Bind the optional session emit and the logger of one site into a total emit.

package/dist/providers/ai-sdk.js

@@ -97,6 +97,46 @@ function thinkingWithBinding(reasoning, mode) {
         return { blockBinding };
     return { type: "adaptive", display: "summarized", blockBinding };
 }
+/**
+ * The model that answered after a server-side fallback hop, `""` when the hop is
+ * reported without one, and `undefined` when no hop happened.
+ *
+ * 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. This reader
+ * is what lets {@link settleFallbackReply} see the hop the content no longer shows.
+ */
+function fallbackModelOf(metadata) {
+    const entries = metadata?.["anthropic"]?.["iterations"];
+    if (!Array.isArray(entries))
+        return undefined;
+    for (const entry of entries) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const fields = entry;
+        if (fields["type"] !== "fallback_message")
+            continue;
+        return typeof fields["model"] === "string" ? fields["model"] : "";
+    }
+    return undefined;
+}
+/**
+ * The assistant message with no thinking block, and with `""` for content when it held
+ * nothing else. An empty message reaches no wire: `sanitizeMessages` drops it.
+ */
+function withoutThinking(message) {
+    if (typeof message.content === "string")
+        return message;
+    const content = message.content.filter((part) => part.type !== "reasoning" && part.type !== "reasoning-file");
+    if (content.length === message.content.length)
+        return message;
+    return content.length === 0 ? { ...message, content: "" } : { ...message, content };
+}
 /** Reads `providerMetadata.anthropic.inputTransformations`; empty for another vendor. */
 function inputTransformationsOf(metadata) {
     const entries = metadata?.["anthropic"]?.["inputTransformations"];
@@ -476,6 +516,7 @@ export function createAiSdkProvider(deps) {
         // wire that carries no picture there.
         ...(deps.capabilities?.imageToolResults !== undefined ? { imageToolResults: deps.capabilities.imageToolResults } : {}),
         ...(deps.capabilities?.imageUserMessages !== undefined ? { imageUserMessages: deps.capabilities.imageUserMessages } : {}),
+        ...(deps.capabilities?.contextWindow !== undefined ? { contextWindow: deps.capabilities.contextWindow } : {}),
     };
     const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     const maxOutputTokens = deps.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
@@ -524,6 +565,44 @@ export function createAiSdkProvider(deps) {
             logger.warn("thinking block dropped", { workload: workloadOf(session), type: drop.type, path: drop.path, reason: drop.reason });
         }
     }
+    /**
+     * The reply as the harness must hold it when a fallback model served it: with no
+     * thinking block, and with the model that answered named.
+     *
+     * A reply that carries a fallback hop ({@link fallbackModelOf}) reaches the harness
+     * already short of the `fallback` content block the API put in the turn. 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. The conversation is then dead: the loop sends
+     * its history on every request, and nothing downstream can repair a turn.
+     *
+     * A thinking block is optional on the way back, thus the reply without them is a valid
+     * turn, 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 reply of nothing but thinking carries
+     * no part at all, and `sanitizeMessages` drops such a message from the next request.
+     *
+     * `servedModelId` needs the same correction. {@link captureServedModelId} reads the id
+     * the response metadata of the package carries, which is `message_start.message.model`,
+     * and that field keeps the REQUESTED model across a hop. Published as it stands, it
+     * makes the usage ledger of an embedder attribute the tokens to the model that refused
+     * the work. The iteration names the model that answered, thus it wins. An iteration that
+     * names no model changes nothing: there is no better id to publish, and the record above
+     * is then the only account of the hop.
+     */
+    function settleFallbackReply(session, response, metadata) {
+        const servedBy = fallbackModelOf(metadata);
+        if (servedBy === undefined)
+            return response;
+        logger.warn("reply served by a fallback model, thus the harness drops the thinking of that turn", {
+            workload: workloadOf(session),
+            ...(servedBy === "" ? {} : { servedBy }),
+        });
+        return {
+            ...response,
+            message: withoutThinking(response.message),
+            ...(servedBy === "" ? {} : { servedModelId: servedBy }),
+        };
+    }
     function chat(req, session, signal) {
         const reasoning = effortOf(req);
         const providerOptions = deps.providerOptionsFor?.({ session, reasoning });
@@ -602,14 +681,14 @@ export function createAiSdkProvider(deps) {
                 // reports its drops.
                 const { providerMetadata: metadata, ...reply } = collected;
                 logDroppedThinkingBlocks(session, metadata);
-                return ok(responseFromMessages({
+                return ok(settleFallbackReply(session, responseFromMessages({
                     ...reply,
                     requestedModelId,
                     // Read after the drain: the metadata chunk that carries the
                     // served id reaches the capture only as the stream is consumed.
                     servedModelId: capture.servedModelId(),
                     provider: providerId,
-                }));
+                }), metadata));
             }
             catch (e) {
                 if (isAbortError(e) || signal?.aborted || hookCall.unsettled)
@@ -692,7 +771,7 @@ export function createAiSdkProvider(deps) {
             });
             if (opened.kind === "completed") {
                 logDroppedThinkingBlocks(session, opened.providerMetadata);
-                const response = responseFromMessages({
+                const response = settleFallbackReply(session, responseFromMessages({
                     messages: opened.messages,
                     fallbackText: "",
                     finishReason: opened.finishReason,
@@ -701,7 +780,7 @@ export function createAiSdkProvider(deps) {
                     requestedModelId,
                     servedModelId: capture.servedModelId(),
                     provider: providerId,
-                });
+                }), opened.providerMetadata);
                 yield { type: "done", response };
                 return;
             }
@@ -721,7 +800,8 @@ export function createAiSdkProvider(deps) {
                 text += pull.text;
                 yield { type: "text-delta", text: pull.text };
             }
-            const response = responseFromMessages({
+            const metadata = (await result.finalStep).providerMetadata;
+            const response = settleFallbackReply(session, responseFromMessages({
                 messages: await result.responseMessages,
                 fallbackText: text,
                 finishReason: await result.finishReason,
@@ -732,8 +812,8 @@ export function createAiSdkProvider(deps) {
                 // reaches the capture only as the stream is consumed.
                 servedModelId: capture.servedModelId(),
                 provider: providerId,
-            });
-            logDroppedThinkingBlocks(session, (await result.finalStep).providerMetadata);
+            }), metadata);
+            logDroppedThinkingBlocks(session, metadata);
             yield { type: "done", response };
         }
         catch (e) {

package/dist/providers/types.d.ts

@@ -31,6 +31,12 @@ export interface ProviderCapabilities {
      * "unknown".
      */
     readonly imageUserMessages?: boolean;
+    /**
+     * The context window of the model in tokens, when the host knows it. A chat
+     * thread then compacts at 80% of the window at the latest. Absent means "at
+     * least the compaction budget of the agent", thus the budget stays as declared.
+     */
+    readonly contextWindow?: number;
 }
 /**
  * The request carries no free-form provider options. That would let a caller