lobstack 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,7 @@
 # lobstack
 
-One key, every model, and what each call cost.
+The Lobstack API from your terminal: one key, every model, and what each call
+cost.
 
 ```bash
 npx lobstack init
@@ -60,7 +61,7 @@ worse than not having it.
 | | |
 |---|---|
 | `/model [name]` | set the model, or open the picker |
-| `/models` | what the gateway will serve, with prices |
+| `/models` | what the API will serve, with prices. `auto` — Nex 1, the router — is first, priced `—` because it costs whatever it picks |
 | `/spend [days]` | what you have actually spent, from the usage API |
 | `/receipt` | every field of the last receipt, verbatim, plus the session tally |
 | `/proxy [port]` | serve the OpenAI-compatible endpoint from this process |
@@ -101,11 +102,11 @@ your shell reading mouse packets as keystrokes. Nothing here needs a mouse.
 |---|---|
 | `lobstack init` | Save a key to `~/.lobstack/config.json`, mode 0600. Verifies it before writing. |
 | `lobstack chat "<prompt>"` | One call, streamed. Answer to stdout, receipt to stderr, so `> out.txt` gives you the answer alone. |
-| `lobstack models` | What the gateway will serve, with prices. |
-| `lobstack spend [--days 7]` | What you have spent. Needs a key with the `usage:read` scope. |
+| `lobstack models` | What the API will serve, with prices. `auto` — Nex 1 — leads the list with no price of its own. Also public at <https://www.lobstack.ai/models>. |
+| `lobstack spend [--days 7]` | What you have spent: the billing ledger's total, the same figure the Console shows, with routing savings as two separate figures. Needs a key with the `usage:read` scope. |
 | `lobstack proxy [--port 8787]` | A local OpenAI-compatible endpoint. |
 
-Flags: `--model` (default `auto`), `--key`, `--base`, `--json`, `--force`.
+Flags: `--model` (default `auto`, which is **Nex 1**, the router), `--key`, `--base`, `--json`, `--force`.
 `LOBSTACK_API_KEY` and `LOBSTACK_BASE_URL` win over the saved config.
 
 ## The proxy
@@ -157,12 +158,12 @@ window title. Escapes are removed, not rendered.
 
 ## Cost is read, never computed
 
-The gateway puts the price on the final SSE frame under `x_lobstack`, because on
+The Lobstack API puts the price on the final SSE frame under `x_lobstack`, because on
 a streamed response the headers are written before the provider has counted a
 token. This CLI reads that number. It does not multiply token counts by a
 bundled rate card — our own desktop client did exactly that, and printed
 `$0.00` for three months next to a correct invoice, because its copy of the
-rate card knew six models and the gateway serves far more.
+rate card knew six models and the API serves several times that.
 
 That is also why the UI shows no running dollar figure *during* a stream. Until
 the last frame lands there is no price to show, so it shows elapsed time and how
@@ -170,13 +171,13 @@ much text arrived, and says the price is still coming.
 
 Three rules follow, and they hold on every screen:
 
-- `cost_usd` is `null`, never `0`, when the gateway could not price a call. That
+- `cost_usd` is `null`, never `0`, when the API could not price a call. That
   prints `unpriced`. A zero renders as "free", and writing off a real charge is
   the most expensive way to be wrong about money. A session whose calls were all
   unpriced shows `unpriced` as its total, not `$0.000000`; a session with some of
   each shows the priced total and counts the rest out loud — `+1 unpriced`.
 - `saved` means the router beat a model **you named**. `vs ceiling` means you
-  sent `auto` and the gateway measured against the priciest model your plan
+  sent `auto` and the API measured against the priciest model your plan
   allows. `baseline_reason` says which, the receipt says which, and the two are
   separate running totals that are never added together.
 - No figure is ever truncated to fit.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lobstack",
-  "version": "0.1.1",
-  "description": "The Lobstack Gateway from your terminal: one key, every model, and what each call cost.",
+  "version": "0.1.3",
+  "description": "The Lobstack API from your terminal: one key, every model, and what each call cost.",
   "type": "module",
   "bin": {
     "lobstack": "./src/index.mjs"
@@ -20,7 +20,8 @@
     "anthropic",
     "proxy",
     "cli",
-    "lobstack"
+    "lobstack",
+    "lobstack-api"
   ],
   "license": "MIT",
   "repository": {

package/src/gateway.mjs

@@ -41,7 +41,7 @@ export async function gwFetch(url, key, init = {}) {
     // good key with "missing credentials" - the failure that made this look
     // broken for three months.
     throw new GatewayError(
-      `the gateway redirected to ${res.headers.get('location') || 'somewhere else'}.`,
+      `the Lobstack API redirected to ${res.headers.get('location') || 'somewhere else'}.`,
       'A redirect strips your key. Point --base at the host that answers directly.',
     );
   }

package/src/index.mjs

@@ -22,7 +22,7 @@
  */
 
 import { readConfig, writeConfig, resolveKey, resolveBase, gatewayUrl, CONFIG_PATH } from './config.mjs';
-import { printReceipt, dim, bold, green, money, fail } from './render.mjs';
+import { printReceipt, dim, bold, green, money, fail, spendReport } from './render.mjs';
 import { gwFetch, errorText, fetchModels, fetchUsage, streamCompletion } from './gateway.mjs';
 import { startProxy } from './proxy.mjs';
 import { detect } from './tty.mjs';
@@ -35,14 +35,14 @@ const HELP = `${bold('lobstack')} - one key, every model, and what each call cos
   ${bold('lobstack')}                       the interactive UI: watch the cost as it happens
   ${bold('lobstack init')}                  save an API key to ${CONFIG_PATH}
   ${bold('lobstack chat')} "<prompt>"       one call, streamed, with the receipt
