@inflexa-ai/harness 0.19.0 → 0.19.1

package/dist/loop/run-agent.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { jsonSchema, tool as aiTool } from "ai";
+import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -9,7 +9,7 @@ import { classifyProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
-import { isToolError } from "../tools/define-tool.js";
+import { isToolError, readToolResultImage } from "../tools/define-tool.js";
 import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { computeDetail } from "./tool-detail.js";
 import { toolOutcomeForOutputType } from "./tool-outcome.js";
@@ -40,6 +40,10 @@ export async function runAgent(agent, initial, session, opts) {
     // `callPath` rides as an array rather than a joined string — the queryable form;
     // rendering `parent > child` is the sink's choice, not a published package's.
     const log = (opts.logger ?? createNoopLogger()).named("loop").with({ agentId: source.agentId, callPath: source.callPath });
+    // The picture of a tool result rides where the wire renders it. Absent flags
+    // mean "cannot carry", thus the loop degrades to text and records the drop.
+    // The collector belongs to this run, thus two loops never share one.
+    const encoding = { placement: imagePlacementFor(provider.capabilities), deferredImages: [], log };
     const toolsById = new Map(agent.tools.map((t) => [t.id, t]));
     const toolDefs = Object.fromEntries(agent.tools.map((t) => [
         t.id,
@@ -238,7 +242,7 @@ export async function runAgent(agent, initial, session, opts) {
             for (const [idx, tu] of earlier.entries()) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
             }
-            const { results, durations } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+            const { results, durations } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
             const errored = await settleRound(earlier, results, earlierDetails, durations);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             // The trailing call was never dispatched, but it reaches the model as an error
@@ -250,6 +254,7 @@ export async function runAgent(agent, initial, session, opts) {
             errored.push(trailing.toolName);
             log.debug("tool results returned errors", { iteration: i, tools: errored });
             messages.push({ role: "tool", content: results });
+            appendDeferredImages(messages, results, encoding.deferredImages);
             if (hasDenial(results))
                 return stopOnDenial(i);
             if (opts.resolved?.())
@@ -268,11 +273,12 @@ export async function runAgent(agent, initial, session, opts) {
         for (const [idx, tu] of toolCalls.entries()) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
         }
-        const { results, durations } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+        const { results, durations } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
         const errored = await settleRound(toolCalls, results, details, durations);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
+        appendDeferredImages(messages, results, encoding.deferredImages);
         if (hasDenial(results))
             return stopOnDenial(i);
         if (opts.resolved?.())
@@ -385,6 +391,50 @@ function markLastLoopAssistant(messages, initialCount) {
         }
     }
 }
+/**
+ * Where a tool picture goes for this wire. The tool result wins, because it is
+ * the native place and the correlation to the tool call stays implicit. The user
+ * message is the fallback. When the wire renders neither, the loop drops the
+ * picture.
+ */
+function imagePlacementFor(capabilities) {
+    if (capabilities.imageToolResults === true)
+        return "tool-result";
+    if (capabilities.imageUserMessages === true)
+        return "user-message";
+    return "drop";
+}
+/**
+ * Append one user message that carries each deferred picture of the round, then
+ * empty the collector.
+ *
+ * The tool message must come directly after the assistant message with the
+ * tool calls. Thus a picture rides a separate message after the whole tool
+ * message, and one message batches the round. The parts obey the order of
+ * `results`, which is the order of the tool calls. Each deferred picture has a
+ * result of this round, because the collector fills during the dispatch and it
+ * empties here. A text part names the tool call of each picture, because the wire
+ * holds no structural link between a user message and a tool call.
+ *
+ * The message carries the synthetic marker, because a `user` message opens a
+ * conversation turn. An unmarked one is loop machinery that reads as a turn
+ * boundary, and it splits one stored turn in two.
+ */
+function appendDeferredImages(messages, results, deferredImages) {
+    if (deferredImages.length === 0)
+        return;
+    const byToolCallId = new Map(deferredImages.map((deferred) => [deferred.toolCallId, deferred]));
+    const content = [];
+    for (const result of results) {
+        const deferred = byToolCallId.get(result.toolCallId);
+        if (deferred === undefined)
+            continue;
+        content.push({ type: "text", text: `The picture of the tool result ${deferred.toolCallId} of ${deferred.toolName}.` });
+        content.push({ type: "file", mediaType: deferred.image.mediaType, data: { type: "data", data: deferred.image.base64 } });
+    }
+    messages.push(syntheticUserMessage(content));
+    deferredImages.length = 0;
+}
 /**
  * Dispatch one round of tool calls, and measure the time of each call.
  *
@@ -395,7 +445,7 @@ function markLastLoopAssistant(messages, initialCount) {
  * wrapper. The wrapper is part of what the call cost, and a cached replay of a step
  * is genuinely fast. A bracket inside the step would report a body that did not run.
  */
-async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName) {
+async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName, encoding) {
     const results = new Array(toolUses.length);
     // The array starts with holes, which read as `undefined`. The element type
     // says so, thus it agrees with what `settleRound` accepts. Every index is in
@@ -415,19 +465,19 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
         const startedAt = performance.now();
-        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError)).then((r) => {
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding)).then((r) => {
             durations[idx] = elapsedMs(startedAt);
             results[idx] = r;
         });
     }));
     for (const { tu, idx } of workflowTools) {
         const startedAt = performance.now();
-        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
         durations[idx] = elapsedMs(startedAt);
     }
     for (const { tu, idx } of inlineTools) {
         const startedAt = performance.now();
-        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
         durations[idx] = elapsedMs(startedAt);
     }
     return { results, durations };
