@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/tools/display/normalize-echart-spec.js

@@ -0,0 +1,211 @@
+/**
+ * ECharts layout normalization — the renderer-side invariant behind `show_user(kind: "echart")`.
+ *
+ * The layout discipline (no duplicate title, bottom legend, grid margins that fit the axis labels,
+ * every category label shown, a downloadable chart) is applied HERE, deterministically, rather than
+ * being a checklist the model must remember on every chart it composes. A rule a model must remember
+ * is a rule it can forget.
+ *
+ * Two invariants govern every rule below:
+ *
+ * 1. **Defaults, not overrides.** Every property is filled in only when the author left it unset —
+ *    an explicit, sensible authored `grid`/`legend`/`rotate`/filename is respected. The two forced
+ *    fields are `title` (deleted: the `show_user` `title` param is the card heading, so an in-spec
+ *    title is a genuine duplicate render) and `axisLabel.interval` (pinned to `0`: ECharts' default
+ *    `"auto"` SILENTLY DROPS labels, which is the exact bug this rule exists to prevent).
+ * 2. **Never turn a valid chart invalid.** Nothing here is derived from data that may be absent: a
+ *    property is only injected where it is meaningful (a `grid` only for a cartesian chart), and an
+ *    unknown category count yields the safe layout rather than a guessed one.
+ *
+ * Pure: the input spec is never mutated. Modified branches are copy-on-write; untouched branches are
+ * shared by reference. `normalize(normalize(x))` deep-equals `normalize(x)`.
+ */
+/** Max length of a derived `saveAsImage` filename. */
+const MAX_FILENAME_LEN = 64;
+/** Fallback download filename when no heading is available to derive one from. */
+const DEFAULT_FILENAME = "chart";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The axis entries of an `xAxis`/`yAxis` option, which ECharts accepts as one object or an array. */
+function axisEntries(axis) {
+    if (Array.isArray(axis))
+        return axis.filter(isRecord);
+    return isRecord(axis) ? [axis] : [];
+}
+/**
+ * Kebab-case download filename: `"HMGCR — VST Expression"` → `"hmgcr-vst-expression"`.
+ * Diacritics are folded, every other non-alphanumeric run collapses to a single dash.
+ */
+export function kebabFilename(source) {
+    const slug = (source ?? "")
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, MAX_FILENAME_LEN)
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : DEFAULT_FILENAME;
+}
+/** Declared series count. `0` = none declared, which is also "nothing a legend could label". */
+function seriesCount(spec) {
+    const series = spec.series;
+    if (Array.isArray(series))
+        return series.length;
+    return isRecord(series) ? 1 : 0;
+}
+/** True when any series maps its categories to dataset COLUMNS rather than rows. */
+function laysOutByRow(spec) {
+    const series = Array.isArray(spec.series) ? spec.series : [spec.series];
+    return series.some((s) => isRecord(s) && s.seriesLayoutBy === "row");
+}
+/** Header rows to discount from a `dataset.source` array, per ECharts' `sourceHeader` rules. */
+function headerRowCount(dataset, source) {
+    const declared = dataset.sourceHeader;
+    if (declared === true)
+        return 1;
+    if (declared === false)
+        return 0;
+    if (typeof declared === "number" && Number.isFinite(declared)) {
+        return Math.min(Math.max(Math.trunc(declared), 0), source.length);
+    }
+    // `"auto"` (the default): a leading row of all-strings in front of further rows is dimension names.
+    const first = source[0];
+    return source.length > 1 && Array.isArray(first) && first.length > 0 && first.every((cell) => typeof cell === "string") ? 1 : 0;
+}
+/**
+ * Category count on the x axis, or `null` when the spec cannot tell us.
+ *
+ * `null` is the honest answer for a CSV-backed chart (`show_user`'s `dataPath`): the rows are loaded
+ * by the host at render time and deliberately never pulled through the model's context window, so
+ * they are NOT in the spec. Guessing a rotation for an axis of unknown length is worse than not
+ * rotating — an unrotated axis is also exactly what the other `null` cases (a value axis: scatter,
+ * time series) want. The count is used ONLY to pick a label rotation; it never touches the data, so
+ * an off-by-one at a bucket boundary costs at most a rotation, never a rendering.
+ */
+export function categoryCount(spec) {
+    for (const axis of axisEntries(spec.xAxis)) {
+        // An explicit category list is unambiguous — prefer it over any dataset inference.
+        if (Array.isArray(axis.data))
+            return axis.data.length;
+    }
+    // An array of datasets, an object-of-columns `source`, or a row-major layout: do not guess.
+    const dataset = spec.dataset;
+    if (!isRecord(dataset) || laysOutByRow(spec))
+        return null;
+    const source = dataset.source;
+    if (!Array.isArray(source) || source.length === 0)
+        return null;
+    return Math.max(0, source.length - headerRowCount(dataset, source));
+}
+/** The label rotation for `count` categories, or `null` for "leave the labels horizontal". */
+function rotationFor(count) {
+    if (count === null || count <= 10)
+        return null;
+    // >20 categories: ECharts' own escape hatch is a `dataZoom` slider, but that rewrites the chart's
+    // interaction model and its vertical budget — a 90° turn is the mutation that cannot surprise.
+    return count <= 20 ? 45 : 90;
+}
+/** True when the legend (authored or defaulted) sits below the chart and consumes bottom margin. */
+function isBottomLegend(legend) {
+    const entries = Array.isArray(legend) ? legend.filter(isRecord) : isRecord(legend) ? [legend] : [];
+    return entries.some((entry) => entry.show !== false && entry.bottom !== undefined);
+}
+/** True when a component option carries any explicit placement — adding another would fight it. */
+function hasPlacement(option) {
+    return option.left !== undefined || option.right !== undefined || option.top !== undefined || option.bottom !== undefined;
+}
+/**
+ * Apply the ECharts layout invariant to an author-composed spec.
+ *
+ * - `title` is deleted (always) — the `show_user` `title` param is the visible card heading, and
+ *   `title.subtext` is the documented misuse for stats that belong in the tooltip.
+ * - `legend` defaults to `{ bottom: 0 }` for a multi-series chart and `{ show: false }` for a
+ *   single-series one (nothing to disambiguate); an authored legend is left alone.
+ * - `grid` (cartesian charts only) gets `top` 8% — 12% when a `graphic` annotation shares the canvas
+ *   — `bottom` 20% / 25% (rotated labels) / 30% (rotated labels above a bottom legend), `left` 10%,
+ *   `right` 5%. Only unset keys are filled.
+ * - `axisLabel.interval` is pinned to `0` on every axis; the x axis is rotated 45° (11–20 categories)
+ *   or 90° (>20) unless the author chose a rotation.
+ * - `toolbox.feature.saveAsImage` is injected with `type: "png"` and a kebab-case filename derived
+ *   from the `show_user` title (falling back to the stripped in-spec title, then `"chart"`).
+ */
+export function normalizeEchartSpec(spec, opts = {}) {
+    const { title: specTitle, ...out } = spec;
+    // ── Legend ──────────────────────────────────────────────────────────
+    const legendAuthored = out.legend !== undefined && out.legend !== null;
+    if (!legendAuthored) {
+        const count = seriesCount(out);
+        if (count >= 2)
+            out.legend = { bottom: 0 };
+        // A single series has nothing to disambiguate: hide it explicitly rather than omit it, so a
+        // themed legend component cannot reintroduce an orphan swatch. An undeclared series count
+        // (0) gets no legend option at all — there is nothing to show or hide.
+        else if (count === 1)
+            out.legend = { show: false };
+    }
+    const bottomLegend = isBottomLegend(out.legend);
+    // ── Axis labels ─────────────────────────────────────────────────────
+    const rotate = rotationFor(categoryCount(out));
+    let rotated = false;
+    // Rotation is an x-axis rule: turning a horizontal bar chart's y-axis category labels on their
+    // side would be actively wrong, so only `interval` crosses to the y axis (where it is inert on a
+    // value axis and prevents silent label-skipping on a category one).
+    const normalizeAxis = (axis, isX) => {
+        const axisLabel = isRecord(axis.axisLabel) ? { ...axis.axisLabel } : {};
+        axisLabel.interval = 0;
+        if (isX && rotate !== null && axisLabel.rotate === undefined)
+            axisLabel.rotate = rotate;
+        if (isX && typeof axisLabel.rotate === "number" && axisLabel.rotate !== 0)
+            rotated = true;
+        return { ...axis, axisLabel };
+    };
+    for (const key of ["xAxis", "yAxis"]) {
+        const axis = out[key];
+        // A malformed entry is passed through rather than dropped — normalization rewrites layout,
+        // never the shape of the spec it was handed.
+        if (Array.isArray(axis))
+            out[key] = axis.map((entry) => (isRecord(entry) ? normalizeAxis(entry, key === "xAxis") : entry));
+        else if (isRecord(axis))
+            out[key] = normalizeAxis(axis, key === "xAxis");
+    }
+    // ── Grid ────────────────────────────────────────────────────────────
+    const cartesian = out.xAxis !== undefined || out.yAxis !== undefined;
+    const grid = out.grid;
+    // An array of grids, or a grid the author sized explicitly (`width`/`height`): a margin added on
+    // top of an explicit box could over-constrain it. Non-cartesian charts (pie, sunburst, graph)
+    // have no grid to lay out.
+    const gridNormalizable = cartesian && !Array.isArray(grid) && (grid === undefined || (isRecord(grid) && grid.width === undefined && grid.height === undefined));
+    if (gridNormalizable) {
+        const authored = isRecord(grid) ? grid : {};
+        out.grid = {
+            ...authored,
+            ...(authored.top === undefined ? { top: out.graphic !== undefined ? "12%" : "8%" } : {}),
+            ...(authored.bottom === undefined ? { bottom: rotated ? (bottomLegend ? "30%" : "25%") : "20%" } : {}),
+            ...(authored.left === undefined ? { left: "10%" } : {}),
+            ...(authored.right === undefined ? { right: "5%" } : {}),
+        };
+    }
+    // ── Toolbox ─────────────────────────────────────────────────────────
+    if (!Array.isArray(out.toolbox)) {
+        const authored = isRecord(out.toolbox) ? out.toolbox : {};
+        const feature = isRecord(authored.feature) ? authored.feature : {};
+        const saveAsImage = isRecord(feature.saveAsImage) ? feature.saveAsImage : {};
+        // The in-spec title is stripped, but it is still the author's own description of the chart —
+        // a better filename seed than the generic fallback when no card title was given.
+        const specTitleText = isRecord(specTitle) && typeof specTitle.text === "string" ? specTitle.text : undefined;
+        out.toolbox = {
+            ...authored,
+            ...(hasPlacement(authored) ? {} : { right: 0, top: 0 }),
+            feature: {
+                ...feature,
+                saveAsImage: {
+                    ...saveAsImage,
+                    ...(saveAsImage.type === undefined ? { type: "png" } : {}),
+                    ...(saveAsImage.name === undefined ? { name: kebabFilename(opts.title ?? specTitleText) } : {}),
+                },
+            },
+        };
+    }
+    return out;
+}

