pi-provider-litellm 2.3.0 → 3.0.0

package/src/skills.ts

@@ -0,0 +1,275 @@
+import type { Static } 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 { normalizeBaseUrl } from "./discover.js";
+import type { LiteLLMRuntimeAuth, LiteLLMSkill } from "./types.js";
+
+const SKILLS_CACHE_TTL_MS = 60_000;
+
+let skillsCache:
+  | {
+      baseUrl: string;
+      apiKey: string;
+      fetchedAt: number;
+      skills: LiteLLMSkill[];
+    }
+  | undefined;
+
+function getSkillsFromBody(body: unknown): LiteLLMSkill[] {
+  if (Array.isArray(body)) return body as LiteLLMSkill[];
+  if (body && typeof body === "object") {
+    const record = body as { plugins?: unknown; data?: unknown; skills?: unknown };
+    if (Array.isArray(record.plugins)) return record.plugins as LiteLLMSkill[];
+    if (Array.isArray(record.data)) return record.data as LiteLLMSkill[];
+    if (Array.isArray(record.skills)) return record.skills as LiteLLMSkill[];
+  }
+  return [];
+}
+
+export async function listSkills(
+  baseUrl: string,
+  apiKey: string,
+  headers?: Record<string, string>,
+  allowInsecureHttp = false,
+): Promise<LiteLLMSkill[]> {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl, allowInsecureHttp);
+  if (
+    skillsCache &&
+    skillsCache.baseUrl === normalizedBaseUrl &&
+    skillsCache.apiKey === apiKey &&
+    Date.now() - skillsCache.fetchedAt < SKILLS_CACHE_TTL_MS
+  ) {
+    return skillsCache.skills;
+  }
+
+  const fetchSkills = async (path: string): Promise<LiteLLMSkill[]> => {
+    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()) : [];
+    } catch {
+      return [];
+    }
+  };
+
+  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))];
+  skillsCache = { baseUrl: normalizedBaseUrl, apiKey, fetchedAt: Date.now(), skills };
+  return skills;
+}
+
+export async function createSkill(
+  baseUrl: string,
+  apiKey: string,
+  input: {
+    name: string;
+    description?: string;
+    source?: Record<string, unknown>;
+    code?: string;
+    inputSchema?: 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");
+  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"}`, {
+    method: "POST",
+    headers: {
+      ...headers,
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(skillHubPayload),
+    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}`);
+  }
+  return response.json().catch(() => ({}));
+}
+
+export async function deleteSkill(
+  baseUrl: string,
+  apiKey: string,
+  skillId: string,
+  headers?: Record<string, string>,
+  allowInsecureHttp = false,
+): Promise<void> {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl, allowInsecureHttp);
+  let skillHubError: unknown;
+  const skillHubResponse = await fetch(`${normalizedBaseUrl}/claude-code/plugins/${encodeURIComponent(skillId)}`, {
+    method: "DELETE",
+    headers: { ...headers, Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+    signal: AbortSignal.timeout(10_000),
+  }).catch((error: unknown) => {
+    skillHubError = error;
+    return undefined;
+  });
+  let response = skillHubResponse;
+  if (!response || response.status === 404 || response.status >= 500) {
+    response = await fetch(`${normalizedBaseUrl}/v1/skills/${encodeURIComponent(skillId)}`, {
+      method: "DELETE",
+      headers: { ...headers, Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+  }
+  if (response.status === 404 && skillHubResponse?.status !== 404) {
+    if (skillHubError instanceof Error) throw skillHubError;
+    throw new Error(`LiteLLM skill delete failed: HTTP ${skillHubResponse?.status}`);
+  }
+  if (!response.ok && response.status !== 404) throw new Error(`LiteLLM skill delete failed: HTTP ${response.status}`);
+  skillsCache = undefined;
+}
+
+function escapeXml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+
+export function createSkillsPromptSection(skills: LiteLLMSkill[]): string | undefined {
+  const enabled = skills.filter((skill) => skill.enabled !== false && skill.name);
+  if (enabled.length === 0) return undefined;
+
+  const body = enabled
+    .map((skill) => {
+      const description = skill.description?.trim() || "No description provided.";
+      return `<skill name="${escapeXml(skill.name)}">\n${escapeXml(description)}\n</skill>`;
+    })
+    .join("\n");
+  return `LiteLLM Skills Gateway provided these active skills. Use them as additional guidance when relevant.\n<litellm_skills>\n${body}\n</litellm_skills>`;
+}
+
+function formatSkills(skills: LiteLLMSkill[]): string {
+  if (skills.length === 0) return "No LiteLLM skills are registered.";
+  return skills
+    .map((skill) => `- ${skill.name}${skill.enabled === false ? " (disabled)" : ""}: ${skill.description ?? ""}`)
+    .join("\n");
+}
+
+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" })),
+});
+
+const DeleteSkillParams = Type.Object({
+  skillId: Type.String({ description: "LiteLLM skill id" }),
+});
+
+function parseJsonObject(value: string, fieldName: string): Record<string, unknown> {
+  const parsed = JSON.parse(value) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${fieldName} must be a JSON object`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function createSkillToolDefinitions(
+  getAuth: (ctx?: ExtensionContext) => Promise<LiteLLMRuntimeAuth>,
+): ToolDefinition[] {
+  return [
+    defineTool({
+      name: "litellm_skill_list",
+      label: "LiteLLM Skills",
+      description: "List skills registered on the LiteLLM proxy Skills Gateway.",
+      promptSnippet: "List LiteLLM Skills Gateway skills",
+      parameters: Type.Object({}),
+      async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+        const auth = await getAuth(ctx);
+        const skills = await listSkills(auth.baseUrl, auth.apiKey, auth.headers, auth.allowInsecureHttp);
+        return { content: [{ type: "text", text: formatSkills(skills) }], details: { count: skills.length } };
+      },
+    }),
+    defineTool({
+      name: "litellm_skill_create",
+      label: "Create LiteLLM Skill",
+      description: "Create a skill on the LiteLLM proxy Skills Gateway.",
+      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 result = await createSkill(
+          auth.baseUrl,
+          auth.apiKey,
+          {
+            name: params.name,
+            description: params.description,
+            source,
+            code: params.code,
+            inputSchema,
+          },
+          auth.headers,
+          auth.allowInsecureHttp,
+        );
+        return { content: [{ type: "text", text: "LiteLLM skill created." }], details: { result } };
+      },
+    }),
+    defineTool({
+      name: "litellm_skill_delete",
+      label: "Delete LiteLLM Skill",
+      description: "Delete a skill from the LiteLLM proxy Skills Gateway.",
+      parameters: DeleteSkillParams,
+      async execute(_toolCallId, params: Static<typeof DeleteSkillParams>, _signal, _onUpdate, ctx) {
+        const auth = await getAuth(ctx);
+        await deleteSkill(auth.baseUrl, auth.apiKey, params.skillId, auth.headers, auth.allowInsecureHttp);
+        return { content: [{ type: "text", text: `LiteLLM skill deleted: ${params.skillId}` }], details: {} };
+      },
+    }),
+  ];
+}
+
+export function resetSkillsCache(): void {
+  skillsCache = undefined;
+}

