pi-provider-litellm 3.1.0 → 3.3.0

package/src/mcp-tools.ts

@@ -1,9 +1,14 @@
 import { createHash, createHmac, randomBytes } from "node:crypto";
-import type { Static, TSchema } from "@earendil-works/pi-ai";
+import type { JsonValue, Static, TSchema } from "@earendil-works/pi-ai";
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+  defineTool,
+  type ExtensionContext,
+  type ToolDefinition,
+  type ToolExposure,
+} from "@earendil-works/pi-coding-agent";
 import { normalizeBaseUrl } from "./discover.js";
-import type { LiteLLMMcpTool, LiteLLMRuntimeAuth } from "./types.js";
+import type { LiteLLMMcpTool, LiteLLMRuntimeAuth, McpToolAnnotations } from "./types.js";
 
 const LIST_TIMEOUT_MS = 10_000;
 const CALL_TIMEOUT_MS = 30_000;
@@ -15,6 +20,8 @@ const MAX_DESCRIPTION_BYTES = 4 * 1024;
 const MAX_SCHEMA_BYTES = 64 * 1024;
 const MAX_SCHEMA_DEPTH = 16;
 const MAX_RESULT_BYTES = 64 * 1024;
+// Pi 0.99 caps its own structured bash results at the same size.
+const MAX_STRUCTURED_RESULT_BYTES = 1024 * 1024;
 const MAX_TOOL_NAME_LENGTH = 64;
 const TOOL_NAME_HASH_LENGTH = 10;
 const MAX_LABEL_BYTES = 256;
@@ -27,26 +34,119 @@ const TRUNCATION_MARKER = "\n[truncated by pi-provider-litellm]";
 const DESCRIPTION_TRUNCATION_MARKER = "… [truncated]";
 const SHORT_TRUNCATION_MARKER = "…";
 
-type DiagnosticSink = (message: string) => void;
+// `incidentScope` separates the suppression state of catalogs from different providers, so one
+// provider's clean pass cannot clear, and its differing report cannot re-trigger, another's incident.
+type DiagnosticSink = ((message: string) => void) & { readonly incidentScope?: string };
 
 interface RawLiteLLMMcpTool {
   name?: unknown;
   description?: unknown;
   inputSchema?: unknown;
   input_schema?: unknown;
+  annotations?: unknown;
   server_id?: unknown;
   server_name?: unknown;
   mcp_info?: {
     server_id?: unknown;
     server_name?: unknown;
+    description?: unknown;
   };
 }
 
