copilotz 1.0.0-rc.3 → 1.0.0-rc.4

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 1.0.0-rc.4 — 2026-10-30
+
+- **Usage: every use has a price.** It's the cost (a margin of 0) unless the app's price book says
+  otherwise: rates of its own, or a gross `margin` on the cost (`{ margin: 0.9 }` is ten times the
+  cost), from its `since` date on. `markup` is gone: a margin says it. Uses recorded before count at
+  their cost, in totals and when re-rated.
+- **Usage: by part.** Each record keeps its cost and price by part (input, cache reads, cache
+  writes, output, reasoning…) and what caching saved; totals and rollups sum them.
+- **Usage: people see prices.** `usage.totals`, `usage.org` and `usage.calls` give people prices
+  only; costs (and so margins) only platform staff and the system. Each of `usage.org` and
+  `usage.calls` says whether it shows costs (`costs`).
+- **Usage page and `/usage`:** spend (the price) everywhere, with caching visible: hit rate, what
+  reading and writing the cache was charged, and what it saved, overall and by model; cached tokens
+  in the chart and in each call. Platform staff also see cost and gross margin, marked staff-only.
+- **Models:** OpenAI-compatible providers' cache reads and writes are read as each reports them
+  (DeepSeek's cache hits, Moonshot's cached tokens, OpenRouter's cache writes).
+
 ## 1.0.0-rc.3 — 2026-10-30
 
 - **Computers:** connecting one more app (`computer install <app> --code`) no longer stops the

package/README.md

@@ -22,7 +22,7 @@ bun add copilotz                     # Bun
 deno add jsr:@copilotz/copilotz      # Deno (or `deno add npm:copilotz`)
 ```
 
-On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.3"`), and
+On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.4"`), and
 the imports below are the same everywhere. Some pieces need a package of their own, installed beside
 it: `esbuild` to bundle the web host on Node, `@electric-sql/pglite` for PostgreSQL in the process,
 and `@types/react` for the front ends' types.
@@ -204,7 +204,7 @@ and an app serves it from there by default:
 import { computerDownloads } from "copilotz/plugins/compute/downloads";
 
 plugins: [...plugins, await computerDownloads()], // this Copilotz's release
-plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.3" })], // its own: /computer/download/
+plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.4" })], // its own: /computer/download/
 plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })], // or elsewhere
 ```
 
@@ -382,9 +382,15 @@ name, never by importing its code.
     billing; billing builds on models. An app records its own uses with `usage.record`.
   - **Rated as recorded,** so a record keeps what applied. Cost comes from `resources.cost` (the
     app's rates: negotiated, a subscription at 0, compute by the second), else from the catalog's
-    prices; price comes from `resources.price` only (rates of its own, or a `markup` on cost). Rates
-    are keyed by subject, then `provider/*`, then the catalog, then `*`, and dated lists apply each
-    rate from its `since`. A use nothing prices is kept and flagged `unpriced`.
+    prices (each kind of token at its own: input, cache reads and writes, output, reasoning). The
+    price is the cost, a margin of 0, unless `resources.price` says otherwise: rates of its own, or
+    a gross margin on the cost (`{ "*": { margin: 0.2 }, "cloud/*": { margin: 0.9 } }`: 0.9 is ten
+    times the cost). Rates are keyed by subject, then `provider/*`, then the catalog, then `*`, and
+    dated lists apply each rate from its `since`, so a new margin applies from its date on. Each
+    record keeps its cost and price by part too, and what caching saved. A use nothing prices is
+    kept and flagged `unpriced`.
+  - **People see prices** (what they're charged); costs, and so margins, only platform staff and the
+    system.
   - **Totals** by any field or tag, summed by the store (`aggregate`) over indexed fields (time,
     meter, subject, thread; more from the app:
     `collections: { usage: { indexes: [["tags.tenant", "at"]] } }`):
@@ -399,7 +405,8 @@ name, never by importing its code.
   - **Re-rating** (`usage.rerate`) never changes a record: it appends adjustments, dated when made,
     and totals follow.
   - **On the web** (`usageWeb`): an org's Usage page, day by day and against the period before, by
-    person, agent and model; owners and admins see everyone's, anyone else their own.
+    person, agent and model, with what the cache read, wrote and saved; owners and admins see
+    everyone's, anyone else their own.
 
 **`compute/`**: **`computers`**, machines people connect (the computer program in
 `computers/program/`, a worker of the plugin's `computer` kind) and their desks, one per space

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilotz",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "description": "Copilotz: one runtime for Node, Deno, Bun, Cloudflare Workers and the browser.",
   "keywords": [
     "agents",

package/plugins/billing/usage/actions/close.js

@@ -68,7 +68,7 @@ async function close(ctx, rollups, input) {
         // Each day's rollups, as the records hold their fields.
         const byDay = new Map();
         for (const group of groups) {
-            const { day, meter, subject, _kind, _unpriced, ...dims } = group._id;
+            const { day, meter, subject, _kind, _unpriced, _rated, ...dims } = group._id;
             const doc = { _id: "", day, meter, subject, quantities: {}, n: group.n };
             rollups.dimensions.forEach((d, i) => {
                 if (dims[`d${i}`] !== null && dims[`d${i}`] !== undefined)
@@ -78,14 +78,33 @@ async function close(ctx, rollups, input) {
                 doc.kind = _kind;
             if (_unpriced !== null)
                 doc.unpriced = _unpriced;
+            const costs = {};
+            const prices = {};
             for (const unit of rollups.units) {
                 if (group[unit])
                     doc.quantities[unit] = group[unit];
+                if (group[`cost_${unit}`])
+                    costs[unit] = group[`cost_${unit}`];
+                if (group[`price_${unit}`])
+                    prices[unit] = group[`price_${unit}`];
             }
             if (group.cost)
                 doc.cost = group.cost;
             if (group.price)
                 doc.price = group.price;
+            if (Object.keys(costs).length)
+                doc.costs = costs;
+            if (Object.keys(prices).length)
+                doc.prices = prices;
+            const saved = {
+                ...(group.savedCost ? { cost: group.savedCost } : {}),
+                ...(group.savedPrice ? { price: group.savedPrice } : {}),
+            };
+            if (Object.keys(saved).length)
+                doc.saved = saved;
+            // Who rated the price, as the records say (none: priced at cost, as they were before).
+            if (_rated !== null && _rated !== undefined)
+                doc.rated = { price: _rated };
             const list = byDay.get(day) ?? [];
             doc._id = `${day}#${list.length}`;
             list.push(doc);

package/plugins/billing/usage/actions/org.js

@@ -9,19 +9,25 @@
  *   by day, person (`tags.person`), agent (`tags.agent`), model (`subject`).
  * - `usage.calls`: the latest uses, newest first (`{ filter, limit }`).
  *
- * Both only read, so neither is recorded.
+ * People see prices: what they're charged. What it cost (and so the margin)
+ * only platform staff see; each says whether it shows them (`costs`). Both
+ * only read, so neither is recorded.
  */
 import { defineAction } from "../../../../runtime/mod.js";
 import { rollupsOf } from "../shared/settings.js";
-import { totals, UNITS } from "../shared/totals.js";
-import { personOf } from "../shared/use.js";
+import { priceOnly, totals, UNITS } from "../shared/totals.js";
+import { personOf, priceOf } from "../shared/use.js";
 const forbidden = (message) => Object.assign(new Error(message), { code: "forbidden" });
