@malloy-publisher/server 0.0.231 → 0.0.233

package/src/mcp/query_envelope.ts

@@ -0,0 +1,230 @@
+import type * as Malloy from "@malloydata/malloy-interfaces";
+import { bigIntReplacer } from "../json_utils";
+import type { QueryRowLimitSource } from "../service/model_limits";
+
+/**
+ * The agent-facing shape for a query result, matched to what Credible's
+ * `execute_query` returns.
+ *
+ * Matching matters for a specific workflow: a data app is authored locally
+ * against Publisher and then served through Credible. An agent that sees one
+ * response shape while developing and a different one in production has to
+ * learn both, and a shared skill cannot describe either without forking. So the
+ * field names here are Credible's, deliberately, including the leading
+ * underscores and the mixed casing of `renderLogErrors`.
+ *
+ * Also following Credible: the truncation fields appear only when truncation
+ * happened, rather than always carrying `false`.
+ *
+ * The two `_limit_...` fields are new to both products. Three separate things
+ * can shorten a result and only one of them was ever reported:
+ *
+ *   1. The query row cap, pushed into the SQL. A query with no `limit:` of its
+ *      own gets DEFAULT_QUERY_ROW_LIMIT (1000) rows, which is far under
+ *      PUBLISHER_MAX_QUERY_ROWS, so nothing raises and nothing warns. An agent
+ *      reports statistics on a silent sample. This is why `_limit_hit` exists,
+ *      and unlike the others it is not derivable by a client: the cap depends on
+ *      server config and on the query's own LIMIT.
+ *   2. The hard ceiling (maxRows / maxBytes), which throws 413 and is loud.
+ *   3. The payload cap below, which degrades to a truncated result plus a
+ *      warning instead of overflowing the client's per-result limit.
+ *
+ * `_limit_hit` is a bound, not a total. The server cannot know the true row
+ * count, because the database applied the cap. Landing exactly on the limit is
+ * the only evidence available that rows were left behind.
+ *
+ * It is reported only when the cap was the server default, which `_limit_source`
+ * names. `resolveModelQueryRowLimit` folds the query's own `limit:`/`top:` into
+ * the same number, so equality also holds every time an author limited the query
+ * on purpose: three of the eight views in the bundled storefront example use
+ * `top:`, and each would otherwise report its complete answer as cut off. The
+ * silent sample this exists to catch only ever happens under the default.
+ */
+export interface QueryEnvelope {
+   rows: unknown;
+   /** Malloy metadata the flat rows drop: field types, render tags, timezone. */
+   _meta: {
+      schema: Malloy.Schema;
+      annotations: Malloy.Annotation[];
+      connection_name: string;
+      model_annotations?: Malloy.Annotation[];
+      query_timezone?: string;
+      source_annotations?: Malloy.Annotation[];
+   };
+   /** The cap pushed into the SQL: the query's own LIMIT, else the server default. */
+   _query_row_limit: number;
+   /** Which of those two the cap came from. */
+   _limit_source: QueryRowLimitSource;
+   /**
+    * Row count equals the cap AND the cap was the server default, so rows were
+    * almost certainly left behind. A deliberate `limit:`/`top:` that returns
+    * exactly what it asked for is a complete answer and does not set this.
+    */
+   _limit_hit: boolean;
+   /** Present only when the payload cap dropped rows. */
+   _rows_truncated?: boolean;
+   _total_rows?: number;
+   _returned_rows?: number;
+   warning?: string;
+   renderLogErrors?: string[];
+}
+
+/**
+ * Cap on the serialized envelope, in characters. Same value Credible uses.
+ *
+ * Host-loop MCP clients enforce a per-tool-result ceiling of roughly 25k tokens;
+ * past it the result is spilled to disk or rejected outright, and the model then
+ * struggles to recover it. Chars stand in for tokens at about 4:1, with headroom
+ * for the envelope itself.
+ */
+export const MAX_RESULT_CHARS = 90_000;
+
+function serialize(envelope: QueryEnvelope): string {
+   return JSON.stringify(envelope, bigIntReplacer, 2);
+}
+
+/**
+ * Build the envelope, applying the payload cap.
+ *
+ * @param rows      compactResult: flat row objects, straight from the driver.
+ * @param rowLimit  the cap pushed into the SQL.
+ * @param result    the full Malloy result, read only for its metadata.
+ */
+export function buildQueryEnvelope(
+   rows: unknown,
+   rowLimit: number,
+   result: Malloy.Result,
+   renderLogErrors: string[] = [],
+   limit = MAX_RESULT_CHARS,
+   rowLimitSource: QueryRowLimitSource = "server_default",
+): QueryEnvelope {
+   const rowCount = Array.isArray(rows) ? rows.length : 0;
+   // Equality, not >=: the cap is pushed into the SQL, so the database cannot
+   // return more than it. Landing exactly on it is the signal.
+   //
+   // Restricted to the server default on purpose. resolveModelQueryRowLimit
+   // folds the query's own limit:/top: into the same cap, so equality also holds
+   // every time an author deliberately limited the query: a modelled `top: 10`
+   // view returning its 10 rows would otherwise be reported as cut off, and the
+   // Contract rule would tell an agent that a top-N is "not the answer". Only
+   // the silently-applied default is evidence that rows were left behind.
+   const limitHit =
+      rowLimitSource === "server_default" &&
+      rowLimit > 0 &&
+      rowCount === rowLimit;
+
+   const envelope: QueryEnvelope = {
+      rows,
+      _meta: {
+         schema: result.schema,
+         annotations: result.annotations ?? [],
+         connection_name: result.connection_name,
+         ...(result.model_annotations !== undefined && {
+            model_annotations: result.model_annotations,
+         }),
+         ...(result.query_timezone !== undefined && {
+            query_timezone: result.query_timezone,
+         }),
+         ...(result.source_annotations !== undefined && {
+            source_annotations: result.source_annotations,
+         }),
+      },
+      _query_row_limit: rowLimit,
+      _limit_source: rowLimitSource,
+      _limit_hit: limitHit,
+      ...(renderLogErrors.length > 0 && { renderLogErrors }),
+   };
+
+   if (limitHit) {
+      envelope.warning =
+         `Returned exactly ${rowLimit} rows, the row limit applied to this query, so there are probably more. ` +
+         `This is not a complete result: add an explicit limit, aggregate, or filter rather than reporting these rows as the whole set.`;
+   }
+
+   return fitToBudget(envelope, limit);
+}
+
+/**
+ * Drop rows until the serialized envelope fits, by binary search on the row
+ * count.
+ *
+ * The marker fields are set BEFORE the search, so their serialized size counts
+ * against the limit. Adding them afterwards pushes the payload back over the cap
+ * the truncation existed to respect. `_returned_rows` is measured at `total`
+ * first, whose digit width is at least that of any value it ends up holding, so
+ * the finished payload stays under the limit. Credible's `_truncate_rows` does
+ * the same thing for the same reason.
+ *
+ * The search can land on zero rows, which needs its own wording rather than
+ * "Showing 0 of N rows": that reads as an empty result set, and an agent will
+ * report "no rows matched" for what is really one row too large to send. It is
+ * reachable, because the hard ceiling upstream is maxBytes (50MB by default), so
+ * a single row carrying a large text or JSON column passes
+ * assertWithinModelResponseLimits and arrives here. Both wordings are measured,
+ * and the search uses whichever is longer, so swapping one for the other after
+ * the fact cannot push the payload back over the cap.
+ *
+ * One case cannot be fixed by dropping rows: when the envelope minus its rows
+ * already exceeds the limit (a very wide schema in `_meta`). The result is then
+ * returned over-limit rather than emptied further, and the warning says so.
+ */
+function fitToBudget(envelope: QueryEnvelope, limit: number): QueryEnvelope {
+   if (serialize(envelope).length <= limit) return envelope;
+
+   const rows = envelope.rows;
+   if (!Array.isArray(rows) || rows.length === 0) return envelope;
+   const total = rows.length;
+
+   const truncating: QueryEnvelope = {
+      ...envelope,
+      _rows_truncated: true,
+      _total_rows: total,
+      _returned_rows: total,
+   };
+   // The size warning joins any limit warning already present, and is included
+   // in the measurement for the same reason as the counts.
+   const sizeWarning = (kept: number) =>
+      `Showing ${kept} of ${total} rows; the rest were dropped to fit the result size limit. Narrow the query rather than paging through it.`;
+   const noneFitWarning =
+      `No rows fit the result size limit: the first of ${total} rows is too large to send on its own. ` +
+      `This is NOT an empty result and does not mean nothing matched. Select fewer columns, or truncate the oversized field, then run it again.`;
+   // Measure with whichever wording is longer, so the one actually returned is
+   // never bigger than the one the search sized the payload against.
+   const measured =
+      noneFitWarning.length > sizeWarning(total).length
+         ? noneFitWarning
+         : sizeWarning(total);
+   truncating.warning = [envelope.warning, measured].filter(Boolean).join(" ");
+
+   let low = 0;
+   let high = total;
+   let best = 0;
+   while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      if (
+         serialize({ ...truncating, rows: rows.slice(0, mid) }).length <= limit
+      ) {
+         best = mid;
+         low = mid + 1;
+      } else {
+         high = mid - 1;
+      }
+   }
+
+   return {
+      ...truncating,
+      rows: rows.slice(0, best),
+      _returned_rows: best,
+      warning: [
+         envelope.warning,
+         best === 0 ? noneFitWarning : sizeWarning(best),
+      ]
+         .filter(Boolean)
+         .join(" "),
+   };
+}
+
+/** Serialize an envelope for transport, BigInt-safe. */
+export function serializeEnvelope(envelope: QueryEnvelope): string {
+   return serialize(envelope);
+}

