@malloy-publisher/server 0.0.231 → 0.0.233

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.docker.md +4 -0
  2. package/dist/app/api-doc.yaml +135 -13
  3. package/dist/app/assets/{EnvironmentPage-wa_EPkwK.js → EnvironmentPage-DutP7T8h.js} +1 -1
  4. package/dist/app/assets/{HomePage-jnCrupQp.js → HomePage-BcxDrBfl.js} +1 -1
  5. package/dist/app/assets/{LightMode-DYbwNULZ.js → LightMode-BJukGxgz.js} +1 -1
  6. package/dist/app/assets/{MainPage-CuJLrPNI.js → MainPage-DXbwlMeF.js} +2 -2
  7. package/dist/app/assets/{MaterializationsPage-D_67x2ee.js → MaterializationsPage-BBQksmTU.js} +1 -1
  8. package/dist/app/assets/{ModelPage-D5JtAWqR.js → ModelPage-C6tK51uU.js} +1 -1
  9. package/dist/app/assets/{PackagePage-BRwtqUSG.js → PackagePage-Bo3cwwZE.js} +1 -1
  10. package/dist/app/assets/{RouteError-CBNNrnSD.js → RouteError-BufkcAKE.js} +1 -1
  11. package/dist/app/assets/{ThemeEditorPage-CTCeBneA.js → ThemeEditorPage-DICvvKpa.js} +1 -1
  12. package/dist/app/assets/{WorkbookPage-SN6f1RBm.js → WorkbookPage-Dkwt75Nj.js} +1 -1
  13. package/dist/app/assets/{core-Dp3q5Ieu.es-CD5FvM2s.js → core-C0nunIQT.es-DlMLKZBK.js} +1 -1
  14. package/dist/app/assets/{index-DU4r7GdU.js → index-BabP-V-S.js} +346 -321
  15. package/dist/app/assets/{index-BLCx1EdC.js → index-BusxL5Pt.js} +1 -1
  16. package/dist/app/assets/{index-C_tJstcx.js → index-CmEVVe-8.js} +15 -15
  17. package/dist/app/assets/{index-CfmBVB6M.js → index-Cs4WVm2z.js} +1 -1
  18. package/dist/app/assets/{index-B3Nn8Vm2.js → index-qnhU9CGo.js} +266 -265
  19. package/dist/app/index.html +1 -1
  20. package/dist/instrumentation.mjs +2 -0
  21. package/dist/package_load_worker.mjs +11 -1
  22. package/dist/server.mjs +22627 -1260
  23. package/package.json +12 -12
  24. package/scripts/bake-duckdb-extensions.js +4 -1
  25. package/src/config.spec.ts +39 -0
  26. package/src/config.ts +135 -0
  27. package/src/controller/materialization.controller.spec.ts +62 -0
  28. package/src/controller/materialization.controller.ts +15 -0
  29. package/src/controller/package.controller.spec.ts +6 -0
  30. package/src/controller/package.controller.ts +7 -2
  31. package/src/controller/query.controller.ts +26 -21
  32. package/src/errors.ts +19 -0
  33. package/src/json_utils.spec.ts +51 -0
  34. package/src/json_utils.ts +33 -0
  35. package/src/logger.spec.ts +18 -1
  36. package/src/logger.ts +3 -1
  37. package/src/materialization_metrics.spec.ts +89 -4
  38. package/src/materialization_metrics.ts +155 -5
  39. package/src/mcp/query_envelope.spec.ts +229 -0
  40. package/src/mcp/query_envelope.ts +230 -0
  41. package/src/mcp/server.protocol.spec.ts +128 -16
  42. package/src/mcp/skills/build_skills_bundle.ts +94 -4
  43. package/src/mcp/skills/skills_bundle.json +1 -1
  44. package/src/mcp/skills/skills_bundle.spec.ts +113 -4
  45. package/src/mcp/tool_response.spec.ts +108 -0
  46. package/src/mcp/tool_response.ts +138 -0
  47. package/src/mcp/tools/compile_tool.spec.ts +112 -4
  48. package/src/mcp/tools/compile_tool.ts +61 -30
  49. package/src/mcp/tools/docs_search_tool.ts +6 -16
  50. package/src/mcp/tools/embedding_index.spec.ts +1236 -0
  51. package/src/mcp/tools/embedding_index.ts +808 -0
  52. package/src/mcp/tools/execute_query_tool.spec.ts +23 -3
  53. package/src/mcp/tools/execute_query_tool.ts +90 -151
  54. package/src/mcp/tools/get_context_eval.ts +194 -45
  55. package/src/mcp/tools/get_context_tool.spec.ts +358 -5
  56. package/src/mcp/tools/get_context_tool.ts +202 -56
  57. package/src/mcp/tools/reload_package_tool.ts +3 -29
  58. package/src/pg_helpers.spec.ts +201 -0
  59. package/src/pg_helpers.ts +44 -5
  60. package/src/server.ts +24 -0
  61. package/src/service/build_plan.spec.ts +128 -2
  62. package/src/service/build_plan.ts +239 -17
  63. package/src/service/compile_fragment_techniques.spec.ts +156 -0
  64. package/src/service/connection.spec.ts +371 -1
  65. package/src/service/connection.ts +339 -20
  66. package/src/service/connection_config.spec.ts +108 -0
  67. package/src/service/connection_config.ts +47 -8
  68. package/src/service/connection_federation.spec.ts +184 -0
  69. package/src/service/duckdb_instance_isolation.spec.ts +137 -0
  70. package/src/service/embedding_provider.spec.ts +329 -0
  71. package/src/service/embedding_provider.ts +236 -0
  72. package/src/service/environment.ts +274 -12
  73. package/src/service/environment_store.spec.ts +678 -3
  74. package/src/service/environment_store.ts +449 -33
  75. package/src/service/environment_store_clone.spec.ts +350 -0
  76. package/src/service/manifest_loader.spec.ts +68 -13
  77. package/src/service/manifest_loader.ts +67 -19
  78. package/src/service/materialization_build_session.spec.ts +435 -0
  79. package/src/service/materialization_build_session.ts +681 -0
  80. package/src/service/materialization_eligibility.spec.ts +158 -0
  81. package/src/service/materialization_eligibility.ts +305 -0
  82. package/src/service/materialization_serve_transform.spec.ts +1003 -0
  83. package/src/service/materialization_serve_transform.ts +779 -0
  84. package/src/service/materialization_service.spec.ts +774 -7
  85. package/src/service/materialization_service.ts +1107 -42
  86. package/src/service/materialization_test_fixtures.ts +7 -0
  87. package/src/service/model.spec.ts +207 -0
  88. package/src/service/model.ts +569 -59
  89. package/src/service/model_limits.spec.ts +28 -0
  90. package/src/service/model_limits.ts +21 -0
  91. package/src/service/model_storage_serve.spec.ts +193 -0
  92. package/src/service/model_storage_serve_joins.spec.ts +193 -0
  93. package/src/service/package.spec.ts +196 -0
  94. package/src/service/package.ts +385 -17
  95. package/src/service/persistence_policy.spec.ts +109 -0
  96. package/src/storage/duckdb/schema.ts +37 -0
  97. package/tests/fixtures/xlsx/database.xlsx +0 -0
  98. package/tests/integration/first_boot/readiness_line.integration.spec.ts +177 -0
  99. package/tests/integration/materialization/manifest_binding.integration.spec.ts +104 -0
  100. package/tests/integration/mcp/mcp_execute_query_tool.integration.spec.ts +37 -12
  101. package/tests/integration/mcp/mcp_get_context_semantic.integration.spec.ts +235 -0
