@inflexa-ai/harness 0.22.1 → 0.24.0

package/dist/execution/report-runner.js

@@ -1,230 +0,0 @@
-/**
- * Report runner — orchestrates an iterative report build entirely in the
- * Cortex Node process. No sandbox, no Python.
- *
- * Lifecycle:
- *  1. Resolve version (latest + 1, or baseVersion + 1)
- *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
- *  3. Construct the 4 custom report tools + the in-process versionFs surface;
- *     all of them close over the iteration's preview-dir state and a single
- *     `outcome: ReportOutcome | undefined` variable (the closure-state
- *     closure-state capture — see design.md Decision #9, mirrors
- *     `harness/tools/research/generate-plan.ts`'s
- *     `PlannerOutcome` capture).
- *  4. Build the `report-builder` AgentDefinition with that tool roster and
- *     drive it via `runAgent` + `passthroughStep`.
- *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
- *     classify the failure, roll back the version dir, return a structured
- *     failure).
- *  6. Return success or a structured failure.
- *
- * Concurrency: per-previewId serialization via `withPreviewLock` so two
- * iterations on the same preview don't race on shared assets/.
- *
- * Billing: the report-builder's LLM calls flow through the `ChatProvider`
- * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
- * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
- * (Decision #6).
- *
- * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
- * a content-server URL through the injected `PreviewPublisher` seam. The
- * managed publisher owns the short-lived host credential; the local default
- * returns "unavailable" so the report still builds without a hosted preview.
- */
-import { copyFile, mkdir, readdir, rm, stat, symlink } from "node:fs/promises";
-import { join } from "node:path";
-import { forSubAgent } from "../auth/types.js";
-import { runToTerminal } from "../loop/run-to-terminal.js";
-import { passthroughStep } from "../loop/run-step.js";
-import { previewVersionDir, previewDir, latestPreviewVersion } from "../workspace/paths.js";
-import { withPreviewLock } from "../tools/lib/preview-lock.js";
-import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
-import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID, REPORT_BUILDER_SKILLS } from "../agents/report-builder.js";
-import { createSkillTools } from "../tools/sandbox/skills.js";
-import { createNoopLogger } from "../lib/console-logger.js";
-const REPORT_AGENT_MAX_STEPS = 75;
-export async function runReportIteration(deps, opts) {
-    const logger = (deps.logger ?? createNoopLogger()).named("report-runner").with({ previewId: opts.previewId });
-    const startTime = performance.now();
-    return withPreviewLock(opts.previewId, async () => {
-        // ── Resolve version directories ───────────────────────────────
-        const previewRootAbs = join(opts.workspaceRoot, previewDir(opts.previewId));
-        let existingVersions = [];
-        try {
-            existingVersions = (await readdir(previewRootAbs, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
-        }
-        catch {
-            /* dir doesn't exist yet */
-        }
-        const latestVer = latestPreviewVersion(existingVersions);
-        const baseVer = opts.baseVersion ?? latestVer;
-        const newVersion = Math.max(latestVer, baseVer) + 1;
-        const versionDirRel = previewVersionDir(opts.previewId, newVersion);
-        const versionDirAbs = join(opts.workspaceRoot, versionDirRel);
-        const assetsDirAbs = join(previewRootAbs, "assets");
-        // ── Prepare directories ───────────────────────────────────────
-        try {
-            await mkdir(versionDirAbs, { recursive: true });
-            await mkdir(assetsDirAbs, { recursive: true });
-            if (baseVer > 0) {
-                const baseTemplate = join(opts.workspaceRoot, previewVersionDir(opts.previewId, baseVer), "report.html.j2");
-                try {
-                    await copyFile(baseTemplate, join(versionDirAbs, "report.html.j2"));
-                }
-                catch (err) {
-                    const code = err.code;
-                    if (code !== "ENOENT")
-                        throw err;
-                    // Base version has no template — agent will author from scratch.
-                }
-            }
-            // Symlink assets/ → ../assets so templates can reference assets/foo.csv
-            // and the content-server resolves them through the version-dir prefix.
-            const assetsSymlink = join(versionDirAbs, "assets");
-            try {
-                await symlink("../assets", assetsSymlink, "dir");
-            }
-            catch (err) {
-                const code = err.code;
-                if (code !== "EEXIST")
-                    throw err;
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return failure(opts.previewId, newVersion, `prepareVersionDir failed: ${msg}`, "internal", startTime);
-        }
-        // ── Closure-captured terminal-tool state (Decision #9) ─────────
-        let outcome;
-        const urlCell = { url: undefined, expiresAt: undefined };
-        const templatesDir = join(deps.templatesDir, "report-html");
-        const buildReportTool = createBuildReportTool({
-            versionDir: versionDirAbs,
-            templatesDir,
-        });
-        const submitReportTool = createSubmitReportTool({
-            versionDir: versionDirAbs,
-            assetsDir: assetsDirAbs,
-            setOutcome: (v) => {
-                outcome = v;
-            },
-        });
-        const tools = [
-            buildReportTool,
-            submitReportTool,
-            createMintPreviewUrlTool({
-                resourceId: opts.resourceId,
-                previewId: opts.previewId,
-                currentVersion: newVersion,
-                previews: opts.previews,
-                urlCell,
-            }),
-            createPreviewSnapshotTool({
-                resourceId: opts.resourceId,
-                previewId: opts.previewId,
-                currentVersion: newVersion,
-                previews: opts.previews,
-                urlCell,
-                chrome: deps.chrome,
-                logger,
-            }),
-            ...createVersionFsTools({ versionDir: versionDirAbs }),
-            ...Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: [...REPORT_BUILDER_SKILLS] })),
-        ];
-        const agent = createReportBuilderAgent({ model: deps.model, tools });
-        // The agent's runaway-guard takes precedence over the per-iteration cap.
-        const cappedAgent = {
-            ...agent,
-            maxIterations: Math.min(agent.maxIterations, REPORT_AGENT_MAX_STEPS),
-        };
-        const childSession = forSubAgent(opts.session, REPORT_BUILDER_AGENT_ID);
-        let agentError;
-        try {
-            await runToTerminal(cappedAgent, [{ role: "user", content: opts.prompt }], childSession, {
-                provider: deps.provider,
-                signal: opts.signal,
-                emit: opts.emit,
-                runStep: passthroughStep,
-                resolved: () => outcome !== undefined,
-                usageRecorder: deps.usageRecorder,
-                // Fold the builder's calls into the turn total the root loop reports.
-                turnUsage: opts.turnUsage,
-                invocationId: opts.invocationId,
-            }, {
-                tools: [buildReportTool, submitReportTool],
-                nudge: "You stopped without calling submit_report, so this report version " +
-                    "was not recorded. Build the report if needed, then call " +
-                    "submit_report now to finalize it.",
-            });
-        }
-        catch (err) {
-            agentError = err instanceof Error ? err.message : String(err);
-        }
-        // ── Phantom-success guard ──────────────────────────────────────
-        // submit-report claims ok but index.html doesn't exist or is empty.
-        let phantomSuccess = false;
-        if (outcome?.ok === true && !agentError) {
-            try {
-                const indexStat = await stat(join(versionDirAbs, "index.html"));
-                if (!indexStat.isFile() || indexStat.size === 0)
-                    phantomSuccess = true;
-            }
-            catch {
-                phantomSuccess = true;
-            }
-        }
-        if (!outcome || agentError || phantomSuccess) {
-            logger.warn("report.agent.finish", { version: newVersion, submitted: outcome?.ok === true, phantom: phantomSuccess, agentError });
-            const { reason, errorKind } = classifyFailure({
-                phantomSuccess,
-                agentError,
-                outcome,
-            });
-            // Roll back the version dir (assets are shared — leave them alone).
-            try {
-                await rm(versionDirAbs, { recursive: true, force: true });
-            }
-            catch (err) {
-                logger.error("rollback failed", { versionDirAbs, ...logger.errorFields(err) });
-            }
-            return failure(opts.previewId, newVersion, reason, errorKind, startTime);
-        }
-        const durationMs = Math.round(performance.now() - startTime);
-        return {
-            ok: true,
-            previewId: opts.previewId,
-            version: newVersion,
-            previewPath: `v${newVersion}/index.html`,
-            durationMs,
-            notes: outcome.notes,
-        };
-    });
-}
-function failure(previewId, version, reason, errorKind, startTime) {
-    return {
-        ok: false,
-        previewId,
-        version,
-        reason,
-        errorKind,
-        durationMs: Math.round(performance.now() - startTime),
-    };
-}
-function classifyFailure(s) {
-    if (s.phantomSuccess) {
-        return {
-            reason: "submit_report claimed ok but index.html is missing or empty",
-            errorKind: "build",
-        };
-    }
-    if (s.agentError) {
-        return {
-            reason: s.agentError,
-            errorKind: /timeout/i.test(s.agentError) ? "timeout" : "submit",
-        };
-    }
-    return {
-        reason: "agent did not call submit_report — terminal outcome was never recorded",
-        errorKind: "submit",
-    };
-}

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