package/src/mcp/server.protocol.spec.ts

@@ -16,10 +16,33 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
    let client: Client;
 
    beforeAll(async () => {
-      // searchDocs does not touch the store; getContext's error path only needs
-      // getEnvironment to reject, so a throwing stub is sufficient here.
+      // searchDocs does not touch the store, and the tools' error paths only
+      // need getEnvironment to reject. The one exception is `compiles-badly`,
+      // which resolves to a compileSource returning an error diagnostic: that
+      // is malloy_compile's own isError path (a bad Malloy snippet rather than
+      // a thrown error), and it is only reachable with an environment that
+      // exists.
       const stubStore = {
-         getEnvironment: async (name: string): Promise<never> => {
+         getEnvironment: async (name: string) => {
+            if (name === "compiles-badly") {
+               return {
+                  compileSource: async () => ({
+                     problems: [
+                        {
+                           severity: "error",
+                           message: "'nope' is not defined",
+                           code: "field-not-found",
+                           at: {
+                              range: {
+                                 start: { line: 2, character: 3 },
+                                 end: { line: 2, character: 7 },
+                              },
+                           },
+                        },
+                     ],
+                  }),
+               };
+            }
             throw new Error(`Environment not found: ${name}`);
          },
       } as unknown as EnvironmentStore;
@@ -42,6 +65,43 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(names.has("malloy_reloadPackage")).toBe(true);
    });
 
+   /**
+    * Tool descriptions are truncated by some clients. `malloy_getContext`'s was
+    * observed arriving cut off mid-sentence at 2271 characters, and what a tail
+    * cut removes is whatever the description put last.
+    *
+    * Two defenses, and the ordering one matters more. No single number is
+    * portable, since the cap belongs to the client and is not published; this
+    * budget only stops silent regrowth past the one length we have watched fail.
+    * The real rule is that contract rules come BEFORE the reference material, so
+    * a cut costs an agent the worked example rather than the invariants it
+    * cannot self-correct without. See docs/agent-skills/tool-description-template.md.
+    */
+   it("keeps every tool description under the truncation budget", async () => {
+      const BUDGET = 2000;
+      const { tools } = await client.listTools();
+      const oversized = tools
+         .filter((t) => (t.description ?? "").length > BUDGET)
+         .map((t) => `${t.name} (${t.description?.length})`);
+      expect(oversized).toEqual([]);
+   });
+
+   it("puts contract rules ahead of the reference sections", async () => {
+      // The section a tail-truncating client drops must never be the invariants.
+      const { tools } = await client.listTools();
+      for (const tool of tools) {
+         const description = tool.description ?? "";
+         const contract = description.indexOf("## Contract rules");
+         if (contract === -1) continue;
+         for (const later of ["## Response", "## Worked example"]) {
+            const index = description.indexOf(later);
+            if (index !== -1) {
+               expect(contract).toBeLessThan(index);
+            }
+         }
+      }
+   });
+
    it("exposes the skill set as dual-channel prompts", async () => {
       const { prompts } = await client.listPrompts();
       expect(prompts.length).toBeGreaterThanOrEqual(24);
@@ -74,18 +134,6 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(results[0].url.length).toBeGreaterThan(0);
    });
 
-   it("malloy_getContext fails gracefully (isError) for an unknown environment", async () => {
-      const res = await client.callTool({
-         name: "malloy_getContext",
-         arguments: {
-            environmentName: "nope",
-            packageName: "nope",
-            query: "x",
-         },
-      });
-      expect(res.isError).toBe(true);
-   });
-
    /**
     * Assert the tool's OWN error payload, not just isError. The SDK sets
     * isError for any uncaught throw, so `expect(res.isError).toBe(true)` passes
@@ -99,16 +147,48 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
    } {
       const res = result as {
          isError?: boolean;
-         content?: Array<{ type?: string; resource?: { text?: string } }>;
+         content?: Array<{
+            type?: string;
+            text?: string;
+            resource?: { text?: string; mimeType?: string };
+         }>;
       };
       expect(res.isError).toBe(true);
       expect(res.content?.[0]?.type).toBe("resource");
+      expect(res.content?.[0]?.resource?.mimeType).toBe("application/json");
       const payload = JSON.parse(res.content?.[0]?.resource?.text ?? "{}");
       expect(typeof payload.error).toBe("string");
       expect(Array.isArray(payload.suggestions)).toBe(true);
+
+      // The structured payload alone is invisible to a client that renders
+      // only text blocks on an error, which is how a real diagnostic ends up
+      // reported as a bare "Unknown error". Every error must also say it in
+      // plain text.
+      const textBlock = res.content?.find((b) => b.type === "text");
+      expect(textBlock?.text).toContain(payload.error);
+
       return payload;
    }
 
+   it("malloy_getContext returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_getContext",
+         arguments: {
+            environmentName: "nope",
+            packageName: "nope",
+            query: "x",
+         },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+      // getContext answers with `results` at every tier, so an error keeps the
+      // key rather than making callers branch on success first.
+      const payload = JSON.parse(
+         (res.content as Array<{ resource?: { text?: string } }>)[0]?.resource
+            ?.text ?? "{}",
+      );
+      expect(payload.results).toEqual([]);
+   });
+
    it("malloy_compile returns its own error payload over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_compile",
@@ -122,6 +202,38 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(expectToolErrorPayload(res).error).toContain("nope");
    });
 
+   it("malloy_compile states a compile diagnostic in text over the protocol", async () => {
+      // The diagnostics path keeps its {status, diagnostics} payload rather
+      // than the {error, suggestions} of the thrown-error path, so it cannot go
+      // through expectToolErrorPayload. What it shares is the invariant that
+      // matters: an isError result is never resource-only. Asserted over the
+      // real transport because a client that renders only text is exactly the
+      // one this was invisible to.
+      const res = await client.callTool({
+         name: "malloy_compile",
+         arguments: {
+            environmentName: "compiles-badly",
+            packageName: "p",
+            modelPath: "m.malloy",
+            source: "run: nope -> { aggregate: c is count() }",
+         },
+      });
+      const content = res.content as Array<{
+         type?: string;
+         text?: string;
+         resource?: { text?: string; mimeType?: string };
+      }>;
+      expect(res.isError).toBe(true);
+      expect(content[0]?.type).toBe("resource");
+      expect(content[0]?.resource?.mimeType).toBe("application/json");
+      expect(JSON.parse(content[0]?.resource?.text ?? "{}").status).toBe(
+         "error",
+      );
+      const textBlock = content.find((b) => b.type === "text");
+      expect(textBlock?.text).toContain("'nope' is not defined");
+      expect(textBlock?.text).toContain("field-not-found");
+   });
+
    it("malloy_reloadPackage returns its own error payload over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_reloadPackage",

package/src/mcp/skills/build_skills_bundle.ts

@@ -51,14 +51,102 @@ export function isCredible(dirName: string): boolean {
    return dirName.toLowerCase().startsWith("credible-");
 }
 
-/** Read every skill under a skills directory, in the bundle's own order. */
+/** The subdirectory a skill keeps its on-demand detail in. */
+const REFERENCE_DIR = "reference";
+
+/** Prompt name for one reference file: `<skill>/<file stem>`. */
+export function referenceName(skillName: string, file: string): string {
+   return `${skillName}/${path.basename(file, ".md")}`;
+}
+
+/**
+ * Turn a reference file into an entry. These carry no frontmatter, so the
+ * description comes from the first H1, which every reference file in the tree
+ * has ("# Rubric: Correctness", "# Severity, Confidence, Categorization").
+ */
+export function parseReference(
+   md: string,
+   skillName: string,
+   file: string,
+): SkillEntry {
+   const body = md.replace(/\r\n/g, "\n").trim();
+   const heading = body.match(/^#\s+(.+)$/m)?.[1]?.trim();
+   return {
+      name: referenceName(skillName, file),
+      description: heading
+         ? `${heading}. Reference detail for the ${skillName} skill.`
+         : `Reference detail for the ${skillName} skill.`,
+      body,
+   };
+}
+
+/**
+ * Tell an agent that reached this body over MCP where the reference files went.
+ *
+ * The skill text points at them by relative path ("see `reference/rubric-*.md`"),
+ * which is correct for a host reading the skill off disk and unresolvable for
+ * one that received this as a prompt: nothing in the prompt says which directory
+ * to stand in. Rewriting the paths in the source file is not an option, since
+ * that would break the filesystem channel, so the mapping is appended to the
+ * bundled copy only. One source file, one correct rendering per channel.
+ */
+export function referencePointer(skillName: string, files: string[]): string {
+   const stems = files.map((f) => path.basename(f, ".md"));
+   return [
+      `## Reference files over MCP`,
+      ``,
+      `This skill's \`${REFERENCE_DIR}/\` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read \`${REFERENCE_DIR}/<name>.md\`, get the prompt named \`${skillName}/<name>\` instead.`,
+      ``,
+      `Available: ${stems.join(", ")}.`,
+   ].join("\n");
+}
+
+/** Reference files for one skill, sorted, or [] when it has none. */
+function referenceFiles(skillDir: string): string[] {
+   const dir = path.join(skillDir, REFERENCE_DIR);
+   if (!fs.existsSync(dir)) return [];
+   return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+}
+
+/**
+ * Read every skill under a skills directory, in the bundle's own order.
+ *
+ * A skill's `reference/` files become entries of their own rather than being
+ * folded into the parent body: they are the skill's on-demand detail (a review
+ * loads the rubrics its scope needs, not all ten), and one prompt per file
+ * keeps that property over MCP. Folding them in would put 83k characters of
+ * malloy-review rubrics in front of an agent that wanted the workflow.
+ */
 export function buildSkills(skillsDir: string): SkillEntry[] {
    const skills: SkillEntry[] = [];
    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || isCredible(entry.name)) continue;
-      const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+      const skillDir = path.join(skillsDir, entry.name);
+      const skillFile = path.join(skillDir, "SKILL.md");
       if (!fs.existsSync(skillFile)) continue;
-      skills.push(parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name));
+
+      const skill = parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name);
+      const files = referenceFiles(skillDir);
+      if (files.length > 0) {
+         skill.body = `${skill.body}\n\n${referencePointer(skill.name, files)}`;
+      }
+      skills.push(skill);
+
+      for (const file of files) {
+         skills.push(
+            parseReference(
+               fs.readFileSync(
+                  path.join(skillDir, REFERENCE_DIR, file),
+                  "utf8",
+               ),
+               skill.name,
+               file,
+            ),
+         );
+      }
    }
    return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -77,7 +165,9 @@ function main(): void {
    const skills = buildSkills(skillsDir);
 
    fs.writeFileSync(outFile, JSON.stringify({ skills }));
-   console.log(`Wrote ${skills.length} skills to ${outFile}`);
+   console.log(
+      `Wrote ${skills.length} entries (${skills.filter((s) => !s.name.includes("/")).length} skills plus ${skills.filter((s) => s.name.includes("/")).length} reference files) to ${outFile}`,
+   );
 }
 
 // Only run when invoked directly (bun run ...), not when imported by a test.