@phnx-labs/agents-cli 1.22.6 → 1.22.8

package/dist/lib/model-tiers.js

@@ -124,7 +124,10 @@ function newer(a, b) {
  */
 function rankCatalog(agent, models) {
     const usable = models.filter((m) => !PSEUDO.test(m.id));
-    const aggregator = agent === 'cursor';
+    // 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' || agent === 'pi';
     const scored = usable.map((m) => {
         const rawId = m.id;
         const baseId = aggregator ? normalizeAggregatorId(rawId) : rawId;

package/dist/lib/models.js

@@ -234,6 +234,18 @@ export function locateModelSource(agent, version) {
             return { path: pathBin, kind: 'cli' };
         return null;
     }
+    if (agent === 'pi') {
+        // omp (Oh My Pi) installs via `bun install -g`; a version-managed install
+        // exposes it under node_modules/.bin/omp, otherwise it lives on PATH. We let
+        // the CLI produce its own catalog via `omp models --json` (extractPiCatalog).
+        const cli = path.join(versionDir, 'node_modules', '.bin', 'omp');
+        if (fs.existsSync(cli))
+            return { path: cli, kind: 'cli' };
+        const pathBin = findOnPath('omp');
+        if (pathBin)
+            return { path: pathBin, kind: 'cli' };
+        return null;
+    }
     return null;
 }
 /** Real Grok binaries are ~100MB+; failed-download stubs are tens of bytes. */
@@ -907,6 +919,55 @@ function extractKimiCatalog(binaryPath) {
     }
     return { models, aliases: {} };
 }
+/**
+ * Extract Oh My Pi's catalog via `omp models --json`. omp is a cross-provider
+ * aggregator: its catalog is the union of every provider it has a key for, so
+ * ids are provider-qualified selectors (`anthropic/claude-opus-4-8`,
+ * `openai/gpt-5.2`, `xai/grok-4`, `deepseek/deepseek-chat`, …) — exactly the
+ * `provider/model` convention `ModelInfo.id` already uses. Output shape:
+ *   {"models":[{"provider":"anthropic","id":"claude-opus-4-8",
+ *               "selector":"anthropic/claude-opus-4-8","name":"Claude Opus 4.8",
+ *               "cost":{...}}, ...]}
+ * The catalog is gated per-provider by key presence (no key -> that provider's
+ * models are absent, and an empty env yields `{"models":[]}`). That is truthful:
+ * the extractor surfaces exactly the providers the user has authenticated.
+ * Pricing is attached uniformly by getModelCatalog via getModelPricing(id),
+ * which strips the `provider/` prefix — so no per-catalog price shape here.
+ */
+function extractPiCatalog(binaryPath) {
+    let stdout;
+    try {
+        stdout = execFileSync(binaryPath, ['models', '--json'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 15_000,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return { models: [], aliases: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''));
+    }
+    catch {
+        return { models: [], aliases: {} };
+    }
+    if (!parsed || !Array.isArray(parsed.models))
+        return { models: [], aliases: {} };
+    const models = [];
+    const seen = new Set();
+    for (const m of parsed.models) {
+        // Prefer the provider-qualified selector; fall back to provider/id.
+        const id = m.selector || (m.provider && m.id ? `${m.provider}/${m.id}` : m.id);
+        if (!id || seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({ id, displayName: typeof m.name === 'string' ? m.name : undefined });
+    }
+    return { models, aliases: {} };
+}
 /**
  * Build (or load from cache) the model catalog for a specific (agent, version).
  * Cache is keyed on source-file mtime (binary or js module), so re-extracts
@@ -964,6 +1025,8 @@ export function getModelCatalog(agent, version) {
             ({ models, aliases } = extractKimiCatalog(src.path));
         else if (agent === 'grok')
             ({ models, aliases } = extractGrokCatalog(src.path));
+        else if (agent === 'pi')
+            ({ models, aliases } = extractPiCatalog(src.path));
     }
     // Attach per-token pricing where the offline table knows the model, so the
     // catalog carries $/token for the tier display and budgeting. Subscription /

package/dist/lib/placement.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+/** Where a job body executes. */
+export type PlacementKind = 'local' | 'device' | 'fleet' | 'cloud' | 'lease';
+/**
+ * Canonical placement object.
+ *
+ *   kind: local  — this machine
+ *   kind: device — named box or affinity pick (target: name | "auto")
+ *   kind: fleet  — pick one online device at fire time (routines)
+ *   kind: cloud  — vendor cloud dispatch
+ *   kind: lease  — disposable crabbox (target: optional backend)
+ */
+export interface Placement {
+    kind: PlacementKind;
+    /** Device/host name, "auto", lease backend, or undefined. */
+    target?: string;
+    /** Flag or path that produced this (errors / diagnostics). */
+    source: string;
+}
+/** Run-flag bag the placement parser understands. */
+export interface RunPlacementFlags {
+    where?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    lease?: string | boolean;
+    box?: string;
+}
+export declare class PlacementError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export declare function parseWhereSpec(raw: string, source?: string): Placement;
+/** First non-empty host-family flag value (host / device / on / computer). */
+export declare function hostFamilyTarget(flags: RunPlacementFlags): string | undefined;
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export declare function placementFromRunFlags(flags: RunPlacementFlags): Placement;
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box'>;
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
+/** One-line human form for logs / help. */
+export declare function formatPlacement(p: Placement): string;
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export declare const PLACEMENT_MATRIX: string;

package/dist/lib/placement.js

@@ -0,0 +1,188 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+export class PlacementError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlacementError';
+    }
+}
+const KINDS = new Set(['local', 'device', 'fleet', 'cloud', 'lease', 'host']);
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export function parseWhereSpec(raw, source = '--where') {
+    const spec = raw.trim();
+    if (!spec) {
+        throw new PlacementError(`${source} requires a value (local | device:<name> | auto | lease | cloud | fleet)`);
+    }
+    const lower = spec.toLowerCase();
+    if (lower === 'local')
+        return { kind: 'local', source };
+    if (lower === 'auto')
+        return { kind: 'device', target: 'auto', source };
+    if (lower === 'fleet')
+        return { kind: 'fleet', source };
+    if (lower === 'cloud')
+        return { kind: 'cloud', source };
+    if (lower === 'lease')
+        return { kind: 'lease', source };
+    const colon = spec.indexOf(':');
+    if (colon === -1) {
+        // Bare token that is not a reserved kind → device target.
+        if (KINDS.has(lower)) {
+            // "device" / "host" alone means device with no pin (invalid for run).
+            throw new PlacementError(`${source} ${spec}: name a target (device:<name>, device:auto) or use local|lease|cloud|fleet`);
+        }
+        return { kind: 'device', target: spec, source };
+    }
+    const head = spec.slice(0, colon).toLowerCase();
+    const tail = spec.slice(colon + 1).trim();
+    if (!tail) {
+        throw new PlacementError(`${source} ${spec}: missing target after ':'`);
+    }
+    if (head === 'device' || head === 'host') {
+        return { kind: 'device', target: tail, source };
+    }
+    if (head === 'lease') {
+        return { kind: 'lease', target: tail, source };
+    }
+    if (head === 'cloud') {
+        return { kind: 'cloud', target: tail, source };
+    }
+    if (head === 'fleet') {
+        return { kind: 'fleet', target: tail, source };
+    }
+    throw new PlacementError(`${source} ${spec}: unknown kind '${head}' (use local | device:<name> | auto | lease[:backend] | cloud | fleet)`);
+}
+/** First non-empty host-family flag value (host / device / on / computer). */
+export function hostFamilyTarget(flags) {
+    for (const v of [flags.host, flags.device, flags.on, flags.computer]) {
+        if (v)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export function placementFromRunFlags(flags) {
+    const where = flags.where?.trim();
+    const hostT = hostFamilyTarget(flags);
+    const hasLease = flags.lease !== undefined && flags.lease !== false;
+    const hasBox = !!flags.box;
+    const placementFlags = [];
+    if (where)
+        placementFlags.push('--where');
+    if (hostT)
+        placementFlags.push('--host/--device');
+    if (hasLease)
+        placementFlags.push('--lease');
+    if (hasBox)
+        placementFlags.push('--box');
+    if (placementFlags.length > 1) {
+        throw new PlacementError(`Conflicting placement flags: ${placementFlags.join(' + ')}. ` +
+            `Use one door — prefer --where (device:<name> | auto | lease | local).`);
+    }
+    if (where)
+        return parseWhereSpec(where, '--where');
+    if (hasBox)
+        return { kind: 'lease', target: flags.box, source: '--box' };
+    if (hasLease) {
+        const backend = typeof flags.lease === 'string' ? flags.lease : undefined;
+        return { kind: 'lease', target: backend, source: '--lease' };
+    }
+    if (hostT)
+        return { kind: 'device', target: hostT, source: '--host/--device' };
+    return { kind: 'local', source: 'default' };
+}
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export function expandPlacementToRunFlags(placement) {
+    switch (placement.kind) {
+        case 'local':
+            return {};
+        case 'device':
+            if (!placement.target) {
+                throw new PlacementError(`${placement.source}: device placement needs a target (name or auto)`);
+            }
+            // Canonical host flag; --device is an alias of the same path.
+            return { host: placement.target };
+        case 'lease':
+            // --box reuses a warm slug; --where lease[:backend] / --lease provisions.
+            if (placement.source === '--box')
+                return { box: placement.target };
+            return placement.target ? { lease: placement.target } : { lease: true };
+        case 'fleet':
+            throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
+                `Use --where device:auto for an affinity pick, or --where device:<name>.`);
+        case 'cloud':
+            throw new PlacementError(`cloud placement is agents cloud run (vendor cloud), not agents run. ` +
+                `For a disposable box use --where lease; for your fleet use --where device:<name>.`);
+    }
+}
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export function placementFromHostStrategy(strategy, host) {
+    switch (strategy) {
+        case 'local':
+            return { kind: 'local', source: 'hostStrategy:local' };
+        case 'host':
+            return { kind: 'device', target: host, source: 'hostStrategy:host' };
+        case 'fleet':
+            return { kind: 'fleet', source: 'hostStrategy:fleet' };
+        case 'cloud':
+            return { kind: 'cloud', source: 'hostStrategy:cloud' };
+    }
+}
+/** One-line human form for logs / help. */
+export function formatPlacement(p) {
+    if (p.kind === 'local')
+        return 'local';
+    if (p.target)
+        return `${p.kind}:${p.target}`;
+    return p.kind;
+}
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export const PLACEMENT_MATRIX = `
+  Intent                         Flag / path
+  ─────────────────────────────  ──────────────────────────────────────────
+  This machine                   (default)  or  --where local
+  Named fleet box                --where device:<name>   (= --host / --device)
+  Affinity pick (14d usage)      --where auto            (= --device auto)
+  Disposable cloud box           --where lease           (= --lease)
+  Reuse warm crabbox             --box <slug>
+  Routines: body on one box      --run-on <name> / --placement host
+  Routines: pick any online      --placement fleet
+  Vendor cloud task              agents cloud run …
+  Monitors: who evaluates        --device <owner>   (NOT body placement)
+  Monitors: where action runs    --run-on <host>
+`.trim();

package/dist/lib/profiles.d.ts

@@ -7,6 +7,7 @@
  */
 import type { AgentId } from './types.js';
 import { type Preset } from './profiles-presets.js';
+import { type ModelTier } from './model-tiers.js';
 /** A named profile binding an agent host, env vars, and optional keychain auth. */
 export interface Profile {
     name: string;
@@ -30,9 +31,10 @@ export interface Profile {
     preset?: string;
     provider?: string;
     /**
-     * Human-facing label for the harness — what `agents view` prints as the
-     * agent-type header, the same slot `AGENTS[id].name` fills for a native
-     * harness. Defaults to the profile name when unset.
+     * Stored for backward-compatible YAML parsing only — no longer read for
+     * display. `profileLabel()` always derives the display name from `name` via
+     * the vendor/brand table. Old YAML files that carry this key still parse
+     * correctly; it is simply ignored.
      */
     label?: string;
     /**
@@ -49,6 +51,19 @@ export interface Profile {
      * changes; auth, base URL, and every other profile env value are preserved.
      */
     fallback_model?: string;
+    /**
+     * Per-tier model ids for this harness's OWN catalog, keyed by the same cost
+     * tiers `agents run --model cheap|default|best|ultra` uses for a native
+     * agent. Lets a custom harness (which runs through a host agent's binary,
+     * e.g. `deepseek-flash` hosted on `claude`) resolve a tier against its own
+     * models instead of colliding with the host agent's native catalog
+     * (`resolveTier` in model-tiers.ts, which only knows native agents).
+     * An unset tier clamps to the next CHEAPER tier that IS set (see
+     * `resolveProfileTierModel`). Omitted entirely -> tiers are not supported
+     * for this profile and a requested tier falls back to the harness's single
+     * pinned model, unchanged from before this field existed.
+     */
+    models?: Partial<Record<ModelTier, string>>;
 }
 /**
  * Stable, machine-readable summary used by `agents view` and `--json`.
@@ -57,7 +72,7 @@ export interface Profile {
  */
 export interface ProfileSummary {
     name: string;
-    /** Human-facing header label — `label` when set, else the profile name. */
+    /** Human-facing header label — always derived from `name` via the vendor/brand table. */
     label: string;
     agent: AgentId;
     host: string;
@@ -111,8 +126,12 @@ export declare function profileModelEnvKey(profile: Profile): string | null;
  */
 export declare function profileAuthLabel(profile: Profile): string;
 /**
- * Header label for the harness — the slot `AGENTS[id].name` fills for a native
- * harness, so `agents view` can print custom and native harnesses the same way.
+ * Header label for the harness — derived from `profile.name` by splitting on
+ * `[-_]` and mapping each token through the vendor/brand table. Never reads
+ * the stored `label` field; old YAML files with a `label:` key are unaffected.
+ *
+ * Examples: `deepseek-flash` → `'DeepSeek Flash'`, `spark` → `'Spark'`,
+ * `deepseek_chat_v3` → `'DeepSeek Chat V3'`.
  */
 export declare function profileLabel(profile: Profile): string;
 /** Build a stable, machine-readable summary for list and view surfaces. */
@@ -139,8 +158,6 @@ export interface HostModelOptions {
     /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
     authEnvVar?: string;
     description?: string;
-    /** Human-facing header label; defaults to the harness name. */
-    label?: string;
 }
 /**
  * Build a custom-harness profile from a host CLI + model in one shot, without a
@@ -162,7 +179,6 @@ export interface ForkProfileOptions {
     authEnvVar?: string;
     /** Re-pin (or unpin, with an empty string) the host CLI version. */
     version?: string;
-    label?: string;
     description?: string;
 }
 /**
@@ -171,6 +187,26 @@ export interface ForkProfileOptions {
  * diverge from here and deleting the source never affects the fork.
  */
 export declare function forkProfile(source: Profile, name: string, opts?: ForkProfileOptions): Profile;
+/**
+ * Edit an existing profile in-place, applying overrides without changing its
+ * name or lineage. Reuses {@link forkProfile}'s validation and override logic
+ * (model swap, base-URL validation, auth repoint), then restores the original
+ * `forkedFrom` so an edit never self-references the profile.
+ *
+ * Note: this returns the updated `Profile` object but does NOT write it to
+ * disk — callers should follow up with `writeProfile(result)` if persistence
+ * is needed.
+ */
+export declare function editProfile(source: Profile, opts?: ForkProfileOptions): Profile;
+/**
+ * Rename a profile on disk, then rewrite `forkedFrom` in every other profile
+ * that pointed at the old name so lineage display never goes stale.
+ *
+ * Throws if `oldName` does not exist or `newName` already exists. There is no
+ * `--force` / overwrite path — a collision is a hard error directing the user
+ * to remove the target first.
+ */
+export declare function renameProfile(oldName: string, newName: string): void;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the
@@ -193,13 +229,40 @@ export interface ResolvedProfileRun {
         envKey: string;
         model: string;
     };
+    /**
+     * Set when the caller requested a cost tier (`--model cheap|default|...`)
+     * but this profile has no `models:` entry to resolve it against (not even a
+     * cheaper tier to clamp to). `env` is returned unmodified — the harness's
+     * single pinned model — and this note is informational only, matching the
+     * "using harness default" convention exec.ts's native tier block already
+     * uses; the caller prints it, it never throws.
+     */
+    tierNote?: string;
+    /**
+     * Set when `requestedModel` was a tier token AND this profile resolved it
+     * against its own `models:` map. Callers that forward a `--model` value
+     * downstream (e.g. as `ExecOptions.model`) should substitute this in place
+     * of the original tier token — exec.ts's native tier block only knows how
+     * to resolve a tier against the HOST agent's own catalog, which is the
+     * wrong catalog for a profile's own harness identity. Undefined both when
+     * no tier was requested and when tier resolution degraded (see `tierNote`).
+     */
+    resolvedModel?: string;
 }
 /**
  * Resolve a name into (agent, version, env). Throws if the name is not a
  * profile. Callers are expected to try agent-id resolution first and fall
  * back to this when that fails, so we don't need a "isProfile" probe.
+ *
+ * `requestedModel` is the caller's raw `--model` value. When it is a cost-tier
+ * token (`cheap`/`default`/`best`/`ultra`), it is resolved against the
+ * profile's OWN `models:` map (see `resolveProfileTierModel`) and substituted
+ * into `env` as a concrete model id BEFORE returning — so exec.ts's native
+ * tier-resolution block (which indexes the HOST agent's catalog, e.g. Claude's
+ * own models) never sees a tier token for a profile-based run, and can't
+ * collide the profile's harness identity with its host's catalog.
  */
-export declare function resolveProfileForRun(name: string): ResolvedProfileRun;
+export declare function resolveProfileForRun(name: string, requestedModel?: string): ResolvedProfileRun;
 /**
  * Look up the preset a profile was created from, if any. Used by
  * `profiles view` to show upstream metadata like signup URLs.