lobstack 0.1.1

package/src/index.mjs

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+/**
+ * lobstack — the Gateway from a terminal.
+ *
+ *   npx lobstack                    the interactive UI, when there is a
+ *                                   terminal on both ends and a key to use
+ *   npx lobstack tui                the same thing, asked for by name
+ *   npx lobstack init
+ *   npx lobstack chat "say hello"
+ *   npx lobstack models
+ *   npx lobstack spend
+ *   npx lobstack proxy
+ *
+ * Zero dependencies, on purpose. `fetch`, `node:http` and `node:readline` are
+ * all in the runtime, so `npx lobstack` starts immediately instead of resolving
+ * a tree first — and there is no supply chain between a user's key and us.
+ *
+ * That still holds with a full-screen UI in the box. `node:readline` already
+ * has the escape-sequence decoder, and the rest of a TUI is nine escape
+ * sequences written by hand in tty.mjs. A process that holds an `lsk_live_`
+ * credential does not get to pull a dependency tree to draw a box.
+ */
+
+import { readConfig, writeConfig, resolveKey, resolveBase, gatewayUrl, CONFIG_PATH } from './config.mjs';
+import { printReceipt, dim, bold, green, money, fail } from './render.mjs';
+import { gwFetch, errorText, fetchModels, fetchUsage, streamCompletion } from './gateway.mjs';
+import { startProxy } from './proxy.mjs';
+import { detect } from './tty.mjs';
+import { runTui, runLineMode, readAll } from './tui.mjs';
+import { createInterface } from 'node:readline/promises';
+import { readFileSync } from 'node:fs';
+
+const HELP = `${bold('lobstack')} - one key, every model, and what each call cost.
+
+  ${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 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
+  --json            machine-readable output where it makes sense
+  --force           draw the UI even where the streams do not look like a terminal
+
+${dim('Environment')}
+  LOBSTACK_API_KEY, LOBSTACK_BASE_URL - both win over the saved config.
+  NO_COLOR, TERM=dumb, LOBSTACK_ASCII - all respected.
+`;
+
+/**
+ * Read from package.json rather than declared here.
+ *
+ * A version constant beside a version field is two places to bump and one
+ * place to forget; `npm version` writes the manifest and nothing else, so the
+ * manifest is the one that is always right.
+ */
+const VERSION = (() => {
+  try {
+    return JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    ).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+
+/**
+ * Flags that take no value. Everything else consumes the next argument.
+ *
+ * `help` and `version` have to be in here, and their absence was not a
+ * cosmetic bug. Anything not listed swallows the next argv item, so
+ * `lobstack chat --version "hi"` ate the prompt and answered "nothing to
+ * send", and a bare `--help` fell through to the no-command branch — which, in
+ * a terminal with a key saved, opens the chat UI instead of printing anything.
+ * `npx lobstack --help` is the first thing a new user types.
+ */
+const BOOLEAN_FLAGS = new Set(['json', 'force', 'help', 'version']);
+
+function parseArgs(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--') && BOOLEAN_FLAGS.has(a.slice(2))) out.flags[a.slice(2)] = true;
+    else if (a.startsWith('--')) out.flags[a.slice(2)] = argv[++i];
+    else out._.push(a);
+  }
+  return out;
+}
+
+function requireKey(flags) {
+  const key = flags.key || resolveKey();
+  if (!key) {
+    fail(
+      'no API key.',
+      'Run `lobstack init`, or set LOBSTACK_API_KEY. Get a key at https://www.lobstack.ai/start',
+    );
+  }
+  return key;
+}
+
+function base(flags) {
+  const { base: b, corrected } = resolveBase(flags.base);
+  if (corrected) {
+    // Not a silent fix. The apex redirects to www, and every HTTP client drops
+    // Authorization when a redirect changes host, so honouring what was typed
+    // would answer a valid key with "missing credentials" - which is precisely
+    // the bug that made this gateway look broken for three months.
+    process.stderr.write(
+      dim(`- using ${b} - the bare domain redirects, and a redirect drops your Authorization header\n`),
+    );
+  }
+  return b;
+}
+
+/* ── init ──────────────────────────────────────────────────────────────── */
+
+async function cmdInit(flags) {
+  let key = flags.key;
+  if (!key) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    process.stdout.write(
+      `Get a key at ${bold('https://www.lobstack.ai/start')} - it is free and takes a minute.\n\n`,
+    );
+    key = (await rl.question('Paste your key (lsk_live_...): ')).trim();
+    rl.close();
+  }
+  if (!/^lsk_(live|test)_[0-9a-f]{56}$/.test(key)) {
+    fail(
+      'that does not look like a Lobstack key.',
+      'A key is lsk_live_ or lsk_test_ followed by 56 hex characters.',
+    );
+  }
+
+  // Verified before saving. Writing an unusable key to disk just moves the
+  // failure to the next command, where it is harder to explain.
+  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)}`);
+
+  writeConfig({ ...readConfig(), key, baseUrl: b });
+  process.stdout.write(
+    `\n${green('Saved')} to ${CONFIG_PATH} ${dim('(0600)')}\n\n` +
+      `Try it:  ${bold('lobstack chat "say hello"')}\n`,
+  );
+}
+
+/* ── chat ──────────────────────────────────────────────────────────────── */
+
+async function cmdChat(args, flags) {
+  const prompt = args.join(' ').trim();
+  if (!prompt) fail('nothing to send.', 'lobstack chat "your prompt here"');
+
+  const key = requireKey(flags);
+  const b = base(flags);
+  const model = flags.model || 'auto';
+
+  const { usage, receipt, model: served } = await streamCompletion(b, key, {
+    model,
+    messages: [{ role: 'user', content: prompt }],
+    onText: (t) => process.stdout.write(t),
+  });
+  process.stdout.write('\n');
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ usage, x_lobstack: receipt }, null, 2) + '\n');
+  } else {
+    printReceipt({ receipt, usage, model: served });
+  }
+}
+
+/* ── models ────────────────────────────────────────────────────────────── */
+
+async function cmdModels(flags) {
+  const rows = await fetchModels(base(flags), requireKey(flags));
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+    return;
+  }
+
+  const w = Math.max(...rows.map((m) => (m.id || '').length), 5);
+  process.stdout.write(
+    `${dim('MODEL'.padEnd(w))}  ${dim('TIER'.padEnd(9))}  ${dim('IN/M')}  ${dim('OUT/M')}\n`,
+  );
+  for (const m of rows) {
+    const p = m.price_per_mtok || {};
+    const price = (v) => (typeof v === 'number' ? `$${v}` : dim('-'));
+    process.stdout.write(
+      `${(m.id || '').padEnd(w)}  ${String(m.tier || '').padEnd(9)}  ${price(p.input).padEnd(6)}  ${price(p.output)}\n`,
+    );
+  }
+  process.stdout.write(
+    `\n${dim(`${rows.length} models. Send "auto" and the router picks one, then tells you which.`)}\n`,
+  );
+}
+
+/* ── spend ─────────────────────────────────────────────────────────────── */
+
+async function cmdSpend(flags) {
+  const days = Number(flags.days || 7);
+  const body = await fetchUsage(base(flags), requireKey(flags), days);
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+    return;
+  }
+  if (body.enabled === false) {
+    fail(body.message || 'usage reporting is not enabled on this deployment.');
+  }
+
+  const s = body.summary || {};
+  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',
+  );
+  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 ───────────────────────────────────────────────────────────────── */
+
+/**
+ * The interactive UI, and every way out of it.
+ *
+ * Four cases, in the order they have to be checked. The whole point is that
+ * `lobstack` in a pipeline behaves like a Unix program and `lobstack` at a
+ * keyboard behaves like an application, with no flag to remember either way.
+ *
+ *   1. stdout is not a terminal - redirected, piped, or a CI log. Never draw.
+ *      If stdin is not a terminal either there is nothing interactive about
+ *      this invocation at all, so whatever came in on stdin is the prompt and
+ *      the one-shot `chat` path runs: `echo hi | lobstack > out.txt` puts the
+ *      answer in the file and nothing else.
+ *   2. stdout is a terminal but stdin is a pipe. Same thing: the prompt arrived
+ *      on stdin, there is no keyboard to run a UI with.
+ *   3. Both are terminals but TERM says `dumb` - no cursor addressing exists,
+ *      so a full-screen frame is not a degraded experience, it is garbage. Line
+ *      mode instead.
+ *   4. Draw.
+ */
+async function cmdTui(args, flags) {
+  const key = requireKey(flags);
+  const b = base(flags);
+  const model = flags.model || 'auto';
+  const force = Boolean(flags.force) || process.env.LOBSTACK_TUI === '1';
+  const caps = detect({ force });
+
+  const pipedPrompt = async () => {
+    const typed = args.join(' ').trim();
+    if (typed) return typed;
+    return (await readAll(process.stdin)).trim();
+  };
+
+  if (!caps.outTTY) {
+    if (!process.stdin.isTTY) {
+      const prompt = await pipedPrompt();
+      if (!prompt) {
+        fail(
+          'no terminal to draw on, and nothing on stdin.',
+          'Run `lobstack` in a terminal, or pipe a prompt in: echo "hi" | lobstack',
+        );
+      }
+      return cmdChat([prompt], flags);
+    }
+    // A keyboard on stdin, a file on stdout. Drawing would fill the file with
+    // escape sequences, so this is the plain loop: answers to stdout, prompts
+    // and receipts to stderr.
+    process.stderr.write(dim('- stdout is not a terminal, so this is line mode\n'));
+    return runLineMode({ key, base: b, model });
+  }
+
+  if (!caps.inTTY) {
+    const prompt = await pipedPrompt();
+    if (prompt) return cmdChat([prompt], flags);
+  }
+
+  if (!caps.fullscreen) {
+    // Say which of the three reasons it was. "line mode" with no explanation
+    // reads as a bug, and the fix differs for each: set TERM, or stop piping.
+    const why = caps.dumb
+      ? `TERM=${process.env.TERM} cannot address a cursor`
+      : !caps.inTTY
+        ? 'stdin is not a terminal'
+        : 'stdout is not a terminal';
+    process.stderr.write(dim(`- ${why}, so this is line mode\n`));
+    return runLineMode({ key, base: b, model });
+  }
+
+  return runTui({ key, base: b, model, caps, initial: args.join(' ').trim() || null });
+}
+
+/* ── main ──────────────────────────────────────────────────────────────── */
+
+const { _: positional, flags } = parseArgs(process.argv.slice(2));
+const [command, ...rest] = positional;
+
+// Answered before the switch, so they work with or without a command and
+// cannot be captured by the bare-`lobstack` branch below.
+if (flags.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (flags.version) {
+  process.stdout.write(`${VERSION}\n`);
+  process.exit(0);
+}
+
+try {
+  switch (command) {
+    case 'init':
+      await cmdInit(flags);
+      break;
+    case 'chat':
+      await cmdChat(rest, flags);
+      break;
+    case 'models':
+      await cmdModels(flags);
+      break;
+    case 'spend':
+      await cmdSpend(flags);
+      break;
+    case 'proxy':
+      await startProxy({ key: requireKey(flags), base: base(flags), port: Number(flags.port || 8787) });
+      break;
+    case 'tui':
+    case 'ui':
+      await cmdTui(rest, flags);
+      break;
+    case undefined:
+      // Bare `lobstack` opens the UI, but only when opening it is obviously
+      // what was meant: a terminal on both ends and a key already available.
+      // In a pipeline, in CI, or on a first run with no key, it prints the same
+      // help it always printed - which is also the screen that tells you to run
+      // `init`, so the no-key case still lands somewhere useful.
+      if (
+        (flags.force || (process.stdout.isTTY && process.stdin.isTTY)) &&
+        (flags.key || resolveKey())
+      ) {
+        await cmdTui([], flags);
+        break;
+      }
+      process.stdout.write(HELP);
+      break;
+    case 'help':
+      process.stdout.write(HELP);
+      break;
+    default:
+      fail(`unknown command "${command}".`, 'Run `lobstack help`.');
+  }
+} 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"
+  // and lose the sentence explaining that a redirect strips your key.
+  fail(err instanceof Error ? err.message : String(err), err?.hint);
+}

package/src/proxy.mjs

@@ -0,0 +1,181 @@
+/**
+ * A local OpenAI-compatible endpoint that forwards to the Gateway.
+ *
+ *   lobstack proxy            # http://127.0.0.1:8787/v1
+ *
+ * This is the shortest path from "I have a tool that speaks OpenAI" to routing
+ * and metering: change one base URL in Cursor, Aider, Continue, or anything
+ * else with an OpenAI-compatible setting, and every call it makes goes through
+ * the router and lands in your Console. Nothing else about the tool changes,
+ * and it never sees your Lobstack key.
+ *
+ * Three deliberate choices:
+ *
+ *   · It binds 127.0.0.1, not 0.0.0.0. This process holds a credential and
+ *     answers unauthenticated requests, so anything that can reach the port can
+ *     spend your money. Loopback keeps that to this machine.
+ *   · It streams by piping the upstream body straight through. Buffering a
+ *     stream to inspect it would make every token wait for the last one, which
+ *     is the one thing an interactive tool cannot tolerate.
+ *   · It prints a one-line receipt per request to stderr. The point of routing
+ *     through here is knowing what it cost; a proxy that silently forwards is
+ *     just a slower base URL.
+ */
+
+import { createServer } from 'node:http';
+import { gatewayUrl } from './config.mjs';
+import { dim, green, money, savingsLabel } from './render.mjs';
+
+const HOST = '127.0.0.1';
+
+/** Read a request body without assuming it fits in one chunk. */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Pull the receipt out of a passing stream without holding it up.
+ *
+ * The bytes are forwarded the instant they arrive; a copy of the tail is kept
+ * so the final frame can be parsed after the client already has everything.
+ */
+function receiptFromTail(tail) {
+  const frames = tail.split('\n\n');
+  for (let i = frames.length - 1; i >= 0; i--) {
+    const line = frames[i].split('\n').find((l) => l.startsWith('data:'));
+    if (!line) continue;
+    const payload = line.slice(5).trim();
+    if (!payload || payload === '[DONE]') continue;
+    try {
+      const frame = JSON.parse(payload);
+      if (frame.x_lobstack || frame.usage) return { receipt: frame.x_lobstack, usage: frame.usage };
+    } catch {
+      /* keep looking backwards */
+    }
+  }
+  return {};
+}
+
+function logReceipt(started, { receipt, usage }) {
+  const ms = Date.now() - started;
+  const parts = [`${dim('model')} ${receipt?.served_model ?? '?'}`];
+  if (usage) parts.push(`${dim('tokens')} ${usage.prompt_tokens}/${usage.completion_tokens}`);
+  parts.push(`${dim('cost')} ${money(receipt?.cost_usd)}`);
+  // See render.mjs: a plan-ceiling baseline is not a like-for-like saving and
+  // must not be printed as one. One rule, one implementation.
+  const saving = savingsLabel(receipt);
+  if (saving) parts.push(`${dim(saving.label)} ${green(money(saving.amount))}`);
+  parts.push(`${dim('in')} ${ms}ms`);
+  process.stderr.write(dim('- ') + parts.join(dim('  -  ')) + '\n');
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.key      the Lobstack credential this process holds
+ * @param {string} o.base     the gateway origin
+ * @param {number} o.port     loopback port to listen on
+ * @param {boolean} [o.quiet] return the server instead of printing a banner and
+ *                            blocking forever. The TUI runs the proxy inside
+ *                            itself and owns the screen, so it cannot have a
+ *                            second writer on stderr or a call that never
+ *                            returns.
+ * @param {(r:{receipt:object|undefined,usage:object|undefined,ms:number,path:string}) => void} [o.onReceipt]
+ *                            called per request instead of the stderr line.
+ */
+export async function startProxy({ key, base, port, quiet = false, onReceipt }) {
+  const server = createServer(async (req, res) => {
+    const started = Date.now();
+
+    // Strip the caller's /v1 prefix; the Gateway lives under /api/gateway/v1.
+    // Anything else 404s here rather than being forwarded, so a mistyped path
+    // is a local error instead of a confusing one from upstream.
+    const path = (req.url || '').replace(/^\/v1/, '');
+    if (!path.startsWith('/')) {
+      res.writeHead(404, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: { message: 'this proxy serves the OpenAI paths under /v1' } }));
+      return;
+    }
+
+    try {
+      const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : await readBody(req);
+      const upstream = await fetch(gatewayUrl(base, path), {
+        method: req.method,
+        redirect: 'manual',
+        headers: {
+          Authorization: `Bearer ${key}`,
+          'Content-Type': req.headers['content-type'] || 'application/json',
+          'x-lobstack-client': 'lobstack-cli-proxy',
+        },
+        body,
+      });
+
+      const headers = {};
+      upstream.headers.forEach((v, k) => {
+        // Hop-by-hop headers describe the upstream connection, not this one.
+        if (!['connection', 'keep-alive', 'transfer-encoding', 'content-encoding'].includes(k)) {
+          headers[k] = v;
+        }
+      });
+      res.writeHead(upstream.status, headers);
+
+      if (!upstream.body) {
+        res.end();
+        return;
+      }
+
+      // Forward first, inspect after. Keep only the tail: a long conversation
+      // is megabytes, and the receipt is always in the last frame.
+      const reader = upstream.body.getReader();
+      const decoder = new TextDecoder();
+      let tail = '';
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        res.write(Buffer.from(value));
+        tail = (tail + decoder.decode(value, { stream: true })).slice(-4096);
+      }
+      res.end();
+      const parsed = receiptFromTail(tail);
+      if (onReceipt) onReceipt({ ...parsed, ms: Date.now() - started, path });
+      else logReceipt(started, parsed);
+    } catch (err) {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(
+        JSON.stringify({ error: { message: err instanceof Error ? err.message : 'proxy failure' } }),
+      );
+    }
+  });
+
+  // `listen` reports failure as an 'error' event, and an unhandled one on a
+  // server is an uncaught exception - which inside the TUI would tear down the
+  // screen over something as ordinary as a port already being in use.
+  await new Promise((resolve, reject) => {
+    server.once('error', (err) =>
+      reject(
+        new Error(
+          err.code === 'EADDRINUSE'
+            ? `port ${port} is already in use - pass a different --port.`
+            : `could not listen on ${HOST}:${port}: ${err.message}`,
+        ),
+      ),
+    );
+    server.listen(port, HOST, resolve);
+  });
+  if (quiet) return server;
+
+  process.stderr.write(
+    `\n${green('Listening')} on http://${HOST}:${port}/v1  ${dim('-> ' + base)}\n\n` +
+      `${dim('Point any OpenAI-compatible tool at it:')}\n` +
+      `  OPENAI_BASE_URL=http://${HOST}:${port}/v1\n` +
+      `  OPENAI_API_KEY=anything\n\n` +
+      `${dim('Your Lobstack key stays in this process. Loopback only - anything that')}\n` +
+      `${dim('can reach this port can spend on your account.')}\n\n`,
+  );
+
+  await new Promise(() => {}); // run until interrupted
+}

