@inflexa-ai/harness 0.1.1 → 0.2.0

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,142 @@ 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<{
+/**
+ * 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 {
     readonly provider: ChatProvider;
     readonly pool: Pool;
     /** Embedder-supplied workspace-root resolution seam (see workspace/paths.ts). */
@@ -165,7 +208,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;