-/** Whether the caller runs the org: an owner or an admin there, or platform staff. */
-async function runsOrg(ctx) {
+/**
+ * What the caller sees: everyone's (`all`) when they run the org (an owner or
+ * an admin there, or platform staff), and costs only as staff.
+ */
+async function sight(ctx) {
     const me = await ctx.call("org.me", {})
         // An app without org roles has nobody who runs one.
         .catch(() => undefined);
-    return !!me && (me.staff === true || me.role === "owner" || me.role === "admin");
+    const staff = me?.staff === true;
+    return { all: staff || me?.role === "owner" || me?.role === "admin", costs: staff };
 }
 const filter = { type: "object" };
 export const orgUsageAction = defineAction({
@@ -38,21 +44,19 @@ export const orgUsageAction = defineAction({
     },
     allow: (actor) => actor.kind === "person",
     run: async (ctx, input) => {
-        const all = await runsOrg(ctx);
+        const { all, costs } = await sight(ctx);
         const person = personOf(ctx.actor);
         if (!all && !person)
             throw forbidden("Only people see usage.");
         // The ledger is read as the system: everyone's once the org says they run it, else theirs.
         const system = ctx.as();
         const asked = (input.filter ?? {});
-        return {
-            totals: await totals(system.db.collection("usage"), {
-                filter: all ? asked : { ...asked, "tags.person": person },
-                by: input.by ?? [],
-                units: input.units ?? UNITS,
-            }, { db: system.db, rollups: rollupsOf(ctx) }),
-            all,
-        };
+        const found = await totals(system.db.collection("usage"), {
+            filter: all ? asked : { ...asked, "tags.person": person },
+            by: input.by ?? [],
+            units: input.units ?? UNITS,
+        }, { db: system.db, rollups: rollupsOf(ctx) });
+        return { totals: costs ? found : found.map(priceOnly), all, costs };
     },
 });
 export const usageCallsAction = defineAction({
@@ -69,7 +73,7 @@ export const usageCallsAction = defineAction({
     },
     allow: (actor) => actor.kind === "person",
     run: async (ctx, input) => {
-        const all = await runsOrg(ctx);
+        const { all, costs } = await sight(ctx);
         const person = personOf(ctx.actor);
         if (!all && !person)
             throw forbidden("Only people see usage.");
@@ -78,17 +82,26 @@ export const usageCallsAction = defineAction({
         // Uses only (adjustments correct a rating; they aren't calls); yours unless you run it.
         { ...asked, kind: { $exists: false }, ...(all ? {} : { "tags.person": person }) }, { sort: { at: -1 }, limit: input.limit ?? 20 });
         return {
-            calls: found.map((r) => ({
-                _id: r._id,
-                meter: r.meter,
-                subject: r.subject,
-                quantities: r.quantities,
-                ...(r.tags ? { tags: r.tags } : {}),
-                ...(r.cost !== undefined ? { cost: r.cost } : {}),
-                ...(r.unpriced?.length ? { unpriced: r.unpriced } : {}),
-                at: r.at,
-            })),
+            calls: found.map((r) => {
+                const price = priceOf(r);
+                const saved = r.saved && (costs ? r.saved : { price: r.saved.price });
+                return {
+                    _id: r._id,
+                    meter: r.meter,
+                    subject: r.subject,
+                    quantities: r.quantities,
+                    ...(r.tags ? { tags: r.tags } : {}),
+                    ...(price !== undefined ? { price } : {}),
+                    ...(r.prices ? { prices: r.prices } : {}),
+                    ...(costs && r.cost !== undefined ? { cost: r.cost } : {}),
+                    ...(costs && r.costs ? { costs: r.costs } : {}),
+                    ...(saved && Object.values(saved).some((v) => v !== undefined) ? { saved } : {}),
+                    ...(r.unpriced?.length ? { unpriced: r.unpriced } : {}),
+                    at: r.at,
+                };
+            }),
             all,
+            costs,
         };
     },
 });

package/plugins/billing/usage/actions/rerate.js

@@ -1,14 +1,24 @@
 /** `usage.rerate`: brings records' cost and price to the books in force now, with adjustments. */
 import { defineAction } from "../../../../runtime/mod.js";
 import { rate, round } from "../shared/rate.js";
+import { priceOf } from "../shared/use.js";
 /** Appends adjustments that bring records' cost and price to what the books say now. */
 async function rerate(ctx, filter) {
     const records = await ctx.db.collection("usage").find(filter);
     const net = new Map();
+    const add = (into, parts, sign = 1) => {
+        for (const [unit, usd] of Object.entries(parts ?? {})) {
+            into[unit] = (into[unit] ?? 0) + sign * usd;
+        }
+    };
     for (const record of records) {
         const id = record.adjusts ?? record._id;
-        const sum = net.get(id) ?? { cost: 0, price: 0 };
-        net.set(id, { cost: sum.cost + (record.cost ?? 0), price: sum.price + (record.price ?? 0) });
+        const sum = net.get(id) ?? { cost: 0, price: 0, costs: {}, prices: {} };
+        sum.cost += record.cost ?? 0;
+        sum.price += priceOf(record) ?? 0;
+        add(sum.costs, record.costs);
+        add(sum.prices, record.prices);
+        net.set(id, sum);
     }
     let adjusted = 0;
     for (const record of records) {
@@ -26,6 +36,14 @@ async function rerate(ctx, filter) {
         const price = round((now.price ?? 0) - was.price);
         if (!cost && !price)
             continue;
+        const delta = (to, from) => {
+            const out = {};
+            add(out, to);
+            add(out, from, -1);
+            return Object.fromEntries(Object.entries(out).map(([u, usd]) => [u, round(usd)]).filter(([, usd]) => usd !== 0));
+        };
+        const costs = delta(now.costs, was.costs);
+        const prices = delta(now.prices, was.prices);
         ctx.record("usage", {
             meter: record.meter,
             subject: record.subject,
@@ -33,6 +51,8 @@ async function rerate(ctx, filter) {
             ...(record.tags ? { tags: record.tags } : {}),
             cost,
             price,
+            ...(Object.keys(costs).length ? { costs } : {}),
+            ...(Object.keys(prices).length ? { prices } : {}),
             rated: now.rated,
             adjusts: record._id,
             kind: "adjustment",

package/plugins/billing/usage/collections/rollup.d.ts

@@ -40,6 +40,38 @@ export declare const rollupSchema: {
         readonly price: {
             readonly type: "number";
         };
+        readonly costs: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "number";
+            };
+        };
+        readonly prices: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "number";
+            };
+        };
+        readonly saved: {
+            readonly type: "object";
+            readonly properties: {
+                readonly cost: {
+                    readonly type: "number";
+                };
+                readonly price: {
+                    readonly type: "number";
+                };
+            };
+        };
+        /** Who rated the price (`rated.price`), as the records say: none for those priced at cost before. */
+        readonly rated: {
+            readonly type: "object";
+            readonly properties: {
+                readonly price: {
+                    readonly type: "string";
+                };
+            };
+        };
         /** Records rolled up. */
         readonly n: {
             readonly type: "integer";
@@ -95,6 +127,38 @@ export declare const usageRollup: {
             readonly price: {
                 readonly type: "number";
             };
+            readonly costs: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: "number";
+                };
+            };
+            readonly prices: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: "number";
+                };
+            };
+            readonly saved: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly cost: {
+                        readonly type: "number";
+                    };
+                    readonly price: {
+                        readonly type: "number";
+                    };
+                };
+            };
+            /** Who rated the price (`rated.price`), as the records say: none for those priced at cost before. */
+            readonly rated: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly price: {
+                        readonly type: "string";
+                    };
+                };
+            };
             /** Records rolled up. */
             readonly n: {
                 readonly type: "integer";
@@ -115,7 +179,22 @@ export declare const usageRollup: {
             [x: string]: string;
         } | undefined;
         cost?: number | undefined;
+        saved?: {
+            [x: string]: unknown;
+            cost?: number | undefined;
+            price?: number | undefined;
+        } | undefined;
         price?: number | undefined;
+        costs?: {
+            [x: string]: number;
+        } | undefined;
+        prices?: {
+            [x: string]: number;
+        } | undefined;
+        rated?: {
+            [x: string]: unknown;
+            price?: string | undefined;
+        } | undefined;
         unpriced?: string[] | undefined;
         n: number;
         quantities: {

package/plugins/billing/usage/collections/rollup.js

@@ -18,6 +18,14 @@ export const rollupSchema = {
         quantities: { type: "object", additionalProperties: { type: "number" } },
         cost: { type: "number" },
         price: { type: "number" },
+        costs: { type: "object", additionalProperties: { type: "number" } },
+        prices: { type: "object", additionalProperties: { type: "number" } },
+        saved: {
+            type: "object",
+            properties: { cost: { type: "number" }, price: { type: "number" } },
+        },
+        /** Who rated the price (`rated.price`), as the records say: none for those priced at cost before. */
+        rated: { type: "object", properties: { price: { type: "string" } } },
         /** Records rolled up. */
         n: { type: "integer" },
     },

package/plugins/billing/usage/collections/usage.d.ts

@@ -32,7 +32,36 @@ export declare const usageSchema: {
         readonly price: {
             readonly type: "number";
         };
-        /** Where each came from: `app`, or the catalog and its date. */
+        /** Each by part (USD): the units, `input` and `output` less the parts priced apart. */
+        readonly costs: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "number";
+            };
+        };
+        readonly prices: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "number";
+            };
+        };
+        /** What caching saved (USD), less what writing the cache cost more. */
+        readonly saved: {
+            readonly type: "object";
+            readonly properties: {
+                readonly cost: {
+                    readonly type: "number";
+                };
+                readonly price: {
+                    readonly type: "number";
+                };
+            };
+        };
+        /**
+         * Who rated each: `app`, or the catalog and its date; `cost` for a price at
+         * cost. A record without a price's (from before every use had one) is
+         * priced at its cost.
+         */
         readonly rated: {
             readonly type: "object";
         };
