@inflexa-ai/harness 0.1.1 → 0.2.0

package/dist/tools/bio/pubmed.js

@@ -0,0 +1,100 @@
+/**
+ * pubmed — one tool over PubMed and PubMed Central (NCBI E-utilities):
+ * search the literature, fetch article metadata, and read the full text of an
+ * open-access article.
+ *
+ * Dependency-bearing: the optional NCBI API key is captured by the factory.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`). Each action's required argument is optional
+ * in the schema and enforced by `.refine`, so a malformed call (e.g. 'fulltext'
+ * with no pmcId) fails at the loop boundary and surfaces as an `is_error` tool
+ * result instead of reaching NCBI.
+ *
+ * The three actions form one retrieval chain — search yields PMIDs, details
+ * turns PMIDs into abstracts + the PMC id, fulltext turns a PMC id into the
+ * article body — which is why they share a tool: the identifier for each step
+ * is read off the previous step's result.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { getArticleDetails, getArticleFullText, searchPubmed } from "../lib/pubmed-client.js";
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["search", "details", "fulltext"])
+        .describe("'search' (needs query) — returns totalFound plus, per hit, PMID, title, journal, year and an author summary. " +
+        "'details' (needs pmids, max 20 per call) — each article's full abstract, authors, journal, year, DOI, MeSH terms, and " +
+        "pmcId (non-null only when open-access full text exists in PubMed Central). " +
+        "'fulltext' (needs pmcId, taken from a 'details' result) — the body of ONE open-access PMC article as plain text with " +
+        "section headers preserved; available: false when the article is not open-access."),
+    query: z
+        .string()
+        .optional()
+        .describe("Required for action 'search'. PubMed query syntax — MeSH terms (\"breast neoplasms\"[MeSH]), field tags " +
+        '([Title/Abstract], [Author], [Gene]), Boolean AND/OR/NOT. Example: "BRCA1"[Gene] AND "drug resistance"[Title/Abstract].'),
+    maxResults: z.number().int().min(1).max(50).default(10).optional().describe("action 'search': max results, 1–50 (default 10)."),
+    sort: z.enum(["relevance", "date"]).default("relevance").optional().describe("action 'search': sort order (default \"relevance\")."),
+    dateRange: z
+        .object({
+        from: z.string().describe("Start date in YYYY/MM/DD format"),
+        to: z.string().describe("End date in YYYY/MM/DD format"),
+    })
+        .optional()
+        .describe("action 'search': optional publication date range filter."),
+    pmids: z
+        .array(z.string())
+        .min(1)
+        .max(20)
+        .optional()
+        .describe("Required for action 'details'. Non-empty array of PMID strings, max 20 — batch them, do not call once per PMID."),
+    pmcId: z.string().optional().describe("Required for action 'fulltext'. A PMC ID (e.g. \"PMC1234567\") copied from a 'details' result — not a PMID."),
+})
+    .refine((d) => d.action !== "search" || (d.query !== undefined && d.query.trim().length > 0), {
+    message: "query is required when action is 'search'",
+    path: ["query"],
+})
+    .refine((d) => d.action !== "details" || (d.pmids !== undefined && d.pmids.length > 0), {
+    message: "pmids is required when action is 'details' — pass a non-empty array of PMID strings (max 20), copied from a 'search' result",
+    path: ["pmids"],
+})
+    .refine((d) => d.action !== "fulltext" || (d.pmcId !== undefined && d.pmcId.trim().length > 0), {
+    message: "pmcId is required when action is 'fulltext' — copy it from the pmcId field of a 'details' result; a PMID is not a PMC ID",
+    path: ["pmcId"],
+});
+export function createPubMedTool(deps) {
+    return defineTool({
+        id: "pubmed",
+        description: "Search and read the biomedical literature via PubMed / PubMed Central (NCBI E-utilities). The three actions form a chain " +
+            "— search, then details on the relevant hits, then fulltext; see the action parameter for what each needs and returns. Read " +
+            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
+            "available: false is an expected outcome, not an error — do not retry it.",
+        inputSchema,
+        execute: async (input) => {
+            switch (input.action) {
+                case "search":
+                    return ok(await searchPubmed(deps.ncbiApiKey, input.query, {
+                        maxResults: input.maxResults,
+                        sort: input.sort,
+                        dateRange: input.dateRange,
+                    }));
+                case "details":
+                    return ok(await getArticleDetails(deps.ncbiApiKey, input.pmids));
+                case "fulltext": {
+                    const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId);
+                    // "Not open-access" is an expected outcome — a data variant, not an error.
+                    if (!parsed)
+                        return ok({ pmcId: input.pmcId, available: false });
+                    return ok({
+                        pmcId: input.pmcId,
+                        available: true,
+                        fullText: parsed.fullText,
+                        sections: parsed.sections,
+                    });
+                }
+            }
+        },
+    });
+}

package/dist/tools/bio/search-bgee-expression.js

@@ -8,17 +8,23 @@ import { SUPPORTED_SPECIES, bucketRank, getMultiSpeciesExpression, parseExpressi
 export { SUPPORTED_SPECIES, bucketRank, parseExpressionResponse };
 export const searchBgeeExpressionTool = defineTool({
     id: "search_bgee_expression",
-    description: "Get baseline gene expression across species (human, mouse, rat, dog, macaque) from Bgee. " +
-        "Returns per-species tissue × expression-rank tables. Use to assess whether a target is " +
-        "expressed in tissues of interest, and whether model organisms are suitable surrogates. " +
-        "NOT for differential expression — use the analysis pipeline for that.",
+    description: "Get BASELINE (healthy, untreated) gene expression across species from Bgee — use it to judge tissue-of-action ('where is this target expressed?') and model-organism " +
+        "suitability ('is the mouse a fair surrogate for this gene?'). " +
+        "NOT for differential expression between conditions — that is the analysis pipeline's job, never this tool. " +
+        "Takes a human gene symbol and resolves the per-species orthologs itself, returning a per-species tissue table: each tissue carries an expression score, a gold/silver confidence, " +
+        "an expressed / not-expressed state, and a bucketed rank (absent | low | medium | high). Species with no ortholog are listed in notFound. " +
+        "Sparse output is valid no-data: dog and macaque coverage is thin, and a null humanEnsemblId means the symbol did not resolve. Do NOT retry on empty output.",
     inputSchema: z.object({
-        geneSymbol: z.string().min(1).describe("Human gene symbol, e.g. 'BRCA1'."),
+        geneSymbol: z
+            .string()
+            .min(1)
+            .describe("HUMAN gene symbol, e.g. 'BRCA1' — one gene per call. Ensembl IDs and non-human symbols are not accepted; the human symbol is resolved to an ENSG and orthologs are looked up per species."),
         species: z
             .array(z.enum(SUPPORTED_SPECIES))
             .min(1)
             .default([...SUPPORTED_SPECIES])
-            .describe("Species to fetch. Defaults to all five supported: homo_sapiens, mus_musculus, " + "rattus_norvegicus, canis_lupus_familiaris, macaca_mulatta."),
+            .describe("Species to fetch, any subset of: homo_sapiens, mus_musculus, rattus_norvegicus, canis_lupus_familiaris, macaca_mulatta. " +
+            "Defaults to all five — narrow it only when the cross-species comparison is not needed."),
     }),
     execute: async ({ geneSymbol, species }) => ok(await getMultiSpeciesExpression(geneSymbol, species)),
 });

package/dist/tools/bio/search-clinical-trials.js

@@ -7,12 +7,23 @@ import { defineTool } from "../define-tool.js";
 import { searchTrials } from "../lib/clinical-trials-client.js";
 export const searchClinicalTrialsTool = defineTool({
     id: "search_clinical_trials",
-    description: "Search ClinicalTrials.gov for clinical trials by condition, intervention (drug/gene therapy), or target gene. Use to understand the clinical landscape for a therapeutic target or disease indication.",
+    description: "Search ClinicalTrials.gov to map the clinical development landscape for a target, drug, or indication — what is being tried, at what phase, by whom, and what stopped. " +
+        "Returns totalFound plus per trial: NCT ID, title, status, phase, conditions, interventions, enrollment, start and completion dates, sponsor, brief summary, and whyStopped " +
+        "(the termination reason, when there is one). " +
+        "`query` is free text matched across the whole study record, so a gene symbol, a drug name, a condition, or an NCT ID all work. " +
+        "`phase` and `status` are optional server-side filters — omit them to see the full landscape; totalFound reports the true match count even when it exceeds the page returned. " +
+        "An empty trials array is a valid 'nothing matched' (often an over-narrow filter) — do not retry the identical query.",
     inputSchema: z.object({
-        query: z.string().describe("Search term: condition name, drug name, gene symbol, or NCT ID"),
-        phase: z.enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"]).optional().describe("Filter by trial phase"),
-        status: z.enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING"]).optional().describe("Filter by recruitment status"),
-        limit: z.number().int().min(1).max(50).default(20).describe("Max trials to return"),
+        query: z.string().describe("Free-text search term: condition name, drug/intervention name, gene symbol, or an NCT ID."),
+        phase: z
+            .enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"])
+            .optional()
+            .describe("Optional exact phase filter. Omit for all phases (observational and expanded-access studies carry no phase and are excluded when this is set)."),
+        status: z
+            .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING"])
+            .optional()
+            .describe("Optional recruitment-status filter. Omit for all statuses — note TERMINATED/WITHDRAWN trials are not selectable here and appear only in an unfiltered search."),
+        limit: z.number().int().min(1).max(50).default(20).describe("Max trials to return (default 20, max 50)."),
     }),
     execute: async ({ query, phase, status, limit = 20 }) => {
         const result = await searchTrials(query, { phase, status, limit });

package/dist/tools/bio/search-faers.js

@@ -7,11 +7,15 @@ import { defineTool } from "../define-tool.js";
 import { getFaersByDrug } from "../lib/openfda-client.js";
 export const searchFaersTool = defineTool({
     id: "search_faers",
-    description: "Search FDA FAERS (Adverse Event Reporting System) for adverse event reports associated with a drug. Returns the most frequently reported adverse reactions. Use to assess real-world safety signals for drugs or drug candidates targeting a specific gene/pathway.",
+    description: "Search FDA FAERS for post-market adverse-event reports on one marketed drug — the real-world safety signal for a specific molecule. " +
+        "Returns totalReports and adverseEvents[]: { reaction (MedDRA preferred term), count }, most-reported first. " +
+        "These are spontaneous report counts, NOT incidence rates: there is no denominator and reporting is heavily biased, so use them to rank signals, never to state a rate. " +
+        "Matching is on the openFDA GENERIC name only — 'imatinib' works, the brand name 'Gleevec' does not. For mechanism-based liabilities of a target (rather than a drug), use opentargets({action:\"safety\"}). " +
+        "An empty adverseEvents array is valid no-data (drug absent from FAERS under that generic name) — do not retry.",
     inputSchema: z.object({
-        drugName: z.string().describe("Drug generic name (e.g. imatinib, pembrolizumab)"),
-        limit: z.number().int().min(1).max(100).default(25).describe("Max adverse event types to return"),
-        serious: z.boolean().default(false).describe("Filter to serious adverse events only"),
+        drugName: z.string().describe("Generic (INN) drug name, e.g. 'imatinib', 'pembrolizumab'. Brand names do not match."),
+        limit: z.number().int().min(1).max(100).default(25).describe("Max distinct adverse-reaction terms to return (default 25, max 100)."),
+        serious: z.boolean().default(false).describe("When true, count only reports flagged serious (death, hospitalization, life-threatening, disabling)."),
     }),
     execute: async ({ drugName, limit = 25, serious = false }) => {
         const result = await getFaersByDrug(drugName, { limit, serious });

package/dist/tools/bio/search-geo-datasets.js

@@ -38,17 +38,31 @@ const GeoEsummaryResponseSchema = z.object({
 });
 export const searchGeoDatasetsTool = defineTool({
     id: "search_geo_datasets",
-    description: "Search NCBI GEO for public gene expression datasets by disease, tissue, or experimental condition. Returns dataset accessions and metadata for identifying external validation cohorts. Note: sandbox containers cannot download GEO data directly — use this tool to identify relevant datasets, then reference accessions in analysis plans.",
+    description: "Search NCBI GEO for public gene-expression datasets by disease, tissue, or experimental condition — use it to find external validation cohorts or to cite published data. " +
+        "Returns totalFound plus datasets[]: { accession (GSE…/GDS…), title, summary (truncated to 500 chars), platform, sampleCount, organism, pubmedIds }. " +
+        "HARD CAVEAT: sandbox containers cannot download GEO data. This tool identifies and cites accessions only — never plan an analysis step that fetches a GEO dataset. " +
+        "An empty datasets array is a valid 'nothing matched' — do not retry the identical query.",
     inputSchema: z.object({
-        query: z.string().describe("Search terms (e.g. 'breast cancer RNA-seq responder', 'NSCLC pembrolizumab')"),
-        organism: z.string().optional().describe("Filter by organism (e.g. 'Homo sapiens')"),
-        datasetType: z.enum(["gds", "gse"]).default("gse").describe("GDS (curated datasets) or GSE (series, more numerous)"),
-        limit: z.number().int().min(1).max(50).default(15).describe("Max results"),
+        query: z
+            .string()
+            .describe("NCBI Entrez free-text query (e.g. 'breast cancer RNA-seq responder', 'NSCLC pembrolizumab'). Entrez field tags are allowed."),
+        organism: z
+            .string()
+            .optional()
+            .describe("Optional organism filter, appended as an [Organism] term. Use the scientific name, e.g. 'Homo sapiens', 'Mus musculus'."),
+        datasetType: z
+            .enum(["gds", "gse"])
+            .default("gse")
+            .describe("'gse' (default) — GEO Series: raw submitter-deposited studies, far more numerous. 'gds' — curated DataSets: fewer, but normalized and value-added."),
+        limit: z.number().int().min(1).max(50).default(15).describe("Max datasets to return (default 15, max 50)."),
     }),
     execute: async ({ query, organism, datasetType = "gse", limit = 15 }) => {
         let searchQuery = query;
+        // Escape backslashes first, then quotes, so a `\` in the organism value
+        // cannot smuggle an unescaped `"` past the escaping and break out of the
+        // quoted Entrez phrase.
         if (organism)
-            searchQuery += ` AND "${organism.replace(/"/g, '\\"')}"[Organism]`;
+            searchQuery += ` AND "${organism.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"[Organism]`;
         const db = "gds";
         const typeFilter = datasetType === "gse" ? " AND gse[Entry Type]" : " AND gds[Entry Type]";
         searchQuery += typeFilter;

package/dist/tools/bio/search-gwas-catalog.d.ts

@@ -23,7 +23,7 @@ interface GwasAssociation {
 }
 export declare const searchGwasCatalogTool: import("../define-tool.js").Tool<{
     query: string;
-    searchType: "gene" | "trait" | "variant";
+    searchType: "gene" | "variant" | "trait";
     pValueThreshold: number;
     limit: number;
 }, {

package/dist/tools/bio/search-pharmgkb.js

@@ -20,11 +20,17 @@ const PharmgkbResponseSchema = z.object({
 });
 export const searchPharmgkbTool = defineTool({
     id: "search_pharmgkb",
-    description: "Search PharmGKB for pharmacogenomic clinical annotations — gene-drug interactions, dosing guidelines (CPIC/DPWG), and variant-level clinical significance. Use to determine if a gene variant affects drug metabolism, efficacy, or toxicity.",
+    description: "Search PharmGKB clinical annotations for a gene-drug pharmacogenomic link — use it to judge whether a gene affects a drug's metabolism, efficacy, or toxicity. " +
+        "Returns annotations[]: { gene, drug, levelOfEvidence (PharmGKB 1A…4, where 1A is guideline-backed) }. The phenotype, guidelineSource and summary fields are always null " +
+        "in this tool's output — treat levelOfEvidence as the only strength signal and do not attribute CPIC/DPWG guideline text to it. " +
+        "Matching is an exact field filter, not a search: 'CYP2D6' resolves, 'cytochrome P450 2D6' does not. " +
+        "An empty annotations array is valid no-data (no curated PGx link) — do not retry.",
     inputSchema: z.object({
-        query: z.string().describe("Gene symbol (e.g. CYP2D6) or drug name (e.g. tamoxifen)"),
-        searchType: z.enum(["gene", "drug"]).describe("Search by gene or drug"),
-        limit: z.number().int().min(1).max(50).default(20).describe("Max results"),
+        query: z
+            .string()
+            .describe("Exact gene symbol (e.g. 'CYP2D6') when searchType='gene', or exact drug name (e.g. 'tamoxifen') when searchType='drug'. No fuzzy matching."),
+        searchType: z.enum(["gene", "drug"]).describe("'gene' filters PharmGKB on location.genes.symbol; 'drug' filters on relatedChemicals.name."),
+        limit: z.number().int().min(1).max(50).default(20).describe("Max annotations to return (default 20, max 50); applied client-side after the fetch."),
     }),
     execute: async ({ query, searchType, limit = 20 }) => {
         const filter = searchType === "gene" ? `location.genes.symbol=${encodeURIComponent(query)}` : `relatedChemicals.name=${encodeURIComponent(query)}`;

package/dist/tools/display/index.d.ts

@@ -1,4 +1,5 @@
 /**
  * Display barrel — user-facing presentation cards streamed to chat.
  */