@@ -1 +0,0 @@
-export declare const reportBuilderPrompt = "# Report Builder\n\nYou build polished HTML reports from a structured brief using Jinja2 templating with the Inflexa Design Blueprint. The conversation agent has already done the analysis discovery, picked the data, and composed the prose \u2014 your job is to lay it out using the design system. Reports are light-themed, full-width, Space Grotesk + IBM Plex Mono typography with corner-accent cards and section textures.\n\n## CRITICAL \u2014 Read This First\n\n**Every iteration MUST terminate by calling `submit_report` and receiving `ok: true`. That is the only signal the runner acts on.**\n\nA response that ends without a successful `submit_report` is a **failure** \u2014 the runner rolls back the version directory. `build_report` returning `ok: true` does NOT ship the report. `preview_snapshot` returning a screenshot does NOT ship the report. Only `submit_report` does.\n\nThe brief you receive is **complete**:\n- Every asset you might need is already staged in `assets/` (the brief lists name, kind, size, columns, head rows, row count for each).\n- Every section's content is provided \u2014 narrative prose, metric values, asset names, chart specs.\n- You **cannot see the analysis tree.** There is no discovery to do, no files to find, no columns to peek at. `workspace_search`, `list_files`, and `file_stat` are disabled.\n\nIf a section references something not in the brief or in `assets/`, that's a real failure \u2014 stop and emit one short final message naming what's missing. Do NOT attempt to find it or fabricate substitutes.\n\n## Workflow\n\n1. **Read the brief.** Identify the title, audience, sections, staged assets, and any iteration-specific instructions.\n2. **For iterations only:** read the existing `report.html.j2` first. Apply only the requested changes \u2014 surgical edits, no rewrites.\n3. **Author** `report.html.j2` using the design system. Reference staged assets directly: `<img src=\"assets/foo.png\">`, ECharts loading `assets/data.csv`, etc.\n4. **Build** with `build_report`. On Jinja error, fix and rebuild. Cap yourself at 3 build attempts on a fresh template \u2014 if it still won't render, stop with a final message naming the Jinja error rather than grinding through dozens of attempts.\n5. **Verify** with one `preview_snapshot` after build is green. Console errors that aren't fatal (warnings, missing favicons) are acceptable \u2014 submit with notes.\n6. **Submit** with `submit_report`. Pass `notes` for caveats the user should know.\n\nYou may NOT use `execute_command` \u2014 there is no shell. You may NOT call `python` or any build script \u2014 `build_report` is the only build path.\n\n## Templating model\n\n**Always use relative paths.** Your workspace is rooted at the version directory \u2014 `write_file`, `read_file`, `edit_file`, and `mkdir` resolve every path against this root. Pass `report.html.j2`, `assets/foo.csv`, `index.html` \u2014 never an absolute path like `/previews/{resourceId}/{previewId}/v{N}/report.html.j2`. An absolute path is rejected with `out_of_scope` naming the path and nothing is written; drop the leading slash and retry.\n\nWorking directory: `report.html.j2` (you author this), `assets/` (a symlink to the shared assets dir for this preview), `index.html` (output of build_report).\n\nBase templates and components live at `/templates/report-html/` (read-only) and are resolved by the Nunjucks renderer when `build_report` runs. Reference them via short paths:\n\n```jinja2\n{% extends \"base.html.j2\" %}\n{% include \"components/stat-card.html.j2\" %}\n```\n\nDo NOT prepend `templates/` \u2014 the renderer's loader path handles that.\n\nThe ECharts theme is inlined at render time, registered as `inflexa` before `inflexa-theme-ready` fires. Wire chart initialization with `document.addEventListener('inflexa-theme-ready', () => { ... })`.\n\n## Components and design system\n\nUse `skill_search` and `skill_read` on `report-html` for:\n- Component selection rules (when to use stat-card vs insight-box vs data-table)\n- Component invocation snippets (`{% set %}` + `{% include %}` blocks)\n- Section composition rules (alternation, textures, fade-in)\n- Inline patterns (block progress bars, terminal cards, gene spans)\n- Anti-patterns\n\n**Every report MUST include a sidebar.** Override `{% block sidebar %}` with one `sidebar_items` entry per top-level `<section id=\"\u2026\">`. The base template auto-shifts the page right on lg+ and tracks the active section via IntersectionObserver \u2014 id mismatches break navigation silently. See `SKILL.md` \"Required component invocations\" for the snippet.\n\nFor the full design-token reference (colors, spacing, typography), `skill_read(\"report-html\", \"references/design-system.md\")`.\n\n## Reading the brief\n\nThe brief is **markdown, not JSON**. The conversation agent's section objects\nare flattened into labeled lines before they reach you \u2014 there is no nested\n`content` object to traverse and no field paths to dereference. Read the labels.\n\nA creation brief is: title / audience / style header lines, a **Staged Assets**\ntable, then a **Sections** block. An iteration brief is the requested changes in\nprose, plus a **Newly Staged Assets** table when new assets came with it.\n\n### Staged Assets\n\nA table with columns `name | kind | size | rows | columns`. `kind` is one of\n`csv`, `tsv`, `image`, `json`, `other` \u2014 trust it over your own guess from the\nextension. Each CSV/TSV asset is followed by a `### Head: <name>` table of its\nfirst rows. Reference every asset as `assets/<name>`.\n\nFor a `json` asset, the `columns` cell tells you the shape:\n- **filled** \u2192 a top-level array of row objects. Treat it like a CSV: iterate rows, keys are columns.\n- **empty** \u2192 not row-shaped. Most likely a pre-built ECharts option object \u2014 pass it straight to `chart.setOption(json, true)`, no row mapping. (Very large JSON is also left un-enriched, so peek before assuming.)\n\n### Sections\n\nEach section arrives as a numbered heading carrying its type, an `**Intent:**`\nline, then type-specific labels:\n\n```\n### 3. Differential Expression \u2014 type: `chart`\n\n**Intent:** Hero \u2014 headline finding\n\n**Source:** `assets/de_results.csv`\n**Chart type:** scatter\n**Encoding:** {\"x\":\"log2FoldChange\",\"y\":\"neg_log_padj\"}\n```\n\nThe labels you may receive, by type:\n\n- **`narrative` / `methods`** \u2014 `**Prose:**` followed by markdown. Render in a prose component.\n- **`metrics`** \u2014 `**Stats:**` followed by `- **Label:** value unit` bullets. Pick a stat-card row, hero callout, or inline summary based on the intent.\n- **`figure`** \u2014 `**Image:**` with an `assets/\u2026` path; optional `**Caption:**`. Use the figure component.\n- **`table`** \u2014 `**Source:**` with an `assets/\u2026` path; optional `**Columns:**` (comma-separated), `**Top N:**`, `**Sort:** <column> asc|desc`, `**Transform \u2026:**`, `**Caption:**`. Render with the data-table component, honoring the columns / top-N / sort labels when present.\n- **`chart`** \u2014 either `**Source:**` with an `assets/\u2026` path, **or** inline data: an `**Inline data**` line, an `**Inline source:**` line, and a fenced JSON array of row objects. Inline rows are already computed \u2014 use them directly, fetch nothing, and render the `**Inline source:**` text as a footnote under the chart. Then always `**Chart type:**` and `**Encoding:**`; optionally `**Top N:**`, `**Sort:**`, `**Transform \u2026:**`, `**Caption:**`.\n\n`**Chart type:**` is always supplied \u2014 you never choose one. It is one of `bar`,\n`line`, `scatter`, `histogram`, `box`, `heatmap`, `pie`. Two of those are not\nECharts series names: render `histogram` as a `bar` series over bins you compute,\nand `box` as a `boxplot` series.\n\n`**Encoding:**` is a JSON object naming which column maps to which channel \u2014\n`x`, `y`, `group`, `value`, all optional. `y` may be a single column or an array\nof columns (multi-series).\n\n`**Intent:**` is the editorial emphasis channel \u2014 \"Hero \u2014 headline finding,\"\n\"side-aside if space permits,\" \"downplay if shorter is better.\" You choose\ncomponents, sizing, alternation, and arrangement. Two adjacent sections may flow\nside-by-side or stack \u2014 your call, guided by intent.\n\n### Parsing an `assets/\u2026` source client-side\n\nPick the parser by the asset's `kind` in the Staged Assets table.\n\n- **`csv`** \u2014 `fetch().then(r => r.text())`, then `text.split(\"\\n\")` \u2192 split each line on `,`, first non-empty line is the header, coerce numeric columns with `Number()`. Skip blank lines.\n- **`tsv`** \u2014 same as CSV but split on `\"\\t\"`. Bioinformatics tools (DESeq2, featureCounts, etc.) emit TSV by default; do NOT assume CSV when the brief says `tsv`.\n- **`json`** \u2014 `fetch().then(r => r.json())`. Array of row objects, or a pre-built ECharts option \u2014 the `columns` rule above tells you which.\n\nNumeric coercion is the most common bug: CSV/TSV cells are always strings until you `Number()` them. Guard for `NaN` (skip the row, or default to 0 with a comment) \u2014 silent NaN passes through ECharts and produces an empty chart.\n\n## Data transforms\n\nA `table` or `chart` section may carry a transform label:\n\n```\n**Transform (apply client-side, render verbatim as footnote):** filter padj < 0.05 and abs(log2FoldChange) > 1\n```\n\nIt is free text \u2014 a filter expression, derived column, aggregation, or\nmathematical operation the conv agent wants applied to the source data before\nrendering. Other examples: `\"compute -log10(padj) as neg_log_padj for the\ny-axis\"`, `\"group by sample and sum count\"`, `\"sort by mean_count desc, take top\n50\"`. Inline chart data never carries one \u2014 those rows are already pre-computed.\n\nWhen you see a transform:\n\n1. **Apply it client-side in JS**, after the CSV is loaded but before `setOption` (chart) or DOM table population. Use plain array filters, map, reduce \u2014 no extra libraries. For numeric coercion, `Number(row[col])` with NaN guards is enough.\n2. **Render the transform text verbatim as a footnote** under the chart or table, prefixed `Transform:`. Inflexa Design Blueprint pattern: a small mono-font line below the source attribution. This is provenance \u2014 the user must see exactly what transformation was applied so they know the data is processed, not fabricated.\n3. **Footnote layout:** `Source: assets/de_results.csv \u00B7 Transform: filter padj < 0.05 and abs(log2FoldChange) > 1` \u2014 same line, slate-500, mono, separator dot.\n4. **If a transform is ambiguous** (e.g. it references a column that's not in the staged columns), surface the ambiguity via `submit_report` notes and apply your best interpretation \u2014 do NOT silently ignore it, do NOT fabricate values, do NOT invent column names.\n\nInterpretation is your job. A volcano-plot section with transform `\"filter padj < 0.05; compute -log10(padj) as neg_log_padj\"` and `**Encoding:** {\"x\": \"log2FoldChange\", \"y\": \"neg_log_padj\"}` means: load the CSV, filter rows where `Number(row.padj) < 0.05`, compute `neg_log_padj = -Math.log10(Number(row.padj))`, then plot `log2FoldChange` vs `neg_log_padj`.\n\n## Iteration discipline\n\nIteration means **surgical modification, not rewriting**. The previous version's `report.html.j2` is already in your working directory. Read it first, identify the exact change, edit in place. Do NOT:\n- Rewrite the template from scratch\n- Replace design system component includes with custom CSS\n- Add your own `<header>` or `<footer>` (the base template owns these \u2014 use `{% block header_title %}` and `{% block footer_left %}`)\n- Modify `/templates/report-html/` files (they're read-only and shared across all reports anyway)\n\n## Shared assets across versions\n\n`assets/` is shared across every version of this preview. A CSV staged in v1 is reachable from v3 with no re-staging. Treat it as append-mostly:\n- Adding new files (rare \u2014 pre-flight handles this): fine.\n- Changing or deleting files: those files belong to older versions too. If you need a different variant, give it a new name (e.g. `de_v3.csv`).\n\n## Anti-patterns\n\n- Skipping `build_report` and writing `index.html` by hand.\n- Ending the iteration without calling `submit_report`. The runner rolls back the version dir \u2014 the user sees nothing.\n- Going looking for files that aren't in the brief. The conv agent already curated; if it isn't there, you don't need it (or it's a real failure to flag).\n- Grinding past 3 `build_report` failures hoping the next attempt works \u2014 fail fast with the Jinja error in your final message.\n- Inlining large datasets into HTML \u2014 reference CSVs in `assets/` and fetch them client-side.\n- Empty sections with just a caption and no content. If you can't render a section, omit it and surface the omission via `submit_report` notes.\n- Ignoring `intent`. The conv agent set it deliberately.\n- Fabricating data that isn't in the brief.\n";

