@malloy-publisher/server 0.0.207 → 0.0.209

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.207",
+   "version": "0.0.209",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -36,16 +36,17 @@
       "@azure/storage-blob": "^12.26.0",
       "@duckdb/node-api": "1.5.3-r.2",
       "@google-cloud/storage": "^7.16.0",
-      "@malloydata/db-bigquery": "^0.0.405",
-      "@malloydata/db-databricks": "^0.0.405",
-      "@malloydata/db-duckdb": "^0.0.405",
-      "@malloydata/db-mysql": "^0.0.405",
-      "@malloydata/db-postgres": "^0.0.405",
-      "@malloydata/db-snowflake": "^0.0.405",
-      "@malloydata/db-trino": "^0.0.405",
-      "@malloydata/malloy": "^0.0.405",
-      "@malloydata/malloy-sql": "^0.0.405",
-      "@malloydata/render-validator": "^0.0.405",
+      "@malloydata/db-bigquery": "^0.0.415",
+      "@malloydata/db-databricks": "^0.0.415",
+      "@malloydata/db-duckdb": "^0.0.415",
+      "@malloydata/db-mysql": "^0.0.415",
+      "@malloydata/db-postgres": "^0.0.415",
+      "@malloydata/db-publisher": "^0.0.415",
+      "@malloydata/db-snowflake": "^0.0.415",
+      "@malloydata/db-trino": "^0.0.415",
+      "@malloydata/malloy": "^0.0.415",
+      "@malloydata/malloy-sql": "^0.0.415",
+      "@malloydata/render-validator": "^0.0.415",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.57.0",
@@ -65,6 +66,7 @@
       "globals": "^15.9.0",
       "handlebars": "^4.7.8",
       "http-proxy-middleware": "^3.0.5",
+      "lunr": "^2.3.6",
       "morgan": "^1.10.0",
       "node-cron": "^3.0.3",
       "recursive-readdir": "^2.2.3",
@@ -80,6 +82,7 @@
       "@types/bun": "^1.2.20",
       "@types/cors": "^2.8.12",
       "@types/express": "^4.17.14",
+      "@types/lunr": "^2.3.7",
       "@types/morgan": "^1.9.9",
       "@types/node": "^24.10.1",
       "@types/node-cron": "^3.0.11",

