pi-provider-litellm 3.2.0 → 3.4.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;
@@ -36,19 +43,110 @@ interface RawLiteLLMMcpTool {
   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 {
@@ -104,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.
@@ -460,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;
@@ -474,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,
@@ -482,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 } : {}),
   };
 }
 
@@ -682,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,
@@ -692,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;
@@ -721,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;
@@ -758,6 +907,16 @@ function buildPiToolName(tool: LiteLLMMcpTool, namespace?: string): string {
   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}`;
+}
+
 function schemaDepth(value: unknown, depth = 0): number {
   if (!value || typeof value !== "object") return depth;
   if (depth > MAX_SCHEMA_DEPTH) return depth;
@@ -1147,6 +1306,7 @@ function buildParameters(tool: LiteLLMMcpTool): BuiltParameters | McpDropReason
 export function prepareTools(
   discovery: McpDiscovery,
   namespace?: string,
+  exposurePolicy: McpExposurePolicy = DEFAULT_MCP_EXPOSURE_POLICY,
 ): {
   prepared: PreparedTool[];
   report: McpPreparationReport;
@@ -1185,6 +1345,7 @@ export function prepareTools(
       tool,
       parameters: built.parameters,
       syntheticArgsEnvelope: built.syntheticArgsEnvelope,
+      exposure: resolveMcpExposure(exposurePolicy, tool.server_name, tool.name),
       degraded: built.degraded,
     });
   }
@@ -1222,6 +1383,7 @@ export function prepareTools(
     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 };
 }
@@ -1273,6 +1435,7 @@ export async function createMcpToolDefinitions(
   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(
@@ -1284,7 +1447,7 @@ export async function createMcpToolDefinitions(
     discoveryAuth.allowInsecureHttp,
     onDiagnostic,
   );
-  const { prepared, report } = prepareTools(discovery, namespace);
+  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 = [
@@ -1298,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,
@@ -1314,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,
@@ -1321,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,
@@ -1338,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,4 +1,5 @@
 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";
 
@@ -37,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"]>;
@@ -57,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[];
@@ -86,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;
@@ -738,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): {
@@ -754,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),
   };
 }
 
@@ -798,9 +795,15 @@ 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;
+  // LiteLLM v1.100+ reports `supported_endpoints: null` for every model its model map does not
+  // list, so null means unknown, like an absent field. Only a list without Messages, or a
+  // malformed non-null value, withholds the transport.
   const messagesEndpointAllowed = deployments.every((entry) => {
     const endpoints = entry.model_info?.supported_endpoints;
-    return endpoints === undefined || (Array.isArray(endpoints) && endpoints.includes("/v1/messages"));
+    return endpoints == null || (Array.isArray(endpoints) && endpoints.includes("/v1/messages"));
   });
   const api = candidateModes.every((mode) => mode === "responses")
     ? "openai-responses"
@@ -968,6 +971,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,

package/src/provider.ts

@@ -1,12 +1,15 @@
 import {
+  type AnyModel,
+  type Api,
   type ApiStreamOptions,
-  type Context,
   type Credential,
   createProvider,
+  getCurrentTools,
   type Model,
   type Provider,
   type ProviderAuth,
   type SimpleStreamOptions,
+  type TranscriptContext,
 } from "@earendil-works/pi-ai";
 import { LITELLM_DISCOVERY_VERSION } from "./backend-identity.js";
 import { enrichCachedModel, normalizeBaseUrl, restoreCachedModelPolicy } from "./discover.js";
@@ -26,6 +29,11 @@ export type LiteLLMProviderOptions = {
   discover(credential: Credential, signal?: AbortSignal): Promise<DiscoveryResult & { baseUrl?: string }>;
 };
 
+// Chat models may omit `type`; Pi's `isModelType()` is newer than the peer floor, so keep the check local.
+function isChatModel(model: AnyModel): model is Model<Api> {
+  return (model.type ?? "chat") === "chat";
+}
+
 export function toNativeModels(
   provider: string,
   baseUrl: string,
@@ -112,7 +120,7 @@ function modelRootError(
 function requestModel(
   provider: string,
   model: Model<LiteLLMApi>,
-  context: Context,
+  context: TranscriptContext,
   credentialRoot: string | undefined,
   allowInsecureHttp = false,
 ): Model<LiteLLMApi> {
@@ -120,14 +128,13 @@ function requestModel(
   const active = activeCredentialRoot(credentialRoot, allowInsecureHttp);
   const error = modelRootError(model, active, allowInsecureHttp);
   if (error) throw error;
-  if (
-    model.api === "openai-completions" &&
-    (model as LiteLLMModel).litellmBackendFamily === "openai" &&
-    context.tools &&
-    context.tools.length > CHAT_TOOL_CAP
-  ) {
+  const toolCount =
+    model.api === "openai-completions" && (model as LiteLLMModel).litellmBackendFamily === "openai"
+      ? getCurrentTools(context.messages).length
+      : 0;
+  if (toolCount > CHAT_TOOL_CAP) {
     throw new Error(
-      `LiteLLM model ${model.id} uses Chat Completions with ${context.tools.length} tools, exceeding the ` +
+      `LiteLLM model ${model.id} uses Chat Completions with ${toolCount} tools, exceeding the ` +
         `${CHAT_TOOL_CAP}-tool cap; route this model via Responses or reduce enabled extensions`,
     );
   }
@@ -189,7 +196,7 @@ export function createLiteLLMProvider(options: LiteLLMProviderOptions): Provider
   const refreshModels = provider.refreshModels;
   const guardedProvider: Provider<LiteLLMApi> = {
     ...provider,
-    stream: <T extends LiteLLMApi>(model: Model<T>, context: Context, requestOptions?: ApiStreamOptions<T>) =>
+    stream: <T extends LiteLLMApi>(model: Model<T>, context: TranscriptContext, requestOptions?: ApiStreamOptions<T>) =>
       provider.stream(
         requestModel(
           options.id,
@@ -201,7 +208,7 @@ export function createLiteLLMProvider(options: LiteLLMProviderOptions): Provider
         context,
         requestOptions,
       ),
-    streamSimple: (model: Model<LiteLLMApi>, context: Context, requestOptions?: SimpleStreamOptions) =>
+    streamSimple: (model: Model<LiteLLMApi>, context: TranscriptContext, requestOptions?: SimpleStreamOptions) =>
       provider.streamSimple(
         requestModel(
           options.id,
@@ -215,13 +222,21 @@ export function createLiteLLMProvider(options: LiteLLMProviderOptions): Provider
       ),
   };
   if (!refreshModels) return guardedProvider;
+  const seedKey = (model: { id: string; baseUrl: string }) => `${model.id}\0${model.baseUrl}`;
+  const seeded = new Map((options.models ?? []).map((model) => [seedKey(model), model]));
   return {
     ...guardedProvider,
     refreshModels: async (context) => {
-      const storedModels = context.stored?.models ?? [];
+      // Pi 0.99 persists models of every type; this provider only publishes chat models, and the
+      // policy helpers below read chat-only fields.
+      const storedModels = (context.stored?.models ?? []).filter(isChatModel);
       let legacyCount = 0;
       const models = storedModels.map((model) => {
         if ((model as LiteLLMModel).litellmDiscoveryVersion !== LITELLM_DISCOVERY_VERSION) {
+          // Pi applies stored models over the seed, so a stale entry would otherwise mask what
+          // startup discovery just proved for the same route.
+          const fresh = seeded.get(seedKey(model));
+          if (fresh) return fresh;
           legacyCount++;
           return restoreCachedModelPolicy(model);
         }

package/src/proxy-version.ts

@@ -0,0 +1,68 @@
+import type { DiscoveryOptions } from "./types.js";
+
+export interface ProxyVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  // Any suffix (rc, dev, post, local build). It orders before the release it names,
+  // so a pre-release never claims a fix that only the release is known to carry.
+  prerelease: boolean;
+}
+
+export type ProxyVersionFloor = readonly [major: number, minor: number, patch: number];
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_VERSION_LENGTH = 64;
+const VERSION_PATTERN = /^v?(\d{1,5})\.(\d{1,5})\.(\d{1,5})(.*)$/s;
+const VERSION_HEADER = "x-litellm-version";
+// LiteLLM stamps its version on inference routes only; `/model/info`, `/v1/models`
+// and `/health/*` do not carry it. A made-up Responses id names no deployment, so
+// the read is answered with an error that still carries the header and calls no model.
+const VERSION_PROBE_PATH = "/v1/responses/resp_version_probe";
+
+// The value is proxy-supplied: bound it before matching and keep only the numbers.
+export function parseProxyVersion(value: unknown): ProxyVersion | undefined {
+  if (typeof value !== "string" || value.length > MAX_VERSION_LENGTH) return undefined;
+  const match = VERSION_PATTERN.exec(value.trim());
+  if (!match) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== "",
+  };
+}
+
+// An unknown version satisfies no floor, so a version-gated workaround stays on
+// whenever the proxy does not say what it is.
+export function proxyVersionAtLeast(version: ProxyVersion | undefined, floor: ProxyVersionFloor): boolean {
+  if (!version) return false;
+  const actual = [version.major, version.minor, version.patch];
+  for (const [index, required] of floor.entries()) {
+    if (actual[index] !== required) return actual[index]! > required;
+  }
+  return !version.prerelease;
+}
+
+// Best effort by design: the header rides on an error path LiteLLM does not
+// document, so a missing header, an unreachable proxy or a timeout all mean
+// "unknown" and never fail discovery.
+export async function probeProxyVersion(
+  base: string,
+  apiKey: string,
+  options: Pick<DiscoveryOptions, "timeoutMs" | "signal" | "headers">,
+): Promise<ProxyVersion | undefined> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  try {
+    const response = await fetch(`${base}${VERSION_PROBE_PATH}`, {
+      headers: { ...options.headers, Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      signal: options.signal
+        ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)])
+        : AbortSignal.timeout(timeoutMs),
+    });
+    await response.body?.cancel().catch(() => undefined);
+    return parseProxyVersion(response.headers.get(VERSION_HEADER));
+  } catch {
+    return undefined;
+  }
+}

package/src/skills.ts

@@ -169,6 +169,10 @@ function parseJsonObject(value: string, fieldName: string): Record<string, unkno
   return parsed as Record<string, unknown>;
 }
 
+// Pi 0.99 groups tools by namespace and lets permission extensions read annotation hints; older
+// Pi ignores both fields.
+const SKILLS_NAMESPACE = { name: "litellm_skills", description: "LiteLLM Skills Gateway" };
+
 export function createSkillToolDefinitions(
   getAuth: (ctx?: ExtensionContext) => Promise<LiteLLMRuntimeAuth>,
 ): ToolDefinition[] {
@@ -178,6 +182,8 @@ export function createSkillToolDefinitions(
       label: "LiteLLM Skills",
       description: "List skills registered on the LiteLLM proxy Skills Gateway.",
       promptSnippet: "List LiteLLM Skills Gateway skills",
+      namespace: SKILLS_NAMESPACE,
+      annotations: { readOnlyHint: true, openWorldHint: false },
       parameters: Type.Object({}),
       async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
         const auth = await getAuth(ctx);
@@ -189,6 +195,8 @@ export function createSkillToolDefinitions(
       name: "litellm_skill_create",
       label: "Create LiteLLM Skill",
       description: "Create and enable a skill on the LiteLLM proxy Skill Hub from source metadata.",
+      namespace: SKILLS_NAMESPACE,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       parameters: CreateSkillParams,
       async execute(_toolCallId, params: Static<typeof CreateSkillParams>, _signal, _onUpdate, ctx) {
         const auth = await getAuth(ctx);
@@ -207,6 +215,8 @@ export function createSkillToolDefinitions(
       name: "litellm_skill_delete",
       label: "Delete LiteLLM Skill",
       description: "Delete a skill from the LiteLLM proxy Skills Gateway.",
+      namespace: SKILLS_NAMESPACE,
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
       parameters: DeleteSkillParams,
       async execute(_toolCallId, params: Static<typeof DeleteSkillParams>, _signal, _onUpdate, ctx) {
         const auth = await getAuth(ctx);