@wrenai/genbi 0.0.1

package/dist-server/harness/render/envelope.d.ts

@@ -0,0 +1,145 @@
+import type { Agent } from "../bundle/schema.js";
+import type { DataflowArtifacts } from "../loop/index.js";
+import type { ProviderRegistry, TierBinding } from "../providers/index.js";
+/**
+ * The structured answer synthesized from an agent's finished dataflow
+ * artifacts, shaped by `agent.output_schema`. The golden `answer_query`
+ * schema requires `blocks` and allows `summary`/`verified` to be present —
+ * this type only pins down the fields the harness itself inspects
+ * (`verified`, for `gated_check` enforcement); everything else the schema
+ * defines flows through as-is.
+ */
+export interface RenderEnvelope {
+    readonly blocks: unknown;
+    readonly summary?: string | null;
+    readonly verified?: boolean | null;
+    readonly [key: string]: unknown;
+}
+/**
+ * A flat table payload captured from a data-access tool's real, successful
+ * result (the `query` tool's `{columns, rows}` reshaped to positional rows,
+ * plus the SQL that produced it). When present, `renderEnvelope` builds the
+ * envelope's table/definition blocks directly from this — deterministic, and
+ * carrying the agent's actual rows — instead of routing through the render
+ * model, which is lossy for structured data.
+ */
+export interface ToolTableSeed {
+    readonly columns: readonly string[];
+    readonly rows: readonly unknown[][];
+    readonly sql?: string;
+    readonly summary?: string;
+}
+/**
+ * A full `{blocks}` payload captured from a `build_dashboard` tool's real,
+ * successful result (see `harness/tools/native.ts`'s `assembleDashboardBlocks`).
+ * Unlike {@link ToolTableSeed} (a flat table reshaped into table/definition
+ * blocks), this is already a complete, ordered dashboard envelope — the
+ * deterministic assembly tool did all the reshaping. When present and it
+ * validates against `output_schema`, `renderEnvelope` returns it directly,
+ * ahead of every other path (see `renderEnvelope`'s seed-precedence order).
+ */
+export interface DashboardSeed {
+    readonly blocks: readonly unknown[];
+    readonly summary?: string;
+    readonly verified?: boolean;
+}
+export interface RenderEnvelopeContext {
+    readonly binding: TierBinding;
+    readonly registry: ProviderRegistry;
+    /** The user's original question, threaded into the synthesis prompt. */
+    readonly userInput: string;
+    /**
+     * Deterministic render seed: a data-access tool's real result. When set
+     * and it validates against `output_schema`, the envelope is built straight
+     * from it and the render model is skipped entirely. See {@link ToolTableSeed}.
+     */
+    readonly toolTable?: ToolTableSeed;
+    /**
+     * Deterministic render seed: a `build_dashboard` tool's real, already-
+     * assembled `{blocks}` result (see {@link DashboardSeed}). Takes priority
+     * over every other seed/path — see `renderEnvelope`'s seed-precedence order.
+     */
+    readonly dashboardSeed?: DashboardSeed;
+    /**
+     * Tier to run the envelope-synthesis `generateText` call on. Defaults
+     * to the tier of the agent's *last* `independent` step (in `steps[]`
+     * array order) — the reasoning behind this default: the last independent
+     * step is the one that did the heaviest lifting toward the final answer
+     * (e.g. `generate_sql` in the golden `answer_query` shape), so synthesis
+     * warrants at least that much model strength. Callers with a dedicated
+     * "render" tier in their bundle can override this explicitly.
+     */
+    readonly tier?: string;
+}
+/**
+ * The two-stage structured-output envelope. Deliberately kept OUT of the
+ * `ToolLoopAgent` construction in `executeAgent` — attaching `Output.object`
+ * to a tool-bearing loop constrains every turn's output to the final
+ * schema, including turns that are just making tool calls. Instead, this
+ * runs as its own separate call, once, after the loop's dataflow artifacts
+ * have all been produced.
+ *
+ * This deliberately uses `generateText`, not `generateObject` — the schema
+ * is enforced in prompt text plus `collectJsonSchemaErrors` below, not via
+ * an SDK-level `responseFormat: json_schema`/structured-output request.
+ * `generateObject`'s `json_schema` response format isn't supported by every
+ * OpenAI-compatible endpoint (e.g. Ollama's `/v1` endpoint 400s on it), so a
+ * provider-agnostic envelope stage can't rely on it; `generateText` has no
+ * such requirement and works identically against mock, cloud, and local
+ * providers. Enforcement doesn't get any weaker: `jsonSchema()`'s own
+ * `validate` callback was already the only thing giving `output_schema`
+ * real teeth (it performs no runtime validation on its own without one), so
+ * running `collectJsonSchemaErrors` directly against the parsed JSON here
+ * is the same enforcement, just invoked by hand instead of through the SDK.
+ */
+export declare function renderEnvelope(agent: Agent, artifacts: DataflowArtifacts, ctx: RenderEnvelopeContext): Promise<RenderEnvelope>;
+/**
+ * Extracts the set of block `type` consts an `output_schema` permits, by
+ * walking `properties.blocks.items` — either a single item schema (e.g.
+ * `explain_change`'s narrative-only shape) or an `anyOf` of several (e.g.
+ * `answer_query`'s table/definition shape, or `generate_dashboard`'s
+ * kpi_card/table/chart/definition shape). Each variant contributes its
+ * `properties.type.const`, if it declares one.
+ *
+ * Returns `undefined` when the schema declares no `type` consts at all (e.g.
+ * `explore_model`'s bare `{type: "object"}` item schema, which places no
+ * constraint on block shape) — an unconstrained schema is deliberately never
+ * treated as "table-only" by {@link isTableOnlySchema}, since there's no
+ * actual evidence it only permits table/definition blocks.
+ */
+export declare function getAllowedBlockTypes(outputSchema: Record<string, unknown>): Set<string> | undefined;
+/**
+ * True when `output_schema`'s `blocks.items` permits ONLY `table`/
+ * `definition` block types — the `answer_query` shape, and the exact
+ * precondition for applying `ToolTableSeed` (see `renderEnvelope`). An
+ * unconstrained schema (`getAllowedBlockTypes` returns `undefined`) is never
+ * table-only.
+ */
+export declare function isTableOnlySchema(outputSchema: Record<string, unknown>): boolean;
+/**
+ * Best-effort extraction of a {@link RenderEnvelope} from dispatched's raw
+ * `finalText` — a CLI stdout string (`DispatchedResult.finalText`), not a
+ * structured artifact map the way in-process's `executeAgent` output is. Dispatched
+ * has no dataflow-artifact scan or tool-outcome capture of its own (see
+ * `runDispatchedDefault` — it only reads the dispatcher's terminal stdout line),
+ * so this is the only signal available to build a `form: "rich"` answer from.
+ *
+ * The agent is expected to emit its final structured answer as a JSON
+ * object, plain or ```json-fenced (the same contract the render model
+ * itself follows — see `extractJsonObjectText`), in one of the shapes
+ * {@link normalizeToEnvelopeShape} already reconciles:
+ *  - already `{blocks: [...]}` (e.g. `generate_dashboard`) -> used as-is.
+ *  - flat `{columns, rows, verified?, summary?, definition?}` (`answer_query`'s
+ *    actual tool contract) -> reshaped into a `table` (+ `definition`) block.
+ *  - an MCP `CallToolResult` (`{content: [{type:"text", text}], ...}` or
+ *    `{structuredContent}`) -> unwrapped one level and the same rules
+ *    re-applied to what's inside. This is a known trap (see the
+ *    harness-tooltable-seed-dead follow-up): the real `query` MCP tool's raw
+ *    result is this wrapper shape, not the flat one above, so an extractor
+ *    that only checked for `{columns, rows}` would silently miss it.
+ *
+ * Returns `undefined` when nothing recognizable is found (not JSON at all,
+ * or JSON that matches none of the above), so the caller can fall back to
+ * `form: "text"` instead of fabricating an envelope.
+ */
+export declare function extractEnvelopeFromText(text: string): RenderEnvelope | undefined;