package/src/thinking-levels.ts

@@ -0,0 +1,35 @@
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { DiscoveredModel } from "./types.js";
+
+export const THINKING_LEVEL_DEFINITIONS = [
+  ["off", "none", "supports_none_reasoning_effort"],
+  ["minimal", "minimal", "supports_minimal_reasoning_effort"],
+  ["low", "low", "supports_low_reasoning_effort"],
+  ["medium", "medium", undefined],
+  ["high", "high", undefined],
+  ["xhigh", "xhigh", "supports_xhigh_reasoning_effort"],
+  ["max", "max", "supports_max_reasoning_effort"],
+] as const;
+
+type AssertNever<T extends never> = T;
+// biome-ignore lint/correctness/noUnusedVariables: This assertion must fail if Pi adds an uncovered thinking level.
+type ThinkingLevelDefinitionsAreExhaustive = AssertNever<
+  Exclude<ModelThinkingLevel, (typeof THINKING_LEVEL_DEFINITIONS)[number][0]>
+>;
+
+type ThinkingLevelMap = DiscoveredModel["thinkingLevelMap"];
+
+// Intersects independently authoritative maps. A level mentioned by any source
+// is denied unless every source supplies the same mapping for that level.
+export function intersectThinkingLevelMaps(maps: readonly ThinkingLevelMap[]): ThinkingLevelMap {
+  if (maps.every((map) => map === undefined)) return undefined;
+
+  const intersection: NonNullable<ThinkingLevelMap> = {};
+  for (const [level] of THINKING_LEVEL_DEFINITIONS) {
+    const values = maps.map((map) => map?.[level]);
+    if (values.every((value) => value === undefined)) continue;
+    const first = values[0];
+    intersection[level] = first !== undefined && values.every((value) => value === first) ? first : null;
+  }
+  return Object.keys(intersection).length > 0 ? intersection : undefined;
+}