@@ -436,14 +486,14 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
 function elapsedMs(startedAt) {
     return Math.round(performance.now() - startedAt);
 }
-async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
+async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const tool = toolsById.get(tu.toolName);
     if (tool === undefined) {
         return errorResult(tu, `unknown tool: ${tu.toolName}`);
     }
     const parsed = tool.inputSchema.safeParse(tu.input);
     if (parsed.success)
-        return execute(tu, tool, parsed.data, ctx, isFatalLoopError);
+        return execute(tu, tool, parsed.data, ctx, isFatalLoopError, encoding);
     // A complete JSON argument can arrive as a string behind function-call
     // markup or a code fence. Repair only makes the schema reachable — the
     // repaired value is validated in full, and the tool's own semantic checks
@@ -451,15 +501,15 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
     const repairedInput = repairToolInput(tu.input, parsed.error);
     const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
     if (repaired?.success === true)
-        return execute(tu, tool, repaired.data, ctx, isFatalLoopError);
+        return execute(tu, tool, repaired.data, ctx, isFatalLoopError, encoding);
     return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`);
 }
-async function execute(tu, tool, input, ctx, isFatalLoopError) {
+async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
     try {
         const output = await tool.execute(input, ctx);
         if (output.isErr())
             return errorResult(tu, toolErrorContent(output.error));
-        return successResult(tu, output.value);
+        return successResult(tu, output.value, encoding);
     }
     catch (err) {
         if (isFatalLoopError(err))
@@ -478,12 +528,51 @@ async function execute(tu, tool, input, ctx, isFatalLoopError) {
 function jsonValue(value) {
     return JSON.parse(JSON.stringify(value ?? null), (_key, v) => (typeof v === "string" ? stripNulCharacters(v) : v));
 }
-function successResult(toolCall, value) {
+/**
+ * Encode a tool ok value onto a tool-result message. A value with no picture
+ * stays a plain JSON result, byte-identical to a value that never carried one.
+ *
+ * A value that carries a picture splits: the JSON data goes to a text part, and
+ * the bytes ride as an image content block. Thus the model sees the picture, and
+ * the JSON text holds no bytes. When the wire carries no picture, the block drops
+ * and the text stays, because base64 text floods the context and the model cannot
+ * see it. The drop rides the log, thus an operator sees that the picture did not
+ * reach the model.
+ *
+ * A wire that renders a picture on a user message only gets the fallback: the
+ * result keeps its JSON text, and the picture goes to the collector of the round.
+ * The round then sends the bytes after the tool message.
+ */
+function successResult(toolCall, value, encoding) {
+    const jsonData = jsonValue(value);
+    const jsonOnly = {
+        type: "tool-result",
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        output: { type: "json", value: jsonData },
+    };
+    const image = readToolResultImage(value);
+    if (image === undefined)
+        return jsonOnly;
+    if (encoding.placement === "drop") {
+        encoding.log.warn("the wired provider carries no picture in a tool result, thus the picture is dropped", { toolName: toolCall.toolName });
+        return jsonOnly;
+    }
+    if (encoding.placement === "user-message") {
+        encoding.deferredImages.push({ toolCallId: toolCall.toolCallId, toolName: toolCall.toolName, image });
+        return jsonOnly;
+    }
     return {
         type: "tool-result",
         toolCallId: toolCall.toolCallId,
         toolName: toolCall.toolName,
-        output: { type: "json", value: jsonValue(value) },
+        output: {
+            type: "content",
+            value: [
+                { type: "text", text: JSON.stringify(jsonData) },
+                { type: "file", mediaType: image.mediaType, data: { type: "data", data: image.base64 } },
+            ],
+        },
     };
 }
 // NUL is stripped from the prose BEFORE it is serialized: past the stringify it

package/dist/memory/ai-sdk-message-storage.d.ts

@@ -1,4 +1,4 @@
-import { type ModelMessage } from "ai";
+import { type ModelMessage, type UserContent } from "ai";
 import { z } from "zod";
 export declare const SUPPORTED_AI_SDK_MAJOR = 7;
 export declare const StoredMessageEnvelopeSchema: z.ZodObject<{
@@ -50,8 +50,9 @@ export declare function markInterruptedMessage(message: ModelMessage): ModelMess
 /** Whether a client abort cut off this message's production (see {@link markInterruptedMessage}); an absent key reads as not interrupted. */
 export declare function isInterruptedMessage(message: ModelMessage): boolean;
 /**
- * Build a `user` message the LOOP synthesized rather than a human typing it — today, the nudge that
- * continues a reply the model truncated at its output-token limit.
+ * Build a `user` message the LOOP synthesized rather than a human typing it — the nudge that
+ * continues a reply the model truncated at its output-token limit, and the message that carries a
+ * tool picture that the tool result cannot carry.
  *
  * It has to carry the `user` role because the wire format requires a user turn after a truncated
  * assistant message, but it is not user input, and the difference is load-bearing: a `user` message is
@@ -59,11 +60,15 @@ export declare function isInterruptedMessage(message: ModelMessage): boolean;
  * splitting one turn into two for the token window and, worse, giving a tail-turn removal a cut point in
  * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
  *
+ * `content` takes prose or the parts of a user message, because a picture rides a file part and no
+ * string can carry one. The marker is the same either way: what makes a message synthetic is who wrote
+ * it, not what it holds.
+ *
  * This one is loop MACHINERY and is not rendered: showing it would put words on screen nobody typed.
  * An embedder recording out-of-band work — an analysis run's outcome — wants
  * {@link syntheticRecordMessage} instead, which is equally non-turn-opening but IS displayed.
  */
-export declare function syntheticUserMessage(text: string): ModelMessage;
+export declare function syntheticUserMessage(content: UserContent): ModelMessage;
 /**
  * Build a record of out-of-band work for an embedder to append between turns — an analysis run's
  * outcome, which the model should read on its next turn but which nobody said.

package/dist/memory/ai-sdk-message-storage.js

@@ -73,8 +73,9 @@ export function isInterruptedMessage(message) {
     return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[INTERRUPTED_MESSAGE_KEY] === true;
 }
 /**
- * Build a `user` message the LOOP synthesized rather than a human typing it — today, the nudge that
- * continues a reply the model truncated at its output-token limit.
+ * Build a `user` message the LOOP synthesized rather than a human typing it — the nudge that
+ * continues a reply the model truncated at its output-token limit, and the message that carries a
+ * tool picture that the tool result cannot carry.
  *
  * It has to carry the `user` role because the wire format requires a user turn after a truncated
  * assistant message, but it is not user input, and the difference is load-bearing: a `user` message is
@@ -82,14 +83,18 @@ export function isInterruptedMessage(message) {
  * splitting one turn into two for the token window and, worse, giving a tail-turn removal a cut point in
  * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
  *
+ * `content` takes prose or the parts of a user message, because a picture rides a file part and no
+ * string can carry one. The marker is the same either way: what makes a message synthetic is who wrote
+ * it, not what it holds.
+ *
  * This one is loop MACHINERY and is not rendered: showing it would put words on screen nobody typed.
  * An embedder recording out-of-band work — an analysis run's outcome — wants
  * {@link syntheticRecordMessage} instead, which is equally non-turn-opening but IS displayed.
  */
-export function syntheticUserMessage(text) {
+export function syntheticUserMessage(content) {
     return {
         role: "user",
-        content: text,
+        content,
         providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true } },
     };
 }

package/dist/memory/count-tokens.js

@@ -17,10 +17,39 @@ function enc() {
     return encoder;
 }
 /**
- * The token-bearing text of one content block. Text-carrying fields are
- * extracted directly; structural blocks (`tool_use` input, `tool_result`
- * payload) are JSON-stringified. A signed `thinking` block counts only its
- * reasoning text — the opaque `signature` is metadata, not prompt tokens.
+ * The token-bearing text of one tool-result output.
+ *
+ * A `content` output holds the text parts and the attachments side by side. Only
+ * the text is prompt text. A file rides the wire as an attachment, and the
+ * provider bills it at its own rate, thus its bytes count as `0` — the same rule
+ * as a top-level `file` block. A file that is stringified into the count inflates
+ * the row of the message by tens of thousands of tokens, and the load window then
+ * drops the true history.
+ *
+ * Each other output arm is plain JSON, thus it is stringified whole.
+ */
+function toolResultText(output) {
+    if (typeof output !== "object" || output === null)
+        return JSON.stringify(output ?? {});
+    const out = output;
+    if (out.type !== "content" || !Array.isArray(out.value))
+        return JSON.stringify(out);
+    const texts = [];
+    for (const item of out.value) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const nested = item;
+        if (nested.type === "text" && typeof nested.text === "string")
+            texts.push(nested.text);
+    }
+    return texts.join(" ");
+}
+/**
+ * The token-bearing text of one content block. A text-carrying field is
+ * extracted directly. A `tool_use` input is JSON-stringified, and a
+ * `tool_result` output goes through {@link toolResultText}. A signed `thinking`
+ * block counts only its reasoning text, because the opaque `signature` is
+ * metadata and not prompt tokens.
  */
 function tokenizableText(block) {
     if (typeof block === "string")
@@ -40,7 +69,7 @@ function tokenizableText(block) {
         case "tool-call":
             return `${String(part.toolName ?? "")} ${JSON.stringify(part.input ?? {})}`;
         case "tool-result": {
-            return `${String(part.toolName ?? "")} ${JSON.stringify(part.output ?? {})}`;
+            return `${String(part.toolName ?? "")} ${toolResultText(part.output)}`;
         }
         default:
             return JSON.stringify(part);

package/dist/prompts/report-session.d.ts

@@ -1 +1 @@
-export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user, one block at a time, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, its\n  per-file types. Read it when you must state a fact about the data itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one section, or one atom inside a section. You choose the id,\n  and it is unique in the draft. A section holds atoms. An atom is one piece of\n  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a\n  claim. The block schema of `add_block` gives every kind and its fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nBuild the report as a shape first, then fill each section. Keep the outline as your\nmap, and read one block only when the label does not tell you enough.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap, or the finished document. Read\nthe gaps, repair the draft, and finish again.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Do NOT\n\n- **Transcribe a number from memory.** Every metric, every table cell, and every\n  figure binds to a reference that resolves against the pinned evidence.\n- **Start a run, or change the analysis.** You read the analysis; you never run it\n  and never write to it. You hold no tool that does either, and that is by design.\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot\n  of this session alone. Do not cite an artifact that the snapshot does not hold.\n- **Rebuild when one amend serves.** One feedback is one block change. Change, move,\n  or remove that block by its id, and do not re-author the report.\n- **Leave a gap unread.** When `finish_draft` or `preview_report` reports a gap or\n  an unresolved reference, repair it. Do not present a report that does not finish.\n";
+export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user, one block at a time, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, its\n  per-file types. Read it when you must state a fact about the data itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one section, or one atom inside a section. You choose the id,\n  and it is unique in the draft. A section holds atoms. An atom is one piece of\n  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a\n  claim. The block schema of `add_block` gives every kind and its fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nBuild the report as a shape first, then fill each section. Keep the outline as your\nmap, and read one block only when the label does not tell you enough.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap, or the finished document. Read\nthe gaps, repair the draft, and finish again.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page. The Preview section above\n  gives its rules.\n- `examine_page` opens the rendered page in a real browser. It gives back a\n  screenshot, the console errors, and the failed requests. Look at the page.\n- Repair each fault that the look shows. A broken layout, an absent chart, and a\n  failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version.\n\nLook again after each repair, because a repair changes the page. Record when the\npage reads clean.\n\n## Do NOT\n\n- **Transcribe a number from memory.** Every metric, every table cell, and every\n  figure binds to a reference that resolves against the pinned evidence.\n- **Start a run, or change the analysis.** You read the analysis; you never run it\n  and never write to it. You hold no tool that does either, and that is by design.\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot\n  of this session alone. Do not cite an artifact that the snapshot does not hold.\n- **Rebuild when one amend serves.** One feedback is one block change. Change, move,\n  or remove that block by its id, and do not re-author the report.\n- **Leave a gap unread.** When `finish_draft` or `preview_report` reports a gap or\n  an unresolved reference, repair it. Do not present a report that does not finish.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. Look one time, then repair a real fault: a broken layout, an\n  absent chart, or a failed request. A matter of taste is not a fault. When the page\n  reads clean, record.\n";

package/dist/prompts/report-session.js

@@ -72,6 +72,23 @@ the reference resolver is absent, tell the user, and do not preview again. Previ
 when the draft is ready to show, or when you want to confirm that each reference
 resolves.
 
+## Verify and Record
+
+The loop that ends a report is preview, look, repair, and record. Run it in order:
+
+- \`preview_report\` renders the current draft to a page. The Preview section above
+  gives its rules.
+- \`examine_page\` opens the rendered page in a real browser. It gives back a
+  screenshot, the console errors, and the failed requests. Look at the page.
+- Repair each fault that the look shows. A broken layout, an absent chart, and a
+  failed request each name a block or a binding that you repair.
+- \`record_report_version\` records the report as one version. It records only after
+  you look at the current page. It runs the whole gate first, thus a gap or an
+  unresolved reference comes back, and no version lands. A thread holds one version.
+
+Look again after each repair, because a repair changes the page. Record when the
+page reads clean.
+
 ## Do NOT
 
 - **Transcribe a number from memory.** Every metric, every table cell, and every
@@ -86,4 +103,8 @@ resolves.
   or remove that block by its id, and do not re-author the report.
 - **Leave a gap unread.** When \`finish_draft\` or \`preview_report\` reports a gap or
   an unresolved reference, repair it. Do not present a report that does not finish.
+- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries
+  with no fault to repair. Look one time, then repair a real fault: a broken layout, an
+  absent chart, or a failed request. A matter of taste is not a fault. When the page
+  reads clean, record.
 `;

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