+export * from "./normalize-echart-spec.js";
 export * from "./show-user.js";

package/dist/tools/display/index.js

@@ -1,4 +1,5 @@
 /**
  * Display barrel — user-facing presentation cards streamed to chat.
  */
+export * from "./normalize-echart-spec.js";
 export * from "./show-user.js";

package/dist/tools/display/normalize-echart-spec.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ECharts layout normalization — the renderer-side invariant behind `show_user(kind: "echart")`.
+ *
+ * The layout discipline (no duplicate title, bottom legend, grid margins that fit the axis labels,
+ * every category label shown, a downloadable chart) is applied HERE, deterministically, rather than
+ * being a checklist the model must remember on every chart it composes. A rule a model must remember
+ * is a rule it can forget.
+ *
+ * Two invariants govern every rule below:
+ *
+ * 1. **Defaults, not overrides.** Every property is filled in only when the author left it unset —
+ *    an explicit, sensible authored `grid`/`legend`/`rotate`/filename is respected. The two forced
+ *    fields are `title` (deleted: the `show_user` `title` param is the card heading, so an in-spec
+ *    title is a genuine duplicate render) and `axisLabel.interval` (pinned to `0`: ECharts' default
+ *    `"auto"` SILENTLY DROPS labels, which is the exact bug this rule exists to prevent).
+ * 2. **Never turn a valid chart invalid.** Nothing here is derived from data that may be absent: a
+ *    property is only injected where it is meaningful (a `grid` only for a cartesian chart), and an
+ *    unknown category count yields the safe layout rather than a guessed one.
+ *
+ * Pure: the input spec is never mutated. Modified branches are copy-on-write; untouched branches are
+ * shared by reference. `normalize(normalize(x))` deep-equals `normalize(x)`.
+ */
+export interface NormalizeEchartSpecOptions {
+    /**
+     * The `show_user` `title` param — the card heading rendered above the chart canvas. Seeds the
+     * `saveAsImage` download filename when the author supplied none.
+     */
+    title?: string;
+}
+/**
+ * Kebab-case download filename: `"HMGCR — VST Expression"` → `"hmgcr-vst-expression"`.
+ * Diacritics are folded, every other non-alphanumeric run collapses to a single dash.
+ */
+export declare function kebabFilename(source: string | undefined): string;
+/**
+ * Category count on the x axis, or `null` when the spec cannot tell us.
+ *
+ * `null` is the honest answer for a CSV-backed chart (`show_user`'s `dataPath`): the rows are loaded
+ * by the host at render time and deliberately never pulled through the model's context window, so
+ * they are NOT in the spec. Guessing a rotation for an axis of unknown length is worse than not
+ * rotating — an unrotated axis is also exactly what the other `null` cases (a value axis: scatter,
+ * time series) want. The count is used ONLY to pick a label rotation; it never touches the data, so
+ * an off-by-one at a bucket boundary costs at most a rotation, never a rendering.
+ */
+export declare function categoryCount(spec: Record<string, unknown>): number | null;
+/**
+ * Apply the ECharts layout invariant to an author-composed spec.
+ *
+ * - `title` is deleted (always) — the `show_user` `title` param is the visible card heading, and
+ *   `title.subtext` is the documented misuse for stats that belong in the tooltip.
+ * - `legend` defaults to `{ bottom: 0 }` for a multi-series chart and `{ show: false }` for a
+ *   single-series one (nothing to disambiguate); an authored legend is left alone.
+ * - `grid` (cartesian charts only) gets `top` 8% — 12% when a `graphic` annotation shares the canvas
+ *   — `bottom` 20% / 25% (rotated labels) / 30% (rotated labels above a bottom legend), `left` 10%,
+ *   `right` 5%. Only unset keys are filled.
+ * - `axisLabel.interval` is pinned to `0` on every axis; the x axis is rotated 45° (11–20 categories)
+ *   or 90° (>20) unless the author chose a rotation.
+ * - `toolbox.feature.saveAsImage` is injected with `type: "png"` and a kebab-case filename derived
+ *   from the `show_user` title (falling back to the stripped in-spec title, then `"chart"`).
+ */
+export declare function normalizeEchartSpec(spec: Record<string, unknown>, opts?: NormalizeEchartSpecOptions): Record<string, unknown>;

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

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

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

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