package/src/types.ts

@@ -0,0 +1,162 @@
+import type { Model } from "@earendil-works/pi-ai";
+import type { BackendFamily, LITELLM_DISCOVERY_VERSION } from "./backend-identity.js";
+
+export type DiscoverySource = "model_info" | "models_list" | "health";
+
+export type LiteLLMApi = "anthropic-messages" | "openai-completions" | "openai-responses";
+
+export type LiteLLMRuntimeAuth = {
+  baseUrl: string;
+  apiKey: string;
+  headers?: Record<string, string>;
+  allowInsecureHttp?: boolean;
+};
+
+export interface LiteLLMModelPolicy {
+  // Moonshot/Kimi's strict schema requires assistant tool calls to carry string
+  // content. Discovery enables this outbound rewrite only from deployment evidence.
+  normalizeStrictToolMessages: boolean;
+  // Moonshot routes can inline reasoning as `<think>` text in the visible
+  // answer. Whether to unwrap it is a per-model conclusion discovery reaches
+  // from deployment evidence, carried here so the `message_end` hook does not
+  // re-derive it from the route name.
+  normalizeThinkTags: boolean;
+  // Hide duplicate visible reasoning only for deployment-evidenced Kimi routes
+  // that do not use an always-thinking generation.
+  suppressReasoningVisibility: boolean;
+  // Gemini-backed deployments require lowercase effort values. Discovery carries
+  // this evidence so the request hook does not infer a backend from the route name.
+  normalizeGeminiReasoningEffort?: boolean;
+}
+
+export type DiscoveredModelFor<TApi extends LiteLLMApi> = Omit<Model<TApi>, "provider" | "baseUrl"> & {
+  suppressReasoningContent?: boolean;
+  litellmPolicy?: LiteLLMModelPolicy;
+  litellmResponsesReasoningControl?: true;
+  litellmBackendFamily?: BackendFamily;
+  litellmDiscoveryVersion?: typeof LITELLM_DISCOVERY_VERSION;
+};
+
+export type DiscoveredModel = {
+  [TApi in LiteLLMApi]: DiscoveredModelFor<TApi>;
+}[LiteLLMApi];
+
+export type ModelProtocol = {
+  [TApi in LiteLLMApi]: Pick<DiscoveredModelFor<TApi>, "api" | "compat">;
+}[LiteLLMApi];
+
+export type LiteLLMModel = Model<LiteLLMApi> & {
+  suppressReasoningContent?: boolean;
+  litellmPolicy?: LiteLLMModelPolicy;
+  litellmResponsesReasoningControl?: true;
+  litellmBackendFamily?: BackendFamily;
+  litellmDiscoveryVersion?: typeof LITELLM_DISCOVERY_VERSION;
+};
+
+export interface DiscoveryResult {
+  models: DiscoveredModel[];
+  source: DiscoverySource;
+}
+
+export interface DiscoveryOptions {
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  headers?: Record<string, string>;
+  allowInsecureHttp?: boolean;
+  modelsDev?: boolean;
+  modelsDevCachePath?: string;
+}
+
+export interface ModelInfoEntry {
+  model_name?: string;
+  litellm_params?: {
+    model?: string;
+    custom_llm_provider?: string;
+    api_version?: string;
+    allowed_openai_params?: string[];
+  };
+  model_info?: {
+    id?: string;
+    mode?: string | null;
+    base_model?: string;
+    litellm_provider?: string;
+    supported_endpoints?: string[];
+    supported_openai_params?: string[];
+    input_cost_per_token?: number;
+    output_cost_per_token?: number;
+    cache_read_input_token_cost?: number;
+    cache_creation_input_token_cost?: number;
+    max_input_tokens?: number;
+    max_output_tokens?: number;
+    supports_reasoning?: boolean;
+    supports_none_reasoning_effort?: boolean;
+    supports_minimal_reasoning_effort?: boolean;
+    supports_low_reasoning_effort?: boolean;
+    supports_xhigh_reasoning_effort?: boolean;
+    supports_max_reasoning_effort?: boolean;
+    supports_vision?: boolean;
+  };
+}
+
+export interface ModelInfoResponse {
+  data?: ModelInfoEntry[];
+}
+
+export interface HealthModelEntry {
+  model?: string;
+  model_id?: string;
+  api_base?: string;
+}
+
+export interface HealthResponse {
+  healthy_endpoints?: HealthModelEntry[];
+}
+
+export interface ModelsListEntry {
+  id?: string;
+  owned_by?: string;
+}
+
+export interface ModelsListResponse {
+  data?: ModelsListEntry[];
+}
+
+export type AuthFileEntry =
+  | { type: "oauth"; access: string; refresh: string; expires: number; baseUrl?: string }
+  | { type: "api_key"; key: string };
+
+export interface ResolvedCredentials {
+  baseUrl?: string;
+  apiKey?: string;
+  apiKeyConfig?: string;
+  // `apiKey` was minted from Google ADC rather than config, helper, or env.
+  apiKeyFromGcloudAdc?: boolean;
+}
+
+export interface LiteLLMMcpTool {
+  name: string;
+  server_name: string;
+  server_id?: string;
+  description: string;
+  // Absent or `{}` means the proxy supplied no schema; both use the extension-owned envelope.
+  input_schema: Record<string, unknown>;
+  // True when the proxy supplied an `inputSchema`/`input_schema` that was not a JSON object.
+  input_schema_malformed?: boolean;
+}
+
+export interface LiteLLMSkill {
+  id?: string;
+  name: string;
+  description?: string;
+  enabled?: boolean;
+  source?: Record<string, unknown>;
+  version?: string;
+  keywords?: string[];
+  domain?: string;
+  namespace?: string;
+  category?: string;
+  author?: string;
+  homepage?: string;
+  input_schema?: Record<string, unknown>;
+  code?: string;
+}

