@malloy-publisher/server 0.0.226 → 0.0.228

package/src/mcp/tools/reload_package_tool.spec.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from "bun:test";
+import { registerReloadPackageTool } from "./reload_package_tool";
+import type { EnvironmentStore } from "../../service/environment_store";
+import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
+
+// Capture the handler registerReloadPackageTool passes to McpServer.tool, so it
+// can be exercised against a mocked EnvironmentStore. The tool builds a
+// PackageController internally, which calls environment.getPackage(pkg, reload),
+// so the mock only needs getEnvironment -> { getPackage }.
+type Handler = (params: Record<string, unknown>) => Promise<{
+   isError?: boolean;
+   content: Array<{ resource: { text: string } }>;
+}>;
+
+function captureHandler(store: Partial<EnvironmentStore>): Handler {
+   let handler: Handler | undefined;
+   const fakeServer = {
+      tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
+         handler = h;
+      },
+   };
+   registerReloadPackageTool(fakeServer as never, store as EnvironmentStore);
+   if (!handler) throw new Error("handler was not registered");
+   return handler;
+}
+
+function parse(result: { content: Array<{ resource: { text: string } }> }) {
+   return JSON.parse(result.content[0].resource.text);
+}
+
+// A store whose package reload returns `metadata`. `location` is left undefined
+// so PackageController takes the in-place-reload branch (no re-download). The
+// optional `calls` array records the `reload` flag of every getPackage call.
+function storeReturning(
+   metadata: Record<string, unknown>,
+   calls?: boolean[],
+): Partial<EnvironmentStore> {
+   return {
+      getEnvironment: async () =>
+         ({
+            getPackage: async (_pkg: string, reload: boolean) => {
+               calls?.push(reload);
+               return { getPackageMetadata: () => metadata } as never;
+            },
+         }) as never,
+   };
+}
+
+// A store whose cached package metadata carries `location`, so PackageController
+// takes the re-fetch branch: installPackage instead of an in-place recompile.
+// This is the only remaining path that overwrites on-disk edits, so it is worth
+// pinning that the routing and the reported mode both match.
+function storeWithInstallLocation(installed: Record<string, unknown>): {
+   store: Partial<EnvironmentStore>;
+   installCalls: string[];
+} {
+   const installCalls: string[] = [];
+   return {
+      installCalls,
+      store: {
+         getEnvironment: async () =>
+            ({
+               getPackage: async () =>
+                  ({
+                     getPackageMetadata: () => ({
+                        name: "ecommerce",
+                        location: "https://github.com/example/pkg",
+                     }),
+                  }) as never,
+               installPackage: async (pkg: string) => {
+                  installCalls.push(pkg);
+                  return { getPackageMetadata: () => installed } as never;
+               },
+            }) as never,
+      },
+   };
+}
+
+const args = { environmentName: "malloy-samples", packageName: "ecommerce" };
+
+describe("malloy_reloadPackage tool", () => {
+   it("returns status reloaded with the package name", async () => {
+      const handler = captureHandler(storeReturning({ name: "ecommerce" }));
+      const result = await handler(args);
+      expect(result.isError).toBe(false);
+      expect(parse(result)).toEqual({
+         status: "reloaded",
+         mode: "in-place",
+         name: "ecommerce",
+      });
+   });
+
+   it("includes description and non-empty warnings", async () => {
+      const warnings = [
+         {
+            model: "ecommerce.malloy",
+            target: "top_categories",
+            severity: "error",
+         },
+      ];
+      const handler = captureHandler(
+         storeReturning({ name: "ecommerce", description: "shop", warnings }),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed).toEqual({
+         status: "reloaded",
+         mode: "in-place",
+         name: "ecommerce",
+         description: "shop",
+         warnings,
+      });
+   });
+
+   it("omits warnings when the reloaded package has none", async () => {
+      const handler = captureHandler(
+         storeReturning({ name: "ecommerce", warnings: [] }),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.warnings).toBeUndefined();
+      expect(parsed.status).toBe("reloaded");
+   });
+
+   it("forwards reload=true (recompiles, not just reads)", async () => {
+      const calls: boolean[] = [];
+      const handler = captureHandler(
+         storeReturning({ name: "ecommerce" }, calls),
+      );
+      await handler(args);
+      // The controller probes cached metadata (reload=false) then reloads
+      // (reload=true); the tool must trigger the recompile.
+      expect(calls).toContain(true);
+   });
+
+   it("surfaces a thrown error as a tool error, not a transport fault", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new Error("Environment 'nope' could not be resolved");
+         },
+      });
+      const result = await handler({ ...args, environmentName: "nope" });
+      expect(result.isError).toBe(true);
+      expect(parse(result).error).toBeDefined();
+   });
+
+   it("reports a missing package as not-found, not as a Malloy syntax problem", async () => {
+      // Pin the remediation text, not just that an error came back. Asserting
+      // only that `error` is defined is what let every error class funnel
+      // through the Malloy helper unnoticed: a typo'd package name told the
+      // caller to go check its Malloy syntax.
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new PackageNotFoundError("Package 'nope' not found");
+         },
+      });
+      const parsed = parse(await handler({ ...args, packageName: "nope" }));
+      expect(parsed.error).toContain("Resource not found");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("reports back-pressure as retryable, not as a Malloy syntax problem", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new ServiceUnavailableError("Memory limit reached");
+         },
+      });
+      const parsed = parse(await handler(args));
+      expect(parsed.error).toContain("Memory limit reached");
+      expect(JSON.stringify(parsed.suggestions)).toContain("Retry");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("surfaces a hard compile failure on reload as a tool error", async () => {
+      // A Package.create compile failure propagates out of environment.getPackage
+      // (the reload site), not out of getEnvironment. The controller swallows the
+      // first probe call and re-throws on the reload call.
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({
+               getPackage: async () => {
+                  throw new Error("'nonexistent_status_field' is not defined");
+               },
+            }) as never,
+      });
+      const result = await handler(args);
+      expect(result.isError).toBe(true);
+      expect(parse(result).error).toBeDefined();
+   });
+
+   it("reports mode in-place for a package with no install location", async () => {
+      const handler = captureHandler(storeReturning({ name: "ecommerce" }));
+      expect(parse(await handler(args)).mode).toBe("in-place");
+   });
+
+   it("re-fetches and reports mode reinstalled when the package carries an install location", async () => {
+      // The one path that still overwrites on-disk edits. It must route through
+      // installPackage, and the payload must say so, since an agent cannot
+      // otherwise tell that its saved edit was just re-fetched over.
+      const { store, installCalls } = storeWithInstallLocation({
+         name: "ecommerce",
+         location: "https://github.com/example/pkg",
+      });
+      const handler = captureHandler(store);
+      const result = await handler(args);
+      expect(result.isError).toBe(false);
+      expect(installCalls).toEqual(["ecommerce"]);
+      expect(parse(result).mode).toBe("reinstalled");
+   });
+
+   it("never echoes the package location back to the caller", async () => {
+      // The payload hand-picks fields; REST spreads the whole ApiPackage. Pin
+      // that the allowlist holds, since location is the one field here that is
+      // deployment detail rather than something an agent needs.
+      const { store } = storeWithInstallLocation({
+         name: "ecommerce",
+         location: "https://github.com/example/pkg",
+      });
+      const parsed = parse(await captureHandler(store)(args));
+      expect(parsed.location).toBeUndefined();
+   });
+
+   it("surfaces exploresWarnings (a mistyped explores entry is not swallowed)", async () => {
+      const exploresWarnings = [
+         "explore 'ordrs' does not resolve to a model in this package",
+      ];
+      const handler = captureHandler(
+         storeReturning({ name: "ecommerce", exploresWarnings }),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.status).toBe("reloaded");
+      expect(parsed.exploresWarnings).toEqual(exploresWarnings);
+   });
+});

