@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/menubar/snapshot.d.ts

@@ -1,54 +1,18 @@
+import { type GithubViewer } from '../github/viewer.js';
+import { type PhoenixSession } from '../identity/client.js';
 import type { DeviceStats } from '../devices/health.js';
 import type { WatchdogTickResult } from '../watchdog/runner.js';
-/**
- * One registered fleet device, for the menu-bar's collapsible DEVICES section.
- * Sourced from the local registry read (`loadDevices`) — no network probe — so
- * it carries only local persisted state (name, platform, preferred status,
- * whether it is the interactive host, whether it is this machine). Live load% is merged in
- * on the Swift side from the daemon-warmed `.fleet-stats.json`; online/offline
- * is deliberately NOT claimed here (the registry's cached tailscale flag is
- * documented as stale in both directions — registry.ts isLikelyOnline).
- */
 interface MenubarDevice {
     name: string;
     platform: string;
-    /**
-     * Physical form factor for a factual hardware icon: `laptop` | `desktop` |
-     * `server` | `unknown` (PHNX-3999). A shared device-scope config fact set
-     * explicitly per device — never inferred from `platform`. `unknown` when unset.
-     */
     formFactor: string;
     interactive: boolean;
     isLocal: boolean;
     preferred: boolean;
-    /**
-     * The operator's role mark — `worker` | `personal` | `desktop`, or `unknown`
-     * when the device was never marked (PHNX-3999 F25). Read from the same
-     * device-scope config `--device auto` consults, so the menu shows the fact that
-     * governs placement rather than a second notion of it.
-     */
     role: string;
-    /**
-     * True when automatic placement (`agents run --device auto`) may pick this
-     * device: the verdict of the ONE canonical pool filter, so a `personal` box the
-     * user sits at reads as ineligible here exactly as it behaves there.
-     */
     autoEligible: boolean;
-    /** Hardware facts and the current reading, or null when never observed. */
     stats: MenubarDeviceStats | null;
 }