package/src/render.mjs

@@ -0,0 +1,87 @@
+/** Terminal output. Colour only when the stream is a TTY and NO_COLOR is unset. */
+const ESC = '[';
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `${ESC}${code}m${s}${ESC}0m` : s);
+
+export const dim = wrap('2');
+export const bold = wrap('1');
+export const red = wrap('31');
+export const green = wrap('32');
+
+export const money = (n) =>
+  typeof n !== 'number' || !Number.isFinite(n)
+    ? 'unpriced'
+    : n >= 0.01
+      ? `$${n.toFixed(4)}`
+      : `$${n.toFixed(6)}`;
+
+/**
+ * Whether a saving may be called a saving, in one place.
+ *
+ * `baseline_reason` decides. "named" means the caller asked for a model and got
+ * something cheaper -- a like-for-like comparison, and the only case that may
+ * be labelled `saved`. "plan_ceiling" means they sent `auto` and the gateway
+ * measured against the most expensive model their plan allows, which is a real
+ * comparison but not one they asked for.
+ *
+ * This lives here rather than in each renderer because there are now three of
+ * them -- the single-shot receipt, the proxy's per-request line and the TUI --
+ * and three copies of a rule about overstating savings is three chances to
+ * drift apart on the one thing this product is arguing about.
+ *
+ * @returns {{label:string, named:boolean, amount:number}|null}
+ */
+export function savingsLabel(receipt) {
+  const amount = receipt?.savings_usd;
+  if (typeof amount !== 'number' || !(amount > 0)) return null;
+  const named = receipt.baseline_reason === 'named';
+  return { label: named ? 'saved' : 'vs ceiling', named, amount };
+}
+
+/**
+ * Print the receipt.
+ *
+ * `cost_usd` is null, never zero, when the Gateway could not price the call.
+ * Rendering that null as $0.00 would write off a real charge — which is the
+ * whole reason the field is nullable — so "unpriced" is printed instead.
+ *
+ * It goes to stderr, so `lobstack chat "..." > out.txt` gives you the answer
+ * and nothing else while you still see what it cost.
+ */
+export function printReceipt({ receipt, usage, model }) {
+  const served = receipt?.served_model || model || 'unknown';
+  const asked = receipt?.requested_model;
+  const parts = [];
+
+  parts.push(`${dim('model')} ${served}`);
+  if (asked && receipt?.routed) parts.push(`${dim('asked')} ${asked}`);
+  if (usage) parts.push(`${dim('tokens')} ${usage.prompt_tokens}/${usage.completion_tokens}`);
+  parts.push(`${dim('cost')} ${money(receipt?.cost_usd)}`);
+
+  // Printing a plan-ceiling comparison as a like-for-like saving is the
+  // overstatement the receipt exists to prevent. `savingsLabel` decides.
+  const saving = savingsLabel(receipt);
+  if (saving) parts.push(`${dim(saving.label)} ${green(money(saving.amount))}`);
+
+  process.stderr.write('\n' + dim('- ') + parts.join(dim('  -  ')) + '\n');
+
+  if (receipt?.baseline_reason === 'plan_ceiling' && receipt.baseline_model) {
+    process.stderr.write(
+      dim(`  measured against ${receipt.baseline_model}, the priciest model your plan allows - you sent auto, not that model\n`),
+    );
+  }
+  if (receipt && receipt.priced === false) {
+    process.stderr.write(dim('  the gateway 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
+    // silently showing nothing where a price belongs.
+    process.stderr.write(dim('  no receipt on this response - the endpoint did not send one\n'));
+  }
+}
+
+export function fail(message, hint) {
+  process.stderr.write(`${red('error')} ${message}\n`);
+  if (hint) process.stderr.write(dim(`  ${hint}\n`));
+  process.exit(1);
+}