terramend 0.2.0

package/src/mcp/geminiSanitizer.test.ts

@@ -0,0 +1,287 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Tool } from "fastmcp";
+import { describe, expect, it } from "vitest";
+import {
+  isGeminiRouted,
+  sanitizeForGemini,
+  sanitizeToolForGemini,
+  wrapSchemaForGemini,
+} from "#app/mcp/geminiSanitizer";
+import type { ToolContext } from "#app/mcp/server";
+
+describe("sanitizeForGemini", () => {
+  it("passes through primitives and null untouched", () => {
+    expect(sanitizeForGemini(null)).toBeNull();
+    expect(sanitizeForGemini(undefined)).toBeUndefined();
+    expect(sanitizeForGemini("string")).toBe("string");
+    expect(sanitizeForGemini(42)).toBe(42);
+    expect(sanitizeForGemini(true)).toBe(true);
+  });
+
+  it("maps arrays element-wise", () => {
+    expect(sanitizeForGemini([{ $schema: "x", type: "object" }, 1])).toEqual([
+      { type: "object" },
+      1,
+    ]);
+  });
+
+  it("adds type: string to an enum-only string union (case 1)", () => {
+    expect(sanitizeForGemini({ enum: ["A", "B"] })).toEqual({
+      type: "string",
+      enum: ["A", "B"],
+    });
+  });
+
+  it("keeps the description when typing an enum-only schema", () => {
+    expect(sanitizeForGemini({ enum: ["A"], description: "pick one" })).toEqual({
+      type: "string",
+      enum: ["A"],
+      description: "pick one",
+    });
+  });
+
+  it("leaves a mixed-type enum to the generic pass (no fabricated type)", () => {
+    expect(sanitizeForGemini({ enum: ["A", 1] })).toEqual({ enum: ["A", 1] });
+  });
+
+  it("does not re-type an enum that already declares a string type", () => {
+    expect(sanitizeForGemini({ type: "string", enum: ["A"], extra: 1 })).toEqual({
+      type: "string",
+      enum: ["A"],
+      extra: 1,
+    });
+  });
+
+  it("collapses an anyOf of string enums into a typed enum (case 2)", () => {
+    expect(
+      sanitizeForGemini({
+        anyOf: [{ enum: ["a"] }, { enum: ["b", "c"] }],
+        description: "choice",
+      }),
+    ).toEqual({ type: "string", enum: ["a", "b", "c"], description: "choice" });
+  });
+
+  it("collapses const branches and dedupes repeated values", () => {
+    expect(sanitizeForGemini({ oneOf: [{ const: "x" }, { const: "y" }, { enum: ["x"] }] })).toEqual(
+      { type: "string", enum: ["x", "y"] },
+    );
+  });
+
+  it("strips sibling fields from a non-collapsible anyOf (case 3)", () => {
+    const result = sanitizeForGemini({
+      anyOf: [{ type: "string" }, { type: "number" }],
+      type: "string",
+      description: "dropped per gemini rule",
+    });
+    expect(result).toEqual({ anyOf: [{ type: "string" }, { type: "number" }] });
+  });
+
+  it("handles a oneOf-only non-collapsible union (no anyOf key fabricated)", () => {
+    expect(
+      sanitizeForGemini({ oneOf: [{ type: "number" }, { type: "boolean" }], description: "d" }),
+    ).toEqual({ oneOf: [{ type: "number" }, { type: "boolean" }] });
+  });
+
+  it("keeps both anyOf and oneOf when neither collapses, recursing into branches", () => {
+    const result = sanitizeForGemini({
+      anyOf: [{ $schema: "x", type: "string" }],
+      oneOf: [{ type: "number" }, { type: "boolean" }],
+    });
+    expect(result).toEqual({
+      anyOf: [{ type: "string" }],
+      oneOf: [{ type: "number" }, { type: "boolean" }],
+    });
+  });
+
+  it("treats a branch with an empty or non-string enum as non-collapsible", () => {
+    // the union is NOT collapsed (case 2 fails); branches are still sanitized
+    // individually, so the all-strings empty enum gains a string type (case 1).
+    expect(sanitizeForGemini({ anyOf: [{ enum: [] }, { enum: ["a"] }] })).toEqual({
+      anyOf: [
+        { type: "string", enum: [] },
+        { type: "string", enum: ["a"] },
+      ],
+    });
+    expect(sanitizeForGemini({ anyOf: [{ enum: [1, 2] }, "not-an-object"] })).toEqual({
+      anyOf: [{ enum: [1, 2] }, "not-an-object"],
+    });
+  });
+
+  it("drops $schema and renames $defs to definitions (case 4)", () => {
+    expect(
+      sanitizeForGemini({
+        $schema: "http://json-schema.org/draft-07/schema#",
+        $defs: { inner: { enum: ["a"] } },
+        type: "object",
+        properties: { mode: { enum: ["Build", "Review"] } },
+      }),
+    ).toEqual({
+      definitions: { inner: { type: "string", enum: ["a"] } },
+      type: "object",
+      properties: { mode: { type: "string", enum: ["Build", "Review"] } },
+    });
+  });
+});
+
+// structural view of the proxied schema, so tests can reach into the wrapped
+// `~standard`/`toJsonSchema` chain without scattering `any` casts.
+type SchemaView = {
+  "~standard": {
+    vendor: string;
+    validate: unknown;
+    jsonSchema: {
+      input: (args?: unknown) => unknown;
+      output: () => unknown;
+      version: string;
+    };
+  };
+  toJsonSchema: (() => unknown) | string;
+  infer: unknown;
+};
+
+function view(schema: StandardSchemaV1<unknown>): SchemaView {
+  return schema as unknown as SchemaView;
+}
+
+describe("wrapSchemaForGemini", () => {
+  function makeSchema(overrides?: Record<string, unknown>): StandardSchemaV1<unknown> {
+    return {
+      "~standard": {
+        version: 1,
+        vendor: "arktype",
+        validate: () => ({ value: undefined }),
+        jsonSchema: {
+          input: () => ({ $schema: "x", enum: ["a", "b"] }),
+          output: () => ({ $defs: { d: {} }, type: "object" }),
+          version: "v1",
+        },
+      },
+      ...overrides,
+    } as unknown as StandardSchemaV1<unknown>;
+  }
+
+  it("sanitizes through the ~standard.jsonSchema.input path (xsschema path A)", () => {
+    const wrapped = view(wrapSchemaForGemini(makeSchema()));
+    const produced = wrapped["~standard"].jsonSchema.input({ target: "draft-07" });
+    expect(produced).toEqual({ type: "string", enum: ["a", "b"] });
+  });
+
+  it("sanitizes the jsonSchema.output producer too", () => {
+    const wrapped = view(wrapSchemaForGemini(makeSchema()));
+    expect(wrapped["~standard"].jsonSchema.output()).toEqual({
+      definitions: { d: {} },
+      type: "object",
+    });
+  });
+
+  it("passes non-function jsonSchema members through unchanged", () => {
+    const wrapped = view(wrapSchemaForGemini(makeSchema()));
+    expect(wrapped["~standard"].jsonSchema.version).toBe("v1");
+  });
+
+  it("passes other ~standard members (vendor, validate) through unchanged", () => {
+    const wrapped = view(wrapSchemaForGemini(makeSchema()));
+    expect(wrapped["~standard"].vendor).toBe("arktype");
+    expect(typeof wrapped["~standard"].validate).toBe("function");
+  });
+
+  it("sanitizes through the toJsonSchema path (xsschema path B)", () => {
+    const schema = makeSchema({
+      toJsonSchema: () => ({ $schema: "x", type: "object" }),
+    });
+    const wrapped = view(wrapSchemaForGemini(schema));
+    expect(typeof wrapped.toJsonSchema).toBe("function");
+    if (typeof wrapped.toJsonSchema === "function") {
+      expect(wrapped.toJsonSchema()).toEqual({ type: "object" });
+    }
+  });
+
+  it("returns a non-function toJsonSchema property as-is", () => {
+    const schema = makeSchema({ toJsonSchema: "not callable" });
+    const wrapped = view(wrapSchemaForGemini(schema));
+    expect(wrapped.toJsonSchema).toBe("not callable");
+  });
+
+  it("returns a non-object ~standard value as-is", () => {
+    const schema = { "~standard": null } as unknown as StandardSchemaV1<unknown>;
+    const wrapped = view(wrapSchemaForGemini(schema));
+    expect(wrapped["~standard"]).toBeNull();
+  });
+
+  it("returns a non-object jsonSchema value as-is", () => {
+    const schema = {
+      "~standard": { version: 1, vendor: "arktype", jsonSchema: "nope" },
+    } as unknown as StandardSchemaV1<unknown>;
+    const wrapped = view(wrapSchemaForGemini(schema));
+    expect(wrapped["~standard"].jsonSchema).toBe("nope");
+  });
+
+  it("passes unrelated schema properties through the outer proxy", () => {
+    const schema = makeSchema({ infer: "marker" });
+    const wrapped = view(wrapSchemaForGemini(schema));
+    expect(wrapped.infer).toBe("marker");
+  });
+});
+
+describe("sanitizeToolForGemini", () => {
+  type AnyTool = Tool<Record<string, never>, StandardSchemaV1<unknown>>;
+
+  it("returns the tool unchanged when it has no parameters", () => {
+    const bare = { name: "t", execute: async () => "ok" } as unknown as AnyTool;
+    expect(sanitizeToolForGemini(bare)).toBe(bare);
+  });
+
+  it("wraps the parameters schema and preserves the other fields", () => {
+    const params = {
+      "~standard": {
+        version: 1,
+        vendor: "arktype",
+        jsonSchema: { input: () => ({ enum: ["x"] }) },
+      },
+    } as unknown as StandardSchemaV1<unknown>;
+    const original = {
+      name: "t",
+      description: "d",
+      parameters: params,
+      execute: async () => "ok",
+    } as unknown as AnyTool;
+    const wrapped = sanitizeToolForGemini(original);
+    expect(wrapped).not.toBe(original);
+    expect(wrapped.name).toBe("t");
+    const wrappedParams = wrapped.parameters as StandardSchemaV1<unknown> | undefined;
+    expect(wrappedParams).toBeDefined();
+    if (wrappedParams) {
+      expect(view(wrappedParams)["~standard"].jsonSchema.input()).toEqual({
+        type: "string",
+        enum: ["x"],
+      });
+    }
+  });
+});
+
+describe("isGeminiRouted", () => {
+  const ctx = (resolvedModel: string | undefined, payloadModel?: string): ToolContext =>
+    ({ resolvedModel, payload: { model: payloadModel } }) as unknown as ToolContext;
+
+  it("matches any slug containing 'gemini' regardless of provider prefix", () => {
+    expect(isGeminiRouted(ctx("google/gemini-3.1-pro-preview"))).toBe(true);
+    expect(isGeminiRouted(ctx("opencode/Gemini-2.5-flash"))).toBe(true);
+    expect(isGeminiRouted(ctx("openrouter/google/gemini-2.5-pro"))).toBe(true);
+  });
+
+  it("treats an unresolved specifier (undefined / auto / bare slug) as gemini-possible", () => {
+    expect(isGeminiRouted(ctx(undefined))).toBe(true);
+    expect(isGeminiRouted(ctx("auto"))).toBe(true);
+    expect(isGeminiRouted(ctx("some-unknown-slug"))).toBe(true);
+  });
+
+  it("falls back to the payload model when no resolved model exists", () => {
+    expect(isGeminiRouted(ctx(undefined, "google/gemini-2.5-pro"))).toBe(true);
+    expect(isGeminiRouted(ctx(undefined, "anthropic/claude-opus-4-7"))).toBe(false);
+  });
+
+  it("returns false for a concrete non-gemini provider/model", () => {
+    expect(isGeminiRouted(ctx("anthropic/claude-opus-4-7"))).toBe(false);
+    expect(isGeminiRouted(ctx("openai/gpt-5.2"))).toBe(false);
+  });
+});