@@ -98,7 +127,36 @@ export declare const usage: {
             readonly price: {
                 readonly type: "number";
             };
-            /** Where each came from: `app`, or the catalog and its date. */
+            /** Each by part (USD): the units, `input` and `output` less the parts priced apart. */
+            readonly costs: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: "number";
+                };
+            };
+            readonly prices: {
+                readonly type: "object";
+                readonly additionalProperties: {
+                    readonly type: "number";
+                };
+            };
+            /** What caching saved (USD), less what writing the cache cost more. */
+            readonly saved: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly cost: {
+                        readonly type: "number";
+                    };
+                    readonly price: {
+                        readonly type: "number";
+                    };
+                };
+            };
+            /**
+             * Who rated each: `app`, or the catalog and its date; `cost` for a price at
+             * cost. A record without a price's (from before every use had one) is
+             * priced at its cost.
+             */
             readonly rated: {
                 readonly type: "object";
             };
@@ -136,7 +194,18 @@ export declare const usage: {
             [x: string]: string;
         } | undefined;
         cost?: number | undefined;
+        saved?: {
+            [x: string]: unknown;
+            cost?: number | undefined;
+            price?: number | undefined;
+        } | undefined;
         price?: number | undefined;
+        costs?: {
+            [x: string]: number;
+        } | undefined;
+        prices?: {
+            [x: string]: number;
+        } | undefined;
         rated?: {
             [x: string]: unknown;
         } | undefined;