package/src/controller/materialization.controller.spec.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "bun:test";
+import * as sinon from "sinon";
+import { BadRequestError } from "../errors";
+import type { MaterializationService } from "../service/materialization_service";
+import { MaterializationController } from "./materialization.controller";
+
+/**
+ * Unit tests for {@link MaterializationController.createMaterialization}'s body
+ * validation. The service is stubbed so each test asserts the parsed options
+ * the controller forwards (or the rejection for a malformed body).
+ */
+function build() {
+   const createMaterialization = sinon.stub().resolves({ id: "m1" });
+   const service = {
+      createMaterialization,
+   } as unknown as MaterializationService;
+   const controller = new MaterializationController(service);
+   return { controller, createMaterialization };
+}
+
+/** Parsed options the controller forwards for a given request body. */
+async function parse(body: Record<string, unknown>) {
+   const { controller, createMaterialization } = build();
+   await controller.createMaterialization("env", "pkg", body);
+   return createMaterialization.firstCall.args[2];
+}
+
+describe("MaterializationController.createMaterialization validation", () => {
+   it("forwards an empty body as empty options", async () => {
+      expect(await parse({})).toEqual({});
+   });
+
+   it("passes through forceRefresh and sourceNames", async () => {
+      expect(
+         await parse({ forceRefresh: true, sourceNames: ["a", "b"] }),
+      ).toEqual({ forceRefresh: true, sourceNames: ["a", "b"] });
+   });
+
+   it("rejects a non-boolean forceRefresh", async () => {
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            forceRefresh: "yes",
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("rejects sourceNames that is not an array of strings", async () => {
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            sourceNames: [1, 2],
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("flattens buildInstructions.sources into the instruction list", async () => {
+      const parsed = await parse({
+         buildInstructions: {
+            sources: [
+               {
+                  buildId: "b1",
+                  sourceID: "orders@m",
+                  materializedTableId: "mt-1",
+                  physicalTableName: "orders_v1",
+                  realization: "COPY",
+               },
+            ],
+         },
+      });
+      expect(parsed).toEqual({
+         buildInstructions: [
+            {
+               buildId: "b1",
+               sourceID: "orders@m",
+               materializedTableId: "mt-1",
+               physicalTableName: "orders_v1",
+               realization: "COPY",
+            },
+         ],
+      });
+   });
+
+   it("treats null buildInstructions as absent (auto-run)", async () => {
+      expect(await parse({ buildInstructions: null })).toEqual({});
+   });
+
+   it("rejects buildInstructions without a non-empty sources array", async () => {
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            buildInstructions: { sources: [] },
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("rejects an instruction missing a required field", async () => {
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            buildInstructions: {
+               sources: [{ buildId: "b1", materializedTableId: "mt-1" }],
+            },
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("rejects an unrecognized realization", async () => {
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            buildInstructions: {
+               sources: [
+                  {
+                     buildId: "b1",
+                     materializedTableId: "mt-1",
+                     physicalTableName: "orders_v1",
+                     realization: "MERGE",
+                  },
+               ],
+            },
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+});

package/src/controller/materialization.controller.ts

@@ -20,18 +20,20 @@ export class MaterializationController {
    private validateCreateBody(body: Record<string, unknown>): {
       forceRefresh?: boolean;
       sourceNames?: string[];
-      pauseBetweenPhases?: boolean;
+      buildInstructions?: BuildInstruction[];
    } {
       const result: {
          forceRefresh?: boolean;
          sourceNames?: string[];
-         pauseBetweenPhases?: boolean;
+         buildInstructions?: BuildInstruction[];
       } = {};
-      if (body.pauseBetweenPhases !== undefined) {
-         if (typeof body.pauseBetweenPhases !== "boolean") {
-            throw new BadRequestError("pauseBetweenPhases must be a boolean");
-         }
-         result.pauseBetweenPhases = body.pauseBetweenPhases;
+      if (
+         body.buildInstructions !== undefined &&
+         body.buildInstructions !== null
+      ) {
+         result.buildInstructions = this.validateBuildInstructions(
+            body.buildInstructions,
+         );
       }
       if (body.forceRefresh !== undefined) {
          if (typeof body.forceRefresh !== "boolean") {
@@ -53,30 +55,24 @@ export class MaterializationController {
       return result;
    }
 
-   async buildMaterialization(
-      environmentName: string,
-      packageName: string,
-      materializationId: string,
-      body: Record<string, unknown>,
-   ) {
-      return this.materializationService.buildMaterialization(
-         environmentName,
-         packageName,
-         materializationId,
-         this.validateBuildBody(body),
-      );
-   }
-
-   private validateBuildBody(
-      body: Record<string, unknown>,
-   ): BuildInstruction[] {
-      const sources = body.sources;
+   /**
+    * Validate the orchestrated `buildInstructions` payload (BuildInstructions:
+    * `{ sources: BuildInstruction[] }`) and flatten it to the instruction list
+    * the service consumes.
+    */
+   private validateBuildInstructions(raw: unknown): BuildInstruction[] {
+      if (typeof raw !== "object" || raw === null) {
+         throw new BadRequestError("buildInstructions must be an object");
+      }
+      const sources = (raw as Record<string, unknown>).sources;
       if (!Array.isArray(sources) || sources.length === 0) {
          throw new BadRequestError(
-            "build requires a non-empty 'sources' array of BuildInstruction",
+            "buildInstructions requires a non-empty 'sources' array of BuildInstruction",
          );
       }
-      return sources.map((raw) => this.validateInstruction(raw));
+      return sources.map((instruction) =>
+         this.validateInstruction(instruction),
+      );
    }
 
    private validateInstruction(raw: unknown): BuildInstruction {

package/src/health.ts

@@ -74,6 +74,7 @@ export function registerSignalHandlers(
    mcpServer: Server,
    shutdownDrainDurationSeconds: number = 0,
    shutdownGracefulCloseTimeoutSeconds: number = 0,
+   agentMcpServer?: Server,
 ): void {
    // Keep the process alive on SIGTERM — do not close the server.
    // K8s will SIGKILL after terminationGracePeriodSeconds (which cannot be caught).
@@ -96,6 +97,7 @@ export function registerSignalHandlers(
          server,
          mcpServer,
          shutdownGracefulCloseTimeoutSeconds,
+         agentMcpServer,
       );
    });
 }
@@ -114,6 +116,7 @@ export async function performGracefulShutdownAfterDrain(
    server: Server,
    mcpServer: Server,
    shutdownGracefulCloseTimeoutSeconds: number,
+   agentMcpServer?: Server,
 ): Promise<void> {
    const closeServer = (server: Server, name: string) =>
       new Promise<void>((resolve) => {
@@ -134,6 +137,9 @@ export async function performGracefulShutdownAfterDrain(
    await Promise.all([
       closeServer(server, "Main server"),
       closeServer(mcpServer, "MCP server"),
+      ...(agentMcpServer
+         ? [closeServer(agentMcpServer, "Agent MCP server")]
+         : []),
    ]);
 
    try {

package/src/materialization_metrics.ts

@@ -1,12 +1,11 @@
 /**
- * Centralized telemetry for the two-round materialization protocol.
+ * Centralized telemetry for materialization builds.
  *
- * Operators need to answer "are builds completing, how long do the two
- * rounds take, and where are they failing?" without grepping logs. The
- * counter carries `round` (`round1`|`round2`) and `outcome`
- * (`success`|`failed`|`cancelled`); the histogram carries `round` so a
- * dashboard can render Round 1 (compile+plan) vs Round 2 (build) latency
- * side by side.
+ * Operators need to answer "are builds completing, how long do they take, and
+ * where are they failing?" without grepping logs. The run counter carries
+ * `mode` (`auto`|`orchestrated`) and `outcome` (`success`|`failed`|`cancelled`);
+ * the run-duration histogram carries `mode` so a dashboard can render auto-run
+ * vs orchestrated build latency side by side.
  *
  * Lazy init for the same reason as {@link ./query_cap_metrics}: instruments
  * created before `setGlobalMeterProvider` bind to a NoOp meter
@@ -15,58 +14,138 @@
 
 import { metrics, type Counter, type Histogram } from "@opentelemetry/api";
 
-export type MaterializationRound = "round1" | "round2" | "auto";
+export type MaterializationMode = "auto" | "orchestrated";
 export type MaterializationOutcome = "success" | "failed" | "cancelled";
 /** Manifest bind outcome: timeout is split out from generic failure on purpose. */
 export type ManifestBindOutcome = "success" | "failure" | "timeout";
 
-let roundCounter: Counter | null = null;
-let roundDuration: Histogram | null = null;
+let runCounter: Counter | null = null;
+let runDuration: Histogram | null = null;
+let sourcesCounter: Counter | null = null;
+let buildPlanComputeDuration: Histogram | null = null;
+let autoLoadCounter: Counter | null = null;
+let connectionDigestSkipCounter: Counter | null = null;
 let manifestBindCounter: Counter | null = null;
 let sourceBuildDuration: Histogram | null = null;
 let dropTablesCounter: Counter | null = null;
 
 function ensureTelemetry(): { counter: Counter; duration: Histogram } {
-   if (roundCounter && roundDuration) {
-      return { counter: roundCounter, duration: roundDuration };
+   if (runCounter && runDuration) {
+      return { counter: runCounter, duration: runDuration };
    }
    const meter = metrics.getMeter("publisher");
-   if (!roundCounter) {
-      roundCounter = meter.createCounter(
-         "publisher_materialization_rounds_total",
-         {
-            description:
-               "Materialization rounds completed. Labels: round ('round1'|'round2'|'auto'), outcome ('success'|'failed'|'cancelled').",
-         },
-      );
+   if (!runCounter) {
+      runCounter = meter.createCounter("publisher_materialization_runs_total", {
+         description:
+            "Materialization builds completed. Labels: mode ('auto'|'orchestrated'), outcome ('success'|'failed'|'cancelled').",
+      });
    }
-   if (!roundDuration) {
-      roundDuration = meter.createHistogram(
-         "publisher_materialization_round_duration_ms",
+   if (!runDuration) {
+      runDuration = meter.createHistogram(
+         "publisher_materialization_run_duration_ms",
          {
             description:
-               "Wall-clock duration of a materialization round. Label: round ('round1'|'round2'|'auto').",
+               "Wall-clock duration of a materialization build. Label: mode ('auto'|'orchestrated').",
             unit: "ms",
          },
       );
    }
-   return { counter: roundCounter, duration: roundDuration };
+   return { counter: runCounter, duration: runDuration };
 }
 
-/** Record the outcome and duration of a materialization round. */
-export function recordMaterializationRound(
-   round: MaterializationRound,
+/** Record the outcome and duration of a materialization build. */
+export function recordMaterializationRun(
+   mode: MaterializationMode,
    outcome: MaterializationOutcome,
    durationMs: number,
 ): void {
    const { counter, duration } = ensureTelemetry();
-   counter.add(1, { round, outcome });
-   duration.record(durationMs, { round });
+   counter.add(1, { mode, outcome });
+   duration.record(durationMs, { mode });
+}
+
+/**
+ * Record how many persist sources a run built vs. reused (carried forward
+ * unchanged via skip-if-unchanged). Lets a dashboard show the reuse ratio,
+ * the main lever on materialization cost.
+ */
+export function recordSourcesOutcome(
+   outcome: "built" | "reused",
+   count: number,
+): void {
+   if (count <= 0) return;
+   if (!sourcesCounter) {
+      sourcesCounter = metrics
+         .getMeter("publisher")
+         .createCounter("publisher_materialization_sources_total", {
+            description:
+               "Persist sources processed by a materialization run. Label: outcome ('built'|'reused').",
+         });
+   }
+   sourcesCounter.add(count, { outcome });
+}
+
+/**
+ * Record the wall-clock cost of compiling a package's build plan
+ * (`Package.buildPlan`). This recompiles models at load, so it is worth
+ * tracking as a discrete cost separate from the build itself.
+ */
+export function recordBuildPlanComputeDuration(durationMs: number): void {
+   if (!buildPlanComputeDuration) {
+      buildPlanComputeDuration = metrics
+         .getMeter("publisher")
+         .createHistogram(
+            "publisher_materialization_build_plan_compute_duration_ms",
+            {
+               description:
+                  "Wall-clock duration of compiling a package's build plan (Package.buildPlan).",
+               unit: "ms",
+            },
+         );
+   }
+   buildPlanComputeDuration.record(durationMs);
+}
+
+/**
+ * Record an auto-run manifest auto-load attempt. Auto-load is best-effort (a
+ * failure does not fail the run), so a failure here is otherwise invisible:
+ * the run is MANIFEST_FILE_READY but queries still resolve to the old tables.
+ */
+export function recordAutoLoadOutcome(outcome: "success" | "failure"): void {
+   if (!autoLoadCounter) {
+      autoLoadCounter = metrics
+         .getMeter("publisher")
+         .createCounter("publisher_materialization_auto_load_total", {
+            description:
+               "Auto-run manifest auto-load attempts. Label: outcome ('success'|'failure').",
+         });
+   }
+   autoLoadCounter.add(1, { outcome });
+}
+
+/**
+ * Record that a connection digest could not be computed during build-plan
+ * compilation because the connection failed to resolve. The resulting buildIds
+ * are computed without a digest, so this is a correctness signal, not just noise.
+ */
+export function recordConnectionDigestSkipped(): void {
+   if (!connectionDigestSkipCounter) {
+      connectionDigestSkipCounter = metrics
+         .getMeter("publisher")
+         .createCounter(
+            "publisher_materialization_connection_digest_skipped_total",
+            {
+               description:
+                  "Connection digests skipped during build-plan compile because the connection did not resolve.",
+            },
+         );
+   }
+   connectionDigestSkipCounter.add(1);
 }
 
 /**
- * Record a manifest-bind attempt (publisher binding a control-plane manifest to
- * a package at load). `timeout` is distinguished from `failure` so operators can
+ * Record a manifest-bind attempt (publisher binding a configured manifest to a
+ * package at load). `timeout` is distinguished from `failure` so operators can
  * tell an unreachable/slow manifest store from a malformed manifest.
  */
 export function recordManifestBind(outcome: ManifestBindOutcome): void {
@@ -113,8 +192,12 @@ export function recordDropTables(outcome: "success" | "failure"): void {
 
 /** Visible for tests. Drops cached instruments so a fresh MeterProvider can capture emissions. */
 export function resetMaterializationTelemetryForTesting(): void {
-   roundCounter = null;
-   roundDuration = null;
+   runCounter = null;
+   runDuration = null;
+   sourcesCounter = null;
+   buildPlanComputeDuration = null;
+   autoLoadCounter = null;
+   connectionDigestSkipCounter = null;
    manifestBindCounter = null;
    sourceBuildDuration = null;
    dropTablesCounter = null;

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

@@ -0,0 +1,78 @@
+import { beforeAll, describe, expect, it } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { initializeAgentMcpServer } from "./agent_server";
+import type { EnvironmentStore } from "../service/environment_store";
+
+/**
+ * End-to-end coverage of the agent MCP server over the real MCP protocol, using
+ * the SDK's in-memory transport (no HTTP, no network, no DuckDB). Exercises tool
+ * registration, the dual-channel prompts, a real tool call (searchDocs over the
+ * bundled index), and the getContext error path.
+ */
+describe("agent 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.
+      const stubStore = {
+         getEnvironment: async (name: string): Promise<never> => {
+            throw new Error(`Environment not found: ${name}`);
+         },
+      } as unknown as EnvironmentStore;
+
+      const server = initializeAgentMcpServer(stubStore);
+      const [clientTransport, serverTransport] =
+         InMemoryTransport.createLinkedPair();
+      await server.connect(serverTransport);
+      client = new Client({ name: "agent-protocol-test", version: "0.0.0" });
+      await client.connect(clientTransport);
+   });
+
+   it("exposes exactly the two agent tools", async () => {
+      const { tools } = await client.listTools();
+      expect(new Set(tools.map((t) => t.name))).toEqual(
+         new Set(["malloy_getContext", "malloy_searchDocs"]),
+      );
+   });
+
+   it("exposes the skill set as dual-channel prompts", async () => {
+      const { prompts } = await client.listPrompts();
+      expect(prompts.length).toBeGreaterThanOrEqual(24);
+      expect(prompts.some((p) => p.name === "malloy-analysis")).toBe(true);
+   });
+
+   it("malloy_searchDocs returns relevant docs over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_searchDocs",
+         arguments: { query: "window functions" },
+      });
+      const content = res.content as Array<{ resource?: { text?: string } }>;
+      const results = JSON.parse(
+         content?.[0]?.resource?.text ?? "[]",
+      ) as Array<{
+         url: string;
+      }>;
+      expect(results.length).toBeGreaterThan(0);
+      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);
+   });
+
+   it("a skill prompt returns its body", async () => {
+      const res = await client.getPrompt({ name: "malloy-analysis" });
+      const content = res.messages[0].content as { text?: string };
+      expect((content.text ?? "").length).toBeGreaterThan(200);
+   });
+});

package/src/mcp/agent_server.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "bun:test";
+import { agentServerInfo, initializeAgentMcpServer } from "./agent_server";
+import type { EnvironmentStore } from "../service/environment_store";
+
+describe("agent MCP server", () => {
+   it("advertises a distinct server name from the core MCP server", () => {
+      expect(agentServerInfo.name).toBe("malloy-publisher-agent-mcp-server");
+   });
+
+   it("initializes and registers its tools and skill prompts without throwing", () => {
+      // The store is captured for later handler calls, not used during
+      // registration, so a placeholder is sufficient for this smoke test.
+      const server = initializeAgentMcpServer(
+         {} as unknown as EnvironmentStore,
+      );
+      expect(server).toBeTruthy();
+   });
+});