package/dist-server/harness/render/envelope.js

@@ -0,0 +1,428 @@
+import { generateText } from "ai";
+import { resolveTierModel } from "../providers/index.js";
+import { EnvelopeParseError, EnvelopeSchemaError, NoRenderTierError } from "./errors.js";
+import { collectJsonSchemaErrors } from "./validate.js";
+/** Bounded: at most one reformat attempt if the model's first response doesn't parse. */
+const MAX_PARSE_ATTEMPTS = 2;
+/**
+ * The two-stage structured-output envelope. Deliberately kept OUT of the
+ * `ToolLoopAgent` construction in `executeAgent` — attaching `Output.object`
+ * to a tool-bearing loop constrains every turn's output to the final
+ * schema, including turns that are just making tool calls. Instead, this
+ * runs as its own separate call, once, after the loop's dataflow artifacts
+ * have all been produced.
+ *
+ * This deliberately uses `generateText`, not `generateObject` — the schema
+ * is enforced in prompt text plus `collectJsonSchemaErrors` below, not via
+ * an SDK-level `responseFormat: json_schema`/structured-output request.
+ * `generateObject`'s `json_schema` response format isn't supported by every
+ * OpenAI-compatible endpoint (e.g. Ollama's `/v1` endpoint 400s on it), so a
+ * provider-agnostic envelope stage can't rely on it; `generateText` has no
+ * such requirement and works identically against mock, cloud, and local
+ * providers. Enforcement doesn't get any weaker: `jsonSchema()`'s own
+ * `validate` callback was already the only thing giving `output_schema`
+ * real teeth (it performs no runtime validation on its own without one), so
+ * running `collectJsonSchemaErrors` directly against the parsed JSON here
+ * is the same enforcement, just invoked by hand instead of through the SDK.
+ */
+export async function renderEnvelope(agent, artifacts, ctx) {
+    const outputSchema = agent.output_schema;
+    // Deterministic render seed (STRONGEST path, checked first): a
+    // `build_dashboard` tool's real, already-assembled `{blocks}` result
+    // (`ctx.dashboardSeed`). This is a complete dashboard envelope built
+    // deterministically by the native tool (see `assembleDashboardBlocks`), so
+    // there is nothing left to reconcile — it wins over the table-only
+    // `toolTable` seed below (whose gate below would skip a dashboard schema
+    // anyway) and over the artifact scan / render LLM. Only taken when it
+    // validates against `output_schema`; otherwise fall through (e.g.
+    // `build_dashboard` was never called for this run).
+    if (ctx.dashboardSeed !== undefined) {
+        const seeded = {
+            blocks: ctx.dashboardSeed.blocks,
+            ...(ctx.dashboardSeed.summary !== undefined ? { summary: ctx.dashboardSeed.summary } : {}),
+            ...(ctx.dashboardSeed.verified !== undefined ? { verified: ctx.dashboardSeed.verified } : {}),
+        };
+        if (collectJsonSchemaErrors(outputSchema, seeded).length === 0) {
+            return seeded;
+        }
+    }
+    // Deterministic render seed: if the caller captured a data-access tool's
+    // real result (`ctx.toolTable` — e.g. the `query` tool's rows), build the
+    // envelope straight from it. This preserves the agent's actual data
+    // regardless of whether the step model chose to re-emit that structure as
+    // text (many models summarize it to prose, which the artifact scan below
+    // then can't recover). `verified: true` is warranted here specifically
+    // because the payload IS a successful, non-erroring execution result — the
+    // exact evidence `runAgent`'s deterministic `gated_check` requires.
+    //
+    // Gated on `isTableOnlySchema`: this seed only ever produces `table`/
+    // `definition` blocks, so it must only be applied when `output_schema`
+    // permits *just* those block types (the `answer_query` shape). Without
+    // this gate, a table-only seed captured from an incidental `query` call
+    // (e.g. inside `generate_dashboard`'s multi-panel flow) would fire FIRST
+    // and collapse a whole dashboard down to a single table — the schema
+    // validation below would eventually reject it (a dashboard schema also
+    // permits `kpi_card`/`chart`, so a table-only payload can actually still
+    // validate against it, since every block in the array only needs to match
+    // ONE `anyOf` branch), silently losing every other panel. Gating on the
+    // schema's allowed types catches this before validation, not after.
+    // Only taken when it also validates against `output_schema`; otherwise
+    // fall through.
+    if (ctx.toolTable !== undefined && isTableOnlySchema(outputSchema)) {
+        const seeded = normalizeToEnvelopeShape({
+            columns: ctx.toolTable.columns,
+            rows: ctx.toolTable.rows,
+            verified: true,
+            ...(ctx.toolTable.summary !== undefined ? { summary: ctx.toolTable.summary } : {}),
+            ...(ctx.toolTable.sql !== undefined
+                ? { definition: { sql: ctx.toolTable.sql, source_tables: [], filters: [] } }
+                : {}),
+        });
+        if (collectJsonSchemaErrors(outputSchema, seeded).length === 0) {
+            return seeded;
+        }
+    }
+    // Deterministic fast-path: if a terminal artifact is ALREADY a renderable
+    // payload (answer_query emits the flat {columns,rows,verified,definition};
+    // other agents may already emit a {blocks} envelope), build the envelope
+    // straight from it — no render LLM. This preserves the agent's real data
+    // (the table rows) instead of asking a render model to re-synthesize it,
+    // which is lossy (it tends to summarize the table away, leaving a bare
+    // `{type:"table"}`) and an extra call. Only taken when the result validates;
+    // otherwise fall through to the render-LLM path below.
+    const direct = tryDirectEnvelope(artifacts);
+    if (direct !== undefined && collectJsonSchemaErrors(outputSchema, direct).length === 0) {
+        return direct;
+    }
+    const tier = ctx.tier ?? defaultRenderTier(agent);
+    const model = resolveTierModel(ctx.binding, tier, ctx.registry);
+    const prompt = buildEnvelopePrompt(agent, artifacts, ctx.userInput, outputSchema);
+    let lastParseError;
+    for (let attempt = 1; attempt <= MAX_PARSE_ATTEMPTS; attempt += 1) {
+        const { text } = await generateText({ model, prompt: attempt === 1 ? prompt : reformatPrompt(prompt) });
+        let value;
+        try {
+            value = JSON.parse(extractJsonObjectText(text));
+        }
+        catch (error) {
+            lastParseError = error;
+            continue;
+        }
+        const normalized = normalizeToEnvelopeShape(value);
+        const errors = collectJsonSchemaErrors(outputSchema, normalized);
+        if (errors.length > 0) {
+            throw new EnvelopeSchemaError(agent.id, errors);
+        }
+        return normalized;
+    }
+    throw new EnvelopeParseError(agent.id, lastParseError);
+}
+/**
+ * `answer_query`'s ACTUAL tool contract (see `answer_tool.ts`/warble's own
+ * eval, which this must never change) is a FLAT table shape —
+ * `{columns, rows, verified, definition}` — not the `{blocks}`
+ * RenderEnvelope this module otherwise expects. Left unreconciled, that flat
+ * shape fails `output_schema` validation below and the run degrades to an
+ * unverified raw-JSON text blob (see `runAgent`'s `gated_check`, which only
+ * trusts `envelope.verified === true`).
+ *
+ * This is a compatibility/normalization shim, applied to every parsed
+ * candidate before schema validation:
+ *  - Already has a `blocks` array (e.g. `generate_dashboard`, or any future
+ *    agent that already speaks the block contract) → returned unchanged.
+ *  - Otherwise, if it structurally matches the flat table shape (`columns`
+ *    and `rows` are both arrays — a shape a real `{blocks: [...]}` envelope
+ *    never has at its top level, so this can't misfire against one) →
+ *    synthesize `blocks = [{type: "table", columns, rows}, ...(definition
+ *    block, if present)]` and carry `verified`/`summary` onto the result,
+ *    so the flat payload renders as a verified table instead of failing
+ *    validation.
+ *  - Anything else (unrecognized shape) → returned unchanged, so it still
+ *    fails `output_schema` validation below with a useful error rather than
+ *    being silently coerced into something misleading.
+ */
+/**
+ * Scans the loop's dataflow artifacts for one that is ALREADY a renderable
+ * payload and builds the envelope from it deterministically (via
+ * `normalizeToEnvelopeShape`), skipping the render LLM. Artifacts are checked
+ * in reverse insertion order so the agent's terminal output (the last step's
+ * result) wins over any intermediate one. String artifacts are parsed the same
+ * way a model response would be. Returns `undefined` when nothing is directly
+ * renderable, so the caller falls back to the render-LLM path.
+ */
+function tryDirectEnvelope(artifacts) {
+    for (const raw of [...artifacts.values()].reverse()) {
+        const candidate = coerceToObject(raw);
+        if (candidate === undefined)
+            continue;
+        if (hasBlocksArray(candidate) || isFlatTablePayload(candidate)) {
+            return normalizeToEnvelopeShape(candidate);
+        }
+    }
+    return undefined;
+}
+/** An artifact value as a parsed object: objects pass through; strings are
+ * parsed like a model response (fence-stripped); anything else is skipped. */
+function coerceToObject(raw) {
+    if (typeof raw === "object" && raw !== null)
+        return raw;
+    if (typeof raw === "string") {
+        try {
+            return JSON.parse(extractJsonObjectText(raw));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function normalizeToEnvelopeShape(value) {
+    if (hasBlocksArray(value))
+        return value;
+    const candidate = isCodexQueryResultPayload(value)
+        ? codexQueryResultToFlatTable(value)
+        : value;
+    if (!isFlatTablePayload(candidate))
+        return value;
+    const { columns, rows, verified, summary, definition } = candidate;
+    const blocks = [{ type: "table", columns, rows }];
+    if (definition && typeof definition === "object") {
+        const { sql, source_tables, filters } = definition;
+        blocks.push({ type: "definition", sql, source_tables, filters });
+    }
+    return {
+        blocks,
+        ...(summary !== undefined ? { summary } : {}),
+        ...(verified !== undefined ? { verified } : {}),
+    };
+}
+const TABLE_ONLY_BLOCK_TYPES = new Set(["table", "definition"]);
+/**
+ * Extracts the set of block `type` consts an `output_schema` permits, by
+ * walking `properties.blocks.items` — either a single item schema (e.g.
+ * `explain_change`'s narrative-only shape) or an `anyOf` of several (e.g.
+ * `answer_query`'s table/definition shape, or `generate_dashboard`'s
+ * kpi_card/table/chart/definition shape). Each variant contributes its
+ * `properties.type.const`, if it declares one.
+ *
+ * Returns `undefined` when the schema declares no `type` consts at all (e.g.
+ * `explore_model`'s bare `{type: "object"}` item schema, which places no
+ * constraint on block shape) — an unconstrained schema is deliberately never
+ * treated as "table-only" by {@link isTableOnlySchema}, since there's no
+ * actual evidence it only permits table/definition blocks.
+ */
+export function getAllowedBlockTypes(outputSchema) {
+    const items = extractBlocksItemsSchema(outputSchema);
+    if (items === undefined)
+        return undefined;
+    const variants = Array.isArray(items.anyOf) ? items.anyOf : [items];
+    const types = new Set();
+    for (const variant of variants) {
+        if (!isPlainRecord(variant))
+            continue;
+        const properties = variant.properties;
+        if (!isPlainRecord(properties))
+            continue;
+        const typeSchema = properties.type;
+        if (isPlainRecord(typeSchema) && typeof typeSchema.const === "string") {
+            types.add(typeSchema.const);
+        }
+    }
+    return types.size > 0 ? types : undefined;
+}
+/**
+ * True when `output_schema`'s `blocks.items` permits ONLY `table`/
+ * `definition` block types — the `answer_query` shape, and the exact
+ * precondition for applying `ToolTableSeed` (see `renderEnvelope`). An
+ * unconstrained schema (`getAllowedBlockTypes` returns `undefined`) is never
+ * table-only.
+ */
+export function isTableOnlySchema(outputSchema) {
+    const allowed = getAllowedBlockTypes(outputSchema);
+    if (allowed === undefined)
+        return false;
+    for (const type of allowed) {
+        if (!TABLE_ONLY_BLOCK_TYPES.has(type))
+            return false;
+    }
+    return true;
+}
+function extractBlocksItemsSchema(outputSchema) {
+    const properties = outputSchema.properties;
+    if (!isPlainRecord(properties))
+        return undefined;
+    const blocks = properties.blocks;
+    if (!isPlainRecord(blocks))
+        return undefined;
+    const items = blocks.items;
+    return isPlainRecord(items) ? items : undefined;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasBlocksArray(value) {
+    return typeof value === "object" && value !== null && Array.isArray(value.blocks);
+}
+function isFlatTablePayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return Array.isArray(record.columns) && Array.isArray(record.rows);
+}
+/**
+ * codex:local's terminal child value is deliberately an execution-evidence
+ * object rather than the legacy flat answer_query payload. Recognize only
+ * the complete shape: a partial or model-invented lookalike must fall back
+ * to unverified text instead of being promoted into a verified table.
+ */
+function isCodexQueryResultPayload(value) {
+    if (!isPlainRecord(value) || !isPlainRecord(value.result_set))
+        return false;
+    const resultSet = value.result_set;
+    return (Array.isArray(resultSet.columns) &&
+        resultSet.columns.every((column) => typeof column === "string") &&
+        Array.isArray(resultSet.rows) &&
+        typeof value.sql === "string" &&
+        Array.isArray(value.source_tables) &&
+        value.source_tables.every((table) => typeof table === "string") &&
+        Array.isArray(value.filters) &&
+        typeof value.execution_passed === "boolean" &&
+        typeof value.validation_passed === "boolean" &&
+        (typeof value.validation_error === "string" || value.validation_error === null));
+}
+function codexQueryResultToFlatTable(value) {
+    const { columns, rows } = value.result_set;
+    const positionalRows = rows.map((row) => isPlainRecord(row) ? columns.map((column) => row[column]) : row);
+    return {
+        columns,
+        rows: positionalRows,
+        verified: value.execution_passed &&
+            value.validation_passed &&
+            value.validation_error === null,
+        definition: {
+            sql: value.sql,
+            source_tables: value.source_tables,
+            filters: value.filters,
+        },
+    };
+}
+/**
+ * Extracts a JSON object from a model's raw text response: strips
+ * ```json …``` / ``` fences, trims surrounding prose, and locates the outer
+ * `{ … }` object by its first `{` and matching last `}`. Throws (falls
+ * through to `JSON.parse`'s own error) if no object-shaped substring is
+ * found, so callers can treat "couldn't extract" and "extracted but invalid
+ * JSON" the same way.
+ */
+function extractJsonObjectText(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = (fenced?.[1] ?? text).trim();
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end === -1 || end < start) {
+        throw new SyntaxError(`no JSON object found in model response: ${JSON.stringify(text.slice(0, 200))}`);
+    }
+    return candidate.slice(start, end + 1);
+}
+/**
+ * Best-effort extraction of a {@link RenderEnvelope} from dispatched's raw
+ * `finalText` — a CLI stdout string (`DispatchedResult.finalText`), not a
+ * structured artifact map the way in-process's `executeAgent` output is. Dispatched
+ * has no dataflow-artifact scan or tool-outcome capture of its own (see
+ * `runDispatchedDefault` — it only reads the dispatcher's terminal stdout line),
+ * so this is the only signal available to build a `form: "rich"` answer from.
+ *
+ * The agent is expected to emit its final structured answer as a JSON
+ * object, plain or ```json-fenced (the same contract the render model
+ * itself follows — see `extractJsonObjectText`), in one of the shapes
+ * {@link normalizeToEnvelopeShape} already reconciles:
+ *  - already `{blocks: [...]}` (e.g. `generate_dashboard`) -> used as-is.
+ *  - flat `{columns, rows, verified?, summary?, definition?}` (`answer_query`'s
+ *    actual tool contract) -> reshaped into a `table` (+ `definition`) block.
+ *  - an MCP `CallToolResult` (`{content: [{type:"text", text}], ...}` or
+ *    `{structuredContent}`) -> unwrapped one level and the same rules
+ *    re-applied to what's inside. This is a known trap (see the
+ *    harness-tooltable-seed-dead follow-up): the real `query` MCP tool's raw
+ *    result is this wrapper shape, not the flat one above, so an extractor
+ *    that only checked for `{columns, rows}` would silently miss it.
+ *
+ * Returns `undefined` when nothing recognizable is found (not JSON at all,
+ * or JSON that matches none of the above), so the caller can fall back to
+ * `form: "text"` instead of fabricating an envelope.
+ */
+export function extractEnvelopeFromText(text) {
+    let candidate;
+    try {
+        candidate = JSON.parse(extractJsonObjectText(text));
+    }
+    catch {
+        return undefined;
+    }
+    return normalizeExtractedCandidate(candidate);
+}
+/** Bounded: at most one MCP `CallToolResult` unwrap, so a pathological/self-referential payload can't recurse forever. */
+const MAX_UNWRAP_DEPTH = 2;
+function normalizeExtractedCandidate(value, depth = 0) {
+    const normalized = normalizeToEnvelopeShape(value);
+    if (hasBlocksArray(normalized))
+        return normalized;
+    if (depth >= MAX_UNWRAP_DEPTH)
+        return undefined;
+    const unwrapped = unwrapCallToolResult(value);
+    return unwrapped === undefined ? undefined : normalizeExtractedCandidate(unwrapped, depth + 1);
+}
+/**
+ * Unwraps one layer of an MCP `CallToolResult` (`{content, structuredContent,
+ * isError}`) to the value inside — `structuredContent` when present,
+ * otherwise the first `type: "text"` content item's own JSON (fence-stripped
+ * the same way a model response is). Returns `undefined` for anything that
+ * isn't recognizably this shape.
+ */
+function unwrapCallToolResult(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    if (value.structuredContent !== undefined)
+        return value.structuredContent;
+    if (!Array.isArray(value.content))
+        return undefined;
+    const textItem = value.content.find((item) => isPlainRecord(item) && item.type === "text" && typeof item.text === "string");
+    if (textItem === undefined)
+        return undefined;
+    try {
+        return JSON.parse(extractJsonObjectText(textItem.text));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Wraps the original prompt with a stricter instruction for the one bounded retry. */
+function reformatPrompt(prompt) {
+    return (`${prompt}\n\nYour previous response could not be parsed as a single JSON object. ` +
+        `Respond again with ONLY the JSON object — no prose, no markdown code fences.`);
+}
+function defaultRenderTier(agent) {
+    const independentSteps = agent.steps.filter((step) => step.realization.kind === "independent");
+    const lastIndependent = independentSteps[independentSteps.length - 1];
+    if (!lastIndependent) {
+        throw new NoRenderTierError(agent.id);
+    }
+    return lastIndependent.tier;
+}
+/**
+ * Renders every accumulated dataflow artifact plus `output_schema` into the
+ * synthesis prompt. Since there's no SDK-level `responseFormat` doing the
+ * asking for us (see `renderEnvelope`), the instruction to emit bare JSON
+ * matching the schema — and nothing else — has to live in the prompt text.
+ */
+function buildEnvelopePrompt(agent, artifacts, userInput, outputSchema) {
+    const sections = [
+        `User's question: ${userInput}`,
+        `Synthesize the final structured answer for agent "${agent.id}" from the artifacts below.`,
+    ];
+    for (const [name, value] of artifacts) {
+        sections.push(`${name}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+    sections.push(`Respond with ONLY a single JSON object conforming to this JSON Schema — no prose, ` +
+        `no markdown code fences, no explanation before or after it:\n${JSON.stringify(outputSchema)}`);
+    return sections.join("\n\n");
+}

package/dist-server/harness/render/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thrown when the render envelope stage (the two-stage structured-output
+ * synthesis) needs a tier to run on but the caller didn't supply one
+ * explicitly and the agent has no `independent` step to fall back to —
+ * e.g. an agent made up entirely of `repair_fold` steps. This should never
+ * happen for a v1-scoped agent (`executeAgent` already requires at least
+ * one independent step to produce anything), but the envelope stage
+ * doesn't assume that invariant on its own.
+ */
+export declare class NoRenderTierError extends Error {
+    constructor(agentId: string);
+}
+/**
+ * Thrown when the model's envelope response parses as JSON but doesn't
+ * structurally match `agent.output_schema` — checked by hand via
+ * `collectJsonSchemaErrors` against the `generateText` output (see
+ * `renderEnvelope`; the envelope stage doesn't use `generateObject`'s
+ * SDK-level schema enforcement, so this replaces the errors that used to
+ * surface as a `NoObjectGeneratedError`'s cause).
+ */
+export declare class EnvelopeSchemaError extends Error {
+    constructor(agentId: string, violations: readonly string[]);
+}
+/**
+ * Thrown when the model's envelope response still doesn't extract into
+ * parseable JSON after `renderEnvelope`'s one bounded reformat retry (see
+ * `extractJsonObjectText`). Distinct from `EnvelopeSchemaError`, which is
+ * for JSON that parses but doesn't match `output_schema` — this is for
+ * responses that never became valid JSON at all.
+ */
+export declare class EnvelopeParseError extends Error {
+    constructor(agentId: string, cause: unknown);
+}

package/dist-server/harness/render/errors.js

@@ -0,0 +1,46 @@
+/**
+ * Thrown when the render envelope stage (the two-stage structured-output
+ * synthesis) needs a tier to run on but the caller didn't supply one
+ * explicitly and the agent has no `independent` step to fall back to —
+ * e.g. an agent made up entirely of `repair_fold` steps. This should never
+ * happen for a v1-scoped agent (`executeAgent` already requires at least
+ * one independent step to produce anything), but the envelope stage
+ * doesn't assume that invariant on its own.
+ */
+export class NoRenderTierError extends Error {
+    constructor(agentId) {
+        super(`agent "${agentId}" has no "independent" step to default the render envelope's ` +
+            `tier from, and no explicit tier was supplied to renderEnvelope()`);
+        this.name = "NoRenderTierError";
+    }
+}
+/**
+ * Thrown when the model's envelope response parses as JSON but doesn't
+ * structurally match `agent.output_schema` — checked by hand via
+ * `collectJsonSchemaErrors` against the `generateText` output (see
+ * `renderEnvelope`; the envelope stage doesn't use `generateObject`'s
+ * SDK-level schema enforcement, so this replaces the errors that used to
+ * surface as a `NoObjectGeneratedError`'s cause).
+ */
+export class EnvelopeSchemaError extends Error {
+    constructor(agentId, violations) {
+        super(`agent "${agentId}"'s render envelope does not match its output_schema:\n` +
+            violations.map((violation) => `  - ${violation}`).join("\n"));
+        this.name = "EnvelopeSchemaError";
+    }
+}
+/**
+ * Thrown when the model's envelope response still doesn't extract into
+ * parseable JSON after `renderEnvelope`'s one bounded reformat retry (see
+ * `extractJsonObjectText`). Distinct from `EnvelopeSchemaError`, which is
+ * for JSON that parses but doesn't match `output_schema` — this is for
+ * responses that never became valid JSON at all.
+ */
+export class EnvelopeParseError extends Error {
+    constructor(agentId, cause) {
+        super(`agent "${agentId}"'s render envelope response could not be parsed as JSON after retrying: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "EnvelopeParseError";
+        this.cause = cause;
+    }
+}

package/dist-server/harness/render/index.d.ts

@@ -0,0 +1,5 @@
+export { extractEnvelopeFromText, getAllowedBlockTypes, isTableOnlySchema, renderEnvelope } from "./envelope.js";
+export type { DashboardSeed, RenderEnvelope, RenderEnvelopeContext, ToolTableSeed } from "./envelope.js";
+export { EnvelopeParseError, EnvelopeSchemaError, NoRenderTierError } from "./errors.js";
+export { collectJsonSchemaErrors } from "./validate.js";
+export type { JsonSchemaDocument } from "./validate.js";

package/dist-server/harness/render/index.js

@@ -0,0 +1,3 @@
+export { extractEnvelopeFromText, getAllowedBlockTypes, isTableOnlySchema, renderEnvelope } from "./envelope.js";
+export { EnvelopeParseError, EnvelopeSchemaError, NoRenderTierError } from "./errors.js";
+export { collectJsonSchemaErrors } from "./validate.js";