package/dist/cost.d.ts

@@ -1,2 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export declare function setupLiteLLMCostTracking(pi: ExtensionAPI, providerNames: string[]): void;

package/dist/cost.js

@@ -1,49 +0,0 @@
-export function setupLiteLLMCostTracking(pi, providerNames) {
-    const knownProviders = new Set(providerNames);
-    // Keyed by provider: with multiple LiteLLM providers active, overlapping
-    // requests interleave, so a single shared slot lets one provider's response
-    // (or a headerless one clearing it) clobber another's pending cost.
-    const pendingResponseCosts = new Map();
-    pi.on("after_provider_response", (event, ctx) => {
-        // Global Pi hook: responses from other providers must not feed LiteLLM cost state.
-        if (!ctx.model?.provider || !knownProviders.has(ctx.model.provider))
-            return;
-        const costHeader = event.headers?.["x-litellm-response-cost"] ?? event.headers?.["X-Litellm-Response-Cost"];
-        if (costHeader) {
-            const cost = Number.parseFloat(String(costHeader));
-            if (!Number.isNaN(cost)) {
-                pendingResponseCosts.set(ctx.model.provider, cost);
-                return;
-            }
-        }
-        pendingResponseCosts.delete(ctx.model.provider);
-    });
-    pi.on("message_end", async (event) => {
-        if (event.message.role !== "assistant" || !knownProviders.has(event.message.provider))
-            return;
-        const usage = event.message.usage;
-        if (!usage)
-            return;
-        const totalCost = pendingResponseCosts.get(event.message.provider);
-        if (totalCost === undefined)
-            return;
-        pendingResponseCosts.delete(event.message.provider);
-        const totalTokens = usage.input + usage.output + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
-        const fraction = (tokens) => (totalTokens > 0 ? tokens / totalTokens : 0);
-        return {
-            message: {
-                ...event.message,
-                usage: {
-                    ...usage,
-                    cost: {
-                        input: totalCost * fraction(usage.input),
-                        output: totalCost * fraction(usage.output),
-                        cacheRead: totalCost * fraction(usage.cacheRead ?? 0),
-                        cacheWrite: totalCost * fraction(usage.cacheWrite ?? 0),
-                        total: totalCost,
-                    },
-                },
-            },
-        };
-    });
-}

package/dist/discover.d.ts

@@ -1,12 +0,0 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
-import type { DiscoveredModel, DiscoveryOptions, DiscoveryResult } from "./types.js";
-export declare function normalizeBaseUrl(input: string, allowInsecureHttp?: boolean): string;
-export declare function isMoonshotModel(modelId: string): boolean;
-export declare function isGpt55Model(modelId: string): boolean;
-export declare function emitsThinkTags(modelId: string): boolean;
-export declare function buildCompat(modelId: string): DiscoveredModel["compat"];
-export declare function enrichCachedModel(model: Model<Api>): Model<Api>;
-export declare function discoverModels(baseUrl: string, apiKey: string, options?: DiscoveryOptions & {
-    onProgress?: (message: string) => void;
-    silent?: boolean;
-}): Promise<DiscoveryResult>;