pi-provider-litellm 3.1.0 → 3.3.0

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/public-catalog.ts

@@ -73,6 +73,7 @@ const PROVIDER_ALIASES: Readonly<Record<string, readonly string[]>> = {
 const PI_PROVIDER_ALIASES: Readonly<Record<string, readonly string[]>> = {
   "amazon-bedrock": ["amazon-bedrock"],
   azure: ["azure-openai-responses"],
+  azure_ai: ["azure-openai-responses"],
   chatgpt: ["openai-codex"],
   "fireworks-ai": ["fireworks"],
   openai: ["openai"],
@@ -245,6 +246,7 @@ export async function loadPublicCatalog(options: LoadPublicCatalogOptions = {}):
       const providers = providerCandidates(provider);
       const ids = lookupIds(id);
       const vendor = providers.find((candidate) => candidate !== "azure") ?? providers[0];
+      const adapter = provider?.trim().toLowerCase();
       for (const candidate of providers) {
         const models = catalog?.[candidate]?.models;
         for (const modelId of ids) {
@@ -252,20 +254,25 @@ export async function loadPublicCatalog(options: LoadPublicCatalogOptions = {}):
           if (!model) continue;
           const record = mapModelsDev(candidate, modelId, model);
           if (candidate === providers[0] || !vendor) return record;
-          return { ...record, piProvider: (PI_PROVIDER_ALIASES[vendor] ?? [vendor])[0] };
+          const fallback =
+            adapter && (PI_PROVIDER_ALIASES[adapter] ?? [adapter]).some((piProvider) => findPiModel(piProvider, ids))
+              ? adapter
+              : vendor;
+          return { ...record, piProvider: (PI_PROVIDER_ALIASES[fallback] ?? [fallback])[0] };
         }
       }
-      if (vendor) {
-        for (const piProvider of PI_PROVIDER_ALIASES[vendor] ?? [vendor]) {
+      // Provider-specific limits and pricing must not be replaced by the generic
+      // vendor's entry just because both catalogs recognize the model id.
+      if (adapter && adapter !== vendor) {
+        for (const piProvider of PI_PROVIDER_ALIASES[adapter] ?? [adapter]) {
           const model = findPiModel(piProvider, ids);
-          if (model) return toPiRecord("pi-vendor", piProvider, model);
+          if (model) return toPiRecord("pi-adapter", piProvider, model);
         }
       }
-      const adapter = provider?.trim().toLowerCase();
-      if (adapter) {
-        for (const piProvider of PI_PROVIDER_ALIASES[adapter] ?? [adapter]) {
+      if (vendor) {
+        for (const piProvider of PI_PROVIDER_ALIASES[vendor] ?? [vendor]) {
           const model = findPiModel(piProvider, ids);
-          if (model) return toPiRecord("pi-adapter", piProvider, model);
+          if (model) return toPiRecord("pi-vendor", piProvider, model);
         }
       }
       return undefined;

package/src/skills.ts

@@ -42,97 +42,55 @@ export async function listSkills(
     return skillsCache.skills;
   }
 
-  const fetchSkills = async (path: string): Promise<LiteLLMSkill[]> => {
+  const fetchSkills = async (path: string): Promise<LiteLLMSkill[] | undefined> => {
     try {
       const response = await fetch(`${normalizedBaseUrl}${path}`, {
         headers: { ...headers, Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
         signal: AbortSignal.timeout(10_000),
       });
-      return response.ok ? getSkillsFromBody(await response.json()) : [];
+      return response.ok ? getSkillsFromBody(await response.json()) : undefined;
     } catch {
-      return [];
+      return undefined;
     }
   };
 
-  const [skillHub, legacy] = await Promise.all([
-    fetchSkills("/claude-code/marketplace.json"),
-    fetchSkills("/v1/skills"),
-  ]);
-  const skillHubNames = new Set(skillHub.map((skill) => skill.name));
-  const skills = [...skillHub, ...legacy.filter((skill) => !skillHubNames.has(skill.name))];
+  const skills = (await fetchSkills("/claude-code/marketplace.json")) ?? (await fetchSkills("/v1/skills")) ?? [];
   skillsCache = { baseUrl: normalizedBaseUrl, apiKey, fetchedAt: Date.now(), skills };
   return skills;
 }
 
+// Only the Skill Hub creates skills from JSON. LiteLLM's POST /v1/skills is Anthropic's multipart
+// Skills API, so a JSON code skill sent there never becomes a listable skill.
 export async function createSkill(
   baseUrl: string,
   apiKey: string,
-  input: {
-    name: string;
-    description?: string;
-    source?: Record<string, unknown>;
-    code?: string;
-    inputSchema?: Record<string, unknown>;
-  },
+  input: { name: string; description?: string; source: Record<string, unknown> },
   headers?: Record<string, string>,
   allowInsecureHttp = false,
 ): Promise<unknown> {
-  if (!input.source && !input.code) throw new Error("code is required when source is omitted");
+  if (!input.source) throw new Error("source is required: skills are created through the LiteLLM Skill Hub");
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl, allowInsecureHttp);
-  let usedSkillHub = input.source !== undefined;
-  const skillHubPayload = input.source
-    ? {
-        name: input.name,
-        description: input.description,
-        source: input.source,
-      }
-    : {
-        name: input.name,
-        description: input.description,
-        code: input.code,
-        input_schema: input.inputSchema ?? { type: "object", properties: {} },
-      };
-  let response = await fetch(`${normalizedBaseUrl}${input.source ? "/claude-code/plugins" : "/v1/skills"}`, {
+  const response = await fetch(`${normalizedBaseUrl}/claude-code/plugins`, {
     method: "POST",
     headers: {
       ...headers,
       Authorization: `Bearer ${apiKey}`,
       "Content-Type": "application/json",
     },
-    body: JSON.stringify(skillHubPayload),
+    body: JSON.stringify({ name: input.name, description: input.description, source: input.source }),
     signal: AbortSignal.timeout(10_000),
   });
-  if (input.source && response.status === 404) {
-    usedSkillHub = false;
-    response = await fetch(`${normalizedBaseUrl}/v1/skills`, {
-      method: "POST",
-      headers: {
-        ...headers,
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        name: input.name,
-        description: input.description,
-        code: input.code,
-        input_schema: input.inputSchema ?? { type: "object", properties: {} },
-      }),
-      signal: AbortSignal.timeout(10_000),
-    });
-  }
   if (!response.ok) throw new Error(`LiteLLM skill create failed: HTTP ${response.status}`);
   skillsCache = undefined;
-  if (usedSkillHub) {
-    const enableResponse = await fetch(
-      `${normalizedBaseUrl}/claude-code/plugins/${encodeURIComponent(input.name)}/enable`,
-      {
-        method: "POST",
-        headers: { ...headers, Authorization: `Bearer ${apiKey}` },
-        signal: AbortSignal.timeout(10_000),
-      },
-    );
-    if (!enableResponse.ok) throw new Error(`LiteLLM skill enable failed: HTTP ${enableResponse.status}`);
-  }
+  const enableResponse = await fetch(
+    `${normalizedBaseUrl}/claude-code/plugins/${encodeURIComponent(input.name)}/enable`,
+    {
+      method: "POST",
+      headers: { ...headers, Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+  if (!enableResponse.ok) throw new Error(`LiteLLM skill enable failed: HTTP ${enableResponse.status}`);
   return response.json().catch(() => ({}));
 }
 
@@ -196,9 +154,7 @@ function formatSkills(skills: LiteLLMSkill[]): string {
 const CreateSkillParams = Type.Object({
   name: Type.String({ description: "Skill name" }),
   description: Type.Optional(Type.String({ description: "Skill description" })),
-  sourceJson: Type.Optional(Type.String({ description: "Optional Skill Hub source metadata JSON object" })),
-  code: Type.Optional(Type.String({ description: "Legacy Skills Gateway implementation or prompt code" })),
-  inputSchemaJson: Type.Optional(Type.String({ description: "Optional JSON Schema string for skill inputs" })),
+  sourceJson: Type.String({ description: "Skill Hub source metadata JSON object" }),
 });
 
 const DeleteSkillParams = Type.Object({
@@ -213,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[] {
@@ -222,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);
@@ -232,24 +194,17 @@ export function createSkillToolDefinitions(
     defineTool({
       name: "litellm_skill_create",
       label: "Create LiteLLM Skill",
-      description: "Create a skill on the LiteLLM proxy Skills Gateway.",
+      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);
-        const source = params.sourceJson ? parseJsonObject(params.sourceJson, "sourceJson") : undefined;
-        const inputSchema = params.inputSchemaJson
-          ? parseJsonObject(params.inputSchemaJson, "inputSchemaJson")
-          : undefined;
+        const source = parseJsonObject(params.sourceJson, "sourceJson");
         const result = await createSkill(
           auth.baseUrl,
           auth.apiKey,
-          {
-            name: params.name,
-            description: params.description,
-            source,
-            code: params.code,
-            inputSchema,
-          },
+          { name: params.name, description: params.description, source },
           auth.headers,
           auth.allowInsecureHttp,
         );
@@ -260,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);

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { BackendFamily, LITELLM_DISCOVERY_VERSION } from "./backend-identity.js";
+import type { ProxyVersion } from "./proxy-version.js";
 
 export type DiscoverySource = "model_info" | "models_list" | "health";
 
@@ -56,6 +57,9 @@ export type LiteLLMModel = Model<LiteLLMApi> & {
 export interface DiscoveryResult {
   models: DiscoveredModel[];
   source: DiscoverySource;
+  // Present only when a `/model/info` discovery had to read it and the proxy
+  // answered. Absent means unknown, not old: discovery asks only when it must.
+  proxyVersion?: ProxyVersion;
 }
 
 export interface DiscoveryOptions {
@@ -138,6 +142,14 @@ export interface ResolvedCredentials {
   apiKeyFromGcloudAdc?: boolean;
 }
 
+// The boolean MCP tool annotation hints, with the meaning Pi gives `ToolAnnotations`.
+export interface McpToolAnnotations {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+}
+
 export interface LiteLLMMcpTool {
   name: string;
   server_name: string;
@@ -147,6 +159,10 @@ export interface LiteLLMMcpTool {
   input_schema: Record<string, unknown>;
   // True when the proxy supplied an `inputSchema`/`input_schema` that was not a JSON object.
   input_schema_malformed?: boolean;
+  // Boolean hints from the proxy-supplied `annotations`; every other annotation field is dropped.
+  annotations?: McpToolAnnotations;
+  // `mcp_info.description` of the server, when the proxy supplies one.
+  server_description?: string;
 }
 
 export interface LiteLLMSkill {