@tryinget/pi-model-selection 0.1.0

package/LICENSE

@@ -0,0 +1,78 @@
+MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
+
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
+
+This rider is part of the "conditions" of this License. In the event of any
+conflict between this rider and any other portion of this License, this rider
+controls.
+
+"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
+following PRC frontier AI labs and related entities: Baidu (including ERNIE-
+related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
+Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
+related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
+(Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
+respective Affiliates and any person or entity acting directly or indirectly
+on behalf of, for the benefit of, or under the direction of any of the
+foregoing (including any officer, director, employee, contractor, agent,
+consultant, service provider, or representative).
+
+Notwithstanding any other provision of this License, no rights are granted to
+any Restricted Party. Any purported license, sublicense, assignment, transfer,
+or other permission to any Restricted Party is null and void absent the
+express prior written permission of the copyright holders.
+
+You may not provide, disclose, distribute, sublicense, sell, lease, lend,
+host, make available, or otherwise permit access to the Software or any
+derivative work of the Software (as defined in applicable copyright law)
+(collectively, "Derivative Works") to or for any Restricted Party.
+
+For purposes of this rider, "use" includes, without limitation: copying,
+modifying, merging, publishing, distributing, sublicensing, selling,
+transferring, making available, hosting, deploying, executing, benchmarking,
+testing, analyzing, indexing, or incorporating the Software or any Derivative
+Works into any dataset, training corpus, evaluation harness, or pipeline for
+machine learning or other automated systems.
+
+This rider applies to the Software and all Derivative Works. As a condition of
+use, you agree that this rider is a precondition to exercising any rights
+under this License, and you agree that any distribution of the Software or any
+Derivative Works must include this rider provision unmodified.
+
+Any breach of this rider automatically and immediately terminates the
+permissions granted by this License. Upon termination, you must immediately
+cease all use and distribution of the Software and any Derivative Works and
+destroy all copies under your control.
+
+You agree that a breach of this rider would cause irreparable harm and that
+the copyright holders may seek injunctive or other equitable relief to enforce
+this rider, in addition to any other remedies available at law. To the maximum
+extent permitted by applicable law, the prevailing party in any action to
+enforce this rider shall be entitled to recover reasonable attorneys' fees and
+costs.
+
+For purposes of this rider, "Affiliate" means any entity that directly or
+indirectly controls, is controlled by, or is under common control with the
+specified party. "Control" means ownership of more than 50% of the voting
+securities or other ownership interest, or the power to direct management or
+policies by contract or otherwise.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+---
+summary: "@tryinget/pi-model-selection package overview."
+read_when:
+  - "Orienting to this package or directory before changing its behavior."
+---
+
+# @tryinget/pi-model-selection
+
+Shared Pi model-selection and auth-resolution primitives.
+
+This is a top-level support package at `packages/pi-model-selection`, not a `pi-interaction` subpackage. Consumers should depend on `@tryinget/pi-model-selection` directly rather than depending on `@tryinget/pi-interaction` for model-selection helpers.
+
+This package owns prompt-template-model-compatible model resolver semantics that are needed by more than one extension:
+
+- exact `modelId`
+- exact `provider/modelId`
+- comma-separated fallback lists
+- current-model preservation when the active model matches any candidate
+- provider-priority ordering for ambiguous bare model IDs:
+  1. `openai-codex`
+  2. `anthropic`
+  3. `github-copilot`
+  4. `openrouter`
+- auth-aware selection via `getAvailable()`, `isUsingOAuth()`, `getApiKey()`, and `getApiKeyAndHeaders()`
+- preservation of model-level `headers`
+
+It intentionally does not own prompt-template slash-command registration, compaction preset parsing, loops/workflows, or subagent execution.
+
+## Template baseline
+
+This package was reconciled through `../pi-extensions-template` in `simple-package` mode, then intentionally adapted as a root-managed support library. It keeps template lineage and baseline files such as `.copier-answers.yml`, `biome.jsonc`, `policy/stack-lane.json`, and `docs/tech-stack.local.md`, but it deliberately omits `package.json#pi.extensions` and `package.json#pi.prompts` so it cannot register slash commands or package prompts by accident.

package/index.d.ts

@@ -0,0 +1,58 @@
+export interface PiModelLike {
+  id?: string;
+  provider?: string;
+  headers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface PiModelRegistryLike {
+  find?(provider: string, modelId: string): PiModelLike | undefined;
+  getAll?(): PiModelLike[];
+  getAvailable?(): PiModelLike[];
+  isUsingOAuth?(model: PiModelLike): boolean;
+  getApiKey?(model: PiModelLike): Promise<string | undefined> | string | undefined;
+  getApiKeyAndHeaders?(
+    model: PiModelLike,
+  ):
+    | Promise<{ ok?: boolean; apiKey?: string; headers?: Record<string, unknown>; error?: string }>
+    | { ok?: boolean; apiKey?: string; headers?: Record<string, unknown>; error?: string };
+}
+
+export interface PiModelSelectionContext {
+  model?: PiModelLike;
+  modelRegistry?: PiModelRegistryLike;
+}
+
+export interface SelectedModelCandidate {
+  model: PiModelLike;
+  alreadyActive: boolean;
+}
+
+export interface ResolvedModelAuth {
+  ok: boolean;
+  apiKey?: string;
+  headers?: Record<string, unknown>;
+  error?: string;
+}
+
+export const PREFERRED_PROVIDERS: string[];
+
+export function parseProviderModel(value: unknown): { provider: string; modelId: string };
+export function parseModelSpecList(value: unknown): string[];
+export function resolveModelAuth(
+  ctx: PiModelSelectionContext,
+  model: PiModelLike,
+): Promise<ResolvedModelAuth>;
+export function resolveModelReference(ctx: PiModelSelectionContext, reference: string): PiModelLike;
+export function selectModelCandidate(
+  modelSpecs: string[] | string,
+  currentModel: PiModelLike | undefined,
+  ctx: PiModelSelectionContext,
+): Promise<SelectedModelCandidate | undefined>;
+
+export const modelSelectionInternals: {
+  getModelCandidates(modelSpec: string, registry?: PiModelRegistryLike): PiModelLike[];
+  modelDisplayRef(model: PiModelLike): string;
+  modelSpecMatches(modelSpec: string, model: PiModelLike): boolean;
+  orderMatchesByProviderPreference(models: PiModelLike[]): PiModelLike[];
+};

package/index.js

@@ -0,0 +1,9 @@
+export {
+  modelSelectionInternals,
+  PREFERRED_PROVIDERS,
+  parseModelSpecList,
+  parseProviderModel,
+  resolveModelAuth,
+  resolveModelReference,
+  selectModelCandidate,
+} from "./src/modelSelection.js";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tryinget/pi-model-selection",
+  "version": "0.1.0",
+  "description": "Shared Pi model selection and auth resolution primitives.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryingET/pi-extensions.git",
+    "directory": "packages/pi-model-selection"
+  },
+  "bugs": {
+    "url": "https://github.com/tryingET/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/tryingET/pi-extensions/tree/main/packages/pi-model-selection",
+  "keywords": [
+    "pi-package",
+    "model-selection",
+    "prompt-template"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "fix": "bash ../../scripts/package-quality-gate.sh fix . --mode simple-package",
+    "lint": "bash ../../scripts/package-quality-gate.sh lint . --mode simple-package",
+    "typecheck": "bash ../../scripts/package-quality-gate.sh typecheck . --mode simple-package",
+    "test": "bash ../../scripts/package-quality-gate.sh test . --mode simple-package",
+    "quality:pre-commit": "bash ../../scripts/package-quality-gate.sh pre-commit . --mode simple-package",
+    "quality:pre-push": "bash ../../scripts/package-quality-gate.sh pre-push . --mode simple-package",
+    "quality:ci": "bash ../../scripts/package-quality-gate.sh ci . --mode simple-package",
+    "check": "npm run quality:ci",
+    "release:check": "npm pack --dry-run --json",
+    "release:check:quick": "npm pack --dry-run --json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src"
+  ],
+  "x-pi-template": {
+    "scaffoldMode": "simple-package",
+    "workspacePath": "packages/pi-model-selection",
+    "releaseComponent": "pi-model-selection",
+    "releaseConfigMode": "component"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.4"
+  }
+}

package/src/modelSelection.js

@@ -0,0 +1,237 @@
+export const PREFERRED_PROVIDERS = ["openai-codex", "anthropic", "github-copilot", "openrouter"];
+
+function normalizeText(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function getModelRegistryModels(modelRegistry) {
+  if (typeof modelRegistry?.getAll !== "function") return [];
+  const models = modelRegistry.getAll();
+  return Array.isArray(models) ? models.filter(Boolean) : [];
+}
+
+function getAvailableRegistryModels(modelRegistry) {
+  if (typeof modelRegistry?.getAvailable !== "function") return undefined;
+  const models = modelRegistry.getAvailable();
+  return Array.isArray(models) ? models.filter(Boolean) : undefined;
+}
+
+function modelProvider(model) {
+  return normalizeText(model?.provider);
+}
+
+function modelId(model) {
+  return normalizeText(model?.id);
+}
+
+function modelDisplayRef(model) {
+  const provider = modelProvider(model);
+  const id = modelId(model);
+  if (provider && id) return `${provider}/${id}`;
+  return id ?? provider ?? "<unknown-model>";
+}
+
+function sameModel(a, b) {
+  return Boolean(a && b && modelProvider(a) === modelProvider(b) && modelId(a) === modelId(b));
+}
+
+function modelSpecMatches(modelSpec, model) {
+  const spec = normalizeText(modelSpec);
+  if (!spec || !model) return false;
+
+  const slashIndex = spec.indexOf("/");
+  if (slashIndex !== -1) {
+    const provider = spec.slice(0, slashIndex);
+    const id = spec.slice(slashIndex + 1);
+    return provider === modelProvider(model) && id === modelId(model);
+  }
+
+  return spec === modelId(model);
+}
+
+function orderMatchesByProviderPreference(models) {
+  const prioritized = [];
+  const seen = new Set();
+
+  for (const provider of PREFERRED_PROVIDERS) {
+    for (const model of models) {
+      const key = modelDisplayRef(model);
+      if (modelProvider(model) === provider && !seen.has(key)) {
+        prioritized.push(model);
+        seen.add(key);
+      }
+    }
+  }
+
+  for (const model of models) {
+    const key = modelDisplayRef(model);
+    if (!seen.has(key)) {
+      prioritized.push(model);
+      seen.add(key);
+    }
+  }
+
+  return prioritized;
+}
+
+function isValidModelSelectionSpec(spec) {
+  if (!spec || spec.includes("*") || /\s/.test(spec)) return false;
+
+  const segments = spec.split("/");
+  if (segments.length === 1) return true;
+  if (segments.length !== 2) return false;
+  return segments[0].length > 0 && segments[1].length > 0;
+}
+
+export function parseProviderModel(value) {
+  const raw = normalizeText(value);
+  if (!raw) {
+    throw new Error("Invalid model reference: expected provider/modelId");
+  }
+
+  const separatorIndex = raw.indexOf("/");
+  if (separatorIndex <= 0 || separatorIndex === raw.length - 1) {
+    throw new Error(`Invalid model reference '${raw}'. Expected provider/modelId`);
+  }
+
+  const provider = raw.slice(0, separatorIndex).trim();
+  const modelId = raw.slice(separatorIndex + 1).trim();
+  if (!provider || !modelId || modelId.includes("/")) {
+    throw new Error(`Invalid model reference '${raw}'. Expected provider/modelId`);
+  }
+
+  return { provider, modelId };
+}
+
+export function parseModelSpecList(value) {
+  const raw = normalizeText(value);
+  if (!raw) {
+    throw new Error("Model spec list must be a non-empty string");
+  }
+
+  const specs = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  if (specs.length === 0) {
+    throw new Error("Model spec list must contain at least one model");
+  }
+
+  const invalidSpec = specs.find((spec) => !isValidModelSelectionSpec(spec));
+  if (invalidSpec) {
+    throw new Error(`Invalid model spec '${invalidSpec}'. Expected modelId or provider/modelId`);
+  }
+
+  return specs;
+}
+
+function getModelCandidates(modelSpec, registry) {
+  const spec = normalizeText(modelSpec);
+  if (!spec) return [];
+
+  const slashIndex = spec.indexOf("/");
+  if (slashIndex !== -1) {
+    let parsed;
+    try {
+      parsed = parseProviderModel(spec);
+    } catch {
+      return [];
+    }
+
+    if (typeof registry?.find === "function") {
+      const found = registry.find(parsed.provider, parsed.modelId);
+      return found ? [found] : [];
+    }
+
+    return getModelRegistryModels(registry).filter(
+      (model) => modelProvider(model) === parsed.provider && modelId(model) === parsed.modelId,
+    );
+  }
+
+  const allMatches = getModelRegistryModels(registry).filter((model) => modelId(model) === spec);
+  if (allMatches.length <= 1) return allMatches;
+  return orderMatchesByProviderPreference(allMatches);
+}
+
+export async function resolveModelAuth(ctx, model) {
+  const registry = ctx?.modelRegistry;
+
+  if (typeof registry?.getApiKeyAndHeaders === "function") {
+    const result = await registry.getApiKeyAndHeaders(model);
+    if (result?.ok === false) return result;
+    return {
+      ok: true,
+      apiKey: result?.apiKey,
+      headers: result?.headers ?? model?.headers,
+    };
+  }
+
+  if (typeof registry?.getApiKey === "function") {
+    const apiKey = await registry.getApiKey(model);
+    return {
+      ok: true,
+      apiKey,
+      headers: model?.headers,
+    };
+  }
+
+  return {
+    ok: false,
+    error: "Model registry does not expose getApiKeyAndHeaders or getApiKey",
+  };
+}
+
+async function hasUsableAuth(model, ctx) {
+  const registry = ctx?.modelRegistry;
+  const availableModels = getAvailableRegistryModels(registry);
+  if (availableModels?.some((candidate) => sameModel(candidate, model))) return true;
+
+  if (typeof registry?.isUsingOAuth === "function" && !registry.isUsingOAuth(model)) {
+    return false;
+  }
+
+  const auth = await resolveModelAuth(ctx, model);
+  return auth.ok && Boolean(auth.apiKey || auth.headers);
+}
+
+export async function selectModelCandidate(modelSpecs, currentModel, ctx) {
+  const specs = Array.isArray(modelSpecs) ? modelSpecs : parseModelSpecList(modelSpecs);
+
+  if (currentModel && specs.some((spec) => modelSpecMatches(spec, currentModel))) {
+    return { model: currentModel, alreadyActive: true };
+  }
+
+  for (const spec of specs) {
+    for (const model of getModelCandidates(spec, ctx?.modelRegistry)) {
+      if (await hasUsableAuth(model, ctx)) {
+        return { model, alreadyActive: false };
+      }
+    }
+  }
+
+  return undefined;
+}
+
+export function resolveModelReference(ctx, reference) {
+  const specs = parseModelSpecList(reference);
+  if (specs.length !== 1) {
+    throw new Error(`Model reference '${reference}' contains multiple fallback specs`);
+  }
+
+  const candidates = getModelCandidates(specs[0], ctx?.modelRegistry);
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length > 1) {
+    throw new Error(
+      `Model reference '${reference}' is ambiguous: ${candidates.map(modelDisplayRef).join(", ")}`,
+    );
+  }
+  throw new Error(`Model reference '${reference}' did not match any registered model`);
+}
+
+export const modelSelectionInternals = {
+  getModelCandidates,
+  modelDisplayRef,
+  modelSpecMatches,
+  orderMatchesByProviderPreference,
+};