@phantomcodes/cli 1.2.7 → 1.2.8

package/README.md

@@ -70,7 +70,9 @@ pi gets the agent skill.
 
 Preview without changing files with `phantom setup --dry-run`. To leave your
 shell startup file alone, untick "Your shell" in the checklist or pass
-`--no-shell`; setup then prints the lines to add yourself. The Phantom CLI keeps backups;
+`--no-shell`; setup then prints the lines to add yourself. Cap what the key can spend each
+month with `phantom setup --limit 20` (`--limit none` removes it); at a terminal,
+setup asks once when the key has no cap. The Phantom CLI keeps backups;
 undo the changes with `phantom setup --restore`.
 
 ## Connect for one run
@@ -180,6 +182,7 @@ it cancels. A named model, not `phantom-1`, still spends credit.
 | --- | --- |
 | Connect | `phantom login`, `phantom logout` |
 | Connect existing agents | `phantom setup`, `phantom setup --dry-run`, `phantom setup --restore` |
+| Providers that answer soonest | `phantom route set --sort fast` (`--sort default` for cheapest first) |
 | Run inference | `phantom claude`, `phantom codex`, `phantom pi` |
 | Fund and check spending | `phantom fund`, `phantom balance`, `phantom spend`, `phantom workspace status` |
 | Manage workspace keys | `phantom keys create`, `phantom keys set`, `phantom keys rotate`, `phantom keys revoke` |

package/dist/cli/commands.mjs