package/plugins/billing/usage/collections/usage.js

@@ -1,7 +1,7 @@
 /** The ledger: one record per use, rated as it was recorded. Appended only. */
 import { defineCollection, } from "../../../../runtime/mod.js";
 import { rollupsOf } from "../shared/settings.js";
-import { totals } from "../shared/totals.js";
+import { priceOnly, totals } from "../shared/totals.js";
 export const usageSchema = {
     type: "object",
     properties: {
@@ -14,7 +14,19 @@ export const usageSchema = {
         /** USD. */
         cost: { type: "number" },
         price: { type: "number" },
-        /** Where each came from: `app`, or the catalog and its date. */
+        /** Each by part (USD): the units, `input` and `output` less the parts priced apart. */
+        costs: { type: "object", additionalProperties: { type: "number" } },
+        prices: { type: "object", additionalProperties: { type: "number" } },
+        /** What caching saved (USD), less what writing the cache cost more. */
+        saved: {
+            type: "object",
+            properties: { cost: { type: "number" }, price: { type: "number" } },
+        },
+        /**
+         * Who rated each: `app`, or the catalog and its date; `cost` for a price at
+         * cost. A record without a price's (from before every use had one) is
+         * priced at its cost.
+         */
         rated: { type: "object" },
         /** What nothing priced: `cost`, `price`. */
         unpriced: { type: "array", items: { type: "string" } },
@@ -43,11 +55,15 @@ export const usage = defineCollection({
          * days come from their rollups when those hold what's asked.
          */
         totals: {
-            // A person sees their own usage; the system, everyone's.
+            // A person sees their own usage, at its price; the system, everyone's, cost too.
             allow: (actor) => actor.kind === "person",
-            run: (records, params = {}, ctx) => totals(records, ctx.actor?.kind === "person"
-                ? { ...params, filter: { ...params.filter, "tags.person": ctx.actor.id } }
-                : params, { db: ctx.db, rollups: rollupsOf(ctx) }),
+            run: async (records, params = {}, ctx) => {
+                const person = ctx.actor?.kind === "person";
+                const found = await totals(records, person
+                    ? { ...params, filter: { ...params.filter, "tags.person": ctx.actor.id } }
+                    : params, { db: ctx.db, rollups: rollupsOf(ctx) });
+                return person ? found.map(priceOnly) : found;
+            },
         },
         /** The records matching `filter`, newest first. */
         list: (records, params = {}) => records.find(params.filter ?? {}, { sort: { at: -1 }, limit: params.limit ?? 100 }),

package/plugins/billing/usage/mod.d.ts

@@ -11,9 +11,14 @@
  *   - its **cost** comes from `resources.cost` (the app's rates: negotiated,
  *     a subscription at 0, a terminal's seconds), else from the models.dev
  *     catalog for models it knows;
- *   - its **price** (what the app charges) comes from `resources.price` only:
- *     rates of its own, or a `markup` on the cost. Nothing ships one.
- *   - A use nothing prices is recorded all the same, and flagged `unpriced`.
+ *   - its **price** (what the app charges) is its cost (a margin of 0) unless
+ *     `resources.price` says: rates of its own, or a gross `margin` on the
+ *     cost (`{ "*": { margin: 0.2 } }`; 0.9 is ten times the cost);
+ *   - each is kept by part (input, cached, cacheWrite, output, reasoning,
+ *     seconds…), with what caching saved;
+ *   - a use nothing prices is recorded all the same, and flagged `unpriced`.
+ * - **Who sees what:** people see prices (what they're charged); costs, and
+ *   so margins, only platform staff and the system.
  * - **Totals** by any field or tag: `runtime.query("usage.totals", { filter, by })`.
  *   Whole closed days come from rollups (`usage.close`, scheduled daily),
  *   the rest from the records, with the same result.
@@ -21,7 +26,7 @@
  *   adjustments for what new rates would change, so totals follow.
  * - **Across an org** (where the app serves many): `usage.org` (totals) and
  *   `usage.calls` (the latest uses) give its owners and admins everyone's,
- *   and anyone else their own. Its web front end (web.tsx) is the org
+ *   and anyone else their own, at their price (cost too for staff). Its web front end (web.tsx) is the org
  *   page's Usage section.
  *
  * Rates are keyed by subject (`"openai/gpt-6.1-sol"`), then by provider
@@ -33,7 +38,7 @@
 import { type Plugin } from "../../../runtime/mod.js";
 export type { Use } from "./shared/use.js";
 export type { UsageRecord } from "./collections/usage.js";
-export { priced, type PriceRate, type Quantities, type Rate, rate } from "./shared/rate.js";
+export { type Parts, partsOf, priced, type PriceRate, type Quantities, type Rate, rate, } from "./shared/rate.js";
 export { type Rollups, type Totals, totals, UNITS } from "./shared/totals.js";
 export type { UsageSettings } from "./shared/settings.js";
 /** The usage ledger: records, rating, totals, rollups and re-rating. */

package/plugins/billing/usage/mod.js

@@ -11,9 +11,14 @@
  *   - its **cost** comes from `resources.cost` (the app's rates: negotiated,
  *     a subscription at 0, a terminal's seconds), else from the models.dev
  *     catalog for models it knows;
- *   - its **price** (what the app charges) comes from `resources.price` only:
- *     rates of its own, or a `markup` on the cost. Nothing ships one.
- *   - A use nothing prices is recorded all the same, and flagged `unpriced`.
+ *   - its **price** (what the app charges) is its cost (a margin of 0) unless
+ *     `resources.price` says: rates of its own, or a gross `margin` on the
+ *     cost (`{ "*": { margin: 0.2 } }`; 0.9 is ten times the cost);
+ *   - each is kept by part (input, cached, cacheWrite, output, reasoning,
+ *     seconds…), with what caching saved;
+ *   - a use nothing prices is recorded all the same, and flagged `unpriced`.
+ * - **Who sees what:** people see prices (what they're charged); costs, and
+ *   so margins, only platform staff and the system.
  * - **Totals** by any field or tag: `runtime.query("usage.totals", { filter, by })`.
  *   Whole closed days come from rollups (`usage.close`, scheduled daily),
  *   the rest from the records, with the same result.
@@ -21,7 +26,7 @@
  *   adjustments for what new rates would change, so totals follow.
  * - **Across an org** (where the app serves many): `usage.org` (totals) and
  *   `usage.calls` (the latest uses) give its owners and admins everyone's,
- *   and anyone else their own. Its web front end (web.tsx) is the org
+ *   and anyone else their own, at their price (cost too for staff). Its web front end (web.tsx) is the org
  *   page's Usage section.
  *
  * Rates are keyed by subject (`"openai/gpt-6.1-sol"`), then by provider
@@ -40,7 +45,7 @@ import { DEFAULTS, rollupsOf } from "./shared/settings.js";
 import { recordAction } from "./actions/record.js";
 import { orgUsageAction, usageCallsAction } from "./actions/org.js";
 import { ledger } from "./resources/ledger.js";
-export { priced, rate } from "./shared/rate.js";
+export { partsOf, priced, rate, } from "./shared/rate.js";
 export { totals, UNITS } from "./shared/totals.js";
 /** The usage ledger: records, rating, totals, rollups and re-rating. */
 export const usagePlugin = definePlugin({

package/plugins/billing/usage/resources/commands.js

@@ -2,7 +2,7 @@
 import { command } from "../../../../hosts/terminal/mod.js";
 export const commands = {
     "/usage": command({
-        description: "What was used and what it cost, by model",
+        description: "What was used and what it was charged, by model",
         usage: "[all]",
         async run(rest, term) {
             const { open } = await term.state();