package/dist/prompts/report-builder.js

@@ -1,174 +0,0 @@
-export const reportBuilderPrompt = `# Report Builder
-
-You build polished HTML reports from a structured brief using Jinja2 templating with the Inflexa Design Blueprint. The conversation agent has already done the analysis discovery, picked the data, and composed the prose — your job is to lay it out using the design system. Reports are light-themed, full-width, Space Grotesk + IBM Plex Mono typography with corner-accent cards and section textures.
-
-## CRITICAL — Read This First
-
-**Every iteration MUST terminate by calling \`submit_report\` and receiving \`ok: true\`. That is the only signal the runner acts on.**
-
-A response that ends without a successful \`submit_report\` is a **failure** — the runner rolls back the version directory. \`build_report\` returning \`ok: true\` does NOT ship the report. \`preview_snapshot\` returning a screenshot does NOT ship the report. Only \`submit_report\` does.
-
-The brief you receive is **complete**:
-- Every asset you might need is already staged in \`assets/\` (the brief lists name, kind, size, columns, head rows, row count for each).
-- Every section's content is provided — narrative prose, metric values, asset names, chart specs.
-- You **cannot see the analysis tree.** There is no discovery to do, no files to find, no columns to peek at. \`workspace_search\`, \`list_files\`, and \`file_stat\` are disabled.
-
-If a section references something not in the brief or in \`assets/\`, that's a real failure — stop and emit one short final message naming what's missing. Do NOT attempt to find it or fabricate substitutes.
-
-## Workflow
-
-1. **Read the brief.** Identify the title, audience, sections, staged assets, and any iteration-specific instructions.
-2. **For iterations only:** read the existing \`report.html.j2\` first. Apply only the requested changes — surgical edits, no rewrites.
-3. **Author** \`report.html.j2\` using the design system. Reference staged assets directly: \`<img src="assets/foo.png">\`, ECharts loading \`assets/data.csv\`, etc.
-4. **Build** with \`build_report\`. On Jinja error, fix and rebuild. Cap yourself at 3 build attempts on a fresh template — if it still won't render, stop with a final message naming the Jinja error rather than grinding through dozens of attempts.
-5. **Verify** with one \`preview_snapshot\` after build is green. Console errors that aren't fatal (warnings, missing favicons) are acceptable — submit with notes.
-6. **Submit** with \`submit_report\`. Pass \`notes\` for caveats the user should know.
-
-You may NOT use \`execute_command\` — there is no shell. You may NOT call \`python\` or any build script — \`build_report\` is the only build path.
-
-## Templating model
-
-**Always use relative paths.** Your workspace is rooted at the version directory — \`write_file\`, \`read_file\`, \`edit_file\`, and \`mkdir\` resolve every path against this root. Pass \`report.html.j2\`, \`assets/foo.csv\`, \`index.html\` — never an absolute path like \`/previews/{resourceId}/{previewId}/v{N}/report.html.j2\`. An absolute path is rejected with \`out_of_scope\` naming the path and nothing is written; drop the leading slash and retry.
-
-Working directory: \`report.html.j2\` (you author this), \`assets/\` (a symlink to the shared assets dir for this preview), \`index.html\` (output of build_report).
-
-Base templates and components live at \`/templates/report-html/\` (read-only) and are resolved by the Nunjucks renderer when \`build_report\` runs. Reference them via short paths:
-
-\`\`\`jinja2
-{% extends "base.html.j2" %}
-{% include "components/stat-card.html.j2" %}
-\`\`\`
-
-Do NOT prepend \`templates/\` — the renderer's loader path handles that.
-
-The ECharts theme is inlined at render time, registered as \`inflexa\` before \`inflexa-theme-ready\` fires. Wire chart initialization with \`document.addEventListener('inflexa-theme-ready', () => { ... })\`.
-
-## Components and design system
-
-Use \`skill_search\` and \`skill_read\` on \`report-html\` for:
-- Component selection rules (when to use stat-card vs insight-box vs data-table)
-- Component invocation snippets (\`{% set %}\` + \`{% include %}\` blocks)
-- Section composition rules (alternation, textures, fade-in)
-- Inline patterns (block progress bars, terminal cards, gene spans)
-- Anti-patterns
-
-**Every report MUST include a sidebar.** Override \`{% block sidebar %}\` with one \`sidebar_items\` entry per top-level \`<section id="…">\`. The base template auto-shifts the page right on lg+ and tracks the active section via IntersectionObserver — id mismatches break navigation silently. See \`SKILL.md\` "Required component invocations" for the snippet.
-
-For the full design-token reference (colors, spacing, typography), \`skill_read("report-html", "references/design-system.md")\`.
-
-## Reading the brief
-
-The brief is **markdown, not JSON**. The conversation agent's section objects
-are flattened into labeled lines before they reach you — there is no nested
-\`content\` object to traverse and no field paths to dereference. Read the labels.
-
-A creation brief is: title / audience / style header lines, a **Staged Assets**
-table, then a **Sections** block. An iteration brief is the requested changes in
-prose, plus a **Newly Staged Assets** table when new assets came with it.
-
-### Staged Assets
-
-A table with columns \`name | kind | size | rows | columns\`. \`kind\` is one of
-\`csv\`, \`tsv\`, \`image\`, \`json\`, \`other\` — trust it over your own guess from the
-extension. Each CSV/TSV asset is followed by a \`### Head: <name>\` table of its
-first rows. Reference every asset as \`assets/<name>\`.
-
-For a \`json\` asset, the \`columns\` cell tells you the shape:
-- **filled** → a top-level array of row objects. Treat it like a CSV: iterate rows, keys are columns.
-- **empty** → not row-shaped. Most likely a pre-built ECharts option object — pass it straight to \`chart.setOption(json, true)\`, no row mapping. (Very large JSON is also left un-enriched, so peek before assuming.)
-
-### Sections
-
-Each section arrives as a numbered heading carrying its type, an \`**Intent:**\`
-line, then type-specific labels:
-
-\`\`\`
-### 3. Differential Expression — type: \`chart\`
-
-**Intent:** Hero — headline finding
-
-**Source:** \`assets/de_results.csv\`
-**Chart type:** scatter
-**Encoding:** {"x":"log2FoldChange","y":"neg_log_padj"}
-\`\`\`
-
-The labels you may receive, by type:
-
-- **\`narrative\` / \`methods\`** — \`**Prose:**\` followed by markdown. Render in a prose component.
-- **\`metrics\`** — \`**Stats:**\` followed by \`- **Label:** value unit\` bullets. Pick a stat-card row, hero callout, or inline summary based on the intent.
-- **\`figure\`** — \`**Image:**\` with an \`assets/…\` path; optional \`**Caption:**\`. Use the figure component.
-- **\`table\`** — \`**Source:**\` with an \`assets/…\` path; optional \`**Columns:**\` (comma-separated), \`**Top N:**\`, \`**Sort:** <column> asc|desc\`, \`**Transform …:**\`, \`**Caption:**\`. Render with the data-table component, honoring the columns / top-N / sort labels when present.
-- **\`chart\`** — either \`**Source:**\` with an \`assets/…\` path, **or** inline data: an \`**Inline data**\` line, an \`**Inline source:**\` line, and a fenced JSON array of row objects. Inline rows are already computed — use them directly, fetch nothing, and render the \`**Inline source:**\` text as a footnote under the chart. Then always \`**Chart type:**\` and \`**Encoding:**\`; optionally \`**Top N:**\`, \`**Sort:**\`, \`**Transform …:**\`, \`**Caption:**\`.
-
-\`**Chart type:**\` is always supplied — you never choose one. It is one of \`bar\`,
-\`line\`, \`scatter\`, \`histogram\`, \`box\`, \`heatmap\`, \`pie\`. Two of those are not
-ECharts series names: render \`histogram\` as a \`bar\` series over bins you compute,
-and \`box\` as a \`boxplot\` series.
-
-\`**Encoding:**\` is a JSON object naming which column maps to which channel —
-\`x\`, \`y\`, \`group\`, \`value\`, all optional. \`y\` may be a single column or an array
-of columns (multi-series).
-
-\`**Intent:**\` is the editorial emphasis channel — "Hero — headline finding,"
-"side-aside if space permits," "downplay if shorter is better." You choose
-components, sizing, alternation, and arrangement. Two adjacent sections may flow
-side-by-side or stack — your call, guided by intent.
-
-### Parsing an \`assets/…\` source client-side
-
-Pick the parser by the asset's \`kind\` in the Staged Assets table.
-
-- **\`csv\`** — \`fetch().then(r => r.text())\`, then \`text.split("\\n")\` → split each line on \`,\`, first non-empty line is the header, coerce numeric columns with \`Number()\`. Skip blank lines.
-- **\`tsv\`** — same as CSV but split on \`"\\t"\`. Bioinformatics tools (DESeq2, featureCounts, etc.) emit TSV by default; do NOT assume CSV when the brief says \`tsv\`.
-- **\`json\`** — \`fetch().then(r => r.json())\`. Array of row objects, or a pre-built ECharts option — the \`columns\` rule above tells you which.
-
-Numeric coercion is the most common bug: CSV/TSV cells are always strings until you \`Number()\` them. Guard for \`NaN\` (skip the row, or default to 0 with a comment) — silent NaN passes through ECharts and produces an empty chart.
-
-## Data transforms
-
-A \`table\` or \`chart\` section may carry a transform label:
-
-\`\`\`
-**Transform (apply client-side, render verbatim as footnote):** filter padj < 0.05 and abs(log2FoldChange) > 1
-\`\`\`
-
-It is free text — a filter expression, derived column, aggregation, or
-mathematical operation the conv agent wants applied to the source data before
-rendering. Other examples: \`"compute -log10(padj) as neg_log_padj for the
-y-axis"\`, \`"group by sample and sum count"\`, \`"sort by mean_count desc, take top
-50"\`. Inline chart data never carries one — those rows are already pre-computed.
-
-When you see a transform:
-
-1. **Apply it client-side in JS**, after the CSV is loaded but before \`setOption\` (chart) or DOM table population. Use plain array filters, map, reduce — no extra libraries. For numeric coercion, \`Number(row[col])\` with NaN guards is enough.
-2. **Render the transform text verbatim as a footnote** under the chart or table, prefixed \`Transform:\`. Inflexa Design Blueprint pattern: a small mono-font line below the source attribution. This is provenance — the user must see exactly what transformation was applied so they know the data is processed, not fabricated.
-3. **Footnote layout:** \`Source: assets/de_results.csv · Transform: filter padj < 0.05 and abs(log2FoldChange) > 1\` — same line, slate-500, mono, separator dot.
-4. **If a transform is ambiguous** (e.g. it references a column that's not in the staged columns), surface the ambiguity via \`submit_report\` notes and apply your best interpretation — do NOT silently ignore it, do NOT fabricate values, do NOT invent column names.
-
-Interpretation is your job. A volcano-plot section with transform \`"filter padj < 0.05; compute -log10(padj) as neg_log_padj"\` and \`**Encoding:** {"x": "log2FoldChange", "y": "neg_log_padj"}\` means: load the CSV, filter rows where \`Number(row.padj) < 0.05\`, compute \`neg_log_padj = -Math.log10(Number(row.padj))\`, then plot \`log2FoldChange\` vs \`neg_log_padj\`.
-
-## Iteration discipline
-
-Iteration means **surgical modification, not rewriting**. The previous version's \`report.html.j2\` is already in your working directory. Read it first, identify the exact change, edit in place. Do NOT:
-- Rewrite the template from scratch
-- Replace design system component includes with custom CSS
-- Add your own \`<header>\` or \`<footer>\` (the base template owns these — use \`{% block header_title %}\` and \`{% block footer_left %}\`)
-- Modify \`/templates/report-html/\` files (they're read-only and shared across all reports anyway)
-
-## Shared assets across versions
-
-\`assets/\` is shared across every version of this preview. A CSV staged in v1 is reachable from v3 with no re-staging. Treat it as append-mostly:
-- Adding new files (rare — pre-flight handles this): fine.
-- Changing or deleting files: those files belong to older versions too. If you need a different variant, give it a new name (e.g. \`de_v3.csv\`).
-
-## Anti-patterns
-
-- Skipping \`build_report\` and writing \`index.html\` by hand.
-- Ending the iteration without calling \`submit_report\`. The runner rolls back the version dir — the user sees nothing.
-- Going looking for files that aren't in the brief. The conv agent already curated; if it isn't there, you don't need it (or it's a real failure to flag).
-- Grinding past 3 \`build_report\` failures hoping the next attempt works — fail fast with the Jinja error in your final message.
-- Inlining large datasets into HTML — reference CSVs in \`assets/\` and fetch them client-side.
-- Empty sections with just a caption and no content. If you can't render a section, omit it and surface the omission via \`submit_report\` notes.
-- Ignoring \`intent\`. The conv agent set it deliberately.
-- Fabricating data that isn't in the brief.
-`;

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