+// The exposure values of a Pi `mcp.json` server entry, so `litellm.mcp.exposure` and
+// `litellm.mcp.toolExposure` mean what Pi's own MCP configuration means.
+export type McpExposure = "direct" | "codemode" | "codemode-deferred" | "deferred" | "hidden";
+const MCP_EXPOSURES: readonly McpExposure[] = ["direct", "codemode", "codemode-deferred", "deferred", "hidden"];
+
+export interface McpExposurePolicy {
+  // Exposure of every tool without a `toolExposure` match.
+  exposure: McpExposure;
+  // `[key, exposure]` in settings order. A key without `/` matches the tool name as the server offers
+  // it; a key with `/` matches `<server>/<tool>`. `*` matches any characters.
+  toolExposure: ReadonlyArray<readonly [string, McpExposure]>;
+}
+
+export const DEFAULT_MCP_EXPOSURE_POLICY: McpExposurePolicy = { exposure: "direct", toolExposure: [] };
+
+function isMcpExposure(value: unknown): value is McpExposure {
+  return typeof value === "string" && (MCP_EXPOSURES as readonly string[]).includes(value);
+}
+
+// Reads `exposure` and `toolExposure` from the `litellm.mcp` settings block. Unusable values fall back
+// to `direct`, today's behavior, and are reported in extension-owned text.
+export function parseMcpExposurePolicy(raw: unknown): { policy: McpExposurePolicy; warnings: string[] } {
+  const settings = asRecord(raw);
+  const warnings: string[] = [];
+  const expected = MCP_EXPOSURES.map((value) => JSON.stringify(value)).join(", ");
+  let exposure: McpExposure = "direct";
+  if (settings?.exposure !== undefined) {
+    if (isMcpExposure(settings.exposure)) exposure = settings.exposure;
+    else warnings.push(`litellm.mcp.exposure must be one of ${expected}; using "direct".`);
+  }
+  const toolExposure: Array<readonly [string, McpExposure]> = [];
+  if (settings?.toolExposure !== undefined) {
+    const overrides = asRecord(settings.toolExposure);
+    if (!overrides)
+      warnings.push("litellm.mcp.toolExposure must be an object mapping tool name patterns to exposures; ignoring it.");
+    else
+      for (const [key, value] of Object.entries(overrides)) {
+        if (isMcpExposure(value)) toolExposure.push([key, value]);
+        else warnings.push(`litellm.mcp.toolExposure[${JSON.stringify(key)}] must be one of ${expected}; ignoring it.`);
+      }
+  }
+  return { policy: { exposure, toolExposure }, warnings };
+}
+
+// Glob match where `*` matches any characters; segments must appear in order without overlapping.
+function wildcardMatches(pattern: string, subject: string): boolean {
+  const segments = pattern.split("*");
+  if (segments.length === 1) return pattern === subject;
+  const first = segments[0] ?? "";
+  const last = segments[segments.length - 1] ?? "";
+  if (!subject.startsWith(first) || !subject.endsWith(last)) return false;
+  const end = subject.length - last.length;
+  let position = first.length;
+  for (const segment of segments.slice(1, -1)) {
+    const index = subject.indexOf(segment, position);
+    if (index === -1 || index + segment.length > end) return false;
+    position = index + segment.length;
+  }
+  return position <= end;
+}
+
+// As in Pi's mcp.json: an exact key wins over patterns, and among patterns the first in settings
+// order wins. A `<server>/<tool>` exact key is more specific than a bare tool name.
+export function resolveMcpExposure(policy: McpExposurePolicy, serverName: string, toolName: string): McpExposure {
+  const qualified = `${serverName}/${toolName}`;
+  let qualifiedExact: McpExposure | undefined;
+  let bareExact: McpExposure | undefined;
+  let firstPattern: McpExposure | undefined;
+  for (const [key, exposure] of policy.toolExposure) {
+    const isQualified = key.includes("/");
+    const subject = isQualified ? qualified : toolName;
+    if (!key.includes("*")) {
+      if (key !== subject) continue;
+      if (isQualified) qualifiedExact ??= exposure;
+      else bareExact ??= exposure;
+    } else if (firstPattern === undefined && wildcardMatches(key, subject)) {
+      firstPattern = exposure;
+    }
+  }
+  return qualifiedExact ?? bareExact ?? firstPattern ?? policy.exposure;
+}
+
+// Pi's tool API has one `deferred`; the two deferred MCP exposures differ only in which discovery
+// tool (codemode or tool_search) is activated to reach them.
+export function toToolExposure(exposure: McpExposure): ToolExposure {
+  return exposure === "codemode-deferred" ? "deferred" : exposure;
+}
+
 interface PreparedTool {
   tool: LiteLLMMcpTool;
   name: string;
   parameters: TSchema;
   syntheticArgsEnvelope: boolean;
+  exposure: McpExposure;
 }
 
 interface InvalidMcpTool {
@@ -102,6 +202,8 @@ export interface McpPreparationReport {
   // Non-printed identities paired with `dropped`, used to detect membership changes safely.
   dropMemberships: Array<{ reason: McpDropReason; identities: string[] }>;
   degraded: Array<{ reason: McpDegradeReason; tools: string[] }>;
+  // Distinct exposures of the prepared tools, so the caller can activate codemode or tool_search.
+  exposures: McpExposure[];
 }
 
 // Bounded discovery result: `raw` is what the proxy returned, so losses can be reconciled.
@@ -130,13 +232,16 @@ function emitSafetyDiagnostic(
     process.stderr.write(line);
   },
 ): void {
-  if (lastEmittedIncident.get(incident) === identity) return;
-  lastEmittedIncident.set(incident, identity);
-  onDiagnostic(`LiteLLM MCP: ${message}\n`);
+  const scope = onDiagnostic.incidentScope;
+  const key = scope === undefined ? incident : `${scope}\0${incident}`;
+  if (lastEmittedIncident.get(key) === identity) return;
+  lastEmittedIncident.set(key, identity);
+  onDiagnostic(`LiteLLM MCP${scope === undefined ? "" : ` (${JSON.stringify(scope)})`}: ${message}\n`);
 }
 
