@lobstack-ai/mcp 0.1.1 → 0.1.3

package/README.md

@@ -173,18 +173,32 @@ structured result carries:
 
 ### `lobstack_spend`
 
-What the organization has spent over `7d`, `14d`, `30d` or `90d`, grouped by
-`day`, `model`, `key` or `agent`, with request counts, tokens, errors and
-latency percentiles. Requires a key holding the `usage:read` scope.
-
-It also reports `unpriced_requests` and sets `is_floor`. The endpoint sums an
-unpriced row as zero — the only arithmetic available — so a total that includes
-one is a lower bound, not a total, and this tool says which.
-
-It does **not** report a savings total. Savings are reported per call, by
-`lobstack_chat`, where the API sends them with the reason attached. Adding them
-up client-side would mean pricing the org's tokens against a copy of the rate
-card, and a copy drifts.
+What the organization has spent over `month` (the UTC calendar month to date,
+the Console's default window), `7d`, `14d`, `30d` or `90d`, grouped by `day`,
+`model`, `key` or `agent`, with request counts, tokens, errors and latency
+percentiles. Requires a key holding the `usage:read` scope. The default range
+is `7d`.
+
+**The total is the Console's figure.** `/api/v1/usage` returns two totals from
+two tables: `spend.cost_usd`, from the billing ledger that the allowance and
+invoices are read from and that the Console's Spend shows, and
+`summary.cost_usd`, the request trace's own copy of each price, kept for older
+callers. They are written separately and can disagree. This tool reports
+`spend.cost_usd` (and each group's `ledger_cost_usd`) as `cost_usd`, with
+`cost_source: "ledger"`. Only when the ledger figure is null or missing does it
+fall back to `summary.cost_usd`, set `cost_source: "trace"`, and say so in the
+output.
+
+It also sets `is_floor`. Unpriced rows sum as zero — the only arithmetic
+available — so a total that includes one is a lower bound, not a total, and
+this tool says how many there were, counted in the same table as the total.
+
+**Routing savings are two figures, never one.** When the API sends `savings`,
+the tool shows `named` (saved on models you asked for, measured) and
+`plan_ceiling` (what `auto` requests would have cost on the best model your
+plan allows: a comparison, not a saving) on separate lines. It never adds them
+together, and it never computes a saving client-side from a copy of the rate
+card.
 
 ## Two rules about the numbers
 

package/dist/gateway.js

@@ -47,12 +47,12 @@ export async function gwFetch(cfg, url, opts = {}) {
         });
     }
     catch (e) {
-        throw new GatewayError(`could not reach the gateway: ${scrub(e instanceof Error ? e.message : String(e), cfg.apiKey)}`, { hint: `Base URL in use: ${cfg.base.origin}` });
+        throw new GatewayError(`could not reach the Lobstack API: ${scrub(e instanceof Error ? e.message : String(e), cfg.apiKey)}`, { hint: `Base URL in use: ${cfg.base.origin}` });
     }
     if (res.status >= 300 && res.status < 400) {
         // Not followed, and not quietly.
         const location = res.headers.get("location");
-        throw new GatewayError(`the gateway redirected (${res.status}) to ${location || "somewhere else"}; the request was not followed.`, {
+        throw new GatewayError(`the Lobstack API redirected (${res.status}) to ${location || "somewhere else"}; the request was not followed.`, {
             status: res.status,
             hint: "A redirect across hosts strips the Authorization header, so the key would never arrive. " +
                 "Set LOBSTACK_BASE_URL to the host that answers directly — https://www.lobstack.ai, never the bare apex.",

package/dist/receipt.js

@@ -108,7 +108,7 @@ export function describeReceipt({ receipt, usage, model, droppedParams }) {
         lines.push(`  measured against ${saving.baseline_model}, the priciest model your plan allows — you sent auto, not that model`);
     }
     if (receipt && !receipt.priced) {
-        lines.push("  the gateway could not price this model, so no cost is claimed");
+        lines.push("  the Lobstack API could not price this model, so no cost is claimed");
     }
     if (!receipt) {
         lines.push("  no receipt on this response — the endpoint did not send one");

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 /**
- * The MCP server: four tools over the Lobstack Gateway.
+ * The MCP server: four tools over the Lobstack API.
  *
  * Exported as a factory rather than wired straight to stdio so the tests can
  * drive it over an in-memory transport with a real MCP client on the other end,
@@ -16,7 +16,8 @@
  *                           what the product does before anybody has signed up.
  *   lobstack_models         the catalogue, with per-token prices and tiers.
  *   lobstack_chat           the actual completion, and the receipt for it.
- *   lobstack_spend          the ledger over a range.
+ *   lobstack_spend          the billing ledger over a range, as the Console
+ *                           shows it, with routing savings split in two.
  *
  * Nothing here mints, rotates or reads API keys, and nothing accepts a base URL
  * as an argument. This process holds a live credential for as long as the MCP

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * The MCP server: four tools over the Lobstack Gateway.
+ * The MCP server: four tools over the Lobstack API.
  *
  * Exported as a factory rather than wired straight to stdio so the tests can
  * drive it over an in-memory transport with a real MCP client on the other end,
@@ -16,7 +16,8 @@
  *                           what the product does before anybody has signed up.
  *   lobstack_models         the catalogue, with per-token prices and tiers.
  *   lobstack_chat           the actual completion, and the receipt for it.
- *   lobstack_spend          the ledger over a range.
+ *   lobstack_spend          the billing ledger over a range, as the Console
+ *                           shows it, with routing savings split in two.
  *
  * Nothing here mints, rotates or reads API keys, and nothing accepts a base URL
  * as an argument. This process holds a live credential for as long as the MCP
@@ -48,7 +49,7 @@ export const SERVER_VERSION = (() => {
         return "0.0.0";
     }
 })();
-const INSTRUCTIONS = `Lobstack is a metered LLM gateway: one key reaches every major model, and every call
+const INSTRUCTIONS = `The Lobstack API is a metered LLM gateway: one key reaches every major model, and every call
 comes back with a receipt saying which model served it and what it cost.
 
 - lobstack_route_preview needs NO API key. It scores a prompt against the same
@@ -56,7 +57,7 @@ comes back with a receipt saying which model served it and what it cost.
   estimated cost. Use it to choose a model, or to show what routing does.
 - lobstack_chat runs the completion. Send model "auto" to let the router pick
   the cheapest model that can handle the prompt.
-- Costs are reported as the gateway priced them. A null cost means the gateway
+- Costs are reported as the API priced them. A null cost means the API
   could not price the call — it does not mean the call was free.
 - A saving labelled "saved" is like-for-like: the caller named a model and got
   something cheaper. A saving labelled "vs ceiling" is measured against the most
@@ -69,23 +70,23 @@ export function createServer(options = {}) {
         title: "Preview routing and cost",
         description: "Score a prompt and report which model the Lobstack router would serve it with, and what that would cost. " +
             "Runs no inference, spends nothing, and NEEDS NO API KEY — use it to pick a model before calling lobstack_chat, " +
-            "or to show what the gateway does on a machine with no key configured. Token counts are estimates; the billed " +
+            "or to show what the Lobstack API does on a machine with no key configured. Token counts are estimates; the billed " +
             "figure comes from the provider's usage block on the real call.",
         inputSchema: routePreviewInput,
         outputSchema: routePreviewOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => runRoutePreview(cfg, args));
     server.registerTool("lobstack_models", {
-        title: "List gateway models",
-        description: "The models the Lobstack Gateway serves, with capability tier, provider, context window and USD price per " +
+        title: "List Lobstack API models",
+        description: "The models the Lobstack API serves, with capability tier, provider, context window and USD price per " +
             "million input and output tokens. A model the registry cannot price shows a null price, not zero.",
         inputSchema: modelsInput,
         outputSchema: modelsOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => runModels(cfg, args));
     server.registerTool("lobstack_chat", {
-        title: "Chat through the gateway",
-        description: "Send a prompt or conversation through the Lobstack Gateway and get the reply plus a receipt: the model that " +
+        title: "Chat through the Lobstack API",
+        description: "Send a prompt or conversation through the Lobstack API and get the reply plus a receipt: the model that " +
             'actually served it, token counts, USD cost, and any saving with the reason it may be claimed. Model "auto" ' +
             "(the default) lets the router pick the cheapest model that can handle the prompt. This call spends money " +
             "against the configured key's allowance.",
@@ -95,9 +96,12 @@ export function createServer(options = {}) {
     }, async (args) => runChat(cfg, args));
     server.registerTool("lobstack_spend", {
         title: "Read spend and usage",
-        description: "What this organization has spent through the gateway over a range, broken down by day, model, key or agent, " +
-            "with request counts, tokens, error counts and latency percentiles. Requires an API key with the usage:read " +
-            "scope. Reports how many requests could not be priced, because a total that includes them is a floor.",
+        description: "What this organization has spent through the Lobstack API over a range, broken down by day, model, key or agent, " +
+            "with request counts, tokens, error counts and latency percentiles. The total is the billing ledger's figure, " +
+            "the same one the Console's Spend shows; if the ledger cannot be read it falls back to the request trace's " +
+            "legacy figure and says so. Also shows routing savings as two separate figures, never summed: saved on models " +
+            "you named, and a comparison against the best model your plan allows. Reports how many rows could not be " +
+            "priced, because a total that includes them is a floor. Requires an API key with the usage:read scope.",
         inputSchema: spendInput,
         outputSchema: spendOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },

package/dist/sse.js

@@ -90,7 +90,7 @@ export async function consume(body, onText) {
             const e = frame.error;
             // A 200 whose stream carries an error. Headers are long gone by then, so
             // this is the only place the gateway can report a mid-stream failure.
-            throw new StreamError(e?.message || "the gateway reported an error mid-stream");
+            throw new StreamError(e?.message || "the Lobstack API reported an error mid-stream");
         }
         if (typeof frame.model === "string")
             model = frame.model;

package/dist/tools/chat.js

@@ -68,7 +68,7 @@ export const chatOutput = {
         cost_usd: z
             .number()
             .nullable()
-            .describe("USD the caller owes. NULL — never 0 — when the gateway could not price the call."),
+            .describe("USD the caller owes. NULL — never 0 — when the API could not price the call."),
         cost_display: z.string().describe('Human form. "unpriced" when cost_usd is null.'),
         priced: z.boolean(),
         savings: z
@@ -85,7 +85,7 @@ export const chatOutput = {
     })
         .nullable()
         .describe("Null when the endpoint sent no receipt at all."),
-    quota: z.record(z.unknown()).nullable().describe("Allowance remaining, as the gateway reported it."),
+    quota: z.record(z.unknown()).nullable().describe("Allowance remaining, as the API reported it."),
     dropped_params: z.array(z.string()),
 };
 export async function runChat(cfg, args) {

package/dist/tools/shared.js

@@ -41,13 +41,13 @@ export function fromThrown(cfg, e) {
                 : "The key was rejected. It may have been revoked or have expired; mint a new one in Console → API keys.");
         }
         if (e.requestId)
-            hints.push(`Gateway request id: ${e.requestId}`);
+            hints.push(`Request id: ${e.requestId}`);
         return failure(cfg, e.message, hints.join("\n"));
     }
     if (e instanceof ConfigError)
         return failure(cfg, e.message, e.hint);
     if (e instanceof StreamError) {
-        return failure(cfg, `the gateway failed part-way through the answer: ${e.message}`);
+        return failure(cfg, `the Lobstack API failed part-way through the answer: ${e.message}`);
     }
     return failure(cfg, e instanceof Error ? e.message : String(e));
 }

package/dist/tools/spend.d.ts

@@ -2,47 +2,140 @@
  * lobstack_spend — what this organization has spent, over a range.
  *
  * `GET /api/v1/usage` is org-scoped and takes either a browser session or an
- * API key holding the `usage:read` scope. It is a sibling of the gateway
- * prefix, not under it, which is why the base URL here is kept as an origin
- * and paths are composed rather than concatenated onto a gateway URL.
- *
- * TWO THINGS THIS TOOL REPORTS THAT THE ENDPOINT BURIES
- *
- * `unpriced_requests` — rows the meter could not price. The endpoint's
- * `cost_usd` sums a NULL as zero, which is the only arithmetic available and
- * not the only truth: a total built partly from unpriced rows is a FLOOR. A
- * reader not told how many were unpriced reads it as exact, which is the same
- * mistake as a $0.00 receipt, one aggregation up.
- *
- * `truncated` — the endpoint pages to a cap. When it binds, the sums are a
- * floor for a second, independent reason.
- *
- * WHAT THIS TOOL DOES NOT REPORT (YET)
- *
- * A savings total. `/api/v1/usage` now computes one, server-side from the
- * priced ledger, as a top-level `savings` object split in two and never
- * summed: `named` (a measured saving against a model the caller asked for) and
- * `plan_ceiling` (a counterfactual against the priciest model the plan allows,
- * when the caller sent `auto`). `savings` is null when the ledger could not be
- * read. This tool does not read it yet; if it ever does, the two blocks must
- * stay separate and `plan_ceiling` must be labelled as a counterfactual. What
- * it must never do is add up per-call savings client-side from a rate card we
- * hold a copy of. Per-call savings are reported by lobstack_chat, where the
- * API sends them with the reason attached.
+ * API key holding the `usage:read` scope. It is a sibling of the API prefix,
+ * not under it, which is why the base URL here is kept as an origin and paths
+ * are composed rather than concatenated onto the API base URL.
+ *
+ * ONE MONEY FIGURE, AND IT IS THE CONSOLE'S
+ *
+ * The endpoint returns two totals of the same quantity, from two tables:
+ *
+ *   spend.cost_usd     the priced ledger (`token_usage`) — what the allowance
+ *                      is metered from, what invoices are cut from, and what
+ *                      the Console's Spend figure shows.
+ *   summary.cost_usd   the request trace's own copy of each price
+ *                      (`gateway_requests`), kept for older callers.
+ *
+ * The two are written by separate statements and can disagree: a request the
+ * trace recorded but the ledger lost is in the second and not the first, a
+ * ledger row whose trace is missing is the other way round, and the unpriced
+ * counts are taken over different rows. This tool used to print
+ * `summary.cost_usd`, so it could quote a different total from the Console for
+ * the same window. It now prints `spend.cost_usd`, and falls back to the trace
+ * figure only when the ledger figure is null (the ledger could not be read) or
+ * absent (an older deployment) — and says so in the output when it does.
+ *
+ * The same rule applies per group: `ledger_cost_usd` when it is there, the
+ * trace's `cost_usd` only when it is not, as the Console's breakdown does.
+ *
+ * WHEN THE TOTAL IS A FLOOR
+ *
+ * Unpriced rows sum as zero, which is the only arithmetic available and not
+ * the only truth: a total built partly from unpriced rows is a FLOOR. The
+ * unpriced count is taken from the same table as the total it qualifies —
+ * `spend.unpriced_rows` for the ledger, `summary.unpriced_requests` for the
+ * trace. A read that hit the row cap (`truncated`) is a floor for a second,
+ * independent reason.
+ *
+ * SAVINGS: TWO FIGURES, NEVER ONE
+ *
+ * The endpoint computes routing savings server-side from the priced ledger, as
+ * a `savings` object split in two: `named` (a measured saving against a model
+ * the caller asked for) and `plan_ceiling` (a counterfactual against the
+ * priciest model the plan allows, when the caller sent `auto`). This tool
+ * shows each one on its own line, labels `plan_ceiling` as a comparison rather
+ * than a saving, and never adds them together. It never computes a saving
+ * client-side from a copy of the rate card.
  */
 import { z } from "zod";
 import type { Config } from "../config.js";
 import { type ToolResult } from "./shared.js";
 export declare const spendInput: {
-    range: z.ZodOptional<z.ZodEnum<["7d", "14d", "30d", "90d"]>>;
+    range: z.ZodOptional<z.ZodEnum<["month", "7d", "14d", "30d", "90d"]>>;
     group_by: z.ZodOptional<z.ZodEnum<["day", "model", "key", "agent"]>>;
 };
 export declare const spendOutput: {
     enabled: z.ZodBoolean;
     range: z.ZodString;
     group_by: z.ZodString;
+    cost_usd: z.ZodNullable<z.ZodNumber>;
+    cost_source: z.ZodNullable<z.ZodEnum<["ledger", "trace"]>>;
+    spend: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     summary: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     groups: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    savings: z.ZodNullable<z.ZodObject<{
+        named: z.ZodObject<{
+            requests: z.ZodNumber;
+            served_cost_usd: z.ZodNumber;
+            baseline_cost_usd: z.ZodNumber;
+            difference_usd: z.ZodNumber;
+            baseline_models: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        }, {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        }>;
+        plan_ceiling: z.ZodObject<{
+            requests: z.ZodNumber;
+            served_cost_usd: z.ZodNumber;
+            baseline_cost_usd: z.ZodNumber;
+            difference_usd: z.ZodNumber;
+            baseline_models: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        }, {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        }>;
+        unpriced_routed_requests: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        named: {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        };
+        plan_ceiling: {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        };
+        unpriced_routed_requests: number;
+    }, {
+        named: {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        };
+        plan_ceiling: {
+            baseline_cost_usd: number;
+            requests: number;
+            served_cost_usd: number;
+            difference_usd: number;
+            baseline_models: string[];
+        };
+        unpriced_routed_requests: number;
+    }>>;
     is_floor: z.ZodBoolean;
     message: z.ZodNullable<z.ZodString>;
 };

package/dist/tools/spend.js

@@ -2,51 +2,104 @@
  * lobstack_spend — what this organization has spent, over a range.
  *
  * `GET /api/v1/usage` is org-scoped and takes either a browser session or an
- * API key holding the `usage:read` scope. It is a sibling of the gateway
- * prefix, not under it, which is why the base URL here is kept as an origin
- * and paths are composed rather than concatenated onto a gateway URL.
+ * API key holding the `usage:read` scope. It is a sibling of the API prefix,
+ * not under it, which is why the base URL here is kept as an origin and paths
+ * are composed rather than concatenated onto the API base URL.
  *
- * TWO THINGS THIS TOOL REPORTS THAT THE ENDPOINT BURIES
+ * ONE MONEY FIGURE, AND IT IS THE CONSOLE'S
  *
- * `unpriced_requests` — rows the meter could not price. The endpoint's
- * `cost_usd` sums a NULL as zero, which is the only arithmetic available and
- * not the only truth: a total built partly from unpriced rows is a FLOOR. A
- * reader not told how many were unpriced reads it as exact, which is the same
- * mistake as a $0.00 receipt, one aggregation up.
+ * The endpoint returns two totals of the same quantity, from two tables:
  *
- * `truncated` — the endpoint pages to a cap. When it binds, the sums are a
- * floor for a second, independent reason.
+ *   spend.cost_usd     the priced ledger (`token_usage`) — what the allowance
+ *                      is metered from, what invoices are cut from, and what
+ *                      the Console's Spend figure shows.
+ *   summary.cost_usd   the request trace's own copy of each price
+ *                      (`gateway_requests`), kept for older callers.
  *
- * WHAT THIS TOOL DOES NOT REPORT (YET)
+ * The two are written by separate statements and can disagree: a request the
+ * trace recorded but the ledger lost is in the second and not the first, a
+ * ledger row whose trace is missing is the other way round, and the unpriced
+ * counts are taken over different rows. This tool used to print
+ * `summary.cost_usd`, so it could quote a different total from the Console for
+ * the same window. It now prints `spend.cost_usd`, and falls back to the trace
+ * figure only when the ledger figure is null (the ledger could not be read) or
+ * absent (an older deployment) — and says so in the output when it does.
  *
- * A savings total. `/api/v1/usage` now computes one, server-side from the
- * priced ledger, as a top-level `savings` object split in two and never
- * summed: `named` (a measured saving against a model the caller asked for) and
- * `plan_ceiling` (a counterfactual against the priciest model the plan allows,
- * when the caller sent `auto`). `savings` is null when the ledger could not be
- * read. This tool does not read it yet; if it ever does, the two blocks must
- * stay separate and `plan_ceiling` must be labelled as a counterfactual. What
- * it must never do is add up per-call savings client-side from a rate card we
- * hold a copy of. Per-call savings are reported by lobstack_chat, where the
- * API sends them with the reason attached.
+ * The same rule applies per group: `ledger_cost_usd` when it is there, the
+ * trace's `cost_usd` only when it is not, as the Console's breakdown does.
+ *
+ * WHEN THE TOTAL IS A FLOOR
+ *
+ * Unpriced rows sum as zero, which is the only arithmetic available and not
+ * the only truth: a total built partly from unpriced rows is a FLOOR. The
+ * unpriced count is taken from the same table as the total it qualifies —
+ * `spend.unpriced_rows` for the ledger, `summary.unpriced_requests` for the
+ * trace. A read that hit the row cap (`truncated`) is a floor for a second,
+ * independent reason.
+ *
+ * SAVINGS: TWO FIGURES, NEVER ONE
+ *
+ * The endpoint computes routing savings server-side from the priced ledger, as
+ * a `savings` object split in two: `named` (a measured saving against a model
+ * the caller asked for) and `plan_ceiling` (a counterfactual against the
+ * priciest model the plan allows, when the caller sent `auto`). This tool
+ * shows each one on its own line, labels `plan_ceiling` as a comparison rather
+ * than a saving, and never adds them together. It never computes a saving
+ * client-side from a copy of the rate card.
  */
 import { z } from "zod";
 import { apiUrl } from "../config.js";
 import { errorFrom, gwFetch } from "../gateway.js";
 import { money } from "../receipt.js";
 import { baseNote, fromThrown, ok, requireKey } from "./shared.js";
-const RANGES = ["7d", "14d", "30d", "90d"];
+const RANGES = ["month", "7d", "14d", "30d", "90d"];
 const GROUPS = ["day", "model", "key", "agent"];
 export const spendInput = {
-    range: z.enum(RANGES).optional().describe("How far back to look. Defaults to 7d."),
+    range: z
+        .enum(RANGES)
+        .optional()
+        .describe('How far back to look. "month" is the UTC calendar month to date, the Console\'s default window. Defaults to 7d.'),
     group_by: z.enum(GROUPS).optional().describe("How to break the total down. Defaults to model."),
 };
+const savingsBlock = z.object({
+    requests: z.number(),
+    served_cost_usd: z.number(),
+    baseline_cost_usd: z.number(),
+    difference_usd: z.number(),
+    baseline_models: z.array(z.string()),
+});
 export const spendOutput = {
     enabled: z.boolean().describe("False when request tracing is not enabled on this deployment."),
     range: z.string(),
     group_by: z.string(),
-    summary: z.record(z.unknown()).nullable(),
+    cost_usd: z
+        .number()
+        .nullable()
+        .describe("The spend total. The billing ledger's figure (spend.cost_usd), the same one the Console shows, unless " +
+        "cost_source says otherwise. Null when neither figure is available."),
+    cost_source: z
+        .enum(["ledger", "trace"])
+        .nullable()
+        .describe('"ledger" when cost_usd is the billing ledger\'s figure, as in the Console. "trace" when the ledger figure was ' +
+        "null or not reported and cost_usd fell back to the request trace's legacy copy (summary.cost_usd), which " +
+        "can differ from the Console."),
+    spend: z
+        .record(z.unknown())
+        .nullable()
+        .describe("The billing ledger's spend block as the API returned it. Null when the ledger could not be read."),
+    summary: z
+        .record(z.unknown())
+        .nullable()
+        .describe("Requests, errors, tokens and latency from the request trace. Its cost_usd is the legacy figure."),
     groups: z.array(z.record(z.unknown())),
+    savings: z
+        .object({
+        named: savingsBlock.describe("Measured: requests that named a model and were routed to a cheaper one."),
+        plan_ceiling: savingsBlock.describe("A comparison, not a saving: auto requests against the priciest model the plan allows, which nobody asked for."),
+        unpriced_routed_requests: z.number(),
+    })
+        .nullable()
+        .describe("Routing savings from the ledger, as two separate figures. Never add them together. Null when not reported."),
     is_floor: z
         .boolean()
         .describe("True when some rows were unpriced or the row cap bound, so the totals are a lower bound, not a total."),
@@ -54,6 +107,42 @@ export const spendOutput = {
 };
 const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
 const padStart = (s, n) => (s.length >= n ? s : " ".repeat(n - s.length) + s);
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+/** A savings block as a complete, typed object, or null when it is not there. */
+function block(b) {
+    if (!b || typeof b !== "object")
+        return null;
+    return {
+        requests: isNum(b.requests) ? b.requests : 0,
+        served_cost_usd: isNum(b.served_cost_usd) ? b.served_cost_usd : 0,
+        baseline_cost_usd: isNum(b.baseline_cost_usd) ? b.baseline_cost_usd : 0,
+        difference_usd: isNum(b.difference_usd) ? b.difference_usd : 0,
+        baseline_models: Array.isArray(b.baseline_models) ? b.baseline_models.filter((m) => typeof m === "string") : [],
+    };
+}
+/** The savings lines. Each figure on its own line; there is no line that adds them. */
+function savingsLines(named, ceiling, unpriced) {
+    const against = (b, fallback) => b.baseline_models.length ? b.baseline_models.join(", ") : fallback;
+    const lines = [];
+    if (named.requests > 0) {
+        const d = named.difference_usd;
+        lines.push(d < 0
+            ? `Models you named: routing cost ${money(-d)} more on ${plural(named.requests, "request")} ` +
+                `(${money(named.served_cost_usd)} instead of ${money(named.baseline_cost_usd)} on ${against(named, "the named models")}).`
+            : `Saved on models you named: ${money(d)} on ${plural(named.requests, "request")} ` +
+                `(${money(named.served_cost_usd)} instead of ${money(named.baseline_cost_usd)} on ${against(named, "the named models")}).`);
+    }
+    if (ceiling.requests > 0) {
+        lines.push(`Compared with the best model your plan allows: ${money(ceiling.difference_usd)} on ` +
+            `${plural(ceiling.requests, "auto request")}. A comparison, not a saving: nothing was named, and ` +
+            `${against(ceiling, "your plan's top model")} was not requested.`);
+    }
+    if (unpriced > 0) {
+        lines.push(`${plural(unpriced, "routed request")} carry a baseline that could not be priced and ${unpriced === 1 ? "is" : "are"} in neither figure.`);
+    }
+    return lines.length ? ["Routing savings (two separate figures, never added together):", ...lines.map((l) => `  ${l}`)] : [];
+}
 export async function runSpend(cfg, args) {
     const missing = requireKey(cfg);
     if (missing)
@@ -75,45 +164,97 @@ export async function runSpend(cfg, args) {
                 enabled: false,
                 range,
                 group_by: groupBy,
+                cost_usd: null,
+                cost_source: null,
+                spend: null,
                 summary: null,
                 groups: [],
+                savings: null,
                 is_floor: false,
                 message: b.message ?? null,
             });
         }
         const s = b.summary ?? {};
-        const unpriced = s.unpriced_requests ?? 0;
-        const truncated = b.truncated === true;
+        const spend = b.spend && typeof b.spend === "object" ? b.spend : null;
+        /*
+         * The Console's figure, or the legacy one and a sentence saying so. The
+         * unpriced count and its denominator always come from the same table as
+         * the total they qualify.
+         */
+        const fromLedger = spend !== null && isNum(spend.cost_usd);
+        const traceCost = isNum(s.cost_usd) ? s.cost_usd : null;
+        const cost = fromLedger ? spend.cost_usd : traceCost;
+        const costSource = fromLedger ? "ledger" : traceCost !== null ? "trace" : null;
+        const unpriced = fromLedger ? spend.unpriced_rows ?? 0 : s.unpriced_requests ?? 0;
+        const truncated = b.truncated === true || (fromLedger && spend.truncated === true);
         const isFloor = unpriced > 0 || truncated;
         const groups = b.groups ?? [];
-        const head = `Last ${b.range ?? range}  ·  ${s.requests ?? 0} request${s.requests === 1 ? "" : "s"}  ·  ` +
-            `${money(typeof s.cost_usd === "number" ? s.cost_usd : null)}` +
+        /* As the Console renders it: a window in which no row carried a price has
+           an unknown total, not a total of zero. */
+        const priceable = fromLedger ? spend.rows ?? 0 : s.requests ?? 0;
+        const costText = cost === null ? "spend unknown" : priceable > 0 && unpriced >= priceable ? "unpriced" : money(cost);
+        const shown = b.range ?? range;
+        const head = `${shown === "month" ? "This month (UTC)" : `Last ${shown}`}  ·  ${plural(s.requests ?? 0, "request")}  ·  ` +
+            costText +
             (s.total_tokens ? `  ·  ${s.total_tokens.toLocaleString("en-US")} tokens` : "") +
-            (s.errors ? `  ·  ${s.errors} error${s.errors === 1 ? "" : "s"}` : "");
+            (s.errors ? `  ·  ${plural(s.errors, "error")}` : "");
+        /* Per group, the same rule as the Console's breakdown: the ledger's spend
+           when the group carries it, the trace's copy only when it does not. */
+        const groupCost = (g) => (isNum(g.ledger_cost_usd) ? g.ledger_cost_usd : isNum(g.cost_usd) ? g.cost_usd : null);
+        const groupUnpriced = (g) => isNum(g.ledger_cost_usd) ? g.ledger_unpriced_rows ?? 0 : g.unpriced_requests ?? 0;
         const w = Math.max(3, ...groups.map((g) => String(g.key ?? "").length));
         const table = groups.length
             ? [
                 "",
                 `${pad(String(groupBy).toUpperCase(), w)}  ${padStart("REQS", 6)}  ${padStart("COST", 11)}`,
-                ...groups.map((g) => `${pad(String(g.key ?? ""), w)}  ${padStart(String(g.requests ?? 0), 6)}  ` +
-                    `${padStart(money(typeof g.cost_usd === "number" ? g.cost_usd : null), 11)}` +
-                    (g.unpriced_requests ? `  (${g.unpriced_requests} unpriced)` : "")),
+                ...groups.map((g) => {
+                    const u = groupUnpriced(g);
+                    return (`${pad(String(g.key ?? ""), w)}  ${padStart(String(g.requests ?? 0), 6)}  ` +
+                        `${padStart(money(groupCost(g)), 11)}` +
+                        (u ? `  (${u} unpriced)` : ""));
+                }),
             ].join("\n")
             : "\nNo requests in this window.";
+        const named = block(b.savings?.named);
+        const ceiling = block(b.savings?.plan_ceiling);
+        const savings = named && ceiling
+            ? {
+                named,
+                plan_ceiling: ceiling,
+                unpriced_routed_requests: isNum(b.savings?.unpriced_routed_requests) ? b.savings.unpriced_routed_requests : 0,
+            }
+            : null;
+        const unmetered = b.ledger?.unmetered_requests ?? 0;
         const notes = [
+            !fromLedger
+                ? spend === null && "spend" in b
+                    ? "The billing ledger could not be read, so this total is the request trace's copy of each price (the legacy summary.cost_usd). It can differ from the Console's Spend."
+                    : "This deployment does not report the billing ledger's spend, so this total is the request trace's copy of each price (the legacy summary.cost_usd). It can differ from the Console's Spend."
+                : null,
+            fromLedger && (spend.byok_cost_usd ?? 0) > 0
+                ? `${money(spend.managed_cost_usd ?? 0)} billed by Lobstack · ${money(spend.byok_cost_usd ?? 0)} on your own provider key.`
+                : null,
             unpriced
-                ? `${unpriced} request${unpriced === 1 ? "" : "s"} could not be priced. Those rows sum as zero, so the total above is a floor, not a total.`
+                ? `${plural(unpriced, fromLedger ? "row" : "request")} could not be priced. Those sum as zero, so the total above is a floor, not a total.`
                 : null,
             truncated ? "The row cap bound on this range, so older requests are not counted here." : null,
+            fromLedger && unmetered > 0
+                ? `${plural(unmetered, "served request")} ${unmetered === 1 ? "has" : "have"} no billing ledger row, so ${unmetered === 1 ? "it is" : "they are"} not in this total.`
+                : null,
             typeof s.p95_latency_ms === "number" ? `p50 ${s.p50_latency_ms ?? "—"}ms · p95 ${s.p95_latency_ms}ms` : null,
             baseNote(cfg),
-        ].filter((n) => n !== null);
-        return ok([head + table + (notes.length ? "\n\n" + notes.join("\n") : "")], {
+        ].filter((n) => typeof n === "string");
+        const saved = savings ? savingsLines(savings.named, savings.plan_ceiling, savings.unpriced_routed_requests) : [];
+        return ok([head + table + (saved.length ? "\n\n" + saved.join("\n") : "") + (notes.length ? "\n\n" + notes.join("\n") : "")], {
             enabled: true,
             range: b.range ?? range,
             group_by: b.group_by ?? groupBy,
+            cost_usd: cost,
+            cost_source: costSource,
+            spend: (spend ?? null),
             summary: (b.summary ?? null),
             groups: groups,
+            savings,
             is_floor: isFloor,
             message: null,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobstack-ai/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The Lobstack API as an MCP server: one key across many model providers, and what each call cost.",
   "type": "module",
   "bin": {