@@ -1,6 +1,11 @@
1
1
  import { describe, expect, it } from "bun:test";
2
+ import * as fs from "node:fs";
2
3
  import * as path from "node:path";
3
- import { buildSkills, type SkillEntry } from "./build_skills_bundle";
4
+ import {
5
+ buildSkills,
6
+ isCredible,
7
+ type SkillEntry,
8
+ } from "./build_skills_bundle";
4
9
  import bundle from "./skills_bundle.json";
5
10
 
6
11
  const skills = (
@@ -54,9 +59,113 @@ describe("skills_bundle.json (generated dual-channel asset)", () => {
54
59
  expect(new Set(names).size).toBe(names.length);
55
60
  });
56
61
 
62
+ /**
63
+ * A skill's reference/ files are its on-demand detail, and this channel is
64
+ * the only way a host without the skills on disk can reach them. Before they
65
+ * were bundled, malloy-review told an agent to load rubrics that, over MCP,
66
+ * did not exist.
67
+ */
68
+ describe("reference files", () => {
69
+ const isReference = (s: SkillEntry) => s.name.includes("/");
70
+ const referenceEntries = skills.filter(isReference);
71
+
72
+ it("bundles every reference/*.md in the tree", () => {
73
+ // Mirror the builder's own exclusion. A stray credible-* skill with a
74
+ // reference/ dir is never bundled, so walking without this filter
75
+ // fails on a correct bundle.
76
+ const onDisk = fs
77
+ .readdirSync(sourceDir, { withFileTypes: true })
78
+ .filter((d) => d.isDirectory() && !isCredible(d.name))
79
+ .flatMap((d) => {
80
+ const dir = path.join(sourceDir, d.name, "reference");
81
+ return fs.existsSync(dir)
82
+ ? fs
83
+ .readdirSync(dir)
84
+ .filter((f) => f.endsWith(".md"))
85
+ .map((f) => `${d.name}/${path.basename(f, ".md")}`)
86
+ : [];
87
+ });
88
+
89
+ expect(onDisk.length).toBeGreaterThan(0);
90
+ expect(referenceEntries.map((s) => s.name).sort()).toEqual(
91
+ onDisk.sort(),
92
+ );
93
+ });
94
+
95
+ it("names each one under its parent skill", () => {
96
+ const skillNames = new Set(
97
+ skills.filter((s) => !isReference(s)).map((s) => s.name),
98
+ );
99
+ for (const entry of referenceEntries) {
100
+ expect(skillNames.has(entry.name.split("/")[0])).toBe(true);
101
+ }
102
+ });
103
+
104
+ it("gives each one a description drawn from its heading", () => {
105
+ // Reference files carry no frontmatter, so a listing would otherwise
106
+ // show them nameless. Every file in the tree has an H1 to use.
107
+ //
108
+ // Assert against the no-heading fallback rather than a length floor:
109
+ // the fallback is itself long enough to clear any such floor, so a
110
+ // length check alone stays green even if heading extraction breaks
111
+ // entirely and all of a skill's entries collapse to one string.
112
+ for (const entry of referenceEntries) {
113
+ const parent = entry.name.split("/")[0];
114
+ expect(entry.description).toContain("Reference detail for");
115
+ expect(entry.description).not.toBe(
116
+ `Reference detail for the ${parent} skill.`,
117
+ );
118
+ }
119
+ });
120
+
121
+ it("tells the parent skill where its reference files went", () => {
122
+ // The parent body points at them by relative path, which resolves for
123
+ // a host reading files off disk and not for one given this as a prompt.
124
+ const parents = new Set(
125
+ referenceEntries.map((s) => s.name.split("/")[0]),
126
+ );
127
+ for (const name of parents) {
128
+ const parent = skills.find((s) => s.name === name);
129
+ expect(parent?.body).toContain("Reference files over MCP");
130
+ expect(parent?.body).toContain(`get the prompt named \`${name}/`);
131
+ }
132
+ });
133
+
134
+ it("leaves skills without a reference/ directory untouched", () => {
135
+ const plain = skills.find((s) => s.name === "malloy-getting-started");
136
+ expect(plain?.body).not.toContain("Reference files over MCP");
137
+ });
138
+ });
139
+
140
+ /**
141
+ * Pre-existing drift, bounded rather than exempted. Every SKILL.md honours
142
+ * the house style; these three reference files never did, because nothing
143
+ * checked them until they entered the bundle. Fixing 23 prose em-dashes in
144
+ * three SHARED skills is an upstream-first change of its own, not something
145
+ * to bundle into the build-time asset that surfaced it.
146
+ *
147
+ * Listed by name so a NEW violation still fails: shrink this list as the
148
+ * files are fixed, and delete it when it is empty.
149
+ */
150
+ const EM_DASH_DRIFT = new Set([
151
+ "malloy-html-data-apps/lazy-load",
152
+ "malloy-html-data-apps/verification-harness",
153
+ "malloy-lookml-review/build-derived-tables",
154
+ ]);
155
+
57
156
  it("carries no em-dashes (house style)", () => {
58
- for (const s of skills) {
59
- expect(s.body).not.toContain("—");
60
- }
157
+ const offenders = skills
158
+ .filter((s) => !EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
159
+ .map((s) => s.name);
160
+ expect(offenders).toEqual([]);
161
+ });
162
+
163
+ it("the em-dash allowlist names only entries that still need fixing", () => {
164
+ // Stops the list outliving the drift: an entry that has been cleaned up,
165
+ // or renamed away, has to leave the list.
166
+ const stillDrifting = skills
167
+ .filter((s) => EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
168
+ .map((s) => s.name);
169
+ expect([...EM_DASH_DRIFT].sort()).toEqual(stillDrifting.sort());
61
170
  });
62
171
  });
@@ -0,0 +1,108 @@
1
+ import { describe, expect, it } from "bun:test";
2
+ import { formatErrorText, jsonResource, jsonToolError } from "./tool_response";
3
+
4
+ // Pins the wire shape every malloy_* tool returns. Two properties here are
5
+ // regressions waiting to happen, so they are asserted explicitly rather than
6
+ // left to the tools' own specs:
7
+ //
8
+ // - the resource carries `mimeType`, not `type`. `type` is not in the MCP
9
+ // ResourceContents schema; it was accepted by .passthrough() and ignored.
10
+ // - an error result carries a text block. The structured payload alone is
11
+ // invisible to a client that renders only text for isError results.
12
+
13
+ describe("jsonResource", () => {
14
+ it("puts the resource block first and types it with mimeType", () => {
15
+ const r = jsonResource("malloy:/x", { a: 1 });
16
+
17
+ expect(r.isError).toBe(false);
18
+ expect(r.content).toHaveLength(1);
19
+ expect(r.content[0].type).toBe("resource");
20
+
21
+ const resource = (r.content[0] as { resource: Record<string, unknown> })
22
+ .resource;
23
+ expect(resource.mimeType).toBe("application/json");
24
+ expect(resource.uri).toBe("malloy:/x");
25
+ // The pre-fix spelling must not come back.
26
+ expect(resource.type).toBeUndefined();
27
+ expect(JSON.parse(resource.text as string)).toEqual({ a: 1 });
28
+ });
29
+
30
+ it("appends an optional text block after the resource", () => {
31
+ const r = jsonResource("malloy:/x", { a: 1 }, { text: "heads up" });
32
+
33
+ expect(r.content).toHaveLength(2);
34
+ expect(r.content[0].type).toBe("resource");
35
+ expect(r.content[1]).toEqual({ type: "text", text: "heads up" });
36
+ });
37
+
38
+ it("omits the text block when no text is supplied", () => {
39
+ expect(jsonResource("malloy:/x", {}).content).toHaveLength(1);
40
+ });
41
+
42
+ it("honours the space option without changing the parsed payload", () => {
43
+ const compact = jsonResource("malloy:/x", { a: 1 });
44
+ const pretty = jsonResource("malloy:/x", { a: 1 }, { space: 2 });
45
+
46
+ const text = (r: typeof compact) =>
47
+ (r.content[0] as { resource: { text: string } }).resource.text;
48
+
49
+ expect(text(pretty)).toContain("\n");
50
+ expect(text(compact)).not.toContain("\n");
51
+ expect(JSON.parse(text(pretty))).toEqual(JSON.parse(text(compact)));
52
+ });
53
+ });
54
+
55
+ describe("formatErrorText", () => {
56
+ it("renders the message and every suggestion", () => {
57
+ const text = formatErrorText({
58
+ message: "Resource not found: env/pkg",
59
+ suggestions: ["Check the spelling.", "Call malloy_getContext."],
60
+ });
61
+
62
+ expect(text).toContain("Resource not found: env/pkg");
63
+ expect(text).toContain("- Check the spelling.");
64
+ expect(text).toContain("- Call malloy_getContext.");
65
+ });
66
+
67
+ it("returns the bare message when there are no suggestions", () => {
68
+ expect(formatErrorText({ message: "boom", suggestions: [] })).toBe(
69
+ "boom",
70
+ );
71
+ });
72
+ });
73
+
74
+ describe("jsonToolError", () => {
75
+ const details = {
76
+ message: "Cannot redefine 'overview'",
77
+ suggestions: ["Rename the view."],
78
+ };
79
+
80
+ it("sets isError and carries the message in BOTH blocks", () => {
81
+ const r = jsonToolError("error://compile", details);
82
+
83
+ expect(r.isError).toBe(true);
84
+ expect(r.content).toHaveLength(2);
85
+
86
+ const payload = JSON.parse(
87
+ (r.content[0] as { resource: { text: string } }).resource.text,
88
+ );
89
+ expect(payload.error).toBe("Cannot redefine 'overview'");
90
+ expect(payload.suggestions).toEqual(["Rename the view."]);
91
+
92
+ // The whole point of the change: a text-only client still sees it.
93
+ const textBlock = r.content[1] as { type: string; text: string };
94
+ expect(textBlock.type).toBe("text");
95
+ expect(textBlock.text).toContain("Cannot redefine 'overview'");
96
+ expect(textBlock.text).toContain("- Rename the view.");
97
+ });
98
+
99
+ it("merges extraPayload so getContext keeps its results key", () => {
100
+ const r = jsonToolError("error://ctx", details, { results: [] });
101
+
102
+ const payload = JSON.parse(
103
+ (r.content[0] as { resource: { text: string } }).resource.text,
104
+ );
105
+ expect(payload.results).toEqual([]);
106
+ expect(payload.error).toBe("Cannot redefine 'overview'");
107
+ });
108
+ });
@@ -0,0 +1,138 @@
1
+ import type { ErrorDetails } from "./error_messages";
2
+
3
+ /**
4
+ * Shared construction of the MCP content blocks every malloy_* tool returns.
5
+ *
6
+ * Two things here are load-bearing and were previously wrong at every call site:
7
+ *
8
+ * 1. The resource block carries `mimeType`, not `type`. The MCP
9
+ * ResourceContents schema is `z.object({uri, mimeType?, _meta?}).passthrough()`,
10
+ * so a `type: "application/json"` field was accepted by passthrough and then
11
+ * ignored by every client, leaving the payload untyped on the wire.
12
+ *
13
+ * 2. An error result also emits a plain text block. A client that renders only
14
+ * text blocks when `isError` is set sees nothing at all in an embedded
15
+ * resource, and reports a bare "Unknown error" while the server's real
16
+ * message and suggestions sit unread in the resource. The text block is what
17
+ * makes a diagnostic legible; the resource block is what keeps it parseable.
18
+ *
19
+ * Ordering matters: the resource block stays at index 0 so callers (and specs)
20
+ * can keep reading `content[0].resource.text` for the structured payload.
21
+ */
22
+
23
+ const JSON_MIME_TYPE = "application/json";
24
+
25
+ // The index signatures mirror the MCP SDK's CallToolResult types, which declare
26
+ // `[x: string]: unknown` on the result and on every content block. Without them
27
+ // these are not assignable to the SDK's tool-callback return type.
28
+ type ResourceBlock = {
29
+ [x: string]: unknown;
30
+ type: "resource";
31
+ resource: {
32
+ [x: string]: unknown;
33
+ uri: string;
34
+ mimeType: string;
35
+ text: string;
36
+ };
37
+ };
38
+
39
+ type TextBlock = { [x: string]: unknown; type: "text"; text: string };
40
+
41
+ export type ToolContent = ResourceBlock | TextBlock;
42
+
43
+ export interface ToolResult {
44
+ [x: string]: unknown;
45
+ isError: boolean;
46
+ content: ToolContent[];
47
+ }
48
+
49
+ function resourceBlock(
50
+ uri: string,
51
+ payload: unknown,
52
+ space?: number,
53
+ replacer?: (key: string, value: unknown) => unknown,
54
+ ): ResourceBlock {
55
+ return {
56
+ type: "resource" as const,
57
+ resource: {
58
+ uri,
59
+ mimeType: JSON_MIME_TYPE,
60
+ text: JSON.stringify(payload, replacer, space),
61
+ },
62
+ };
63
+ }
64
+
65
+ /**
66
+ * Renders ErrorDetails as the prose a client will actually show the agent.
67
+ *
68
+ * The suggestions are included, not just the message: they carry the part that
69
+ * makes an error actionable (which source was denied, which view to look for,
70
+ * that a reload is needed), and a client that cannot read the resource block
71
+ * has no other way to reach them. They are a short, bounded list by
72
+ * construction in error_messages.ts.
73
+ *
74
+ * Exported so a spec can pin the rendering rather than merely its presence.
75
+ */
76
+ export function formatErrorText(details: ErrorDetails): string {
77
+ if (details.suggestions.length === 0) {
78
+ return details.message;
79
+ }
80
+ const suggestions = details.suggestions.map((s) => `- ${s}`).join("\n");
81
+ return `${details.message}\n\nSuggestions:\n${suggestions}`;
82
+ }
83
+
84
+ /**
85
+ * Wraps a JSON payload in the resource-content shape, optionally adding a text
86
+ * block alongside it.
87
+ *
88
+ * `text` is deliberately opt-in rather than automatic on success: a query result
89
+ * is already size-capped (assertWithinModelResponseLimits), and duplicating it
90
+ * as prose would double the payload for no gain. Success paths that have
91
+ * something short and useful to say (render-tag warnings) pass it explicitly.
92
+ *
93
+ * @param space JSON.stringify indentation. Left undefined (compact) except for
94
+ * query results, which have always been pretty-printed for readability.
95
+ */
96
+ export function jsonResource(
97
+ uri: string,
98
+ payload: unknown,
99
+ options?: {
100
+ isError?: boolean;
101
+ text?: string;
102
+ space?: number;
103
+ /** Needed when the payload can carry BigInt: see json_utils.bigIntReplacer. */
104
+ replacer?: (key: string, value: unknown) => unknown;
105
+ },
106
+ ): ToolResult {
107
+ const content: ToolContent[] = [
108
+ resourceBlock(uri, payload, options?.space, options?.replacer),
109
+ ];
110
+ if (options?.text !== undefined) {
111
+ content.push({ type: "text" as const, text: options.text });
112
+ }
113
+ return { isError: options?.isError ?? false, content };
114
+ }
115
+
116
+ /**
117
+ * Builds the standard error result: the {error, suggestions} JSON a parsing
118
+ * client wants, plus the same information as text so every client can read it.
119
+ *
120
+ * @param extraPayload Merged into the JSON payload. malloy_getContext uses it
121
+ * to keep its `results: []` contract on the error path, which its callers
122
+ * (and specs) rely on to treat every tier's response shape uniformly.
123
+ */
124
+ export function jsonToolError(
125
+ uri: string,
126
+ details: ErrorDetails,
127
+ extraPayload?: Record<string, unknown>,
128
+ ): ToolResult {
129
+ return jsonResource(
130
+ uri,
131
+ {
132
+ error: details.message,
133
+ suggestions: details.suggestions,
134
+ ...extraPayload,
135
+ },
136
+ { isError: true, text: formatErrorText(details) },
137
+ );
138
+ }
@@ -1,5 +1,5 @@
1
1
  import { describe, expect, it } from "bun:test";
2
- import { registerCompileTool } from "./compile_tool";
2
+ import { formatDiagnosticsText, registerCompileTool } from "./compile_tool";
3
3
  import type { EnvironmentStore } from "../../service/environment_store";
4
4
  import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
5
5
 
@@ -7,9 +7,15 @@ import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
7
7
  // be exercised against a mocked EnvironmentStore. The tool builds a
8
8
  // CompileController internally, which calls environment.compileSource, so the
9
9
  // mock only needs getEnvironment -> { compileSource }.
10
+ type Content = Array<{
11
+ type?: string;
12
+ text?: string;
13
+ resource?: { text: string };
14
+ }>;
15
+
10
16
  type Handler = (params: Record<string, unknown>) => Promise<{
11
17
  isError?: boolean;
12
- content: Array<{ resource: { text: string } }>;
18
+ content: Content;
13
19
  }>;
14
20
 
15
21
  function captureHandler(store: Partial<EnvironmentStore>): Handler {
@@ -24,8 +30,12 @@ function captureHandler(store: Partial<EnvironmentStore>): Handler {
24
30
  return handler;
25
31
  }
26
32
 
27
- function parse(result: { content: Array<{ resource: { text: string } }> }) {
28
- return JSON.parse(result.content[0].resource.text);
33
+ function parse(result: { content: Content }) {
34
+ return JSON.parse(result.content[0].resource!.text);
35
+ }
36
+
37
+ function textBlock(result: { content: Content }) {
38
+ return result.content.find((b) => b.type === "text")?.text;
29
39
  }
30
40
 
31
41
  function storeReturning(
@@ -89,6 +99,40 @@ describe("malloy_compile tool", () => {
89
99
  ]);
90
100
  });
91
101
 
102
+ it("also states the diagnostics in a text block", async () => {
103
+ // The regression pin for the isError path that matters most: a bad Malloy
104
+ // snippet. A client that renders only text blocks on isError sees nothing
105
+ // without this, and reports a bare "Unknown error" while the diagnostics
106
+ // sit unread in the resource block.
107
+ const handler = captureHandler(
108
+ storeReturning([
109
+ {
110
+ severity: "error",
111
+ message: "'nope' is not defined",
112
+ code: "field-not-found",
113
+ at: {
114
+ range: {
115
+ start: { line: 2, character: 3 },
116
+ end: { line: 2, character: 7 },
117
+ },
118
+ },
119
+ },
120
+ ]),
121
+ );
122
+ const result = await handler(args);
123
+ expect(textBlock(result)).toBe(
124
+ "Compile failed with 1 error (positions are 0-based):\n\n" +
125
+ "- 'nope' is not defined (line 2, character 3) [field-not-found]",
126
+ );
127
+ });
128
+
129
+ it("adds no text block to a clean compile", async () => {
130
+ // Success stays resource-only: the payload is the answer, and duplicating
131
+ // it as prose would double every response for no gain.
132
+ const handler = captureHandler(storeReturning([]));
133
+ expect(textBlock(await handler(args))).toBeUndefined();
134
+ });
135
+
92
136
  it("treats a warning as a clean compile (status success, isError false)", async () => {
93
137
  const handler = captureHandler(
94
138
  storeReturning([
@@ -184,6 +228,70 @@ describe("malloy_compile tool", () => {
184
228
  });
185
229
  });
186
230
 
231
+ describe("formatDiagnosticsText", () => {
232
+ it("renders only the error-severity diagnostics", () => {
233
+ const text = formatDiagnosticsText([
234
+ { severity: "warn", message: "deprecated syntax", code: "dep" },
235
+ { severity: "error", message: "first", line: 1, character: 0 },
236
+ { severity: "error", message: "second", line: 4, character: 2 },
237
+ ]);
238
+ expect(text).toBe(
239
+ "Compile failed with 2 errors (positions are 0-based):\n\n" +
240
+ "- first (line 1, character 0)\n" +
241
+ "- second (line 4, character 2)",
242
+ );
243
+ expect(text).not.toContain("deprecated syntax");
244
+ });
245
+
246
+ it("omits the position when a diagnostic has no location", () => {
247
+ expect(
248
+ formatDiagnosticsText([
249
+ { severity: "error", message: "no location", code: "syntax" },
250
+ ]),
251
+ ).toBe(
252
+ "Compile failed with 1 error (positions are 0-based):\n\n" +
253
+ "- no location [syntax]",
254
+ );
255
+ });
256
+
257
+ it("renders line 0 / character 0 rather than dropping them", () => {
258
+ // 0 is a real position, not a missing one; a falsy check here would
259
+ // silently swallow the first line of the file.
260
+ expect(
261
+ formatDiagnosticsText([
262
+ {
263
+ severity: "error",
264
+ message: "at the top",
265
+ line: 0,
266
+ character: 0,
267
+ },
268
+ ]),
269
+ ).toContain("- at the top (line 0, character 0)");
270
+ });
271
+
272
+ it("defaults character to 0 when only the line is known", () => {
273
+ expect(
274
+ formatDiagnosticsText([
275
+ { severity: "error", message: "line only", line: 7 },
276
+ ]),
277
+ ).toContain("- line only (line 7, character 0)");
278
+ });
279
+
280
+ it("falls back to every diagnostic when none has error severity", () => {
281
+ // Defensive: status is "error" only when an error-severity diagnostic
282
+ // exists, so this should be unreachable. It must not render an empty
283
+ // list if that ever changes.
284
+ expect(
285
+ formatDiagnosticsText([
286
+ { severity: "warn", message: "only a warn" },
287
+ ]),
288
+ ).toBe(
289
+ "Compile failed with 1 error (positions are 0-based):\n\n" +
290
+ "- only a warn",
291
+ );
292
+ });
293
+ });
294
+
187
295
  it("forwards givens to compileSource", async () => {
188
296
  let captured: unknown;
189
297
  const handler = captureHandler({
@@ -6,6 +6,7 @@ import { EnvironmentStore } from "../../service/environment_store";
6
6
  import { CompileController } from "../../controller/compile.controller";
7
7
  import { type ErrorDetails } from "../error_messages";
8
8
  import { buildMalloyUri, classifyToolError } from "../handler_utils";
9
+ import { jsonResource, jsonToolError } from "../tool_response";
9
10
 
10
11
  // Zod shape for malloy_compile. environmentName/packageName mirror the other
11
12
  // tools and point the agent at malloy_getContext for name discovery.
@@ -51,8 +52,53 @@ const COMPILE_DESCRIPTION = `Compile-check Malloy source against a model and ret
51
52
  - source (required): the Malloy text to validate.
52
53
  - includeSql (optional): also return the generated SQL when the source ends in a runnable query. The query is still not executed and no data is scanned.
53
54
 
55
+ ## Checking part of a source
56
+ Your source is APPENDED, so it must stand alone as top-level Malloy: a bare \`view:\`, \`dimension:\` or \`measure:\` does not compile on its own, and resubmitting a source the model already declares reports "Cannot redefine". docs/ai-agents.md gives the two forms that work.
57
+
54
58
  ## Response
55
- A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity.`;
59
+ A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. Any wrapper you add counts toward that offset too. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity. When status is "error" the response also states the error diagnostics in a plain text block alongside the JSON, so the failure is legible without parsing the payload.`;
60
+
61
+ /** The flattened diagnostic shape this tool returns. */
62
+ type CompileDiagnostic = {
63
+ severity: string;
64
+ message: string;
65
+ code?: string;
66
+ line?: number;
67
+ character?: number;
68
+ };
69
+
70
+ /**
71
+ * Renders error diagnostics as the prose a text-only client will show.
72
+ *
73
+ * A failed compile is an isError result whose diagnostics live in the resource
74
+ * block, so a client that renders only text blocks on isError sees nothing —
75
+ * which is how a real compile error gets reported as a bare "Unknown error".
76
+ * The resource block stays the parseable channel; this is the legible one.
77
+ * Positions are labelled 0-based to match the payload rather than introduce a
78
+ * second convention for the same numbers.
79
+ *
80
+ * Only error-severity diagnostics are rendered: status is "error" because of
81
+ * those, and they are what the caller has to fix. Falling back to every
82
+ * diagnostic keeps the text non-empty if that invariant ever breaks.
83
+ *
84
+ * Exported so a spec can pin the rendering rather than merely its presence.
85
+ */
86
+ export function formatDiagnosticsText(
87
+ diagnostics: CompileDiagnostic[],
88
+ ): string {
89
+ const errors = diagnostics.filter((d) => d.severity === "error");
90
+ const shown = errors.length > 0 ? errors : diagnostics;
91
+ const lines = shown.map((d) => {
92
+ const at =
93
+ d.line !== undefined
94
+ ? ` (line ${d.line}, character ${d.character ?? 0})`
95
+ : "";
96
+ const code = d.code ? ` [${d.code}]` : "";
97
+ return `- ${d.message}${at}${code}`;
98
+ });
99
+ const noun = shown.length === 1 ? "error" : "errors";
100
+ return `Compile failed with ${shown.length} ${noun} (positions are 0-based):\n\n${lines.join("\n")}`;
101
+ }
56
102
 
57
103
  /**
58
104
  * Registers the malloy_compile MCP tool: validates Malloy source against a model
@@ -125,19 +171,19 @@ export function registerCompileTool(
125
171
  ...(result.sql !== undefined && { sql: result.sql }),
126
172
  };
127
173
 
128
- return {
129
- isError: result.status === "error",
130
- content: [
131
- {
132
- type: "resource" as const,
133
- resource: {
134
- type: "application/json",
135
- uri,
136
- text: JSON.stringify(payload),
137
- },
138
- },
139
- ],
140
- };
174
+ // A compile that returns error diagnostics is still a successful
175
+ // tool call in the transport sense, but isError tells the agent not
176
+ // to treat the model as valid. This is the most common way the tool
177
+ // fails, so it carries a text block for the same reason the catch
178
+ // below does: the diagnostics are only the message to a client that
179
+ // parses the resource. The payload keeps its documented
180
+ // {status, diagnostics} shape rather than the {error, suggestions}
181
+ // of jsonToolError, so parsing clients are unaffected.
182
+ const isError = result.status === "error";
183
+ return jsonResource(uri, payload, {
184
+ isError,
185
+ ...(isError && { text: formatDiagnosticsText(diagnostics) }),
186
+ });
141
187
  } catch (error) {
142
188
  // Unknown environment/package, a notebook (.malloynb) rejected up
143
189
  // front, an authorize denial, or a system error: surface as a clean
@@ -155,22 +201,7 @@ export function registerCompileTool(
155
201
  `${environmentName}/${packageName}/${modelPath}`,
156
202
  error,
157
203
  );
158
- return {
159
- isError: true,
160
- content: [
161
- {
162
- type: "resource" as const,
163
- resource: {
164
- type: "application/json",
165
- uri,
166
- text: JSON.stringify({
167
- error: errorDetails.message,
168
- suggestions: errorDetails.suggestions,
169
- }),
170
- },
171
- },
172
- ],
173
- };
204
+ return jsonToolError(uri, errorDetails);
174
205
  }
175
206
  },
176
207
  );