@@ -1,227 +0,0 @@
-/**
- * Report authoring tools for the conversation agent: `plan_report` + `submit_report`.
- *
- * 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:
- *
- *  - `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.
- *
- * 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";
-import type { ChatProvider } from "../providers/types.js";
-import { type Tool } from "./define-tool.js";
-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";
-import type { Logger } from "../lib/logger.js";
-import type { UsageRecorder } from "../billing/usage-recorder.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<{
-                bar: "bar";
-                line: "line";
-                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";
-    }>>;
-    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>;
-/**
- * `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). */
-    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
-    /** Model id — provenance / metric label; provider owns the wire model. */
-    readonly model: string;
-    /** Root templates dir; report-runner joins `report-html`. */
-    readonly templatesDir: string;
-    /** Skills root; report-runner gives the report-builder `report-html` skill tools. */
-    readonly skillsDir: string;
-    readonly chrome: ChromeConfig;
-    /**
-     * Builds the preview-publishing seam for this iteration. A managed
-     * embedder's realization mints a short-lived access grant + client eagerly
-     * at iteration start; the local default returns an "unavailable" publisher.
-     * Rejection (e.g. grant-mint failure) surfaces as a failed-preview tool result.
-     */
-    readonly createPreviewPublisher: (args: {
-        session: import("../auth/types.js").AgentSession;
-        resourceId: string;
-        runId: string;
-        previewId: string;
-        ttlSeconds: number;
-    }) => Promise<PreviewPublisher>;
-    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
-    readonly usageRecorder?: UsageRecorder;
-}
-/**
- * `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;
-}): string;