-function clearIncident(incident: string): void {
-  lastEmittedIncident.delete(incident);
+function clearIncident(incident: string, onDiagnostic?: DiagnosticSink): void {
+  const scope = onDiagnostic?.incidentScope;
+  lastEmittedIncident.delete(scope === undefined ? incident : `${scope}\0${incident}`);
 }
 
 function membershipIdentity(tools: readonly string[]): string {
@@ -184,8 +289,8 @@ export function reportMcpRegistrationFatal(
 
 // A successful pass clears any fatal incident left by an earlier extension instance, so the same
 // failure is reported if it later recurs.
-export function reportMcpRegistrationSuccess(): void {
-  clearIncident("registration-fatal");
+export function reportMcpRegistrationSuccess(onDiagnostic?: DiagnosticSink): void {
+  clearIncident("registration-fatal", onDiagnostic);
 }
 
 // `registered` is the generated names of the tools that survived, so a failure that changes
@@ -196,7 +301,7 @@ export function reportMcpPartialDiscovery(
   onDiagnostic?: DiagnosticSink,
 ): void {
   if (!partialFailure) {
-    clearIncident("discovery-partial-failure");
+    clearIncident("discovery-partial-failure", onDiagnostic);
     return;
   }
   emitSafetyDiagnostic(
@@ -212,7 +317,7 @@ export function reportMcpPartialDiscovery(
 // an unchanged message.
 export function reportMcpCatalogOutcome(raw: number, registered: number, onDiagnostic?: DiagnosticSink): void {
   if (registered > 0) {
-    clearIncident("empty-catalog");
+    clearIncident("empty-catalog", onDiagnostic);
     return;
   }
   emitSafetyDiagnostic(
@@ -281,7 +386,7 @@ async function readBoundedText(
   onDiagnostic?: DiagnosticSink,
 ): Promise<string> {
   if (!response.body) {
-    clearIncident(`${surface}-body-cap`);
+    clearIncident(`${surface}-body-cap`, onDiagnostic);
     return "";
   }
   const reader = response.body.getReader();
@@ -312,7 +417,7 @@ async function readBoundedText(
   }
   // A response that stayed within the cap clears the incident, so a later breach on this surface
   // is reported again instead of being suppressed as an unchanged message.
-  clearIncident(`${surface}-body-cap`);
+  clearIncident(`${surface}-body-cap`, onDiagnostic);
   return Buffer.concat(
     chunks.map((chunk) => Buffer.from(chunk)),
     size,
@@ -455,6 +560,21 @@ function parseDiscoveryJson(text: string): unknown {
   return parseJson(text, "MCP discovery");
 }
 
+const ANNOTATION_HINTS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] as const;
+
+// Only the boolean hints, as Pi's own MCP client keeps them; other proxy-supplied annotation fields
+// (such as `title`) never reach Pi.
+function toolAnnotations(value: unknown): McpToolAnnotations | undefined {
+  const raw = asRecord(value);
+  if (!raw) return undefined;
+  const hints: McpToolAnnotations = {};
+  for (const hint of ANNOTATION_HINTS) {
+    const flag = raw[hint];
+    if (typeof flag === "boolean") hints[hint] = flag;
+  }
+  return Object.keys(hints).length > 0 ? hints : undefined;
+}
+
 function normalizeMcpTool(value: unknown): LiteLLMMcpTool | undefined {
   const raw = asRecord(value) as RawLiteLLMMcpTool | undefined;
   if (!raw) return undefined;
@@ -469,6 +589,8 @@ function normalizeMcpTool(value: unknown): LiteLLMMcpTool | undefined {
   const hasSnakeInputSchema = Object.hasOwn(raw, "input_schema");
   const suppliedSchema = hasInputSchema ? raw.inputSchema : hasSnakeInputSchema ? raw.input_schema : undefined;
   const inputSchema = asRecord(suppliedSchema);
+  const annotations = toolAnnotations(raw.annotations);
+  const serverDescription = stringValue(raw.mcp_info?.description);
   return {
     name,
     server_name: serverName,
@@ -477,6 +599,8 @@ function normalizeMcpTool(value: unknown): LiteLLMMcpTool | undefined {
     input_schema: inputSchema ?? {},
     // Present but not an object: malformed, as distinct from absent.
     ...(inputSchema === undefined && (hasInputSchema || hasSnakeInputSchema) ? { input_schema_malformed: true } : {}),
+    ...(annotations ? { annotations } : {}),
+    ...(serverDescription ? { server_description: serverDescription } : {}),
   };
 }
 
@@ -677,6 +801,34 @@ function mcpCallError(serverId: string, toolName: string, detail: string): Error
   );
 }
 
+export interface McpToolOutcome {
+  text: string;
+  structuredContent: Record<string, unknown>;
+  isError: boolean;
+}
+
+// Same shape as Pi's own MCP `createMcpResultSchema()`, which codemode detects to render
+// `CallToolResult`. Extension-owned: a proxy-supplied `outputSchema` is never forwarded.
+const MCP_RESULT_SCHEMA = {
+  type: "object",
+  properties: {
+    content: { type: "array", items: { type: "object" } },
+    isError: { type: "boolean" },
+    _meta: { type: "object" },
+  },
+  required: ["content"],
+} as unknown as TSchema;
+
+function structuredResult(result: unknown, text: string, isError: boolean): Record<string, unknown> {
+  const record = asRecord(result);
+  if (record && Array.isArray(record.content)) {
+    const { _meta: _ignored, ...rest } = record;
+    const structured = isError ? { ...rest, isError: true } : rest;
+    if (Buffer.byteLength(JSON.stringify(structured)) <= MAX_STRUCTURED_RESULT_BYTES) return structured;
+  }
+  return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
+}
+
 export async function executeMcpTool(
   baseUrl: string,
   apiKey: string,
@@ -687,7 +839,7 @@ export async function executeMcpTool(
   parentSignal?: AbortSignal,
   allowInsecureHttp = false,
   onDiagnostic?: DiagnosticSink,
-): Promise<string> {
+): Promise<McpToolOutcome> {
   parentSignal?.throwIfAborted();
   const signal = boundedSignal(CALL_TIMEOUT_MS, parentSignal);
   let response: Response;
@@ -716,9 +868,11 @@ export async function executeMcpTool(
     if (resultRecord?.isError === true || bodyRecord?.isError === true) {
       const message =
         mcpErrorMessage(resultRecord?.content ?? bodyRecord?.content ?? result) ?? serializeResult(result);
-      throw mcpCallError(serverId, toolName, message);
+      const text = mcpCallError(serverId, toolName, message).message;
+      return { text, structuredContent: structuredResult(result, text, true), isError: true };
     }
-    return serializeResult(result);
+    const text = serializeResult(result);
+    return { text, structuredContent: structuredResult(result, text, false), isError: false };
   } catch (error) {
     if (parentSignal?.aborted) throw parentSignal.reason;
     throw error;
@@ -743,9 +897,23 @@ function toolIdentity(tool: LiteLLMMcpTool): string {
 // A conditional hash would make a survivor's name depend on which *other* tools happened to be in
 // the same catalog, so adding or removing a sibling would rename it — and because Pi cannot
 // unregister, the old name would linger and the model would see one tool twice.
-function buildPiToolName(tool: LiteLLMMcpTool): string {
-  const hash = createHash("sha256").update(toolIdentity(tool)).digest("hex").slice(0, TOOL_NAME_HASH_LENGTH);
-  const base = `mcp_${sanitizeName(tool.server_name)}_${sanitizeName(tool.name)}`;
+// An alias provider's catalog is namespaced by the provider name, in both the prefix and the hash,
+// so two providers exposing the same server never replace each other's tools.
+function buildPiToolName(tool: LiteLLMMcpTool, namespace?: string): string {
+  const identity = namespace === undefined ? toolIdentity(tool) : JSON.stringify([namespace, toolIdentity(tool)]);
+  const hash = createHash("sha256").update(identity).digest("hex").slice(0, TOOL_NAME_HASH_LENGTH);
+  const prefix = namespace === undefined ? "mcp" : `mcp_${sanitizeName(namespace)}`;
+  const base = `${prefix}_${sanitizeName(tool.server_name)}_${sanitizeName(tool.name)}`;
+  return `${base.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;
+}
+
+// A namespace groups one server's tools, so its name is a pure function of server identity too:
+// `My-Server` and `My_Server` sanitize alike, and long names truncate alike, so a hash keeps them apart.
+function buildNamespaceName(tool: LiteLLMMcpTool, namespace?: string): string {
+  const identity = JSON.stringify([namespace ?? null, tool.server_id ?? tool.server_name, tool.server_name]);
+  const hash = createHash("sha256").update(identity).digest("hex").slice(0, 6);
+  const prefix = namespace === undefined ? "mcp" : `mcp_${sanitizeName(namespace)}`;
+  const base = `${prefix}_${sanitizeName(tool.server_name)}`;
   return `${base.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;
 }
 
@@ -1135,7 +1303,11 @@ function buildParameters(tool: LiteLLMMcpTool): BuiltParameters | McpDropReason
   return { parameters: Type.Unsafe(inputSchema), syntheticArgsEnvelope: false };
 }
 
-export function prepareTools(discovery: McpDiscovery): {
+export function prepareTools(
+  discovery: McpDiscovery,
+  namespace?: string,
+  exposurePolicy: McpExposurePolicy = DEFAULT_MCP_EXPOSURE_POLICY,
+): {
   prepared: PreparedTool[];
   report: McpPreparationReport;
 } {
@@ -1160,12 +1332,12 @@ export function prepareTools(discovery: McpDiscovery): {
   for (const tool of discovery.tools) {
     const built = buildParameters(tool);
     if (typeof built === "string") {
-      recordDrop(built, buildPiToolName(tool));
+      recordDrop(built, buildPiToolName(tool, namespace));
       continue;
     }
     const identity = toolIdentity(tool);
     if (acceptedIdentities.has(identity)) {
-      recordDrop("duplicate-identity", buildPiToolName(tool));
+      recordDrop("duplicate-identity", buildPiToolName(tool, namespace));
       continue;
     }
     acceptedIdentities.add(identity);
@@ -1173,17 +1345,18 @@ export function prepareTools(discovery: McpDiscovery): {
       tool,
       parameters: built.parameters,
       syntheticArgsEnvelope: built.syntheticArgsEnvelope,
+      exposure: resolveMcpExposure(exposurePolicy, tool.server_name, tool.name),
       degraded: built.degraded,
     });
   }
 
   const candidates = accepted.slice(0, MAX_REGISTERED_TOOLS);
-  const overflowTools = accepted.slice(MAX_REGISTERED_TOOLS).map(({ tool }) => buildPiToolName(tool));
+  const overflowTools = accepted.slice(MAX_REGISTERED_TOOLS).map(({ tool }) => buildPiToolName(tool, namespace));
   const finalNames = new Set<string>();
   const prepared: PreparedTool[] = [];
   for (const candidate of candidates) {
     // Membership-independent: the name depends only on this tool's identity.
-    const name = buildPiToolName(candidate.tool);
+    const name = buildPiToolName(candidate.tool, namespace);
     if (finalNames.has(name)) {
       recordDrop("name-collision", name);
       continue;
@@ -1210,6 +1383,7 @@ export function prepareTools(discovery: McpDiscovery): {
     dropped: [...drops.entries()].map(([reason, tools]) => ({ reason, tools })),
     dropMemberships: [...dropMemberships.entries()].map(([reason, identities]) => ({ reason, identities })),
     degraded: [...degrades.entries()].map(([reason, tools]) => ({ reason, tools })),
+    exposures: [...new Set(prepared.map((tool) => tool.exposure))].sort(),
   };
   return { prepared, report };
 }
@@ -1251,7 +1425,7 @@ function emitPreparationDiagnostics(report: McpPreparationReport, onDiagnostic?:
   // Clear classes that did not recur, so the same incident is reported again if it comes back
   // after a clean refresh instead of being suppressed as an unchanged identity.
   for (const reason of [...Object.keys(INCIDENT_REASON_TEXT), "tool-cap"]) {
-    if (!seen.has(reason)) clearIncident(reason);
+    if (!seen.has(reason)) clearIncident(reason, onDiagnostic);
   }
 }
 
@@ -1260,6 +1434,8 @@ export async function createMcpToolDefinitions(
   onProgress?: (message: string) => void,
   signal?: AbortSignal,
   onDiagnostic?: DiagnosticSink,
+  namespace?: string,
+  exposurePolicy: McpExposurePolicy = DEFAULT_MCP_EXPOSURE_POLICY,
 ): Promise<{ definitions: ToolDefinition[]; report: McpPreparationReport }> {
   const discoveryAuth = await getAuth();
   const discovery = await discoverMcpTools(
@@ -1271,7 +1447,7 @@ export async function createMcpToolDefinitions(
     discoveryAuth.allowInsecureHttp,
     onDiagnostic,
   );
-  const { prepared, report } = prepareTools(discovery);
+  const { prepared, report } = prepareTools(discovery, namespace, exposurePolicy);
   emitPreparationDiagnostics(report, onDiagnostic);
   const lostTotal = report.dropped.reduce((total, entry) => total + entry.tools.length, 0) + report.overflow;
   const lostDetail = [
@@ -1285,7 +1461,7 @@ export async function createMcpToolDefinitions(
       `${lostDetail ? ` (${lostDetail})` : ""}`,
   );
 
-  const definitions = prepared.map(({ tool: mcpTool, name, parameters, syntheticArgsEnvelope }) => {
+  const definitions = prepared.map(({ tool: mcpTool, name, parameters, syntheticArgsEnvelope, exposure }) => {
     const description = truncateUtf8(
       `${mcpTool.description} (via ${mcpTool.server_name} MCP server)`,
       MAX_DESCRIPTION_BYTES,
@@ -1301,6 +1477,16 @@ export async function createMcpToolDefinitions(
     // untrusted string that reaches Pi's UI or the model.
     const label = truncateUtf8(`${mcpTool.server_name}: ${mcpTool.name}`, MAX_LABEL_BYTES, SHORT_TRUNCATION_MARKER);
     const boundedDetail = (value: string): string => truncateUtf8(value, MAX_DETAIL_BYTES, SHORT_TRUNCATION_MARKER);
+    // Pi 0.99 groups tools by namespace, as its own MCP client does per server. The prefix matches the
+    // generated tool names, so a group is recognisable in codemode listings; older Pi ignores it.
+    const toolNamespace = {
+      name: buildNamespaceName(mcpTool, namespace),
+      description: truncateUtf8(
+        mcpTool.server_description ?? `LiteLLM MCP server ${mcpTool.server_name}`,
+        MAX_LABEL_BYTES,
+        SHORT_TRUNCATION_MARKER,
+      ),
+    };
 
     return defineTool({
       name,
@@ -1308,13 +1494,17 @@ export async function createMcpToolDefinitions(
       description,
       promptSnippet,
       executionMode: "parallel",
+      exposure: toToolExposure(exposure),
+      namespace: toolNamespace,
+      ...(mcpTool.annotations ? { annotations: mcpTool.annotations } : {}),
       parameters,
+      outputSchema: MCP_RESULT_SCHEMA,
       async execute(_toolCallId, params: Static<typeof parameters>, toolSignal, _onUpdate, ctx) {
         const auth = await getAuth(ctx);
         const rawParams = params as Record<string, unknown>;
         const args = syntheticArgsEnvelope ? asRecord(rawParams.args) : rawParams;
         if (!args) throw new Error("Synthetic MCP tool arguments must contain an object-valued args property");
-        const text = await executeMcpTool(
+        const { text, structuredContent, isError } = await executeMcpTool(
           auth.baseUrl,
           auth.apiKey,
           mcpTool.server_id ?? mcpTool.server_name,
@@ -1325,8 +1515,13 @@ export async function createMcpToolDefinitions(
           auth.allowInsecureHttp,
           onDiagnostic,
         );
+        // Pi before 0.99 ignores a returned `isError`; `ctx.executeTool` exists only from 0.99.
+        if (isError && typeof (ctx as { executeTool?: unknown }).executeTool !== "function") throw new Error(text);
         return {
           content: [{ type: "text", text }],
+          // The body came from JSON.parse, so it is a JsonValue; Pi's type cannot see that.
+          structuredContent: structuredContent as JsonValue,
+          ...(isError ? { isError: true } : {}),
           details: {
             server: boundedDetail(mcpTool.server_name),
             serverId: boundedDetail(mcpTool.server_id ?? mcpTool.server_name),

package/src/model-groups.ts

@@ -1,8 +1,34 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { routesOnlyThrough } from "./backend-identity.js";
 import { intersectThinkingLevelMaps, THINKING_LEVEL_DEFINITIONS } from "./thinking-levels.js";
 import type { DiscoveredModel, ModelInfoEntry } from "./types.js";
 
-export const DEFAULT_CONTEXT_WINDOW = 128_000;
+const BUILTIN_CONTEXT_WINDOW = 128_000;
+
+/**
+ * Context window used when neither /model/info nor the catalog reports one.
+ * LITELLM_DEFAULT_CONTEXT_WINDOW raises it for proxies whose model map cannot
+ * populate `max_input_tokens`; an unset or unusable value keeps the 128K default.
+ */
+export function defaultContextWindow(): number {
+  // Number, not parseInt: parseInt takes a numeric prefix, so `1.5` would become a
+  // 1-token window and `922000junk` would pass as a limit instead of being rejected.
+  const parsed = Number(process.env.LITELLM_DEFAULT_CONTEXT_WINDOW ?? "");
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : BUILTIN_CONTEXT_WINDOW;
+}
+
+/**
+ * Whether a stored window is one this extension assumed rather than read. A model cached
+ * under the built-in default must still read as evidence-free once an operator configures
+ * LITELLM_DEFAULT_CONTEXT_WINDOW, or the setting would never reach cached entries.
+ * ponytail: a window stored under a setting that was later lowered is indistinguishable
+ * from measured evidence and stays until the next online discovery; persist a fallback
+ * marker on the model if that ever matters.
+ */
+export function isFallbackContextWindow(contextWindow: number): boolean {
+  return contextWindow === BUILTIN_CONTEXT_WINDOW || contextWindow === defaultContextWindow();
+}
+
 export const DEFAULT_MAX_TOKENS = 16_384;
 
 export type SemanticFamily = "claude" | "deepseek" | "gemini" | "kimi" | "openai";
@@ -12,7 +38,7 @@ type FamilyEvidence = SemanticFamily | "conflicting";
 
 export type MessagesBackendCompat = Pick<
   NonNullable<Model<"anthropic-messages">["compat"]>,
-  "forceAdaptiveThinking" | "supportsTemperature" | "supportsStrictTools"
+  "forceAdaptiveThinking" | "supportsTemperature"
 >;
 
 type OpenAICompat = NonNullable<Model<"openai-completions">["compat"]>;
@@ -32,6 +58,9 @@ export interface CatalogResolution {
   semanticFamily?: FamilyEvidence;
   semanticModel?: SemanticModel;
   messagesCompat?: MessagesBackendCompat;
+  // Evidence for the actual Messages route, kept separate from model-generation
+  // serializer policy so strict-tool disagreement cannot change the transport.
+  messagesStrictTools?: boolean;
   messagesThinkingLevelMap?: DiscoveredModel["thinkingLevelMap"];
   reasoning?: boolean;
   effortLevels?: string[];
@@ -52,6 +81,7 @@ export interface ReducedModelGroup {
   thinkingLevelMap?: DiscoveredModel["thinkingLevelMap"];
   vision: boolean;
   contextWindow: number;
+  contextWindowDefaulted?: boolean;
   maxTokens: number;
   cost: DiscoveredModel["cost"];
   hasCompleteCost: boolean;
@@ -60,6 +90,7 @@ export interface ReducedModelGroup {
   semanticModel?: SemanticModel;
   semanticFamily?: FamilyEvidence;
   messagesCompat?: MessagesBackendCompat;
+  messagesStrictTools?: boolean;
   // Set when deployments disagreed on catalog provider identity, so catalog
   // limits, pricing, and reasoning metadata were withheld for the whole group.
   catalogAuthorityAmbiguous?: boolean;
@@ -712,6 +743,7 @@ export function hasMixedIncompatibleDeploymentModes(entries: readonly ModelInfoE
 }
 
 const KIMI_FAMILY_PATTERN = /(?:^|[./_-])(?:moonshotai|moonshot|kimi)(?:$|[./_:-])/i;
+const MOONSHOT_ROUTES: ReadonlySet<string> = new Set(["moonshot", "moonshotai"]);
 const FORCED_THINKING_PATTERN = /(?:^|[./_-])thinking(?:$|[./_:-])/i;
 
 function kimiDeploymentEvidence(entry: ModelInfoEntry): {
@@ -728,21 +760,12 @@ function kimiDeploymentEvidence(entry: ModelInfoEntry): {
     .map((candidate) => wireString(candidate)?.trim())
     .filter((candidate): candidate is string => Boolean(candidate));
   const kimi = identities.filter((identity) => KIMI_FAMILY_PATTERN.test(identity));
-  const routingModel = wireString(entry.litellm_params?.model)?.trim();
-  const routingProviders = [
-    wireString(entry.litellm_params?.custom_llm_provider)?.trim(),
-    routingModel?.includes("/") ? routingModel.split("/", 1)[0] : undefined,
-  ]
-    .filter((provider): provider is string => Boolean(provider))
-    .map((provider) => provider.toLowerCase());
   return {
     identified: kimi.length > 0,
     forcedThinking: kimi.some((identity) => FORCED_THINKING_PATTERN.test(identity)),
     // Visibility parameters are accepted by Moonshot's API, not by every host
     // that serves a Kimi model. Both declared routing signals must name Moonshot.
-    moonshotTransport:
-      routingProviders.length > 0 &&
-      routingProviders.every((provider) => provider === "moonshot" || provider === "moonshotai"),
+    moonshotTransport: routesOnlyThrough(entry, MOONSHOT_ROUTES),
   };
 }
 
@@ -772,6 +795,9 @@ export function reduceModelGroup(
   const semanticModel = unanimous(catalogs.map((catalog) => catalog?.semanticModel));
   const semanticFamily = unanimous(catalogs.map((catalog) => catalog?.semanticFamily));
   const messagesCompat = unanimous(catalogs.map((catalog) => stableJson(catalog?.messagesCompat)));
+  // Strict tools require affirmative evidence from every routable deployment.
+  const messagesStrictTools =
+    catalogs.length > 0 && catalogs.every((catalog) => catalog?.messagesStrictTools === true) ? true : undefined;
   const messagesEndpointAllowed = deployments.every((entry) => {
     const endpoints = entry.model_info?.supported_endpoints;
     return endpoints === undefined || (Array.isArray(endpoints) && endpoints.includes("/v1/messages"));
@@ -801,7 +827,8 @@ export function reduceModelGroup(
     (entry) => wireBoolean(entry.model_info?.supports_reasoning) === false,
   );
   const vision = visionEvidence.every((value) => value ?? false);
-  const contextWindow = min(contextWindowEvidence.map((value) => value ?? DEFAULT_CONTEXT_WINDOW));
+  const fallbackContextWindow = defaultContextWindow();
+  const contextWindow = min(contextWindowEvidence.map((value) => value ?? fallbackContextWindow));
   const maxTokens = min(maxTokensEvidence.map((value) => value ?? DEFAULT_MAX_TOKENS));
 
   const costValues = COST_FIELDS.map((field) =>
@@ -930,6 +957,9 @@ export function reduceModelGroup(
     ...(thinkingLevelMap ? { thinkingLevelMap } : {}),
     vision,
     contextWindow,
+    ...(contextWindowEvidence.includes(undefined) && contextWindow === fallbackContextWindow
+      ? { contextWindowDefaulted: true }
+      : {}),
     maxTokens,
     cost,
     hasCompleteCost,
@@ -938,6 +968,7 @@ export function reduceModelGroup(
     ...(semanticModel ? { semanticModel } : {}),
     ...(semanticFamily ? { semanticFamily } : {}),
     ...(messagesCompat ? { messagesCompat: JSON.parse(messagesCompat) } : {}),
+    ...(messagesStrictTools !== undefined ? { messagesStrictTools } : {}),
     ...(catalogAuthorityAmbiguous ? { catalogAuthorityAmbiguous: true } : {}),
     deploymentFamilies: catalogs.map((catalog) => catalog?.semanticFamily),
     normalizeThinkTags: unanimousNormalKimi,