@@ -119,6 +119,9 @@ export const COMMANDS = [
         name: 'route', handler: routeCommand,
         group: 'Routing', summary: 'which models "auto" runs, and rules for picking',
         help: `  route [get]                       show which model "auto" runs, and why
+  route set --sort fast|cheap|throughput|default
+                                    which providers serve this key's models first: fast
+                                    starts answering soonest; cheap is the default
   route set --models a,b,c          models for "auto", first is the default
             [--applies-to auto|all] [--on-empty stop|cheapest] [--fallback]
             [--stick-minutes n]  keep a conversation's model this long (default 5)
@@ -162,6 +165,7 @@ export const COMMANDS = [
         [--diff]                    show every line each file gains or loses
         [--no-shell]                leave your shell startup file alone and list
                                     the lines to add yourself
+        [--limit <USD|none>]        cap what this key can spend each month
         [--json]                    print JSON in a terminal too (a pipe always gets JSON)
         [--model <id>]              the model each agent starts on (default ${SETUP_MODEL})
   setup --agent <name>              install the skill for one agent, without asking:

package/dist/cli/screens.mjs

@@ -178,12 +178,15 @@ export function routeScreen(r, style = {}) {
     const w = ruleWidth(style);
     const lines = ['', ...caption(p, w, 'ROUTING', p.dim('how model "auto" picks for this key'))];
     const policy = r.route_policy;
-    if (!policy) {
-        lines.push('  No route policy, so model "auto" runs phantom-1, which picks a model for each request.');
-        lines.push(...next(p, 'Make one:', 'phantom route set --models a,b,c'));
+    const row = (label, value) => `  ${p.dim(label.padEnd(14))}${value}`;
+    // Which providers serve first holds for every request, routed or not.
+    const sortWords = { cost: 'cheapest first', ttft: 'fastest to start answering first', tps: 'most tokens a second first' };
+    const providers = row('providers', `${sortWords[policy?.sort ?? 'cost']}${policy?.sort ? '' : p.dim('  (the default)')}${policy?.zdr ? ', zero data retention only' : ''}${policy?.no_training ? ', no training on prompts' : ''}`);
+    if (!policy || !policy.models.length) {
+        lines.push('  No route policy, so model "auto" runs phantom-1, which picks a model for each request.', '', providers);
+        lines.push(...(policy?.sort ? next(p, 'Back to cheapest first:', 'phantom route set --sort default') : next(p, 'Providers that start answering soonest:', 'phantom route set --sort fast')));
         return lines.join('\n');
     }
-    const row = (label, value) => `  ${p.dim(label.padEnd(14))}${value}`;
     // One model a line, in the order "auto" tries them, so a long list doesn't wrap.
     policy.models.forEach((m, k) => lines.push(row(k === 0 ? 'models' : '', `${p.dim(`${k + 1}.`)} ${k === 0 ? `${p.bold(m)}  ${p.dim('the default')}` : m}`)));
     lines.push(row('applies to', policy.applies_to === 'all' ? 'every request' : 'requests for model "auto"'));
@@ -191,6 +194,7 @@ export function routeScreen(r, style = {}) {
     lines.push(row('a model fails', policy.fallback_on_error ? 'try the next one' : 'stop there'));
     const stick = policy.stick_minutes ?? 5;
     lines.push(row('conversations', stick ? `stay on their model for ${plural(stick, 'minute')}${policy.stick_by_prompt === false ? ' (by x-phantom-session only)' : ''}` : 'can change model every request'));
+    lines.push(providers);
     const rules = policy.rules ?? [];
     lines.push('', ...caption(p, w, 'RULES', p.dim(rules.length ? 'checked in order; the first that matches picks' : '')));
     if (!rules.length)

package/dist/core/version.mjs

@@ -1,2 +1,2 @@
 /** This release of phantom. `npm version` keeps it equal to the version in package.json. */
-export const VERSION = '1.2.7';
+export const VERSION = '1.2.8';

package/dist/setup/command.mjs

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline/promises';
 import { die } from "../core/errors.mjs";
 import { out, pickIo } from "../core/helpers.mjs";
 import { BackToMenu, checklist, choose } from "../core/pick.mjs";
+import { request } from "../core/request.mjs";
 import { resolveApiKey } from "../keys/saved.mjs";
 import { workspaceLogin } from "../workspace/command.mjs";
 import { SETUP_AGENTS, SETUP_NAMES } from "./agents.mjs";
@@ -104,6 +105,8 @@ export async function setupCommand(input) {
     // Plain `phantom setup` sets up everything it finds and asks first. Any of
     // the older flags runs just what they name, without asking.
     const guided = agent === undefined && provider === undefined;
+    // Checked before anything is written, so a typo in --limit changes nothing.
+    const limit = capFlag(flags['limit']);
     // With no key yet, sign in first, as phantom claude does, so the agents
     // get one in this run. Its words go to stderr; stdout stays setup's result.
     if (guided && !dryRun && io.isTTY && !resolveApiKey(env)) {
@@ -196,7 +199,7 @@ export async function setupCommand(input) {
                 }
                 break;
             }
-            return finish(applySetup(env, plan));
+            return capAfter(input, await finish(applySetup(env, plan)), limit, guided ? pick : null);
         }
         const ask = io.ask ??
             (process.stdin.isTTY
@@ -219,5 +222,49 @@ export async function setupCommand(input) {
             return 0;
         }
     }
-    return finish(applySetup(env, plan));
+    return capAfter(input, await finish(applySetup(env, plan)), limit, null);
+}
+/** `--limit`: dollars a month above zero, `none` to remove the cap, or undefined when it isn't given. */
+function capFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'none')
+        return null;
+    const usd = Number(String(value).replace(/^\$/, ''));
+    if (typeof value !== 'string' || !Number.isFinite(usd) || usd <= 0)
+        die('--limit takes dollars a month above zero, such as 20, or none', 'setup_limit');
+    return usd;
+}
+/**
+ * After setup has written its files: the key's monthly spend cap (PATCH
+ * /key/budget, a calendar month). `--limit` sets it; without one, setup at a
+ * terminal asks once, only when the key has no cap yet. Returns setup's exit code.
+ */
+async function capAfter(input, code, limit, pick) {
+    const { env, io, baseUrl } = input;
+    const apiKey = resolveApiKey(env);
+    if (!apiKey || (limit === undefined && !pick))
+        return code;
+    let cap = limit;
+    if (cap === undefined) {
+        const now = await request('GET', '/key/budget', apiKey, undefined, baseUrl).catch(() => null);
+        if (!now || now.budget_usd !== null)
+            return code;
+        io.stderr('\n');
+        const answer = await choose(pick, 'Cap what this key can spend each month?', [
+            { label: 'No cap', hint: 'free use is never charged', value: 0 },
+            { label: '$10 a month', value: 10 },
+            { label: '$25 a month', value: 25 },
+            { label: '$50 a month', value: 50 },
+        ]);
+        if (!answer)
+            return code;
+        cap = answer;
+    }
+    await request('PATCH', '/key/budget', apiKey, cap === null ? { budget_usd: null } : { budget_usd: cap, period_days: null }, baseUrl);
+    const p = paint(env, colorOn(env, io.isTTY));
+    io.stderr(cap === null
+        ? `  ${p.lime('✓')} This key has no monthly cap now.\n`
+        : `  ${p.lime('✓')} This key can spend at most $${cap} a month. Change it any time: ${p.cyan('phantom setup --limit <USD|none>')}\n`);
+    return code;
 }

package/dist/spend/command.mjs

@@ -6,7 +6,7 @@ import { colorOn, paint } from "../core/style.mjs";
 import { choose } from "../core/pick.mjs";
 import { hideHints, lineupScreen, priceHint, routeScreen, routeTestScreen, TIER_ABOUT } from "../cli/screens.mjs";
 import { getLineup, putLineup, resetLineup, LINEUP_TIERS } from "./lineup.mjs";
-import { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition } from "./routing.mjs";
+import { getRoute, putRoute, patchRoute, clearRoute, testRoute, parseCondition, SORT_WORDS } from "./routing.mjs";
 /** `phantom route`: the key's route policy, its rules, and a dry run. Run by `run()`. */
 export async function routeCommand(input) {
     const { argv, io, apiKey, subcommand, flags, baseUrl, env } = input;
@@ -44,11 +44,28 @@ export async function routeCommand(input) {
                 fields.stick_minutes = stick;
             if (flags['stick-by-prompt'] !== undefined)
                 fields.stick_by_prompt = flags['stick-by-prompt'] !== 'false';
-            if (Object.keys(fields).length === 0) {
-                die('route set needs --models a,b,c, --applies-to, --on-empty, --fallback, --stick-minutes, --stick-by-prompt, or --file policy.json');
+            const sort = flags['sort'];
+            if (sort !== undefined && (typeof sort !== 'string' || !(sort in SORT_WORDS || sort === 'default'))) {
+                die('--sort takes fast (quickest to start answering), cheap (the default), throughput (most tokens a second) or default', 'route_usage');
+            }
+            if (typeof sort === 'string' && sort !== 'default')
+                fields.sort = SORT_WORDS[sort];
+            if (Object.keys(fields).length === 0 && sort !== 'default') {
+                die('route set needs --models a,b,c, --sort, --applies-to, --on-empty, --fallback, --stick-minutes, --stick-by-prompt, or --file policy.json');
             }
             const current = (await getRoute(apiKey, baseUrl)).route_policy;
-            const result = current ? await patchRoute(apiKey, fields, baseUrl) : await putRoute(apiKey, fields, baseUrl);
+            let result;
+            if (sort === 'default') {
+                // Back to cheapest first: drop sort, and the whole policy when sort was all it held.
+                const { sort: _was, ...rest } = { ...(current ?? { models: [] }), ...fields };
+                void _was;
+                const empty = !rest.models.length && !rest.zdr && !rest.no_training && !(rest.rules ?? []).length;
+                result = !current ? { route_policy: null } : empty ? await clearRoute(apiKey, baseUrl) : await putRoute(apiKey, rest, baseUrl);
+            }
+            else {
+                // A key with no policy gets one of preferences only, which routes nothing, unless --models is given too.
+                result = current ? await patchRoute(apiKey, fields, baseUrl) : await putRoute(apiKey, { models: [], ...fields }, baseUrl);
+            }
             out(result, table, tableRoute, io.stdout);
         }
     }

package/dist/spend/routing.mjs

@@ -1,5 +1,7 @@
 import { die } from "../core/errors.mjs";
 import { request } from "../core/request.mjs";
+/** The words `phantom route set --sort` takes, and the server's name for each. The server's own names work too. */
+export const SORT_WORDS = { cheap: 'cost', fast: 'ttft', throughput: 'tps', cost: 'cost', ttft: 'ttft', tps: 'tps' };
 /** The key's route policy (GET /key/route). */
 export function getRoute(apiKey, baseUrl) {
     return request('GET', '/key/route', apiKey, undefined, baseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantomcodes/cli",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "AI inference for your coding agents. Route models, control spending, and fund your workspace.",
   "keywords": [
     "phantom",