package/src/mcp/geminiSanitizer.ts

@@ -0,0 +1,207 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Tool } from "fastmcp";
+import type { ToolContext } from "#app/mcp/server";
+
+// ── gemini schema sanitizer ────────────────────────────────────────────────────
+//
+// gemini's generateContent API expects an OpenAPI 3.0 Schema subset, not full
+// JSON Schema. arktype 2.x emits constructs that gemini rejects with errors like:
+//   - "parameters.<field>.enum: only allowed for STRING type"
+//   - "functionDeclaration parameters.<field> schema didn't specify the schema type field"
+//   - "anyOf must be the only field in a schema node"
+//
+// transforms applied here:
+//   1. add `type: "string"` to enum-only schemas. arktype emits string literal
+//      unions as `{enum: ["a","b"]}` without a `type` field — gemini requires
+//      the type declaration for any non-object schema.
+//   2. collapse `{anyOf: [{enum:["a"]}, {enum:["b"]}]}` (older arktype form)
+//      into `{type:"string", enum:[...]}`. also handles `{const:"a"}` branches.
+//   3. when `anyOf` / `oneOf` can't be collapsed, strip sibling fields (`type`,
+//      `description`, `items`, etc.) — gemini rejects `anyOf` alongside any
+//      peer keywords. see opencode #14659.
+//   4. drop `$schema` metadata and rename `$defs` → `definitions` (draft-07
+//      compatibility; gemini doesn't understand either).
+//
+// gating: `isGeminiRouted()` detects gemini-targeted traffic so other
+// providers continue to see the original (untransformed) schema.
+//
+// delivery: fastmcp (3.x) uses `xsschema.toJsonSchema()` which reads
+// `schema["~standard"].jsonSchema.input({target:"draft-07"})` when present
+// (arktype 2.x exposes this). we proxy the whole `~standard` chain so our
+// transform runs regardless of which path xsschema takes.
+
+function parseStringEnumBranch(item: unknown): { values: string[] } | null {
+  if (!item || typeof item !== "object") return null;
+  const record = item as Record<string, unknown>;
+  if (Array.isArray(record.enum)) {
+    const strings = record.enum.filter((v): v is string => typeof v === "string");
+    return strings.length === record.enum.length && strings.length > 0 ? { values: strings } : null;
+  }
+  if (typeof record.const === "string") {
+    return { values: [record.const] };
+  }
+  return null;
+}
+
+function collapseStringUnion(branches: unknown[]): { type: "string"; enum: string[] } | null {
+  const values: string[] = [];
+  for (const item of branches) {
+    const parsed = parseStringEnumBranch(item);
+    if (!parsed) return null;
+    values.push(...parsed.values);
+  }
+  if (values.length === 0) return null;
+  return { type: "string", enum: [...new Set(values)] };
+}
+
+/**
+ * Recursively transform a JSON schema to gemini's stricter subset.
+ * See module header for the exact transforms applied.
+ */
+export function sanitizeForGemini(schema: unknown): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map(sanitizeForGemini);
+
+  const source = schema as Record<string, unknown>;
+
+  // case 1: enum-only string union → add `type: "string"`.
+  // arktype emits `type: "'A' | 'B'"` as `{enum: ["A","B"]}` without a type.
+  if (Array.isArray(source.enum) && typeof source.type !== "string") {
+    const allStrings = source.enum.every((v) => typeof v === "string");
+    if (allStrings) {
+      const result: Record<string, unknown> = { type: "string", enum: source.enum };
+      if (typeof source.description === "string") result.description = source.description;
+      return result;
+    }
+  }
+
+  // case 2: collapsible string-enum union (older arktype form)
+  for (const unionKey of ["anyOf", "oneOf"] as const) {
+    const branches = source[unionKey];
+    if (Array.isArray(branches) && branches.length > 0) {
+      const collapsed = collapseStringUnion(branches);
+      if (collapsed) {
+        const result: Record<string, unknown> = { ...collapsed };
+        if (typeof source.description === "string") result.description = source.description;
+        return result;
+      }
+    }
+  }
+
+  // case 3: non-collapsible anyOf/oneOf → strip sibling fields (gemini rule)
+  if (Array.isArray(source.anyOf) || Array.isArray(source.oneOf)) {
+    const result: Record<string, unknown> = {};
+    if (Array.isArray(source.anyOf)) result.anyOf = source.anyOf.map(sanitizeForGemini);
+    if (Array.isArray(source.oneOf)) result.oneOf = source.oneOf.map(sanitizeForGemini);
+    return result;
+  }
+
+  // case 4: generic pass — drop $schema, rename $defs, recurse
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (key === "$schema") continue;
+    if (key === "$defs") {
+      sanitized.definitions = sanitizeForGemini(value);
+      continue;
+    }
+    sanitized[key] = sanitizeForGemini(value);
+  }
+  return sanitized;
+}
+
+// ── delivery mechanism ─────────────────────────────────────────────────────────
+//
+// fastmcp 3.x resolves the JSON schema via xsschema, which takes two paths:
+//   path A: `schema["~standard"].jsonSchema.input({target:"draft-07"})` when
+//           the StandardJSONSchemaV1 extension is present (arktype 2.x).
+//   path B: `schema.toJsonSchema()` via a vendor-dispatched function (older
+//           arktype, other vendors).
+//
+// we proxy both entry points so the transform runs regardless of which path
+// xsschema picks.
+
+function wrapJsonSchemaProducer<T extends object>(producer: T): T {
+  return new Proxy(producer, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if ((prop === "input" || prop === "output") && typeof value === "function") {
+        const fn = value as (...args: unknown[]) => unknown;
+        return (...args: unknown[]) => sanitizeForGemini(fn.apply(target, args));
+      }
+      return value;
+    },
+  });
+}
+
+function wrapStandard<T extends object>(standard: T): T {
+  return new Proxy(standard, {
+    get(target, prop, receiver) {
+      if (prop === "jsonSchema") {
+        const value = Reflect.get(target, prop, receiver);
+        if (value && typeof value === "object") {
+          return wrapJsonSchemaProducer(value as object);
+        }
+        return value;
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}
+
+export function wrapSchemaForGemini(schema: StandardSchemaV1<any>): StandardSchemaV1<any> {
+  return new Proxy(schema, {
+    get(target, prop, receiver) {
+      if (prop === "~standard") {
+        const value = Reflect.get(target, prop, receiver);
+        if (value && typeof value === "object") {
+          return wrapStandard(value as object);
+        }
+        return value;
+      }
+      if (prop === "toJsonSchema") {
+        const method = Reflect.get(target, prop, receiver);
+        if (typeof method === "function") {
+          return () => sanitizeForGemini((method as (...args: unknown[]) => unknown).call(target));
+        }
+        return method;
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as StandardSchemaV1<any>;
+}
+
+export function sanitizeToolForGemini<T extends Tool<any, any>>(tool: T): T {
+  if (!tool.parameters) return tool;
+  return { ...tool, parameters: wrapSchemaForGemini(tool.parameters) } as T;
+}
+
+/**
+ * true when the effective upstream model is — or might become — google
+ * generative language API traffic. matches:
+ *   - direct `google/*`, opencode `opencode/gemini-*`, openrouter
+ *     `openrouter/google/gemini-*` (slug substring "gemini" wins).
+ *   - any unresolved specifier: `undefined`, `"auto"`, or a slug that
+ *     didn't map through the alias registry (no `provider/` prefix).
+ *     these flow through the agent's own auto-select, which may land
+ *     on gemini *after* the MCP server has already registered tools —
+ *     at which point sanitization is too late to apply. erring on the
+ *     side of sanitizing is safe: cases 1 + 2 are universally
+ *     compatible JSON-Schema normalizations (enum-only → typed string,
+ *     collapsible const-unions → string enum); case 3 is gemini-
+ *     specific but only fires on non-collapsible unions, which arktype
+ *     does not emit for our current tool schemas. see issue #676 for
+ *     the prod failure that motivated this widening.
+ */
+export function isGeminiRouted(ctx: ToolContext): boolean {
+  const effective = ctx.resolvedModel ?? ctx.payload.model;
+  if (!effective) return true;
+  const normalized = effective.toLowerCase();
+  if (normalized.includes("gemini")) return true;
+  // every concrete model resolved through the registry carries a
+  // `provider/` prefix (e.g. "anthropic/claude-opus-4-7"). anything
+  // without a slash is either the literal `"auto"` alias or an
+  // unrecognized slug that resolveModel logged a warning for — both
+  // route through the agent's late auto-select, which may pick gemini.
+  if (!normalized.includes("/")) return true;
+  return false;
+}