-  ${bold('lobstack models')}                what the gateway will serve, and at what price
+  ${bold('lobstack models')}                what the Lobstack API will serve, and at what price
   ${bold('lobstack spend')} [--days 7]      what you have spent, from the usage API
   ${bold('lobstack proxy')} [--port 8787]   a local OpenAI-compatible endpoint
 
 ${dim('Options')}
   --model <key>     default: auto (let the router choose)
   --key <lsk_...>   override the saved key for one command
-  --base <url>      override the gateway host
+  --base <url>      override the Lobstack API host
   --json            machine-readable output where it makes sense
   --force           draw the UI even where the streams do not look like a terminal
 
@@ -141,7 +141,7 @@ async function cmdInit(flags) {
   const b = base(flags);
   process.stdout.write(dim('checking the key...\n'));
   const res = await gwFetch(gatewayUrl(b, '/models'), key);
-  if (!res.ok) fail(`the gateway rejected that key: ${await errorText(res)}`);
+  if (!res.ok) fail(`the Lobstack API rejected that key: ${await errorText(res)}`);
 
   writeConfig({ ...readConfig(), key, baseUrl: b });
   process.stdout.write(
@@ -213,18 +213,13 @@ async function cmdSpend(flags) {
     fail(body.message || 'usage reporting is not enabled on this deployment.');
   }
 
-  const s = body.summary || {};
+  const r = spendReport(body, days);
   process.stdout.write(
-    `${bold(`Last ${days} days`)}  ${dim('-')}  ` +
-      `${s.requests ?? 0} requests  ${dim('-')}  ${money(Number(s.cost_usd ?? 0))}` +
-      (Number(s.savings_usd ?? 0) > 0 ? `  ${dim('-')}  saved ${green(money(Number(s.savings_usd)))}` : '') +
-      '\n\n',
+    `${bold(r.head.charAt(0).toUpperCase() + r.head.slice(1))}\n\n` +
+      r.rows.map((row) => `${row}\n`).join('') +
+      (r.savings.length ? `\n${r.savings.map((l) => `  ${l.startsWith('saved') ? green(l) : l}\n`).join('')}` : '') +
+      (r.notes.length ? `\n${r.notes.map((l) => dim(`  ${l}\n`)).join('')}` : ''),
   );
-  for (const g of body.groups ?? []) {
-    process.stdout.write(
-      `  ${String(g.key ?? '').padEnd(24)} ${String(g.requests ?? 0).padStart(6)}  ${money(Number(g.cost_usd ?? 0))}\n`,
-    );
-  }
 }
 
 /* ── tui ───────────────────────────────────────────────────────────────── */
@@ -359,7 +354,7 @@ try {
   }
 } catch (err) {
   // `hint` is how gateway.mjs carries the second line of an error message out
-  // of a throw. Without it a redirect would report "the gateway redirected"
+  // of a throw. Without it a redirect would report "the Lobstack API redirected"
   // and lose the sentence explaining that a redirect strips your key.
   fail(err instanceof Error ? err.message : String(err), err?.hint);
 }

package/src/render.mjs

