@malloy-publisher/server 0.0.235 → 0.0.236

package/src/mcp/handler_utils.ts

@@ -1,251 +0,0 @@
-import { MalloyError } from "@malloydata/malloy";
-import { EnvironmentStore } from "../service/environment_store";
-import {
-   AccessDeniedError,
-   BadRequestError,
-   PackageNotFoundError,
-   ModelNotFoundError,
-   ModelCompilationError,
-   EnvironmentNotFoundError,
-   NotQueryableError,
-   PayloadTooLargeError,
-   QueryTimeoutError,
-   ServiceUnavailableError,
-} from "../errors";
-import {
-   getNotFoundError,
-   getInternalError,
-   getMalloyErrorDetails,
-   type ErrorDetails,
-} from "./error_messages";
-import type { Model } from "../service/model";
-import type { Environment } from "../service/environment";
-import { logger } from "../logger";
-
-/**
- * Remediation for a ServiceUnavailableError, shared by every caller that homes
- * one. The error covers both the memory governor and the concurrency slots, so
- * the wording names both rather than only memory.
- */
-export const BACK_PRESSURE_SUGGESTIONS: readonly string[] = [
-   "Retry once the publisher is below its configured memory or concurrency limit.",
-   "If this persists, raise the limit or scale up the pod.",
-];
-
-/**
- * Turns a thrown error into agent-facing ErrorDetails, homed by error class.
- *
- * Without this, a tool that funnels every failure through getMalloyErrorDetails
- * dresses each one up as a Malloy language problem: a missing package tells the
- * agent to check its Malloy syntax, and a back-pressure rejection sends it
- * hunting for a typo instead of retrying.
- *
- * Only the classes that really are about the caller's Malloy or request reach
- * the Malloy advice; anything else is reported as internal rather than blamed
- * on the model. Routing by class and not by message is deliberate:
- * getMalloyErrorDetails refines on message patterns that the shipped engine
- * does not emit (its syntax pattern wants "no viable alternative at input"
- * where a real error says "unexpected '@'"), so "did it refine?" would send
- * genuine compile errors to the internal branch.
- *
- * @param operation The operation that failed (e.g. 'compile', 'reloadPackage').
- * @param identifier The resource it failed on (e.g. 'env/package').
- */
-export function classifyToolError(
-   operation: string,
-   identifier: string,
-   error: unknown,
-): ErrorDetails {
-   if (
-      error instanceof EnvironmentNotFoundError ||
-      error instanceof PackageNotFoundError ||
-      error instanceof ModelNotFoundError ||
-      // A query-boundary denial is a deliberate 404, and reporting it as a
-      // server fault would tell the caller to contact support about a boundary
-      // that is working. getNotFoundError also drops the source name this class
-      // is careful not to confirm.
-      error instanceof NotQueryableError
-   ) {
-      return getNotFoundError(identifier);
-   }
-   if (error instanceof ServiceUnavailableError) {
-      // Back-pressure: surface the server's own message so the caller knows to
-      // retry rather than to go edit its Malloy.
-      return {
-         message: error.message,
-         suggestions: [...BACK_PRESSURE_SUGGESTIONS],
-      } satisfies ErrorDetails;
-   }
-   if (
-      error instanceof QueryTimeoutError ||
-      error instanceof PayloadTooLargeError
-   ) {
-      // The query was too slow or too big. Both classes already carry their own
-      // "refine the query" remediation in the message, so the suggestions say
-      // the part the message leaves out and the internal branch got backwards:
-      // this is not transient, and retrying it unchanged fails identically.
-      // That distinction is the whole reason these are 504/413 and not the
-      // retryable 503 (see the QueryTimeoutError docstring in errors.ts).
-      return {
-         message: error.message,
-         suggestions: [
-            "This is not transient. The same query will fail the same way, so change the query rather than retrying it.",
-            "If it is already minimal, raise the configured cap named in the message.",
-         ],
-      } satisfies ErrorDetails;
-   }
-   if (
-      // A raw engine error: what a bad query throws (syntax, undefined name,
-      // field not found). executeQuery's catch sees these, so they must keep
-      // the Malloy advice.
-      error instanceof MalloyError ||
-      // The same thing wrapped: what a failed compile or reload throws.
-      error instanceof ModelCompilationError ||
-      // An #(authorize) denial, whose message getMalloyErrorDetails recognizes.
-      error instanceof AccessDeniedError ||
-      // A malformed request is the caller's to fix, not ours to retry.
-      error instanceof BadRequestError
-   ) {
-      return getMalloyErrorDetails(operation, identifier, error);
-   }
-   // Everything else (a filesystem EACCES, a TypeError, a worker crash, a
-   // timeout) is not the caller's Malloy. Telling them to check their syntax
-   // sends them to edit a model that is fine.
-   return getInternalError(operation, error);
-}
-
-/**
- * Fetches and validates the Package and Model instances needed for query execution.
- * Handles errors related to package/model access and initial compilation.
- *
- * The resolved Environment comes back with the model because a query needs it for
- * more than the lookup: it owns the connection configs the per-query metadata
- * layers are read from.
- *
- * @returns An object containing the Model instance or a pre-formatted ErrorDetails object.
- */
-export async function getModelForQuery(
-   environmentStore: EnvironmentStore,
-   environmentName: string,
-   packageName: string,
-   modelPath: string,
-): Promise<
-   { model: Model; environment: Environment } | { error: ErrorDetails }
-> {
-   try {
-      const environment = await environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      // Shed load before any disk / DB work; mirrors the HTTP query
-      // controllers so MCP traffic obeys the same back-pressure rules.
-      environment.assertCanAdmitQuery();
-      const pkg = await environment.getPackage(packageName, false);
-      const model = pkg.getModel(modelPath);
-      if (!model || model.getModelType() === "notebook") {
-         // Ensure it's actually a model
-         const details = getNotFoundError(
-            `model '${modelPath}' in package '${packageName}' for environment '${environmentName}'`,
-         );
-         return { error: details };
-      }
-      // Attempt to get the model definition early to catch initial compilation errors
-      await model.getModel(); // This might throw ModelCompilationError
-      return { model, environment };
-   } catch (error) {
-      // Handle errors during package/model access or initial compilation
-      let errorDetails: ErrorDetails;
-      if (error instanceof EnvironmentNotFoundError) {
-         errorDetails = getNotFoundError(`environment '${environmentName}'`);
-      } else if (error instanceof PackageNotFoundError) {
-         errorDetails = getNotFoundError(
-            `package '${packageName}' in environment '${environmentName}'`,
-         );
-      } else if (error instanceof ModelNotFoundError) {
-         errorDetails = getNotFoundError(
-            `model '${modelPath}' in package '${packageName}' for environment '${environmentName}'`,
-         );
-      } else if (error instanceof ModelCompilationError) {
-         errorDetails = getMalloyErrorDetails(
-            "executeQuery (load model)",
-            `${environmentName}/${packageName}/${modelPath}`,
-            error,
-         );
-      } else if (error instanceof AccessDeniedError) {
-         // An #(authorize) denial during model setup. Funnel through
-         // getMalloyErrorDetails (which recognizes the access-denied message and
-         // gives supply-the-givens guidance) so a 403 never surfaces as an
-         // opaque internal error. Defensive: the gate fires during query
-         // execution today, not setup, but this keeps every error class homed.
-         errorDetails = getMalloyErrorDetails(
-            "executeQuery (load model)",
-            `${environmentName}/${packageName}/${modelPath}`,
-            error,
-         );
-      } else if (error instanceof ServiceUnavailableError) {
-         // Back-pressure: don't dress this up as a 404/500. Surface the
-         // server's own message so the MCP caller knows to retry.
-         errorDetails = {
-            message: error.message,
-            suggestions: [...BACK_PRESSURE_SUGGESTIONS],
-         } satisfies ErrorDetails;
-      } else {
-         // Unexpected error during setup
-         errorDetails = getInternalError("executeQuery (Setup)", error);
-      }
-      logger.error(
-         `[MCP Server Error] Error accessing package/model for query: ${environmentName}/${packageName}/${modelPath}`,
-         { error },
-      );
-      return { error: errorDetails };
-   }
-}
-
-/**
- * Constructs a malloy:// URI string identifying the model a tool response came
- * from. Attached as `uri` metadata on tool results (get-context, execute-query,
- * docs-search); it is not a fetchable MCP resource.
- *
- * @param components The URI parts (environment, package, and optionally the model).
- * @param fragment Optional fragment identifier (e.g., "result", "get-context").
- * @returns A malloy:// URI string.
- */
-export function buildMalloyUri(
-   components: {
-      environment?: string;
-      package?: string;
-      resourceType?: "models";
-      resourceName?: string;
-   },
-   fragment?: string,
-): string {
-   let path = "/environment/";
-
-   if (components.environment) {
-      path += encodeURIComponent(components.environment);
-   } else {
-      // Default to 'home' if not provided, consistent with current behavior
-      path += "home";
-   }
-
-   if (components.package) {
-      path += "/package/" + encodeURIComponent(components.package);
-   }
-
-   if (components.resourceType) {
-      path += "/" + components.resourceType;
-      if (components.resourceName) {
-         path += "/" + encodeURIComponent(components.resourceName);
-      }
-   }
-
-   // The URL constructor normalizes malloy://path to malloy:///path, so we
-   // build the string manually to keep the malloy://environment/... shape.
-   let uriString = "malloy:/" + path; // Start with one slash after scheme
-
-   if (fragment) {
-      uriString += "#" + fragment;
-   }
-
-   return uriString;
-}