@@ -23,6 +23,11 @@ export declare const RETRY_MAX_DELAY_MS = 30000;
  *
  * Lower it per-config for servers that validate `prompt + max_tokens <= context`
  * (vLLM and similar) against a small-context model.
+ *
+ * The openai arm takes no value from this default. `@ai-sdk/openai` clamps
+ * nothing per model, and it puts the number on the wire as it is. Thus a model
+ * whose own cap is smaller answers 400 on each call. That arm sends no ceiling,
+ * and the server then enforces the true cap of the model.
  */
 export declare const DEFAULT_MAX_OUTPUT_TOKENS = 64000;
 export interface AiSdkProviderDeps {
@@ -30,8 +35,14 @@ export interface AiSdkProviderDeps {
     readonly resolveBilling: ResolveBilling;
     readonly capabilities?: Partial<ProviderCapabilities>;
     readonly logger?: Logger;
-    /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
-    readonly maxOutputTokens?: number;
+    /**
+     * Output-token ceiling per request. Defaults to
+     * {@link DEFAULT_MAX_OUTPUT_TOKENS}. The value `"provider-maximum"` sends the
+     * SDK no ceiling, and the server then enforces the true cap of the model. Use
+     * the sentinel for a wire whose SDK puts the number on the request as it is,
+     * because a ceiling above the cap of the model fails the call.
+     */
+    readonly maxOutputTokens?: number | "provider-maximum";
     /** The retry limit of the harness envelope. Defaults to {@link RETRY_MAX_RETRIES}. */
     readonly maxRetries?: number;
     /**
@@ -45,7 +56,7 @@ export interface AiSdkProviderDeps {
 }
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
- * wire protocol (`anthropic` | `openai-compatible`). The `model` is the wire
+ * wire protocol (`anthropic` | `openai` | `openai-compatible`). The `model` is the wire
  * model bound into the provider at construction: `ChatRequest` carries no model
  * field (see `./types.ts`), so a config value describes exactly one model over
  * one connection. An embedder running distinct models builds one provider per
@@ -83,6 +94,73 @@ export type AiSdkProviderConfig = {
      * keeps the default of 10.
      */
     readonly maxRetries?: number;
+} | {
+    readonly kind: "openai";
+    readonly baseURL?: string;
+    readonly apiKey: string;
+    readonly model: string;
+    readonly fetch?: FetchLike;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+    /**
+     * Output-token ceiling per request. An unset value sends no ceiling, and
+     * the model cap of the server governs the reply. The Responses wire holds
+     * no low default, thus the omission cannot truncate a reply. Set a number
+     * to hold the reply under a lower ceiling than the cap of the model.
+     */
+    readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
+    /**
+     * NOTICE: this value is the retention directive of the Responses wire.
+     *
+     * An unset value lets the OpenAI server keep the response for 30 days.
+     * The dashboard logs show that response, and a caller can retrieve it by
+     * id. Thus the arm always sends an explicit value. The default is
+     * `false`, and an analysis payload does not persist at OpenAI.
+     *
+     * An unset value is also not neutral inside the SDK. When the SDK sees
+     * no explicit `false`, its input converter assumes storage. It then
+     * replaces a round-tripped item with an `item_reference` entry. Such a
+     * reference fails with a 404 under Zero Data Retention, and it fails
+     * after the 30-day expiry.
+     *
+     * An explicit `false` selects the stateless reasoning path of the SDK.
+     * The SDK adds `include: ["reasoning.encrypted_content"]` for a
+     * reasoning-family model id. It captures the blob on `providerMetadata`,
+     * and it replays the blob from the history of the thread. The SDK strips
+     * a reasoning part that lost its blob, and it warns. That warning reaches
+     * the harness logger through the SDK warning hook.
+     *
+     * One thread must keep one mode. The wire captures the history of a turn
+     * under the mode of that turn. If a later turn replays a history of the
+     * `false` mode under storage, the SDK emits a reference onto an item that
+     * the server never stored.
+     *
+     * An operator can override the default with `true`. The dashboard then
+     * shows the trail of the thread, and a caller can retrieve a response by
+     * id. The harness does not use `previous_response_id`, and it does not
+     * use `conversation`. This is true for the two modes.
+     */
+    readonly store?: boolean;
 } | {
     readonly kind: "openai-compatible";
     readonly name: string;