@@ -38,6 +38,86 @@ export function savingsLabel(receipt) {
   return { label: named ? 'saved' : 'vs ceiling', named, amount };
 }
 
+/**
+ * `/api/v1/usage`, as lines of text, for `lobstack spend` and the TUI's /spend.
+ *
+ * THE TOTAL IS THE CONSOLE'S. The endpoint returns two totals of one quantity:
+ * `spend.cost_usd`, from the billing ledger the Console's Spend shows and
+ * invoices are cut from, and `summary.cost_usd`, the request trace's own copy
+ * of each price, kept for older callers. They are written separately and can
+ * disagree. The ledger's figure is used, and each group's `ledger_cost_usd`;
+ * the trace's copy only when the ledger figure is null (it could not be read)
+ * or absent (an older deployment), and a note says so.
+ *
+ * SAVINGS ARE TWO FIGURES. `savings.named` is measured against models the
+ * caller asked for; `savings.plan_ceiling` is what `auto` requests would have
+ * cost on the priciest model the plan allows, which nobody asked for. They are
+ * printed on separate lines and never added together.
+ *
+ * Plain strings, no colour, so both renderers can use them.
+ *
+ * @returns {{head: string, rows: string[], savings: string[], notes: string[]}}
+ */
+export function spendReport(body, days) {
+  const s = body?.summary || {};
+  const ledger = body?.spend && typeof body.spend === 'object' ? body.spend : null;
+  const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+  const fromLedger = ledger !== null && isNum(ledger.cost_usd);
+  const cost = fromLedger ? ledger.cost_usd : isNum(s.cost_usd) ? s.cost_usd : null;
+  const unpriced = fromLedger ? ledger.unpriced_rows ?? 0 : s.unpriced_requests ?? 0;
+  const priceable = fromLedger ? ledger.rows ?? 0 : s.requests ?? 0;
+  const costText = priceable > 0 && unpriced >= priceable ? 'unpriced' : money(cost);
+  const n = (count, one) => `${count} ${one}${count === 1 ? '' : 's'}`;
+
+  // The window the server actually summed. It answers an unknown range with
+  // 7d, so `--days 5` is labelled for what came back, not what was asked.
+  const served = typeof body?.range === 'string' ? body.range : `${days}d`;
+  const label = served === 'month' ? 'this month' : /^\d+d$/.test(served) ? `last ${parseInt(served, 10)} days` : `last ${days} days`;
+  const head = `${label}: ${n(s.requests ?? 0, 'request')}, ${costText}`;
+  const rows = (body?.groups ?? []).map((g) => {
+    const gCost = isNum(g.ledger_cost_usd) ? g.ledger_cost_usd : isNum(g.cost_usd) ? g.cost_usd : null;
+    const gUnpriced = isNum(g.ledger_cost_usd) ? g.ledger_unpriced_rows ?? 0 : g.unpriced_requests ?? 0;
+    return (
+      `  ${String(g.key ?? '').padEnd(24)} ${String(g.requests ?? 0).padStart(6)}  ${money(gCost)}` +
+      (gUnpriced ? `  (${gUnpriced} unpriced)` : '')
+    );
+  });
+
+  const savings = [];
+  const named = body?.savings?.named;
+  const ceiling = body?.savings?.plan_ceiling;
+  if (named && named.requests > 0 && isNum(named.difference_usd)) {
+    savings.push(
+      named.difference_usd < 0
+        ? `routing cost ${money(-named.difference_usd)} more than the models you named, on ${n(named.requests, 'request')}`
+        : `saved ${money(named.difference_usd)} on models you named, on ${n(named.requests, 'request')}`,
+    );
+  }
+  if (ceiling && ceiling.requests > 0 && isNum(ceiling.difference_usd)) {
+    savings.push(
+      `vs ceiling ${money(ceiling.difference_usd)} on ${n(ceiling.requests, 'auto request')} - ` +
+        'compared with the best model your plan allows, which you did not ask for; not a saving',
+    );
+  }
+
+  const notes = [];
+  if (!fromLedger) {
+    notes.push(
+      (ledger === null && body && 'spend' in body
+        ? 'the billing ledger could not be read'
+        : 'this deployment does not report the billing ledger') +
+        ", so this total is the request trace's copy of each price (the legacy summary.cost_usd) and can differ from the Console",
+    );
+  }
+  if (unpriced > 0) {
+    notes.push(`${n(unpriced, fromLedger ? 'row' : 'request')} could not be priced, so the total is a floor, not a total`);
+  }
+  if (body?.truncated || (fromLedger && ledger.truncated)) {
+    notes.push('the row cap bound on this range, so older requests are not counted');
+  }
+  return { head, rows, savings, notes };
+}
+
 /**
  * Print the receipt.
  *
@@ -71,7 +151,7 @@ export function printReceipt({ receipt, usage, model }) {
     );
   }
   if (receipt && receipt.priced === false) {
-    process.stderr.write(dim('  the gateway could not price this model, so no cost is claimed\n'));
+    process.stderr.write(dim('  the Lobstack API could not price this model, so no cost is claimed\n'));
   }
   if (!receipt) {
     // An older Gateway, or a non-Lobstack base URL. Say so rather than

package/src/stream.mjs

@@ -54,7 +54,7 @@ export async function consume(body, onText) {
       continue; // a half-frame is not worth ending a turn over
     }
     if (frame.error) {
-      throw new Error(frame.error.message || 'the gateway reported an error mid-stream');
+      throw new Error(frame.error.message || 'the Lobstack API reported an error mid-stream');
     }
     if (frame.model) model = frame.model;
     if (frame.usage) usage = frame.usage;

package/src/tui-view.mjs

@@ -273,8 +273,8 @@ function caveatRow(r, saving, w) {
   }
   if (r && r.priced === false) {
     return pick([
-      '   the gateway could not price this model, so no cost is claimed',
-      '   gateway could not price this model',
+      '   the Lobstack API could not price this model, so no cost is claimed',
+      '   the API could not price this model',
     ]);
   }
   if (!r) {
@@ -362,7 +362,7 @@ const KEYS = [
 
 const COMMANDS = [
   ['/model [name]', 'set the model, or open the picker'],
-  ['/models', 'what the gateway will serve, with prices'],
+  ['/models', 'what the Lobstack API will serve, with prices'],
   ['/spend [days]', 'what you have actually spent, from the usage API'],
   ['/receipt', 'every field of the last receipt, verbatim'],
   ['/proxy [port]', 'serve the OpenAI-compatible endpoint here, and watch it bill'],

package/src/tui.mjs

@@ -19,7 +19,7 @@
 
 import { createInterface } from 'node:readline/promises';
 import { streamCompletion, fetchModels, fetchUsage, GatewayError } from './gateway.mjs';
-import { printReceipt, money, savingsLabel } from './render.mjs';
+import { printReceipt, money, savingsLabel, spendReport } from './render.mjs';
 import { startProxy } from './proxy.mjs';
 import { Terminal, detect, styler, MIN_WIDTH } from './tty.mjs';
 import { frame, newSession, accrue } from './tui-view.mjs';
@@ -55,7 +55,7 @@ class Tui {
         {
           role: 'system',
           text:
-            'Every answer here comes back with a receipt: what the gateway served, what it ' +
+            'Every answer here comes back with a receipt: what the Lobstack API served, what it ' +
             'cost, and what the routing decision saved. Type a prompt, or /help.',
         },
       ],
@@ -494,21 +494,17 @@ class Tui {
       this.say('error', body.message || 'usage reporting is not enabled on this deployment.');
       return;
     }
-    const sum = body.summary || {};
-    // Same rule as everywhere else: a saving the gateway measured against a
-    // plan ceiling is not the same claim as one against a model you named. The
-    // usage API reports a single figure, so it is labelled for what it is
-    // rather than being called a saving outright.
-    const head =
-      `last ${days} days: ${sum.requests ?? 0} requests, ${money(Number(sum.cost_usd ?? 0))}` +
-      (Number(sum.savings_usd ?? 0) > 0
-        ? `, routing saved ${money(Number(sum.savings_usd))} against the baselines the gateway recorded`
-        : '');
-    const rows = (body.groups ?? []).map(
-      (g) =>
-        `  ${String(g.key ?? '').padEnd(24)} ${String(g.requests ?? 0).padStart(6)}  ${money(Number(g.cost_usd ?? 0))}`,
+    // The Console's figure, and the two savings figures kept apart. See spendReport.
+    const r = spendReport(body, days);
+    this.say(
+      'system',
+      [
+        r.head,
+        ...r.rows,
+        ...(r.savings.length ? ['', ...r.savings.map((l) => `  ${l}`)] : []),
+        ...(r.notes.length ? ['', ...r.notes.map((l) => `  ${l}`)] : []),
+      ].join('\n'),
     );
-    this.say('system', [head, ...rows].join('\n'));
   }
 
   showReceipt() {