package/src/mcp/mcp_constants.ts

@@ -1,6 +0,0 @@
-export const MCP_ERROR_MESSAGES = {
-   // Protocol-level errors (validation)
-   MISSING_REQUIRED_PARAMS:
-      "Either 'query' or both 'sourceName' and 'queryName' must be provided",
-   MUTUALLY_EXCLUSIVE_PARAMS: "Cannot provide both 'query' and 'queryName'",
-} as const;

package/src/mcp/query_envelope.spec.ts

@@ -1,229 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import type * as Malloy from "@malloydata/malloy-interfaces";
-import {
-   buildQueryEnvelope,
-   serializeEnvelope,
-   MAX_RESULT_CHARS,
-} from "./query_envelope";
-
-const rows = (n: number) =>
-   Array.from({ length: n }, (_, i) => ({ id: i, name: `row ${i}` }));
-
-/** A minimal Malloy.Result: only the metadata the envelope reads. */
-const result = (extra: Partial<Malloy.Result> = {}): Malloy.Result =>
-   ({
-      schema: { fields: [{ kind: "dimension", name: "id" }] },
-      connection_name: "duckdb",
-      ...extra,
-   }) as Malloy.Result;
-
-/**
- * The field names here are Credible's, on purpose: a data app authored against
- * Publisher is served through Credible, and an agent that sees one shape while
- * developing and another in production has to learn both. These assertions are
- * the contract that keeps them the same, so renaming a field should fail here.
- */
-describe("buildQueryEnvelope", () => {
-   it("returns flat rows plus Credible's metadata block", () => {
-      const e = buildQueryEnvelope(rows(3), 1000, result());
-      expect(e.rows).toHaveLength(3);
-      expect(e._meta.connection_name).toBe("duckdb");
-      expect(e._meta.schema.fields).toHaveLength(1);
-      expect(e._meta.annotations).toEqual([]);
-   });
-
-   it("carries the Malloy metadata that flat rows drop", () => {
-      // Field types and render tags live in the schema, not the rows, so an
-      // agent would otherwise need a second verbose call to reach them.
-      const e = buildQueryEnvelope(rows(1), 1000, {
-         ...result(),
-         query_timezone: "UTC",
-         model_annotations: [{ value: "# dashboard" }],
-      } as Malloy.Result);
-      expect(e._meta.query_timezone).toBe("UTC");
-      expect(e._meta.model_annotations).toEqual([{ value: "# dashboard" }]);
-   });
-
-   it("omits metadata keys the result did not carry", () => {
-      const e = buildQueryEnvelope(rows(1), 1000, result());
-      expect("query_timezone" in e._meta).toBe(false);
-      expect("source_annotations" in e._meta).toBe(false);
-   });
-
-   /**
-    * The correctness fix, and the one field a client cannot compute for itself:
-    * the cap depends on server config and on the query's own LIMIT.
-    */
-   describe("_limit_hit", () => {
-      it("is true when the row count lands exactly on the cap", () => {
-         const e = buildQueryEnvelope(rows(1000), 1000, result());
-         expect(e._limit_hit).toBe(true);
-         expect(e._query_row_limit).toBe(1000);
-         expect(e.warning).toContain("not a complete result");
-      });
-
-      it("is false when the result came in under the cap", () => {
-         const e = buildQueryEnvelope(rows(999), 1000, result());
-         expect(e._limit_hit).toBe(false);
-         expect(e.warning).toBeUndefined();
-      });
-
-      /**
-       * The false positive this guards. resolveModelQueryRowLimit folds the
-       * query's own limit:/top: into the same cap, so equality holds every time
-       * an author limited the query deliberately. Three of the eight views in
-       * the bundled storefront example use `top:`, so a modelled top-N would
-       * otherwise report its complete answer as cut off, and the Contract rule
-       * would tell an agent that a top-N is "not the answer".
-       */
-      it("is false when the author's own limit: produced the cap", () => {
-         const e = buildQueryEnvelope(
-            rows(10),
-            10,
-            result(),
-            [],
-            undefined,
-            "query",
-         );
-         expect(e._limit_hit).toBe(false);
-         expect(e._limit_source).toBe("query");
-         expect(e.warning).toBeUndefined();
-      });
-
-      it("still fires when the silent server default produced the cap", () => {
-         const e = buildQueryEnvelope(
-            rows(1000),
-            1000,
-            result(),
-            [],
-            undefined,
-            "server_default",
-         );
-         expect(e._limit_hit).toBe(true);
-         expect(e._limit_source).toBe("server_default");
-         expect(e.warning).toContain("not a complete result");
-      });
-
-      it("reports the source even when the cap was not reached", () => {
-         const e = buildQueryEnvelope(
-            rows(3),
-            10,
-            result(),
-            [],
-            undefined,
-            "query",
-         );
-         expect(e._limit_hit).toBe(false);
-         expect(e._limit_source).toBe("query");
-      });
-
-      it("is false when no cap was applied", () => {
-         // rowLimit 0 means uncapped; equality against 0 would otherwise call
-         // an empty result "limited".
-         expect(buildQueryEnvelope([], 0, result())._limit_hit).toBe(false);
-      });
-
-      it("does not call an empty result limited", () => {
-         expect(buildQueryEnvelope([], 1000, result())._limit_hit).toBe(false);
-      });
-   });
-
-   /**
-    * compactResult is raw driver output and DuckDB returns count() as a BigInt,
-    * so a plain JSON.stringify throws on the most common query anyone writes.
-    */
-   it("serializes BigInt values instead of throwing", () => {
-      const e = buildQueryEnvelope([{ c: 150930n }], 1000, result());
-      expect(() => serializeEnvelope(e)).not.toThrow();
-      expect(JSON.parse(serializeEnvelope(e)).rows[0].c).toBe(150930);
-   });
-
-   describe("payload truncation", () => {
-      it("drops rows to fit and reports both counts", () => {
-         const e = buildQueryEnvelope(rows(200), 100_000, result(), [], 3_000);
-         expect(e._rows_truncated).toBe(true);
-         expect(e._total_rows).toBe(200);
-         expect(e._returned_rows).toBe((e.rows as unknown[]).length);
-         expect(e._returned_rows).toBeGreaterThan(0);
-         expect(e._returned_rows).toBeLessThan(200);
-         expect(e.warning).toContain("of 200 rows");
-      });
-
-      it("keeps the finished payload under the cap", () => {
-         // The bug this pins: setting the marker fields and the warning AFTER
-         // the search pushes the payload back over the limit the truncation
-         // existed to respect.
-         const e = buildQueryEnvelope(rows(400), 100_000, result(), [], 3_000);
-         expect(serializeEnvelope(e).length).toBeLessThanOrEqual(3_000);
-      });
-
-      /**
-       * Reachable because the hard ceiling is maxBytes (50MB), so one row with a
-       * large text column passes assertWithinModelResponseLimits and lands here.
-       * "Showing 0 of N rows" reads as an empty result set, and an agent will
-       * report "no rows matched" for a row that was merely too big to send.
-       */
-      it("says no rows fit rather than implying nothing matched", () => {
-         const big = [{ doc: "z".repeat(5_000) }, { doc: "small" }];
-         const e = buildQueryEnvelope(big, 1000, result(), [], 2_000);
-         expect((e.rows as unknown[]).length).toBe(0);
-         expect(e._returned_rows).toBe(0);
-         expect(e._total_rows).toBe(2);
-         expect(e.warning).toContain("No rows fit the result size limit");
-         expect(e.warning).toContain("NOT an empty result");
-         expect(e.warning).not.toContain("Showing 0 of");
-      });
-
-      it("keeps the zero-row payload under the cap too", () => {
-         // The longer of the two wordings is what the search measures, so
-         // swapping it in afterwards must not push the payload back over.
-         const big = [{ doc: "z".repeat(5_000) }, { doc: "small" }];
-         const e = buildQueryEnvelope(big, 1000, result(), [], 2_000);
-         expect(serializeEnvelope(e).length).toBeLessThanOrEqual(2_000);
-      });
-
-      it("still reports the row cap when no rows fit", () => {
-         // Both shortenings apply at once; neither may swallow the other.
-         const big = [{ doc: "z".repeat(5_000) }, { doc: "y".repeat(5_000) }];
-         const e = buildQueryEnvelope(big, 2, result(), [], 2_000);
-         expect(e._limit_hit).toBe(true);
-         expect(e.warning).toContain("not a complete result");
-         expect(e.warning).toContain("No rows fit the result size limit");
-      });
-
-      it("omits the truncation fields entirely when nothing was dropped", () => {
-         // Credible's shape: absent rather than false.
-         const e = buildQueryEnvelope(rows(3), 1000, result());
-         expect("_rows_truncated" in e).toBe(false);
-         expect("_total_rows" in e).toBe(false);
-         expect("_returned_rows" in e).toBe(false);
-      });
-
-      it("reports both shortenings when they happen together", () => {
-         const e = buildQueryEnvelope(rows(200), 200, result(), [], 3_000);
-         expect(e._limit_hit).toBe(true);
-         expect(e._rows_truncated).toBe(true);
-         // One says the query was capped, the other that the payload was.
-         // Reporting only one would understate the loss.
-         expect(e.warning).toContain("not a complete result");
-         expect(e.warning).toContain("result size limit");
-      });
-
-      it("leaves an ordinary result well inside the default budget", () => {
-         const e = buildQueryEnvelope(rows(500), 1000, result());
-         expect("_rows_truncated" in e).toBe(false);
-         expect(serializeEnvelope(e).length).toBeLessThan(MAX_RESULT_CHARS);
-      });
-   });
-
-   it("passes render-tag messages through under Credible's key", () => {
-      const e = buildQueryEnvelope(rows(1), 1000, result(), ["bad tag on x"]);
-      expect(e.renderLogErrors).toEqual(["bad tag on x"]);
-   });
-
-   it("omits optional keys when they do not apply", () => {
-      const e = buildQueryEnvelope(rows(1), 1000, result());
-      expect("warning" in e).toBe(false);
-      expect("renderLogErrors" in e).toBe(false);
-   });
-});