@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/model-tiers.js

@@ -1,47 +1,31 @@
 import { getModelCatalog } from './models.js';
 import { getModelPricing } from './pricing/index.js';
 import { resolveTierOverride } from './model-tier-overrides.js';
-/** The four cross-harness cost tiers, cheapest -> most capable. */
 export const MODEL_TIERS = ['cheap', 'default', 'best', 'ultra'];
-/** True if `s` is one of the four tier tokens (not a concrete model id). */
 export function isTierToken(s) {
     return !!s && MODEL_TIERS.includes(s);
 }
-/**
- * Curated tier ladders for harnesses the auto-ranker can't order from names/price
- * (subscription harnesses with no price signal). Each rung is `[tier, matcher]` in
- * cheap -> best order; the newest catalog id matching each rung fills that tier,
- * missing tiers clamp. Extend this table rather than adding per-harness branches.
- */
 const CURATED_LADDERS = {
-    // Kimi: K2.7 Highspeed < K2.7 Coding < K3 (the 1M-context default; k3-256k folds
-    // into K3). No ultra. The name heuristic can't tell K3 > K2.7, so curate it.
     kimi: [
         { tier: 'cheap', match: /highspeed/i },
         { tier: 'default', match: /for-coding(?!.*highspeed)/i },
-        { tier: 'best', match: /(^|[-/])k3\b/i }, // K3 family incl. k3-256k; the plain id represents it
+        { tier: 'best', match: /(^|[-/])k3\b/i },
     ],
 };
-// --- single-model harnesses: the tier is reasoning effort, not a model ---------
 const TIER_EFFORT = {
     cheap: 'low',
     default: 'medium',
     best: 'high',
     ultra: 'xhigh',
 };
-// --- Droid: no live catalog; prices in credit multipliers. Curated map, capped
-//     at 2x (no 4x models like Fable 5 / Fast modes). Ids are Factory -m values.
 const DROID_TIERS = {
-    cheap: 'glm-5.2', // 0.55x (Droid Core)
-    default: 'kimi-k3', // 0.6x (Droid Core)
-    best: 'claude-opus-5', // 2x
-    ultra: 'claude-opus-5', // clamp to best; avoid 4x
+    cheap: 'glm-5.2',
+    default: 'kimi-k3',
+    best: 'claude-opus-5',
+    ultra: 'claude-opus-5',
 };
-/** Router / pseudo models that are not a concrete choice and never a tier target. */
 const PSEUDO = /(^|[-/])(auto|auto-review|router|dynamic)([-/]|$)/i;
-/** Effort / speed suffixes aggregator harnesses (Cursor) bake into ids. */
 const AGGREGATOR_SUFFIX = /-(low|medium|high|xhigh|thinking|fast|reasoning)\b/gi;