package/src/mcp/tools/reload_package_tool.ts

@@ -0,0 +1,158 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { logger } from "../../logger";
+import { EnvironmentStore } from "../../service/environment_store";
+import { PackageController } from "../../controller/package.controller";
+import { type ErrorDetails } from "../error_messages";
+import { buildMalloyUri, classifyToolError } from "../handler_utils";
+
+// Zod shape for malloy_reloadPackage. environmentName/packageName mirror the
+// other tools and point the agent at malloy_getContext for name discovery.
+const reloadShape = {
+   environmentName: z
+      .string()
+      .describe(
+         "Environment name. Call malloy_getContext with no arguments to list the available environments.",
+      ),
+   packageName: z
+      .string()
+      .describe(
+         "Package to reload. Call malloy_getContext with just environmentName to list its packages.",
+      ),
+};
+
+/**
+ * What a failed reload does, in one sentence, shared with MCP_INSTRUCTIONS
+ * rather than restated there. Both surfaces describe the same behavior, so one
+ * copy is what stops them drifting.
+ *
+ * SECURITY: interpolated into MCP_INSTRUCTIONS, which is delivered
+ * pre-authorization to any connecting client. Keep this a static string
+ * literal; never derive it from config, environment, or request data.
+ */
+export const RELOAD_FAILURE_IS_SAFE =
+   "A reload that fails to compile leaves your files on disk alone and keeps serving the previously compiled model, returning the compile errors.";
+
+const RELOAD_DESCRIPTION = `Reload a package so edits to its model files on disk are picked up, making newly added or changed sources, views, and named queries resolvable by malloy_executeQuery WITHOUT restarting the server. Publisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until the package is reloaded. Use this to close the edit -> run loop after saving a model change.
+
+${RELOAD_FAILURE_IS_SAFE} Running malloy_compile first is still the faster way to see diagnostics, and it keeps a broken model from ever reaching the reload.
+
+## Parameters
+- environmentName, packageName (required): the package to recompile. Use the names malloy_getContext returns.
+
+## Behavior
+Recompiles the package from its current on-disk content under publisher_data/, so your saved edits are picked up. This is the path every package from publisher.config.json takes. A package whose stored metadata carries an install location (only a PATCH that supplies one sets it) is re-fetched from that source instead, which overwrites on-disk edits.
+
+## Response
+A JSON object with status "reloaded", a mode of "in-place" or "reinstalled", the package name, any render-tag warnings, and any exploresWarnings (curated-discovery entries that did not resolve to a model). Check mode if you had unsaved-elsewhere edits on disk: "in-place" recompiled them, "reinstalled" re-fetched over them. A reload that hits a hard compile error returns an error payload instead.`;
+
+/**
+ * Registers the malloy_reloadPackage MCP tool: recompiles a package from its
+ * on-disk content so a saved model edit becomes queryable by name without a
+ * server restart. Wraps the same PackageController.getPackage(reload=true) path
+ * the REST GET /environments/:env/packages/:pkg?reload=true endpoint uses, so it
+ * adds no capability beyond that already-exposed endpoint (SECURITY: parity with
+ * REST. The MCP surface is unauthenticated, and so is that endpoint; a reload
+ * mutates the shared in-memory package but returns only names and warnings,
+ * never row data or the package's location).
+ */
+export function registerReloadPackageTool(
+   mcpServer: McpServer,
+   environmentStore: EnvironmentStore,
+): void {
+   const packageController = new PackageController(environmentStore);
+
+   mcpServer.tool(
+      "malloy_reloadPackage",
+      RELOAD_DESCRIPTION,
+      reloadShape,
+      async (params) => {
+         const { environmentName, packageName } = params;
+
+         logger.info("[MCP Tool reloadPackage] Reloading package", {
+            environmentName,
+            packageName,
+         });
+
+         const uri = buildMalloyUri(
+            { environment: environmentName, package: packageName },
+            "reloadPackage",
+         );
+
+         try {
+            const { metadata: pkg, mode } =
+               await packageController.reloadPackage(
+                  environmentName,
+                  packageName,
+               );
+
+            const payload = {
+               status: "reloaded" as const,
+               // Which path ran. "in-place" recompiled the tree on disk and left
+               // it alone; "reinstalled" re-fetched from the package's install
+               // location, so any on-disk edits are gone. The caller cannot tell
+               // these apart otherwise, and only one of them keeps their work.
+               mode,
+               name: pkg.name,
+               ...(pkg.description !== undefined && {
+                  description: pkg.description,
+               }),
+               ...(pkg.warnings !== undefined &&
+                  pkg.warnings.length > 0 && { warnings: pkg.warnings }),
+               // exploresWarnings is a distinct signal from render-tag warnings:
+               // it flags a curated-discovery (explores) entry that did not
+               // resolve to a model, so a mistyped explores edit is not silently
+               // swallowed on reload.
+               ...(pkg.exploresWarnings !== undefined &&
+                  pkg.exploresWarnings.length > 0 && {
+                     exploresWarnings: pkg.exploresWarnings,
+                  }),
+            };
+
+            return {
+               isError: false,
+               content: [
+                  {
+                     type: "resource" as const,
+                     resource: {
+                        type: "application/json",
+                        uri,
+                        text: JSON.stringify(payload),
+                     },
+                  },
+               ],
+            };
+         } catch (error) {
+            // Unknown environment/package, or a compile error in the reloaded
+            // package: surface as a clean isError payload rather than a
+            // transport fault.
+            logger.warn("[MCP Tool reloadPackage] reload failed", {
+               environmentName,
+               packageName,
+               error: error instanceof Error ? error.message : String(error),
+            });
+            const errorDetails: ErrorDetails = classifyToolError(
+               "reloadPackage",
+               `${environmentName}/${packageName}`,
+               error,
+            );
+            return {
+               isError: true,
+               content: [
+                  {
+                     type: "resource" as const,
+                     resource: {
+                        type: "application/json",
+                        uri,
+                        text: JSON.stringify({
+                           error: errorDetails.message,
+                           suggestions: errorDetails.suggestions,
+                        }),
+                     },
+                  },
+               ],
+            };
+         }
+      },
+   );
+}

