@inflexa-ai/harness 0.23.0 → 0.25.0

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;