-/** Anthropic capability family -> rank (cheapest 0 -> dearest 3). */
 function anthropicFamilyRank(id) {
     if (/(^|[-/])claude-haiku|(^|[-/])haiku/.test(id))
         return 0;
@@ -53,7 +37,6 @@ function anthropicFamilyRank(id) {
         return 3;
     return null;
 }
-/** Rank from the provider's own description keywords (e.g. Codex Sol/Terra/Luna). */
 function descriptionRank(desc) {
     if (!desc)
         return null;
@@ -66,7 +49,6 @@ function descriptionRank(desc) {
         return 2;
     return null;
 }
-/** Last-resort ordering from size tokens embedded in the id. */
 function sizeTokenRank(id) {
     if (/(nano|mini|lite|flash|highspeed|small|air|spark)/.test(id))
         return 0;
@@ -78,33 +60,19 @@ const blended = (id) => {
     const p = getModelPricing(id);
     return p ? p.inputPerToken + p.outputPerToken : null;
 };
-/** Strip an aggregator's effort/speed suffixes down to a base provider id. */
 function normalizeAggregatorId(id) {
     return id.replace(AGGREGATOR_SUFFIX, '').replace(/-+$/, '');
 }
-/**
- * Compare two concrete ids so the newest wins within a family. Strips a trailing
- * date stamp (`-20251101`), rebuild marker (`-v1`), and `-fast` first, so a dated
- * `opus-4-5-20251101` doesn't out-rank the genuinely newer `opus-4-8` (a bare
- * `compareVersions` reads the date as a huge version component).
- */
 function cleanForCompare(id) {
     return id
         .replace(/-\d{8}(?=($|-))/, '')
         .replace(/-v\d+$/, '')
         .replace(/-fast$/, '');
 }
-/** Numeric segments of a (cleaned) id, splitting on BOTH dashes and dots. */
 function versionSegments(id) {
     const m = cleanForCompare(id).match(/\d+/g);
     return m ? m.map((n) => parseInt(n, 10)) : [];
 }
-/**
- * Newest concrete id within a family wins. `compareVersions` only splits on `.`,
- * so it degenerates to a single `[0]` segment for a dash-separated model id and
- * mis-ranks e.g. `claude-sonnet-5` below `claude-sonnet-4-6`. Compare the numeric
- * segments directly instead.
- */
 function newer(a, b) {
     const A = versionSegments(a);
     const B = versionSegments(b);
@@ -115,18 +83,8 @@ function newer(a, b) {
     }
     return 0;
 }
-/**
- * Rank a harness's catalog models cheapest -> dearest and collapse variants of
- * one model to a single rung (keeping the newest concrete id). Strategy depends
- * on the harness class: aggregator (Cursor) ranks by price of the normalized
- * base id; single-provider harnesses rank by the provider lineup with price and
- * size tokens as fallbacks.
- */
 function rankCatalog(agent, models) {
     const usable = models.filter((m) => !PSEUDO.test(m.id));
-    // Cursor and Pi (Oh My Pi) are cross-provider aggregators: their ids are
-    // provider-qualified (`anthropic/…`, `openai/…`) and span vendors, so price of
-    // the normalized base id is the only unifying rank signal.
     const aggregator = agent === 'cursor';
     const scored = usable.map((m) => {
         const rawId = m.id;
@@ -136,7 +94,6 @@ function rankCatalog(agent, models) {
         let rank;
         let family;
         if (aggregator) {
-            // cross-provider: price is the unifying signal; family = base id
             rank = price != null ? price * 1e6 : 100 + sizeTokenRank(lc);
             family = baseId;
         }
@@ -153,10 +110,6 @@ function rankCatalog(agent, models) {
             }
             else if (price != null) {
                 rank = 10 + price * 1e6;
-                // Collapse only true re-releases of ONE model (same base id, differing
-                // date/rebuild suffix). Keying on price would merge two DIFFERENT models
-                // that happen to cost the same (e.g. gpt-5.5 and gpt-5.6-sol), dropping
-                // one from every tier.
                 family = cleanForCompare(baseId);
             }
             else {
@@ -166,7 +119,6 @@ function rankCatalog(agent, models) {
         }
         return { id: rawId, baseId, rank, family, price };
     });
-    // collapse by family: keep the newest concrete id, lowest (cheapest) rank
     const byFamily = new Map();
     for (const s of scored) {
         const prev = byFamily.get(s.family);
@@ -174,7 +126,6 @@ function rankCatalog(agent, models) {
             byFamily.set(s.family, s);
             continue;
         }
-        // keep the newer id; keep the cheaper rank
         if (newer(s.id, prev.id) > 0)
             prev.id = s.id;
         if (s.rank < prev.rank)
@@ -184,21 +135,17 @@ function rankCatalog(agent, models) {
     }
     return [...byFamily.values()].sort((a, b) => a.rank - b.rank || newer(b.id, a.id));
 }
-/** Which ranked rung each tier index maps to, collapsing when there are < 4 rungs. */
 function rungIndexFor(tierIndex, n) {
     return n >= 4 ? Math.round((tierIndex / 3) * (n - 1)) : Math.min(tierIndex, n - 1);
 }
-/** Bucket an ordered (cheap -> dear) rung list onto the four tiers, clamping when < 4. */
 function bucketRungs(rungs) {
     const n = rungs.length;
     const map = {};
     if (n === 0) {
-        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
         for (const t of MODEL_TIERS)
             map[t] = { tier: t, model: null };
         return map;
     }
-    // A tier that shares the rung of the tier below has no distinct rung -> mark clamped.
     for (let i = 0; i < MODEL_TIERS.length; i++) {
         const t = MODEL_TIERS[i];
         const idx = rungIndexFor(i, n);
@@ -209,7 +156,6 @@ function bucketRungs(rungs) {
     }
     return map;
 }
-/** Build a tier map from a curated ladder against a catalog (newest match per rung). */
 function tierizeFromLadder(ladder, models) {
     const usable = models.filter((m) => !PSEUDO.test(m.id));
     const rungs = [];
@@ -217,8 +163,6 @@ function tierizeFromLadder(ladder, models) {
         const matches = usable.filter((m) => rung.match.test(m.id));
         if (matches.length === 0)
             continue;
-        // Prefer a plain id over a context-size variant (k3 over k3-256k) -- the
-        // variant folds into the rung but the plain model represents it -- then newest.
         const plain = matches.filter((m) => !/-\d+[km]\b/i.test(m.id));
         const pool = plain.length ? plain : matches;
         rungs.push({ id: pool.reduce((a, b) => (newer(b.id, a.id) > 0 ? b : a)).id });
@@ -229,15 +173,10 @@ function tierizeFromLadder(ladder, models) {
             map[t].source = 'curated';
     return map;
 }
-/**
- * Resolve all four tiers for an (agent, version) -- what `agents models` prints and
- * `resolveTier` indexes. Precedence: user override -> curated ladder / auto-ranking.
- */
 export function resolveTierMap(agent, version) {
     let base;
     let catalogIds;
     if (agent === 'droid') {
-        // Droid: curated credit-multiplier map (no live catalog to validate against).
         base = {
             cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x', source: 'curated' },
             default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x', source: 'curated' },
@@ -256,12 +195,6 @@ export function resolveTierMap(agent, version) {
     const overrides = resolveTierOverride(agent, version);
     return applyTierOverrides(overrides, `${agent}@${version}`, catalogIds, base);
 }
-/**
- * Apply user overrides on top of the auto/curated map. Pure (takes the resolved
- * override map, no config lookup) so it is directly testable. An overridden id is
- * used only when the version actually ships it (or when there is no catalog to
- * check, e.g. Droid); otherwise the tier keeps its base value with a note.
- */
 export function applyTierOverrides(overrides, label, catalogIds, base) {
     if (Object.keys(overrides).length === 0)
         return base;
@@ -279,13 +212,8 @@ export function applyTierOverrides(overrides, label, catalogIds, base) {
     }
     return out;
 }
-/**
- * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup) so
- * it is directly testable. A single-model harness maps the tiers to reasoning effort.
- */
 export function tierizeModels(agent, models) {
     const rungs = rankCatalog(agent, models);
-    // Single-model harness (e.g. Grok): the tier is reasoning effort, not a model.
     if (rungs.length === 1) {
         const only = rungs[0].id;
         const map = {};
@@ -295,7 +223,6 @@ export function tierizeModels(agent, models) {
     }
     return bucketRungs(rungs);
 }
-/** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
 export function resolveTier(agent, version, tier) {
     return resolveTierMap(agent, version)[tier];
 }

package/dist/lib/models.d.ts

@@ -1,6 +1,5 @@
 import type { AgentId } from './types.js';
 import { type ModelPricing } from './pricing/index.js';
-/** Model identifiers per cloud provider (used by Claude's multi-cloud routing). */
 export interface ModelPerCloud {
     firstParty: string;
     bedrock?: string;
@@ -9,198 +8,54 @@ export interface ModelPerCloud {
     anthropicAws?: string;
     mantle?: string | null;
 }
-/** A reasoning effort level exposed by an agent's model. */
 export interface ReasoningLevel {
     effort: string;
     description?: string;
 }
-/** Metadata for a single model within an agent's catalog. */
 export interface ModelInfo {
     id: string;
     displayName?: string;
     description?: string;
-    /** alias label (e.g. "opus", "sonnet", "haiku") that resolves to this id */
     alias?: string;
-    /** true if this is the agent's default model */
     isDefault?: boolean;
-    /** Per-cloud routing IDs (claude only) */
     perCloud?: ModelPerCloud;
-    /** Reasoning levels (codex; claude exposes via --effort with global levels) */
     reasoningLevels?: ReasoningLevel[];
-    /** Default reasoning level if applicable */
     defaultReasoningLevel?: string;
-    /** Per-token USD pricing when known (from prices.json); absent for subscription/unpriced models. */
     pricing?: ModelPricing;
 }
-/** The complete model catalog for a specific (agent, version) pair. */
 export interface ModelCatalog {
     agent: AgentId;
     version: string;
     source: ModelSourceKind;
     sourcePath: string;
     models: ModelInfo[];
-    /** Aliases that the CLI resolves to a canonical id (e.g. { opus: "claude-opus-4-7" } for claude, { flash: "gemini-3-flash-preview" } for gemini) */
     aliases: Record<string, string>;
 }
-/** How the model catalog source was obtained. */
 export type ModelSourceKind = 'bundle' | 'binary' | 'cli';
-/** Describes the location and extraction strategy for a model catalog source. */
 export interface ModelSource {
     path: string;
     kind: ModelSourceKind;
 }
-/**
- * Locate the file that authoritatively describes the installed model catalog
- * for a given (agent, version). The `kind` tells `getModelCatalog` how to
- * read it:
- *   bundle/binary -- strings(1)-style extraction (claude/codex)
- *   js            -- read + regex-parse an exported JS module (gemini)
- *   cli           -- spawn the agent's own `models` command (opencode/cursor/openclaw)
- *
- * Returns null if nothing usable is found.
- */
 export declare function locateModelSource(agent: AgentId, version: string): ModelSource | null;
-/**
- * Extract Claude's model catalog from its bundle/binary.
- *
- * Bundle/binary contains:
- *   - alias map: {opus:"claude-opus-4-7",sonnet:"claude-sonnet-4-6",haiku:"..."}
- *   - per-cloud maps: {firstParty:"claude-opus-4-5-...",bedrock:"...",vertex:"...",...}
- *   - constants: {OPUS_ID:"...",OPUS_NAME:"...",SONNET_ID:"...",...}
- */
-/**
- * Drop a catalog id that is a proper dash-boundary prefix of a more-specific
- * sibling also present in the list (e.g. `claude-opus-4` when `claude-opus-4-8`
- * is present, or `claude-opus-4-1` when `claude-opus-4-1-20250805` is present).
- *
- * Two sources produce these prefix forms in the native binary:
- *  - standalone `.includes("claude-opus-4")` prefix-check strings (#1892)
- *  - per-cloud metadata field values such as `foundry:"claude-opus-4-1"` next
- *    to a real firstParty id `claude-opus-4-1-20250805` (#2233)
- *
- * A genuine bare current id with no longer sibling (e.g. `claude-sonnet-5`) is
- * kept. The dash boundary (`startsWith(id + '-')`) avoids collapsing
- * `claude-opus-4-1` into `claude-opus-4-10`.
- */
 export declare function dropBareLegacyIds(ids: string[]): string[];
-/**
- * Scan raw binary/bundle text for canonical Claude model ids, then drop bare
- * legacy / cloud-metadata prefixes (#1892, #2233). Two independent guards keep
- * non-model strings out of the catalog:
- *
- *  - **Word-boundary anchors on the id regex.** The id must not be glued to a
- *    surrounding identifier character, and must not be the truncated prefix of a
- *    longer *version* token. `(?<![A-Za-z0-9_])` rejects a glued prefix;
- *    `(?![A-Za-z0-9])` rejects a glued alnum suffix; `(?!\.\d)` rejects a
- *    dotted-version continuation — so the bare-major prefix of the binary's own
- *    "Typo in model ID" troubleshooting string `claude-sonnet-4.6` is not
- *    scraped as `claude-sonnet-4`, while a real id followed by an unrelated `.`
- *    suffix (`claude-fable-5.md`) still matches. Dash-separated segments only:
- *    the dotted form never appears in a genuine id.
- *
- *    The id body is captured inside a lookahead (`(?=(...))\1`) so the greedy
- *    `-\d+` run matches **atomically**: without it, a suffix-glued token like
- *    `claude-opus-4-1x` would fail the trailing anchor on the full match, then
- *    backtrack a segment and re-emit the bare `claude-opus-4` — the exact 404-able
- *    id this scan exists to suppress (two packed strings can end up glued with no
- *    separator in the extracted binary text). The atomic match fails outright
- *    instead of degrading to the bare form.
- *  - **`dropBareLegacyIds`.** A fully delimited string the anchors cannot tell
- *    apart from a real id — whether a bare major (`.includes("claude-opus-4")`)
- *    or a bare-minor per-cloud field value (`foundry:"claude-opus-4-1"`) — is
- *    dropped when a more-specific sibling is also present; a genuinely bare
- *    current id with no sibling (`claude-sonnet-5`) is kept.
- */
 export declare function scanClaudeCatalogIds(text: string): string[];
-/**
- * Parse `grok models` stdout into a catalog. Exported for unit tests.
- *
- * Output shape (verified 0.2.118):
- *   You are logged in with grok.com.
- *
- *   Default model: grok-4.5
- *
- *   Available models:
- *     * grok-4.5 (default)
- *
- * The `Default model:` line is authoritative; rows may also carry a leading `*`
- * and a `(default)` flag. Grok has no `--json` on this subcommand. Settings live
- * in `config.toml` / `models_cache.json`, not `settings.json`, so the native
- * settings.json reader cannot surface the default — the catalog is the source
- * that makes `resolveConfiguredModel` return a cli-default for Grok.
- */
 export declare function parseGrokModelsStdout(stdout: string): {
     models: ModelInfo[];
     aliases: Record<string, string>;
 };
 export declare function getModelCatalog(agent: AgentId, version: string): ModelCatalog | null;
-/** The result of resolving a user-supplied model string against the catalog. */
 export interface ResolvedModel {
-    /** The model string to forward to the CLI (canonical id when we can resolve, else passed through unchanged). */
     forwarded: string;
-    /** The canonical id, when we could resolve the input through the alias map. */
     canonical?: string;
-    /** Warning to surface to the user (e.g. "model X not in known catalog for v Y"). */
     warning?: string;
 }
-/**
- * Resolve a user-supplied model string for a specific (agent, version).
- *
- * Pass-through semantics: we never block. If the input doesn't match anything
- * we know about, we forward it as-is and return a warning the caller can log.
- *
- * - If `requested` matches an alias in the catalog (e.g. "opus"), we still
- *   forward the alias (the CLI accepts both), but we report the canonical id
- *   so logs/metadata can record the concrete model.
- * - If `requested` matches a known canonical id, no warning.
- * - If `requested` is unknown to our extractor, we forward it and warn.
- */
 export declare function resolveModel(agent: AgentId, version: string, requested: string): ResolvedModel;
-/**
- * Resolve the model id an `agents run` will ACTUALLY use, for cost estimation
- * (issue #346). The run path resolves the model in this precedence:
- *   1. explicit `--model` (or profile/workflow/runDefaults value) — `requested`
- *   2. otherwise the agent CLI's own built-in default, which we read from the
- *      extracted catalog's `isDefault` model.
- * Returns null only when we have neither — the caller must then treat the
- * estimate as unpriced rather than silently using an unpriced placeholder id
- * like `${agent}-default`.
- */
 export declare function resolveEffectiveModel(agent: AgentId, version: string, requested?: string): string | null;
-/** Where the model a given agent+version will actually run with came from. */
 export type ConfiguredModelSource = 'run-default' | 'config' | 'cli-default';
 export interface ConfiguredModel {
-    /** The model id the agent will run with (e.g. `opus`, `gpt-5-codex`). */
     model: string;
     source: ConfiguredModelSource;
 }
-/**
- * The model a given agent+version is actually configured to use right now, with
- * where that selection comes from. First hit wins:
- *   1. run-default — the user's agents-cli `run.defaults` in agents.yaml
- *   2. config      — the agent's OWN native settings.json `model` field
- *   3. cli-default — the CLI's built-in default: the catalog's `isDefault` model
- *                    if one is flagged (e.g. Kimi), otherwise the literal
- *                    `default` for a model-capable agent whose runtime picks its
- *                    own default (Claude/Codex don't flag one — Claude's own UI
- *                    calls this "Default").
- * Each layer is a real source the agent consults; `version` must be concrete.
- * Returns null only when the agent exposes no model catalog at all.
- */
 export declare function resolveConfiguredModel(agent: AgentId, version: string, home?: string): ConfiguredModel | null;
-/**
- * Join the identity cluster — `agent@version · model · account` — with a dim
- * separator, dropping empty pieces. Pieces are pre-colored by the caller so the
- * same cluster reads identically across `view`, `use`, `add`, and `status`.
- */
 export declare function formatAgentIdentity(...parts: Array<string | null | undefined>): string;
-/**
- * Build the per-agent CLI flags for a unified reasoning effort knob.
- *
- * Both Claude (`--effort`) and Codex (`-c model_reasoning_effort=...`) expose a
- * reasoning intensity dial. Inputs accepted: low | medium | high | xhigh | max | auto.
- * - Codex only supports low/medium/high; xhigh and max are clamped to high.
- * - 'auto' skips reasoning flags for codex (lets it use model default).
- * - 'auto' passes --effort auto to claude if supported.
- */
 export declare function buildReasoningFlags(agent: AgentId, level: string): string[];