package/dist/tools/display/show-user.d.ts

@@ -9,6 +9,11 @@
  * downstream reconciliation concern of the emit pipeline (change 3), not a
  * per-request `Set` smuggled through an ambient context bag.
  *
+ * An `echart` spec's layout is normalized (`normalize-echart-spec.ts`) inside
+ * `buildPresentationCardData`, the one construction site both this tool and the
+ * reconstruct-on-read path share — the model authors the data, the renderer owns
+ * the layout.
+ *
  * For stored plans, use `show_plan`. For existing files, use `show_file`.
  */
 type ShowUserOutput = {
@@ -18,7 +23,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "echart" | "markdown" | "svg" | "table";
+    kind: "code" | "markdown" | "echart" | "svg" | "table";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

package/dist/tools/display/show-user.js

@@ -9,6 +9,11 @@
  * downstream reconciliation concern of the emit pipeline (change 3), not a
  * per-request `Set` smuggled through an ambient context bag.
  *
+ * An `echart` spec's layout is normalized (`normalize-echart-spec.ts`) inside
+ * `buildPresentationCardData`, the one construction site both this tool and the
+ * reconstruct-on-read path share — the model authors the data, the renderer owns
+ * the layout.
+ *
  * For stored plans, use `show_plan`. For existing files, use `show_file`.
  */
 import { ok } from "neverthrow";
@@ -22,12 +27,18 @@ import { validatePath } from "../lib/path-validation.js";
 // LLM picks the right ones based on `kind`.
 const ShowUserInputSchema = z.object({
     kind: z.enum(["echart", "markdown", "code", "svg", "table"]).describe("The type of agent-synthesized content to display"),
-    title: z.string().optional().describe("Title shown above the content"),
-    spec: z.record(z.string(), z.unknown()).optional().describe("Full ECharts option spec as JSON (kind=echart)"),
+    title: z
+        .string()
+        .optional()
+        .describe("Card heading rendered above the content. For an echart it is the chart's only title, and it seeds the PNG download filename."),
+    spec: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Full ECharts option JSON (kind=echart). Author the data, series, `encode`, and tooltip — and OMIT `title`: the card heading is the `title` param, so an in-spec title is stripped (put stats in `tooltip.formatter`, never in `title.subtext`). Layout is normalized for you at render time (legend placement, grid margins, `axisLabel.interval`/rotation, and a PNG `saveAsImage` toolbox), so do not hand-tune it."),
     dataPath: z
         .string()
         .optional()
-        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names and omit `dataset.source` from the spec — the data is never pulled through the context window."),
+        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names (read only its header) and omit `dataset.source` from the spec — the rows are never pulled through the context window. If the data is not chart-ready (needs aggregation, filtering, reshaping), do that in a sandbox step that writes a chart-ready CSV. Inline `dataset.source` is only for a handful of numbers you just computed in conversation that exist nowhere as an artifact."),
     body: z.string().optional().describe("Markdown content to render (kind=markdown)"),
     code: z.string().optional().describe("Code content (kind=code)"),
     language: z.string().optional().describe("Language identifier, e.g. r, python, bash (kind=code)"),
@@ -38,15 +49,17 @@ const ShowUserInputSchema = z.object({
 });
 export const showUserTool = defineTool({
     id: "show_user",
-    description: "Display agent-synthesized content to the user: ECharts visualizations, " +
-        "markdown, code blocks, SVG diagrams, or tables. " +
-        "Use for content you are INVENTING (a chart you just built, a code snippet you are proposing, " +
-        "a markdown synthesis, a table you constructed). " +
-        "For an echart backed by a chart-ready CSV artifact a step already wrote, pass `dataPath` (analysis-rooted) " +
-        "and author `encode`/dimensions by column name with no `dataset.source` — the host loads the CSV as the " +
-        "dataset at render time, so you never inline the rows. " +
-        "For stored plans, use `show_plan`. For existing analysis files (images, CSVs, etc.), use `show_file`. " +
-        "Call once per distinct content item; an identical repeat call resolves to the same card.",
+    description: "Display content you are INVENTING — a chart you composed, a code snippet you are proposing, a markdown " +
+        "synthesis, an SVG diagram, a table you built. The content is inlined on the wire. " +
+        "Pick this tool by what you are referencing, not by how the output looks: " +
+        "NOT for an existing analysis file — never read an artifact and paste its bytes here, reference it with `show_file` " +
+        "(images, CSVs, PDFs, notebooks). NOT for a stored plan — use `show_plan`. " +
+        "NEVER put markdown image syntax pointing at a workspace file in a `markdown` body: `![](runs/.../volcano.png)` " +
+        "renders as a broken image, because the chat UI cannot resolve workspace-relative paths. To interleave figures " +
+        "with prose (a write-up, a narrative summary), emit a SEQUENCE of cards in display order — `show_user(markdown)` " +
+        "for a prose section, then `show_file` for the figures that follow it, and so on — instead of one monolithic card. " +
+        "One card per call, rendered in call order; an identical repeat call resolves to the same card, so compose the " +
+        "finished content before calling rather than re-rendering a draft.",
     inputSchema: ShowUserInputSchema,
     execute: async (input, ctx) => {
         // `dataPath` is a reference the host resolves at render time; validate its

package/dist/tools/execute-plan.js

@@ -32,7 +32,6 @@ import { buildRunCardData } from "../memory/card-builders.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { validatePlan } from "../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
-import { renderStepPrompt } from "../schemas/render-step-prompt.js";
 import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, updateRunStatus } from "../state/index.js";
 import { defineTool } from "./define-tool.js";
 const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
@@ -177,7 +176,11 @@ export function createExecutePlanTool(deps) {
                     id: s.id,
                     depends_on: s.depends_on ?? [],
                 })),
-                promptByStepId: Object.fromEntries(plan.steps.map((s) => [s.id, renderStepPrompt(s)])),
+                // The step DATA, not a rendered prompt: each step's seed is composed
+                // by the scheduler at dispatch, when its dependencies' results exist.
+                // A prompt frozen here — before the first step has run — could never
+                // mention them.
+                planStepById: Object.fromEntries(plan.steps.map((s) => [s.id, s])),
                 agentByStepId: Object.fromEntries(plan.steps.map((s) => [s.id, s.agent ?? "unknown"])),
                 resourcesByStepId: Object.fromEntries(plan.steps.map((s) => {
                     if (!s.resources) {

package/dist/tools/iterate-report.d.ts

@@ -1,23 +1,43 @@
 /**
- * iterate_report — creates or iterates on a report.
+ * Report authoring tools for the conversation agent: `plan_report` + `submit_report`.
  *
- * Two modes:
- *  - Creation (v1): pass `report` with title/audience/sources/sections.
- *    Pre-flight stages every source into the preview's assets/ dir,
- *    enriches the brief with kind/size/columns/headRows/rowCount, and
- *    hands the report-builder agent a complete brief — no discovery, no
- *    staging in the LLM loop.
- *  - Iteration (v2+): pass `modifications` (natural language) with the
- *    existing `previewId`. Optional top-level `sources` adds new assets
- *    on top of the existing assets/ dir.
+ * WHY TWO TOOLS. The report brief (title/audience/sources plus the section
+ * union — narrative/metrics/figure/table/chart, each with its own
+ * encoding/transform/asset sub-fields) is a ~12k-char JSON schema. Every
+ * registered tool's schema ships on EVERY conversation turn, so parking that
+ * brief on an always-on tool would tax every turn for a tool used only when a
+ * report is actually built. We split the single former tool in two and deliver
+ * the heavy schema just-in-time:
  *
- * Emits a `data-report-preview` chat data part on success or `data-report-preview-failed`
- * on pre-flight or builder failure. The hosted preview surface is reached
- * through an injected `PreviewPublisher` seam (managed default mints a
- * short-lived run-authorization grant; local default returns "unavailable").
+ *  - `plan_report` — a tiny, always-on trigger (no-arg). Its `execute` RETURNS
+ *    the brief schema (`z.toJSONSchema(ReportBriefSchema)`) plus the authoring
+ *    rules as its tool RESULT, so the full contract enters context only on a
+ *    report-building turn — and thereafter rides in the cached history prefix,
+ *    not at full price on every request.
+ *  - `submit_report` — takes the composed brief and does the real work
+ *    (pre-flight staging, previewId/versioning, `runReportIteration`, preview
+ *    publishing). It accepts the brief as `unknown` so the 12k schema stays off
+ *    the always-on surface, then validates it against `ReportBriefSchema` INSIDE
+ *    `execute`, returning `{ ok: false, issues }` as DATA the model can fix (not
+ *    a thrown error). That is the same trade `validate_plan` makes: a runtime
+ *    contract in exchange for keeping the schema out of every request. The small
+ *    iterate-mode + common fields (modifications / previewId / baseVersion /
+ *    sources / format) stay fully typed — they cost little and guide iteration.
  *
- * The 4 custom report tools the builder drives are constructed inside
- * `runReportIteration` — see design.md Decision #9.
+ * On a valid brief, `submit_report`'s behaviour is identical to the former
+ * `iterate_report`: two modes (Create v1 via `report`; Iterate v2+ via
+ * `modifications` + `previewId`), pre-flight stages every source into the
+ * preview's assets/ dir, and it emits a `data-report-preview` chat data part on
+ * success or `data-report-preview-failed` on pre-flight/builder failure. The
+ * hosted preview surface is reached through an injected `PreviewPublisher` seam
+ * (managed default mints a short-lived run-authorization grant; local default
+ * returns "unavailable"). The 4 custom report tools the builder drives are
+ * constructed inside `runReportIteration` — see design.md Decision #9.
+ *
+ * Naming note: the report-builder SUB-agent has its OWN same-id `submit_report`
+ * terminal tool (`tools/report/submit-report.ts`). The two never share a tool
+ * roster — this one is the conversation agent's brief-submission entry point;
+ * that one is the builder's finalize gate.
  */
 import type { Pool } from "pg";
 import { z } from "zod";
@@ -27,119 +47,145 @@ import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type StagedAsset } from "./lib/report-preflight.js";
 import type { PreviewPublisher } from "./report/preview-publisher.js";
 import type { ChromeConfig } from "../lib/chrome.js";
-/** Exported for schema-validation tests — the underlying Zod schema. */
-export declare const iterateReportInputSchema: z.ZodObject<{
+import type { Logger } from "../lib/logger.js";
+/**
+ * The report brief the conversation agent composes: title/audience + sources +
+ * the section union. This is the ~12k-char schema that `plan_report` hands back
+ * just-in-time and that `submit_report` validates its `report` field against
+ * inside `execute`. Exported for `plan_report`, `submit_report`, and the
+ * brief-shape tests.
+ */
+export declare const ReportBriefSchema: z.ZodObject<{
+    title: z.ZodString;
+    audience: z.ZodString;
+    styleGuidance: z.ZodOptional<z.ZodString>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        as: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sections: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"narrative">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            prose: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"metrics">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            stats: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                unit: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"figure">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            imageAsset: z.ZodString;
+            caption: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"table">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            dataAsset: z.ZodString;
+            columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            topN: z.ZodOptional<z.ZodNumber>;
+            sortBy: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                order: z.ZodEnum<{
+                    desc: "desc";
+                    asc: "asc";
+                }>;
+            }, z.core.$strip>>;
+            transform: z.ZodOptional<z.ZodString>;
+            caption: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"chart">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            dataAsset: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodObject<{
+                columns: z.ZodArray<z.ZodString>;
+                rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>;
+                source: z.ZodString;
+            }, z.core.$strip>>;
+            chartType: z.ZodEnum<{
+                line: "line";
+                bar: "bar";
+                scatter: "scatter";
+                histogram: "histogram";
+                box: "box";
+                heatmap: "heatmap";
+                pie: "pie";
+            }>;
+            encoding: z.ZodObject<{
+                x: z.ZodOptional<z.ZodString>;
+                y: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                group: z.ZodOptional<z.ZodString>;
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            topN: z.ZodOptional<z.ZodNumber>;
+            sortBy: z.ZodOptional<z.ZodObject<{
+                column: z.ZodString;
+                order: z.ZodEnum<{
+                    desc: "desc";
+                    asc: "asc";
+                }>;
+            }, z.core.$strip>>;
+            transform: z.ZodOptional<z.ZodString>;
+            caption: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"methods">;
+        title: z.ZodString;
+        intent: z.ZodString;
+        content: z.ZodObject<{
+            prose: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+/**
+ * `submit_report`'s always-on input surface. The heavy brief rides in `report`
+ * as `unknown` — typed that way ON PURPOSE so the ~12k `ReportBriefSchema` does
+ * NOT ship on every conversation turn; `execute` validates it against
+ * `ReportBriefSchema` and returns issues as data. The iterate-mode + common
+ * fields stay fully typed (they are small and guide iteration). Exported for
+ * the envelope-validation tests.
+ */
+export declare const submitReportInputSchema: z.ZodObject<{
     previewId: z.ZodOptional<z.ZodString>;
     baseVersion: z.ZodOptional<z.ZodNumber>;
     format: z.ZodDefault<z.ZodEnum<{
         html: "html";
         pdf: "pdf";
     }>>;
-    report: z.ZodOptional<z.ZodObject<{
-        title: z.ZodString;
-        audience: z.ZodString;
-        styleGuidance: z.ZodOptional<z.ZodString>;
-        sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            path: z.ZodString;
-            as: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        sections: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            type: z.ZodLiteral<"narrative">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                prose: z.ZodString;
-            }, z.core.$strip>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"metrics">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                stats: z.ZodArray<z.ZodObject<{
-                    label: z.ZodString;
-                    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
-                    unit: z.ZodOptional<z.ZodString>;
-                }, z.core.$strip>>;
-            }, z.core.$strip>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"figure">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                imageAsset: z.ZodString;
-                caption: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"table">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                dataAsset: z.ZodString;
-                columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                topN: z.ZodOptional<z.ZodNumber>;
-                sortBy: z.ZodOptional<z.ZodObject<{
-                    column: z.ZodString;
-                    order: z.ZodEnum<{
-                        desc: "desc";
-                        asc: "asc";
-                    }>;
-                }, z.core.$strip>>;
-                transform: z.ZodOptional<z.ZodString>;
-                caption: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"chart">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                dataAsset: z.ZodOptional<z.ZodString>;
-                data: z.ZodOptional<z.ZodObject<{
-                    columns: z.ZodArray<z.ZodString>;
-                    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>;
-                    source: z.ZodString;
-                }, z.core.$strip>>;
-                chartType: z.ZodEnum<{
-                    line: "line";
-                    bar: "bar";
-                    scatter: "scatter";
-                    histogram: "histogram";
-                    box: "box";
-                    heatmap: "heatmap";
-                    pie: "pie";
-                }>;
-                encoding: z.ZodObject<{
-                    x: z.ZodOptional<z.ZodString>;
-                    y: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-                    group: z.ZodOptional<z.ZodString>;
-                    value: z.ZodOptional<z.ZodString>;
-                }, z.core.$strip>;
-                topN: z.ZodOptional<z.ZodNumber>;
-                sortBy: z.ZodOptional<z.ZodObject<{
-                    column: z.ZodString;
-                    order: z.ZodEnum<{
-                        desc: "desc";
-                        asc: "asc";
-                    }>;
-                }, z.core.$strip>>;
-                transform: z.ZodOptional<z.ZodString>;
-                caption: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>;
-        }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"methods">;
-            title: z.ZodString;
-            intent: z.ZodString;
-            content: z.ZodObject<{
-                prose: z.ZodString;
-            }, z.core.$strip>;
-        }, z.core.$strip>], "type">>;
-    }, z.core.$strip>>;
+    report: z.ZodOptional<z.ZodUnknown>;
     modifications: z.ZodOptional<z.ZodString>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         as: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-export interface IterateReportDeps {
+/**
+ * `plan_report` — the tiny, always-on trigger (no args). Its result delivers
+ * the brief schema + authoring rules just-in-time, so the ~12k contract enters
+ * context only on a report-building turn (and thereafter rides in the cached
+ * history prefix). Compose the brief from what it returns, then call
+ * `submit_report`. Pure logic, no deps — hence a module-scope leaf tool.
+ */
+export declare const planReportTool: Tool;
+export interface SubmitReportDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     /** Embedder-supplied workspace-root resolution seam (see workspace/paths.ts). */
@@ -165,7 +211,14 @@ export interface IterateReportDeps {
         ttlSeconds: number;
     }) => Promise<PreviewPublisher>;
 }
-export declare function createIterateReportTool(deps: IterateReportDeps): Tool;
+/**
+ * `submit_report` — takes the composed brief and drives the report iteration.
+ * On a valid brief its behaviour is byte-for-byte the former `iterate_report`:
+ * pre-flight staging, previewId/versioning, `runReportIteration`, preview
+ * publishing. The brief rides as `unknown` on the wire (keeping its ~12k schema
+ * off the always-on surface) and is validated against `ReportBriefSchema` here.
+ */
+export declare function createReportSubmitTool(deps: SubmitReportDeps): Tool;
 /** Exported for unit tests — pipe-escape correctness. */
 export declare function stagedAssetsBlock(staged: StagedAsset[], opts?: {
     newOnly?: boolean;