package/src/package_load/package_load_pool.ts

@@ -247,6 +247,8 @@ export interface LoadPackageOutcome {
       }
    >;
    loadDurationMs: number;
+   /** Per-load phase timing breakdown (see {@link LoadPackageResult.timings}). */
+   timings: LoadPackageResult["timings"];
 }
 
 // ──────────────────────────────────────────────────────────────────────
@@ -844,6 +846,7 @@ function adaptResult(result: LoadPackageResult): LoadPackageOutcome {
          sourceInfos: m.sourceInfos as Malloy.SourceInfo[] | undefined,
       })),
       loadDurationMs: result.loadDurationMs,
+      timings: result.timings,
    };
 }
 

package/src/package_load/package_load_worker.ts

@@ -99,6 +99,7 @@ import {
    type MalloyGivenApi,
 } from "../service/given";
 import { ignoreDotfiles } from "../utils";
+import { RpcWaitAccountant } from "./rpc_wait_accountant";
 import type {
    ConnectionMetadata,
    ConnectionMetadataRequest,
@@ -152,6 +153,13 @@ function callMain<T>(send: (requestId: string) => void): Promise<T> {
    });
 }
 
+// Per-load phase timing: brackets the wall-clock spent awaiting proxied schema
+// fetches so `loadPackage` can separate connection I/O from compile CPU. The
+// pool runs one load per worker at a time, so a single module-level instance
+// is safe; it's still keyed by jobId to shrug off a straggler fetch from a
+// prior, reused-worker load. See {@link RpcWaitAccountant}.
+const schemaWait = new RpcWaitAccountant();
+
 function dispatchMainResponse(message: MainToWorkerMessage): void {
    if (
       message.type === "schema-for-tables-response" ||
@@ -202,18 +210,25 @@ class ProxyConnection {
       schemas: Record<string, TableSourceDef>;
       errors: Record<string, string>;
    }> {
-      const response = await callMain<SchemaForTablesResponse>((requestId) => {
-         const req: SchemaForTablesRequest = {
-            type: "schema-for-tables",
-            requestId,
-            jobId: this.jobId,
-            connectionName: this.name,
-            tables,
-            options: serializeFetchOptions(options),
-         };
-         port.postMessage(req);
-      });
-      return { schemas: response.schemas, errors: response.errors };
+      schemaWait.noteStart(this.jobId);
+      try {
+         const response = await callMain<SchemaForTablesResponse>(
+            (requestId) => {
+               const req: SchemaForTablesRequest = {
+                  type: "schema-for-tables",
+                  requestId,
+                  jobId: this.jobId,
+                  connectionName: this.name,
+                  tables,
+                  options: serializeFetchOptions(options),
+               };
+               port.postMessage(req);
+            },
+         );
+         return { schemas: response.schemas, errors: response.errors };
+      } finally {
+         schemaWait.noteSettle(this.jobId);
+      }
    }
 
    async fetchSchemaForSQLStruct(
@@ -223,17 +238,23 @@ class ProxyConnection {
       | { structDef: SQLSourceDef; error?: undefined }
       | { error: string; structDef?: undefined }
    > {
-      const response = await callMain<SchemaForSqlResponse>((requestId) => {
-         const req: SchemaForSqlRequest = {
-            type: "schema-for-sql",
-            requestId,
-            jobId: this.jobId,
-            connectionName: this.name,
-            sentence: sentence as unknown,
-            options: serializeFetchOptions(options),
-         };
-         port.postMessage(req);
-      });
+      schemaWait.noteStart(this.jobId);
+      let response: SchemaForSqlResponse;
+      try {
+         response = await callMain<SchemaForSqlResponse>((requestId) => {
+            const req: SchemaForSqlRequest = {
+               type: "schema-for-sql",
+               requestId,
+               jobId: this.jobId,
+               connectionName: this.name,
+               sentence: sentence as unknown,
+               options: serializeFetchOptions(options),
+            };
+            port.postMessage(req);
+         });
+      } finally {
+         schemaWait.noteSettle(this.jobId);
+      }
       if (response.error !== undefined) return { error: response.error };
       if (response.structDef === undefined) {
          return { error: "Empty SQL schema response from main thread" };
@@ -856,18 +877,41 @@ async function loadPackage(
    const allFiles = await listPackageFiles(job.packagePath);
    const modelPaths = filterModelPaths(allFiles);
 
+   // Bracket the compile region: only work from here on is compilation +
+   // proxied schema fetches. The setup above (manifest read + file listing)
+   // is excluded so it can't inflate the compile figure — it stays in the
+   // derivable remainder (loadDuration - compile - schemaFetch). Begin the
+   // schema-fetch accounting HERE, at the region boundary, not at load start:
+   // that keeps `compileDurationMs = compileRegion - schemaFetchWait` exact
+   // regardless of whether any fetch ever happens during setup (none do
+   // today, but this stops that assumption from silently mattering).
+   const compileRegionStart = performance.now();
+   schemaWait.begin(job.requestId);
    const models = await Promise.all(
       modelPaths.map((modelPath) =>
          compileOneModel(job, malloyConfig, modelPath),
       ),
    );
 
+   const loadEnd = performance.now();
+   const schemaFetchDurationMs = schemaWait.waitMs;
    return {
       type: "load-package-result",
       requestId: job.requestId,
       packageMetadata,
       models,
-      loadDurationMs: performance.now() - loadStart,
+      loadDurationMs: loadEnd - loadStart,
+      timings: {
+         // Compile-region wall minus the schema-fetch wait it contains — a
+         // conservative ceiling on compile CPU (clamped: rounding can nudge
+         // it slightly negative).
+         compileDurationMs: Math.max(
+            0,
+            loadEnd - compileRegionStart - schemaFetchDurationMs,
+         ),
+         schemaFetchDurationMs,
+         schemaFetchCount: schemaWait.fetches,
+      },
    };
 }
 

package/src/package_load/protocol.ts

@@ -189,6 +189,22 @@ export interface LoadPackageResult {
    models: SerializedModel[];
    /** Wall-clock ms inside the worker for the full package load. */
    loadDurationMs: number;
+   /**
+    * Per-load timing breakdown (subset of {@link loadDurationMs}; the
+    * remainder is worker setup + post-compile extraction). See
+    * `rpc_wait_accountant.ts` for how compile time is separated from I/O.
+    */
+   timings: {
+      /**
+       * Compile-region wall-clock minus time awaiting proxied schema fetches —
+       * a conservative ceiling on Malloy compile CPU.
+       */
+      compileDurationMs: number;
+      /** Wall-clock awaiting proxied connection schema fetches (union). */
+      schemaFetchDurationMs: number;
+      /** Number of proxied connection schema fetches the load drove. */
+      schemaFetchCount: number;
+   };
 }
 
 export interface LoadPackageError {

package/src/package_load/rpc_wait_accountant.spec.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "bun:test";
+
+import { RpcWaitAccountant } from "./rpc_wait_accountant";
+
+/** Accountant driven by a settable fake clock. */
+function withClock(): { acc: RpcWaitAccountant; at: (ms: number) => void } {
+   let t = 0;
+   const acc = new RpcWaitAccountant(() => t);
+   return { acc, at: (ms) => (t = ms) };
+}
+
+describe("RpcWaitAccountant", () => {
+   it("brackets a single fetch's wait", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("A");
+      at(10);
+      acc.noteStart("A");
+      at(60);
+      acc.noteSettle("A");
+      expect(acc.waitMs).toBe(50);
+   });
+
+   it("counts overlapping fetches as their union, not the sum", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("A");
+      at(0);
+      acc.noteStart("A"); // window opens
+      at(10);
+      acc.noteStart("A"); // second fetch, window stays open
+      at(40);
+      acc.noteSettle("A"); // one still outstanding
+      at(60);
+      acc.noteSettle("A"); // window closes
+      expect(acc.waitMs).toBe(60); // union [0,60], not 30+50
+   });
+
+   it("accumulates disjoint fetch windows", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("A");
+      at(0);
+      acc.noteStart("A");
+      at(20);
+      acc.noteSettle("A");
+      at(50);
+      acc.noteStart("A");
+      at(70);
+      acc.noteSettle("A");
+      expect(acc.waitMs).toBe(40);
+   });
+
+   it("ignores a straggler fetch from a prior reused-worker load", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("A");
+      at(0);
+      acc.noteStart("A"); // load A opens a fetch and never settles it (failed)
+
+      at(100);
+      acc.begin("B"); // worker reused for load B
+      at(110);
+      acc.noteStart("B");
+      at(130);
+      acc.noteSettle("B");
+
+      at(140);
+      acc.noteSettle("A"); // A's late response — must be a no-op
+
+      expect(acc.waitMs).toBe(20); // only B's [110,130]
+   });
+
+   it("ignores a stray start from a non-active load", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("B");
+      at(10);
+      acc.noteStart("A"); // wrong load
+      at(50);
+      acc.noteSettle("A");
+      expect(acc.waitMs).toBe(0);
+   });
+
+   it("counts active-load fetches only", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("B");
+      acc.noteStart("B");
+      acc.noteSettle("B");
+      acc.noteStart("B");
+      acc.noteStart("A"); // straggler — not counted
+      expect(acc.fetches).toBe(2);
+   });
+
+   it("begin() discards prior-load state", () => {
+      const { acc, at } = withClock();
+      at(0);
+      acc.begin("A");
+      at(0);
+      acc.noteStart("A");
+      at(50);
+      acc.noteSettle("A");
+      expect(acc.waitMs).toBe(50);
+      at(60);
+      acc.begin("B");
+      expect(acc.waitMs).toBe(0);
+   });
+});