-/**
- * One device's hardware facts and last reading, projected from the fleet-stats
- * cache the CLI already keeps (`~/.agents/.cache/.fleet-stats.json`).
- *
- * Cache-only by construction: the snapshot never probes the fleet, so opening
- * Settings costs nothing and a device nobody has measured says so. Every value
- * is `null` when that number was not observed — never 0, which would render as a
- * real "idle, empty disk" reading. `stale` carries the CLI's own freshness bound
- * so the menu can label an old reading instead of showing it as live, and
- * `observedAt` / `specsObservedAt` give the observation age F25 asks for
- * (hardware totals survive an unreachable probe; current-state readings do not).
- */
 interface MenubarDeviceStats {
     reachable: boolean;
     observedAt: string;
@@ -63,50 +27,33 @@ interface MenubarDeviceStats {
     loadPercent: number | null;
     specsObservedAt: string | null;
 }
+export interface MenubarMe {
+    name: string | null;
+    email: string | null;
+    github: string | null;
+    avatarUrl: string | null;
+    avatarSource: 'phoenix' | 'github' | null;
+}
+export declare function resolveMenubarMe(session: PhoenixSession | null, viewer: GithubViewer | null): MenubarMe | null;
 interface MenubarSnapshot {
     version: 1;
     capturedAt: string;
-    /**
-     * The installed CLI version that produced this snapshot — the same string
-     * `agents --version` prints (RUSH-2688). The snapshot is emitted by whatever
-     * `agents` binary is on PATH, so this is resolved at runtime, letting the menu
-     * bar show its own version in the header and making a stale menu bar visible.
-     */
     cliVersion: string;
     routines: Record<string, unknown>[];
     recentSessions: Record<string, unknown>[];
     activeSessions: Record<string, unknown>[];
     devices: MenubarDevice[];
-    /**
-     * AGI Menu preferences (PHNX-3999), keyed by the full `menubar.menu.*` config
-     * name, carrying the EFFECTIVE value — the stored value, else the registered
-     * default. The native menu consumes this from the snapshot it already polls
-     * rather than a second preference-read mechanism. `menubar.menu.defaultProject`
-     * is omitted when unset (it has no default); every other key is always present.
-     * Writes stay one `agents config set/unset <key>` per setting.
-     */
+    me: MenubarMe | null;
     menuPreferences: Record<string, unknown>;
+    menuListPreferences: Record<string, string[]>;
     watchdog: {
         enabled: boolean;
         lastTick: Pick<WatchdogTickResult, 'didNudge' | 'counts'> | null;
     };
 }
-/**
- * The effective AGI Menu preferences map for the snapshot: each `menubar.menu.*`
- * key's stored value, or its registered default when unset. A key with neither
- * (only `defaultProject`) is omitted so the native app keeps its own default.
- */
 export declare function buildMenuPreferences(): Record<string, unknown>;
-/**
- * Project one cached {@link DeviceStats} row into the snapshot shape, or `null`
- * when the device has no cached reading at all.
- *
- * `?? null` rather than a default: an absent number means "not observed", and the
- * menu renders that as unavailable. A 0 would be indistinguishable from a real
- * measurement of an idle box or a full disk.
- */
+export declare function buildMenuListPreferences(): Record<string, string[]>;
 export declare function projectDeviceStats(row: DeviceStats | undefined): MenubarDeviceStats | null;
 export declare function readLastWatchdogTick(stateDir?: string): WatchdogTickResult | null;
-/** One-process read model for AGI Menu's repeating three-minute refresh. */
 export declare function computeMenubarSnapshot(): Promise<MenubarSnapshot>;
 export {};

package/dist/lib/menubar/snapshot.js

@@ -1,5 +1,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { httpsUrl } from '../actor.js';
+import { cachedViewer, emailDigest } from '../github/viewer.js';
+import { readSession } from '../identity/client.js';
 import { buildRoutineListJson } from '../scheduling/routines.js';
 import { backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../session/active.js';
 import { getConfigValue, listConfiguredDeviceRoles, loadAutoLaunchPreferences } from '../device-config.js';
@@ -13,40 +16,59 @@ import { querySessions } from '../session/db.js';
 import { readActiveSessionsCache } from '../session/session-cache.js';
 import { getRuntimeStateDir } from '../state.js';
 import { getCliVersion } from '../version.js';
-/**
- * The effective AGI Menu preferences map for the snapshot: each `menubar.menu.*`
- * key's stored value, or its registered default when unset. A key with neither
- * (only `defaultProject`) is omitted so the native app keeps its own default.
- */
+export function resolveMenubarMe(session, viewer) {
+    const sessionEmail = session?.email?.trim() || null;
+    const github = !session
+        ? viewer
+        : viewer?.emailSha256 && sessionEmail && viewer.emailSha256 === emailDigest(sessionEmail)
+            ? viewer
+            : null;
+    if (!session && !github)
+        return null;
+    const phoenixAvatar = httpsUrl(session?.avatarUrl) ?? null;
+    const githubAvatar = github?.avatarUrl ?? null;
+    return {
+        name: session?.name?.trim() || github?.name || null,
+        email: sessionEmail,
+        github: github?.login ?? null,
+        avatarUrl: phoenixAvatar ?? githubAvatar,
+        avatarSource: phoenixAvatar ? 'phoenix' : githubAvatar ? 'github' : null,
+    };
+}
 export function buildMenuPreferences() {
     const out = {};
+    for (const [name, value] of effectiveMenuPreferences()) {
+        if (!Array.isArray(value))
+            out[name] = value;
+    }
+    return out;
+}
+export function buildMenuListPreferences() {
+    const out = {};
+    for (const [name, value] of effectiveMenuPreferences()) {
+        if (Array.isArray(value))
+            out[name] = value.map(String);
+    }
+    return out;
+}
+function effectiveMenuPreferences() {
+    const out = [];
     for (const prop of MENUBAR_MENU_PROPERTIES) {
         const name = `menubar.menu.${prop}`;
         const entry = getConfigValue(name);
         const value = entry.value !== undefined ? entry.value : entry.spec.defaultValue;
         if (value === undefined)
-            continue; // unset defaultProject — no default to emit
-        out[name] = value;
+            continue;
+        out.push([name, value]);
     }
     return out;
 }
-/**
- * The full registered-device roster for the menu bar, from the local registry
- * file only (no ssh, no stats probe) — as cheap as `buildRoutineListJson()`, so
- * it rides the same 3-minute snapshot poll instead of a second timer.
- */
 async function buildMenubarDevices() {
     const reg = await loadDevices();
     const roster = Object.keys(reg);
-    // Pass the roster so a fleet-wide default (fleet.defaults.config) reaches
-    // devices that have no doc of their own.
     const prefs = loadAutoLaunchPreferences(roster);
     const roles = listConfiguredDeviceRoles(roster);
-    // The placement verdict from the one canonical filter — not a re-implementation
-    // of the role rule (`devices/pool.ts` owns it).
     const autoEligible = new Set(filterAutoPool(roster, { roles, autoLaunch: prefs }));
-    // Cache read only: no ssh, no probe, so this still rides the existing snapshot
-    // poll (docs/menubar.md: the menu bar must not probe the fleet per render).
     const stats = readStatsCache();
     const interactiveHost = getConfigValue('interactive.host').value;
     const self = machineId();
@@ -55,7 +77,6 @@ async function buildMenubarDevices() {
         .map((name) => ({
         name,
         platform: reg[name].platform,
-        // Shared device-scope fact (readable for any device); `unknown` when unset.
         formFactor: getConfigValue('formFactor', { device: name }).value ?? 'unknown',
         interactive: name === interactiveHost,
         isLocal: name === self,
@@ -65,14 +86,6 @@ async function buildMenubarDevices() {
         stats: projectDeviceStats(stats[name]),
     }));
 }
-/**
- * Project one cached {@link DeviceStats} row into the snapshot shape, or `null`
- * when the device has no cached reading at all.
- *
- * `?? null` rather than a default: an absent number means "not observed", and the
- * menu renders that as unavailable. A 0 would be indistinguishable from a real
- * measurement of an idle box or a full disk.
- */
 export function projectDeviceStats(row) {
     if (!row)
         return null;
@@ -99,26 +112,17 @@ export function readLastWatchdogTick(stateDir = path.join(getRuntimeStateDir(),
         return null;
     }
 }
-/** One-process read model for AGI Menu's repeating three-minute refresh. */
 export async function computeMenubarSnapshot() {
-    // One-shot, sentinel-gated, macOS-only lift of legacy UserDefaults prefs into
-    // config before we read them. After the first run it is a cheap existsSync
-    // no-op; it never throws into the snapshot.
     migrateMenubarPreferencesFromUserDefaults();
-    const [routines, recent, devices] = await Promise.all([
+    const viewerRead = cachedViewer();
+    const [routines, recent, devices, viewer] = await Promise.all([
         Promise.resolve(buildRoutineListJson()),
         Promise.resolve(querySessions({ limit: 40, skipExistenceCheck: true })),
         buildMenubarDevices(),
+        viewerRead,
     ]);
     const active = readActiveSessionsCache('local');
     const rawSessions = active?.sessions ?? [];
-    // The raw cache is never filtered at write time (RUSH-2336) — it retains
-    // queued/closed/crashed rows so `--queued`/`--closed`/`--crashed` can
-    // recover them, and the daemon's warm-tick gather (unlike the CLI's own
-    // local gather) never stamps `machine` on a row. Stamp self here — this IS
-    // the 'local' scope by construction — then apply the ONE canonical
-    // bare-active selector so the menubar never shows a retained dead/queued
-    // row nor a process row of unverified liveness.
     const self = machineId();
     for (const s of rawSessions)
         if (!s.machine)
@@ -133,7 +137,9 @@ export async function computeMenubarSnapshot() {
         recentSessions: JSON.parse(serializeSessionsJson(recent)),
         activeSessions: serializeActiveSessionsForJson(activeSessions),
         devices,
+        me: resolveMenubarMe(readSession(), viewer),
         menuPreferences: buildMenuPreferences(),
+        menuListPreferences: buildMenuListPreferences(),
         watchdog: {
             enabled: getConfigValue('watchdog.enabled').value === true,
             lastTick: (() => {

package/dist/lib/merged-resources.d.ts

@@ -1,11 +1 @@
-/**
- * The merged, first-wins DotAgents resource surface — every resource kind, one
- * table, showing the winning layer per row.
- *
- * Ported verbatim from the former `agents resources` command, now surfaced as
- * `agents view --merged`. `agents view agent@version` shows per-version
- * resources; this shows the cross-layer merge across project → user → extras →
- * system. Kept as a shared lib (not inlined into `view.ts`) so `inspect` can
- * reuse it later.
- */
 export declare function renderMergedResources(): void;

package/dist/lib/merged-resources.js

@@ -1,13 +1,3 @@
-/**
- * The merged, first-wins DotAgents resource surface — every resource kind, one
- * table, showing the winning layer per row.
- *
- * Ported verbatim from the former `agents resources` command, now surfaced as
- * `agents view --merged`. `agents view agent@version` shows per-version
- * resources; this shows the cross-layer merge across project → user → extras →
- * system. Kept as a shared lib (not inlined into `view.ts`) so `inspect` can
- * reuse it later.
- */
 import * as path from 'path';
 import chalk from 'chalk';
 import { listResources } from './resources.js';

package/dist/lib/migrate-fold.d.ts

@@ -1,33 +1,2 @@
-/**
- * Leaf migrator: fold ~/.agents-system/ into ~/.agents/.system/.
- *
- * Kept separate from migrate.ts so the always-on startup hop (index.ts) does
- * not load the hosts/routine/teams/daemon/menubar graph that migrate.ts's
- * static imports pull in (RUSH-2454). migrate.ts re-exports and still calls
- * foldLegacySystemRepo() at the top of runMigration().
- *
- * HOME is resolved at call time (not module load) so tests can point at a
- * fixture tree via process.env.HOME without cache-busting the module.
- */
-/**
- * Fold ~/.agents-system/ into ~/.agents/.system/.
- *
- * MUST run first in runMigration() — every other migrator reads SYSTEM_DIR
- * (the new path), so the contents have to be there before they execute.
- *
- * Strategy:
- *   1. If legacy dir doesn't exist or is already a symlink, no-op.
- *   2. If new path doesn't exist yet, rename in one shot (fast path).
- *   3. If both exist (mid-migration / re-run on partially-migrated state),
- *      merge legacy → new with new winning on collision, then drop legacy.
- *
- * After the contents move, the legacy path becomes a symlink → SYSTEM_DIR
- * so external tooling that still references ~/.agents-system/ keeps
- * resolving correctly. The symlink is harmless on its own and can be
- * removed with `rm ~/.agents-system` once everything has updated.
- *
- * Idempotent: re-running converges to "contents at SYSTEM_DIR, symlink at
- * LEGACY_SYSTEM_DIR" without duplicating data.
- */
 export declare function foldLegacySystemRepo(): void;
 export declare function copyDirSkipExisting(src: string, dest: string): void;

package/dist/lib/migrate-fold.js

@@ -1,14 +1,3 @@
-/**
- * Leaf migrator: fold ~/.agents-system/ into ~/.agents/.system/.
- *
- * Kept separate from migrate.ts so the always-on startup hop (index.ts) does
- * not load the hosts/routine/teams/daemon/menubar graph that migrate.ts's
- * static imports pull in (RUSH-2454). migrate.ts re-exports and still calls
- * foldLegacySystemRepo() at the top of runMigration().
- *
- * HOME is resolved at call time (not module load) so tests can point at a
- * fixture tree via process.env.HOME without cache-busting the module.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -25,26 +14,6 @@ function systemDir() {
 function legacySystemDir() {
     return path.join(homeDir(), '.agents-system');
 }
-/**
- * Fold ~/.agents-system/ into ~/.agents/.system/.
- *
- * MUST run first in runMigration() — every other migrator reads SYSTEM_DIR
- * (the new path), so the contents have to be there before they execute.
- *
- * Strategy:
- *   1. If legacy dir doesn't exist or is already a symlink, no-op.
- *   2. If new path doesn't exist yet, rename in one shot (fast path).
- *   3. If both exist (mid-migration / re-run on partially-migrated state),
- *      merge legacy → new with new winning on collision, then drop legacy.
- *
- * After the contents move, the legacy path becomes a symlink → SYSTEM_DIR
- * so external tooling that still references ~/.agents-system/ keeps
- * resolving correctly. The symlink is harmless on its own and can be
- * removed with `rm ~/.agents-system` once everything has updated.
- *
- * Idempotent: re-running converges to "contents at SYSTEM_DIR, symlink at
- * LEGACY_SYSTEM_DIR" without duplicating data.
- */
 export function foldLegacySystemRepo() {
     const LEGACY_SYSTEM_DIR = legacySystemDir();
     const SYSTEM_DIR = systemDir();
@@ -53,7 +22,7 @@ export function foldLegacySystemRepo() {
     try {
         legacyStat = fs.lstatSync(LEGACY_SYSTEM_DIR);
     }
-    catch { /* missing */ }
+    catch { }
     if (!legacyStat)
         return;
     if (legacyStat.isSymbolicLink())
@@ -63,19 +32,18 @@ export function foldLegacySystemRepo() {
     try {
         fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
     }
-    catch { /* best-effort */ }
+    catch { }
     if (!fs.existsSync(SYSTEM_DIR)) {
         try {
             fs.renameSync(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
             try {
                 createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
             }
-            catch { /* best-effort */ }
+            catch { }
             console.error('Folded ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
             return;
         }
         catch {
-            // Cross-device rename or perm issue — fall through to copy + remove.
         }
     }
     try {
@@ -84,10 +52,10 @@ export function foldLegacySystemRepo() {
         try {
             createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
         }
-        catch { /* best-effort */ }
+        catch { }
         console.error('Merged ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
     }
-    catch { /* best-effort */ }
+    catch { }
 }
 export function copyDirSkipExisting(src, dest) {
     let entries;
@@ -124,7 +92,7 @@ export function copyDirSkipExisting(src, dest) {
                     fs.copyFileSync(s, d);
                 }
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
 }

package/dist/lib/model-tier-overrides.d.ts

@@ -1,25 +1,3 @@
-/**
- * Human overrides for the cost-tier -> model mapping.
- *
- * The auto-ranking (lib/model-tiers.ts) is a best guess; for subscription harnesses
- * with no price signal (Kimi, Cursor) it can be wrong. A user pins the right model
- * per tier with `agents models tier set <agent[@version]> <tier> <model>`, which
- * writes here — the user never hand-edits the file.
- *
- * Stored under agents.yaml, same selector shape as run.defaults:
- *
- *   model:
- *     tiers:
- *       "kimi:*":                 # applies to every installed kimi
- *         best: kimi-code/k3
- *         default: kimi-code/kimi-for-coding
- *       "kimi:0.19.2":            # a specific version wins over the wildcard
- *         best: kimi-code/k3-256k
- *
- * Resolution (most-specific-first): `<agent>:<version>` beats `<agent>:*` beats the
- * auto-ranking. resolveTierMap (model-tiers.ts) applies the result and falls back to
- * auto for any tier whose overridden id isn't in that version's catalog.
- */
 import type { AgentId } from './types.js';
 import { type ModelTier } from './model-tiers.js';
 type TierOverrideMap = Partial<Record<ModelTier, string>>;
@@ -27,18 +5,10 @@ interface TierOverrideEntry {
     selector: string;
     tiers: TierOverrideMap;
 }
-/** Validate a tier token, throwing a friendly error otherwise. */
 export declare function parseTier(input: string): ModelTier;
-/**
- * The effective tier overrides for an (agent, version): the `<agent>:*` wildcard
- * merged under the exact `<agent>:<version>` selector (exact wins per-tier).
- */
 export declare function resolveTierOverrideFrom(all: Record<string, unknown>, agent: AgentId, version?: string | null): TierOverrideMap;
 export declare function resolveTierOverride(agent: AgentId, version?: string | null): TierOverrideMap;
-/** Every configured override entry, sorted by selector (for `agents models tier list`). */
 export declare function listTierOverrides(): TierOverrideEntry[];
-/** Pin `tier -> model` for a selector. Writes agents.yaml. */
 export declare function setTierOverride(selectorInput: string, tierInput: string | ModelTier, model: string): TierOverrideEntry;
-/** Clear one tier (or all tiers when `tierInput` is omitted) for a selector. Returns true if anything changed. */
 export declare function clearTierOverride(selectorInput: string, tierInput?: string): boolean;
 export {};

package/dist/lib/model-tier-overrides.js

@@ -4,7 +4,6 @@ import { MODEL_TIERS } from './model-tiers.js';
 function isTier(value) {
     return MODEL_TIERS.includes(value);
 }
-/** Validate a tier token, throwing a friendly error otherwise. */
 export function parseTier(input) {
     const t = input.trim().toLowerCase();
     if (!isTier(t)) {
@@ -12,7 +11,6 @@ export function parseTier(input) {
     }
     return t;
 }
-/** Normalize a stored selector's tier map, dropping unknown/empty entries. */
 function normalize(raw) {
     const out = {};
     if (!raw || typeof raw !== 'object')
@@ -26,10 +24,6 @@ function normalize(raw) {
 function sortedSelectors(map) {
     return Object.fromEntries(Object.entries(map).sort(([a], [b]) => a.localeCompare(b)));
 }
-/**
- * The effective tier overrides for an (agent, version): the `<agent>:*` wildcard
- * merged under the exact `<agent>:<version>` selector (exact wins per-tier).
- */
 export function resolveTierOverrideFrom(all, agent, version) {
     const merged = { ...normalize(all[`${agent}:*`]) };
     if (version) {
@@ -42,14 +36,12 @@ export function resolveTierOverrideFrom(all, agent, version) {
 export function resolveTierOverride(agent, version) {
     return resolveTierOverrideFrom(readMeta().model?.tiers ?? {}, agent, version);
 }
-/** Every configured override entry, sorted by selector (for `agents models tier list`). */
 export function listTierOverrides() {
     const all = readMeta().model?.tiers ?? {};
     return Object.entries(all)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([selector, tiers]) => ({ selector, tiers: normalize(tiers) }));
 }
-/** Pin `tier -> model` for a selector. Writes agents.yaml. */
 export function setTierOverride(selectorInput, tierInput, model) {
     const parsed = parseRunDefaultSelector(selectorInput);
     const tier = parseTier(tierInput);
@@ -65,7 +57,6 @@ export function setTierOverride(selectorInput, tierInput, model) {
     });
     return { selector: parsed.selector, tiers: normalize(readMeta().model?.tiers?.[parsed.selector]) };
 }
-/** Clear one tier (or all tiers when `tierInput` is omitted) for a selector. Returns true if anything changed. */
 export function clearTierOverride(selectorInput, tierInput) {
     const parsed = parseRunDefaultSelector(selectorInput);
     const tier = tierInput ? parseTier(tierInput) : null;
@@ -90,11 +81,6 @@ export function clearTierOverride(selectorInput, tierInput) {
             delete tiers[parsed.selector];
             changed = true;
         }
-        // Drop the emptied container rather than leaving `model: {tiers: {}}` in the
-        // shared agents.yaml — the same discipline lib/hosts/providers/local.ts uses
-        // for an emptied `hosts:`. A vestigial empty map is a real diff on a tracked
-        // file that every machine syncs, so clearing the last override would show up
-        // as a spurious local change on whichever box happened to run the command.
         if (Object.keys(tiers).length > 0) {
             model.tiers = tiers;
             return { ...meta, model };

package/dist/lib/model-tiers.d.ts

@@ -1,60 +1,17 @@
-/**
- * Cost tiers for model selection: cheap / default / best / ultra.
- *
- * An orchestrating agent picks a teammate's model by a stable, cost-first tier
- * instead of a concrete id that churns per release and varies per harness. A
- * tier resolves, per (harness, installed version), to a model that version
- * actually ships — so `--model cheap|default|best|ultra` works on `agents run`
- * and `agents teams add` alike, funnelling through `resolveModel()`.
- *
- * Ranking signal, in priority (see cli/docs — model ranking mechanisms):
- *   1. Provider-declared lineup — the catalog's own family names / descriptions
- *      (opus/sonnet/haiku/fable; Codex "frontier / balanced / fast"). Most
- *      drift-proof: the provider tells us its own ranking.
- *   2. Per-token price (prices.json) — cross-check + the $/Mtok display + budget.
- *   3. Size-token heuristic (nano|mini|lite|flash cheaper; pro|max|opus dearer).
- *   4. Reasoning effort for single-model harnesses (Grok) — tiers steer --effort.
- *
- * The mechanism differs per provider and drifts across versions, so tiers always
- * resolve against the installed version's own catalog.
- */
 import type { AgentId } from './types.js';
 import { type ModelInfo } from './models.js';
-/** The four cross-harness cost tiers, cheapest -> most capable. */
 export declare const MODEL_TIERS: readonly ["cheap", "default", "best", "ultra"];
 export type ModelTier = (typeof MODEL_TIERS)[number];
-/** True if `s` is one of the four tier tokens (not a concrete model id). */
 export declare function isTierToken(s: string | undefined | null): s is ModelTier;
-/** How a single tier resolved for a given (agent, version). */
 export interface TierResolution {
     tier: ModelTier;
-    /** Concrete model id to forward, or null when nothing resolves (fail-safe). */
     model: string | null;
-    /** Reasoning effort to forward, for single-model harnesses where the tier is effort, not model. */
     effort?: string;
-    /** Set when this tier has no rung of its own: the lower tier whose model it borrowed. */
     clampedFrom?: ModelTier;
-    /** Human note (e.g. why it clamped, or that it is a curated/subscription mapping). */
     note?: string;
-    /** Where the model came from: 'auto' ranking, a user 'override', or a 'curated' ladder. */
     source?: 'auto' | 'override' | 'curated';
 }
-/**
- * Resolve all four tiers for an (agent, version) -- what `agents models` prints and
- * `resolveTier` indexes. Precedence: user override -> curated ladder / auto-ranking.
- */
 export declare function resolveTierMap(agent: AgentId, version: string): Record<ModelTier, TierResolution>;
-/**
- * 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 declare function applyTierOverrides(overrides: Partial<Record<ModelTier, string>>, label: string, catalogIds: Set<string> | null, base: Record<ModelTier, TierResolution>): Record<ModelTier, TierResolution>;
-/**
- * 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 declare function tierizeModels(agent: AgentId, models: ModelInfo[]): Record<ModelTier, TierResolution>;
-/** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
 export declare function resolveTier(agent: AgentId, version: string, tier: ModelTier): TierResolution;