waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/sessioncost/costtypes.d.ts

@@ -0,0 +1,209 @@
+/**
+ * How much this conversation carries into every turn, relative to a fresh one.
+ *
+ *  - `fresh`  — nothing to say, or too early to say it. No chip.
+ *  - `warm`   — past the point where a multi-turn task is cheaper elsewhere.
+ *  - `heavy`  — a turn here costs several times a fresh turn.
+ *  - `steep`  — an order of magnitude. The monsters in the measurement.
+ */
+export type SessionCostLevel = "fresh" | "warm" | "heavy" | "steep";
+/**
+ * The thresholds, and where they come from.
+ *
+ * They are read off `breakEvenTurns`, not chosen: each is the multiple at which
+ * a particular size of task stops being cheaper here.
+ *
+ *   2.5× — break-even is ~13 turns: a session's worth of work belongs elsewhere.
+ *   5×   — break-even is ~5 turns: so does an ordinary errand.
+ *   9×   — break-even is ~3 turns: so does nearly anything new.
+ *
+ * They also happen to be the shape of the measured distribution — the long
+ * sessions in the fortnight sampled sat at 4-6×, and the handful that dominated
+ * the bill sat near 10× — which is the sanity check, not the derivation.
+ *
+ * **Those turn counts were 8/3/1 while `breakEvenTurns` wrote the fresh
+ * session's baseline at the 5-minute cache tier.** It does not: measured over
+ * every conversation log on this desktop, 8,160 of 8,160 main-conversation
+ * requests that wrote cache wrote it at the 1-HOUR tier (2× input, not 1.25×),
+ * and the only 5-minute writes anywhere were the 571 subagent logs. The
+ * multiples below are unchanged — they are read off the distribution too — but
+ * each of them now means about 65% more turns than this comment used to claim,
+ * and the old figures were nudging people out of warm sessions early.
+ */
+export declare const MULT_WARM = 2.5;
+export declare const MULT_HEAVY = 5;
+export declare const MULT_STEEP = 9;
+/**
+ * Turns before a multiple means anything.
+ *
+ * The first turns of any session climb steeply off the baseline simply because
+ * the model is reading the files it was pointed at. Calling that "3× a fresh
+ * session" is true and useless — it IS the fresh session, mid-warm-up. Nothing
+ * is said until the conversation has settled into its own slope.
+ */
+export declare const MIN_TURNS = 6;
+/**
+ * How long the prompt cache holds a conversation's prefix, and how long after
+ * that it is worth SAYING the cache is gone.
+ *
+ * ── What is actually knowable ───────────────────────────────────────────────
+ *
+ * The cache is server-side and nothing reports its state. What the CLI's log
+ * gives is the last time this conversation ran, and the entry's lifetime is
+ * measured from the START of a request, refreshed on every hit. So an upper
+ * bound on warmth is derivable and an exact expiry is not — and the difference
+ * is not academic, because three things routinely keep a prefix alive that
+ * this conversation's own log cannot see:
+ *
+ *  - a FORK (`--fork-session`) continues the same prefix in a DIFFERENT log,
+ *  - `--continue` after a limit exit, and the remote-control bridge, do too,
+ *  - a request that hit the usage wall leaves a record with no usage at all,
+ *    and it still warmed the cache.
+ *
+ * ── The measurement, and the two things that corrupt it ─────────────────────
+ *
+ * Asking the logs "was the prefix served from cache" has two traps, and both
+ * of them manufacture fake WARM readings:
+ *
+ *  1. **A compaction inside the gap.** The window drops to a tenth, so the
+ *     request after it writes a small number that looks nothing like a
+ *     re-write of the old window. Those gaps are excluded, not counted warm.
+ *  2. **`cache_creation > cache_read` is the WRONG test.** Every cold resume
+ *     still reads the tools-and-system preamble, which is a separate cache
+ *     entry kept warm by sibling sessions in the same repo and measured at
+ *     32.5k-36.8k here. A 60k conversation coming back cold reads 36.8k and
+ *     writes 30.6k — write < read, and it was stone cold. The test is whether
+ *     the read covers the CONVERSATION's own previous context.
+ *
+ * With both corrected, over every conversation log on this desktop carrying
+ * more than 40k, by the gap between one request and the next:
+ *
+ *   under 30 min   0.2% cold  ·  30-50 min  0%  ·  50-58 min  5%
+ *   58-62 min       36% cold  ·  62-70 min  89%  ·  70-90 min  91%
+ *   90-120 min      96% cold  ·  2-4 h     100% (48 of 48)  ·  over 4 h  99%
+ *
+ * The hour is real and the cliff is sharp — and it is 36% wide at the edge, so
+ * a countdown would be printing minutes into the one band where the answer is
+ * a coin toss. There is no countdown here for that reason, and no expiry
+ * instant on any screen.
+ *
+ * ── Why the threshold is the hour plus a half ───────────────────────────────
+ *
+ * The log record is stamped when GENERATION ENDED, not when the request
+ * started (measured: median 4 s later, p99 49 s, worst 9 min), so
+ * `lastTurnAt + TTL` is already past the true expiry — and a 66-minute gap
+ * that came back warm is in this data, which is what that skew looks like.
+ * Half an hour of margin puts the claim in the 96% band without waiting for
+ * the 100% one: the earlier draft of this rule used TWICE the TTL on a
+ * corpus reading of "5% warm between one and four hours", and that 5% was the
+ * two artefacts above. The real figure is 1 warm resume in 71.
+ *
+ * What is left past four hours is one warm reading in 118 — a fork or a
+ * resurrection continuing the prefix in a file this conversation cannot see.
+ * So it is still a heuristic, worded as one wherever it is printed, and it
+ * never appears as a number of minutes or a figure in dollars.
+ */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Past this much silence, the cache is very likely gone.
+ *
+ * Deliberately not `CACHE_TTL_MS` itself — see above. The TTL is what the API
+ * promises; this is the point where the log alone is evidence.
+ */
+export declare const CACHE_COLD_AFTER_MS: number;
+/**
+ * Has this conversation's cached prefix very likely expired?
+ *
+ *  - `true`  — nothing has run here for `CACHE_COLD_AFTER_MS`.
+ *  - `false` — too recent to say that. NOT a claim that it is warm.
+ *  - `null`  — unknowable: nothing recorded a last turn, or a turn is running
+ *              right now (which refreshes the entry continuously, so any
+ *              reading taken mid-turn is about to be wrong).
+ *
+ * `now` is the CALLER's, and on the phone it must be the phone's own clock at
+ * render time: a flag computed on the host is stale the moment it is sent, and
+ * a device that has been asleep for three hours has to recompute this, not
+ * redraw it.
+ */
+export declare function cacheLikelyCold(lastTurnAt: number | null | undefined, now: number, turnActive?: boolean | null): boolean | null;
+export interface SessionCostInput {
+    /** Context carried by the most recent turn, in tokens — what the next turn
+     *  re-reads. The last reading of the series, not the peak: a compaction
+     *  genuinely makes the next turn cheap again. */
+    tok: number;
+    /**
+     * The session's FIRST reading — the measured price of a turn in a fresh
+     * session in this repo, on this machine, with this CLAUDE.md and these tools.
+     *
+     * Deliberately measured rather than assumed: the baseline is dominated by the
+     * project's own CLAUDE.md and MCP surface, so it is a per-repo fact that
+     * varies by an order of magnitude across one desktop. Null when the log was
+     * truncated and there is no first reading to quote — and then there is no
+     * multiple and nothing is claimed, rather than a number invented from a
+     * constant that would be wrong for most repos.
+     */
+    baseTok: number | null;
+    /** Turns this conversation has completed — user records that opened one, NOT
+     *  readings in the series (a single turn writes one reading per request, so a
+     *  tool-heavy turn writes a dozen). Null when nothing counted them. */
+    turns: number | null;
+    /** Sum of every reading: what this conversation has carried in total. Not a
+     *  bill (cache reads are a tenth of input, and the plan is not in the log) —
+     *  it is the volume, which is what a usage limit actually counts. */
+    spentTok: number | null;
+    /**
+     * What the session has USED in total: the same volume plus what each turn
+     * generated plus everything its subagents spent in their own logs.
+     *
+     * `spentTok` is the curve's integral — the input side of this conversation
+     * alone, which is the right number for "what does the next turn re-read" and
+     * the wrong one for "what has this cost". A session that fans out to eight
+     * agents carries a small window and spends millions, and until this existed
+     * nothing on any screen could say so.
+     *
+     * A FLOOR, always worded "so far": a truncated log undercounts and an agent
+     * log that was cleaned up is one nobody can add. Null when nothing measured
+     * it — an older host sends no such field, and a number invented from
+     * `spentTok` would be the plausible wrong one.
+     */
+    usageTok: number | null;
+    /** The subagent share of `usageTok`, already inside it. Null when unmeasured,
+     *  0 when measured and this session ran none. */
+    agentTok: number | null;
+    /**
+     * `cacheLikelyCold`'s answer for this session, or absent when nobody asked.
+     *
+     * Only `true` changes anything that is said. `false` and `null` both leave
+     * every sentence exactly as it was, because neither is evidence that the
+     * cache is WARM — one is "too recent to claim otherwise" and the other is
+     * "nothing to read". The asymmetry is the point: this may make a reading
+     * more cautious, never more encouraging.
+     *
+     * It goes IN and does not come back out: the reading carries no boolean at
+     * all, because every boolean on it is one a caller can mistake for a gate,
+     * and what a cold window changes is which sentence is true — which is
+     * already in `note` and `advice`.
+     */
+    cacheCold?: boolean | null;
+}
+export interface SessionCostReading {
+    level: SessionCostLevel;
+    tok: number;
+    baseTok: number | null;
+    /** `tok / baseTok`. Null when there is no baseline to divide by. */
+    multiple: number | null;
+    /** More turns of new work than this, and a fresh session would have been
+     *  cheaper. Null when there is no baseline, or when the session is still
+     *  close enough to one that the answer is not a small number. */
+    breakEven: number | null;
+    spentTok: number | null;
+    usageTok: number | null;
+    agentTok: number | null;
+    turns: number | null;
+    /** Short chip text — `"4.8×"`. Null at `fresh`, which draws nothing. */
+    chip: string | null;
+    /** One sentence of fact. Never an instruction. */
+    note: string;
+    /** What the fact implies, as a suggestion, when there is one worth making. */
+    advice: string | null;
+}

package/node_modules/@waterplane/shared/dist/sessioncost/costtypes.js

@@ -0,0 +1,128 @@
+// Cut from sessioncost.ts (move only): the level vocabulary, thresholds, cache age and the input/reading records
+// The one door stays `./sessioncost.js`; this slice imports its siblings directly, never the barrel.
+/**
+ * The thresholds, and where they come from.
+ *
+ * They are read off `breakEvenTurns`, not chosen: each is the multiple at which
+ * a particular size of task stops being cheaper here.
+ *
+ *   2.5× — break-even is ~13 turns: a session's worth of work belongs elsewhere.
+ *   5×   — break-even is ~5 turns: so does an ordinary errand.
+ *   9×   — break-even is ~3 turns: so does nearly anything new.
+ *
+ * They also happen to be the shape of the measured distribution — the long
+ * sessions in the fortnight sampled sat at 4-6×, and the handful that dominated
+ * the bill sat near 10× — which is the sanity check, not the derivation.
+ *
+ * **Those turn counts were 8/3/1 while `breakEvenTurns` wrote the fresh
+ * session's baseline at the 5-minute cache tier.** It does not: measured over
+ * every conversation log on this desktop, 8,160 of 8,160 main-conversation
+ * requests that wrote cache wrote it at the 1-HOUR tier (2× input, not 1.25×),
+ * and the only 5-minute writes anywhere were the 571 subagent logs. The
+ * multiples below are unchanged — they are read off the distribution too — but
+ * each of them now means about 65% more turns than this comment used to claim,
+ * and the old figures were nudging people out of warm sessions early.
+ */
+export const MULT_WARM = 2.5;
+export const MULT_HEAVY = 5;
+export const MULT_STEEP = 9;
+/**
+ * Turns before a multiple means anything.
+ *
+ * The first turns of any session climb steeply off the baseline simply because
+ * the model is reading the files it was pointed at. Calling that "3× a fresh
+ * session" is true and useless — it IS the fresh session, mid-warm-up. Nothing
+ * is said until the conversation has settled into its own slope.
+ */
+export const MIN_TURNS = 6;
+/**
+ * How long the prompt cache holds a conversation's prefix, and how long after
+ * that it is worth SAYING the cache is gone.
+ *
+ * ── What is actually knowable ───────────────────────────────────────────────
+ *
+ * The cache is server-side and nothing reports its state. What the CLI's log
+ * gives is the last time this conversation ran, and the entry's lifetime is
+ * measured from the START of a request, refreshed on every hit. So an upper
+ * bound on warmth is derivable and an exact expiry is not — and the difference
+ * is not academic, because three things routinely keep a prefix alive that
+ * this conversation's own log cannot see:
+ *
+ *  - a FORK (`--fork-session`) continues the same prefix in a DIFFERENT log,
+ *  - `--continue` after a limit exit, and the remote-control bridge, do too,
+ *  - a request that hit the usage wall leaves a record with no usage at all,
+ *    and it still warmed the cache.
+ *
+ * ── The measurement, and the two things that corrupt it ─────────────────────
+ *
+ * Asking the logs "was the prefix served from cache" has two traps, and both
+ * of them manufacture fake WARM readings:
+ *
+ *  1. **A compaction inside the gap.** The window drops to a tenth, so the
+ *     request after it writes a small number that looks nothing like a
+ *     re-write of the old window. Those gaps are excluded, not counted warm.
+ *  2. **`cache_creation > cache_read` is the WRONG test.** Every cold resume
+ *     still reads the tools-and-system preamble, which is a separate cache
+ *     entry kept warm by sibling sessions in the same repo and measured at
+ *     32.5k-36.8k here. A 60k conversation coming back cold reads 36.8k and
+ *     writes 30.6k — write < read, and it was stone cold. The test is whether
+ *     the read covers the CONVERSATION's own previous context.
+ *
+ * With both corrected, over every conversation log on this desktop carrying
+ * more than 40k, by the gap between one request and the next:
+ *
+ *   under 30 min   0.2% cold  ·  30-50 min  0%  ·  50-58 min  5%
+ *   58-62 min       36% cold  ·  62-70 min  89%  ·  70-90 min  91%
+ *   90-120 min      96% cold  ·  2-4 h     100% (48 of 48)  ·  over 4 h  99%
+ *
+ * The hour is real and the cliff is sharp — and it is 36% wide at the edge, so
+ * a countdown would be printing minutes into the one band where the answer is
+ * a coin toss. There is no countdown here for that reason, and no expiry
+ * instant on any screen.
+ *
+ * ── Why the threshold is the hour plus a half ───────────────────────────────
+ *
+ * The log record is stamped when GENERATION ENDED, not when the request
+ * started (measured: median 4 s later, p99 49 s, worst 9 min), so
+ * `lastTurnAt + TTL` is already past the true expiry — and a 66-minute gap
+ * that came back warm is in this data, which is what that skew looks like.
+ * Half an hour of margin puts the claim in the 96% band without waiting for
+ * the 100% one: the earlier draft of this rule used TWICE the TTL on a
+ * corpus reading of "5% warm between one and four hours", and that 5% was the
+ * two artefacts above. The real figure is 1 warm resume in 71.
+ *
+ * What is left past four hours is one warm reading in 118 — a fork or a
+ * resurrection continuing the prefix in a file this conversation cannot see.
+ * So it is still a heuristic, worded as one wherever it is printed, and it
+ * never appears as a number of minutes or a figure in dollars.
+ */
+export const CACHE_TTL_MS = 60 * 60 * 1000;
+/**
+ * Past this much silence, the cache is very likely gone.
+ *
+ * Deliberately not `CACHE_TTL_MS` itself — see above. The TTL is what the API
+ * promises; this is the point where the log alone is evidence.
+ */
+export const CACHE_COLD_AFTER_MS = CACHE_TTL_MS + 30 * 60 * 1000;
+/**
+ * Has this conversation's cached prefix very likely expired?
+ *
+ *  - `true`  — nothing has run here for `CACHE_COLD_AFTER_MS`.
+ *  - `false` — too recent to say that. NOT a claim that it is warm.
+ *  - `null`  — unknowable: nothing recorded a last turn, or a turn is running
+ *              right now (which refreshes the entry continuously, so any
+ *              reading taken mid-turn is about to be wrong).
+ *
+ * `now` is the CALLER's, and on the phone it must be the phone's own clock at
+ * render time: a flag computed on the host is stale the moment it is sent, and
+ * a device that has been asleep for three hours has to recompute this, not
+ * redraw it.
+ */
+export function cacheLikelyCold(lastTurnAt, now, turnActive) {
+    if (turnActive)
+        return null;
+    if (lastTurnAt == null || !(lastTurnAt > 0) || !Number.isFinite(now))
+        return null;
+    return now - lastTurnAt >= CACHE_COLD_AFTER_MS;
+}
+//# sourceMappingURL=costtypes.js.map

package/node_modules/@waterplane/shared/dist/sessioncost/costtypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costtypes.js","sourceRoot":"","sources":["../../src/sessioncost/costtypes.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,qGAAqG;AAYrG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAE5B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAqC,EACrC,GAAW,EACX,UAA2B;IAE3B,IAAI,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,UAAU,IAAI,IAAI,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClF,OAAO,GAAG,GAAG,UAAU,IAAI,mBAAmB,CAAC;AACjD,CAAC"}

package/node_modules/@waterplane/shared/dist/sessioncost/costwords.d.ts

@@ -0,0 +1,169 @@
+import type { SessionCostReading } from "./costtypes.js";
+/** `n×`, at the precision the number deserves: 2.5 below ten, 12 above it. */
+export declare function fmtMultiple(m: number): string;
+/** Tokens, short — `71k`, `1.2M`. Local to this module on purpose: it is used
+ *  inside the sentences, and a sentence that reads differently on two screens
+ *  because each formatted its own numbers is the bug `tokens.ts` exists over. */
+export declare function fmtTok(n: number): string;
+/**
+ * What a session has used, in one sentence — the ONE wording.
+ *
+ * Every screen that prints the total says it this way: the row's title, the
+ * session header, the context sheet's panel and the toast. It is written "so
+ * far" in all of them because the number is a floor (a truncated log, an agent
+ * log that has been cleaned up), and the agent share is named only when there
+ * IS one — "0 of it in subagents" is a sentence about nothing.
+ */
+export declare function usageText(usageTok: number, agentTok: number | null): string;
+/**
+ * The same total as a chip: `1.4M`, or null when nothing measured it.
+ *
+ * Null rather than `0`, and rather than falling back to the carried volume: a
+ * zero beside a running session reads as a measurement that came back empty,
+ * and this one is simply absent on a host that does not send it.
+ */
+export declare function usageChip(usageTok: number | null | undefined): string | null;
+/**
+ * What the session WOULD have cost, as a chip: `$4.21`, or null.
+ *
+ * The money twin of `usageChip`, and for the same reason it is a separate
+ * function rather than a `fmtUsdShort` call at each site: this is the one place
+ * that decides what "no figure" looks like. Null — never `$0` — when nothing
+ * measured it or nothing could be priced, so the caller falls back to the token
+ * total rather than printing an amount that reads as "this was free".
+ *
+ * Why the chip is money at all: two conversations that carried 38M and 18M
+ * tokens tell you nothing about which one was expensive, because the answer is
+ * the model they ran and how much of the traffic was cache reads at a tenth of
+ * the rate. A dollar figure is the same fact with the arithmetic already done.
+ */
+export declare function costChip(costUsd: number | null | undefined): string | null;
+/**
+ * Fewest weekly percent a calibration is taken from. `/usage` prints a whole
+ * percent, so the reading is ±0.5 of itself: at 5% that is ±10% on every share
+ * derived from it, at 1% it is ±50% — a number that wide is a wrong number.
+ */
+export declare const WEEK_CAL_MIN_PCT = 5;
+/**
+ * Dollars of list-price spend per percent of the weekly limit, or null.
+ *
+ * The account never says what one percent IS, so this measures it: what this
+ * desktop's logs priced in the weekly window up to the scrape, divided by the
+ * percentage the scrape read. The limit weighs models by price, not by raw
+ * tokens (a cache read is a tenth of an input token in both), which is why the
+ * calibration is in money. Traffic the logs never saw — claude.ai, another
+ * machine — counts against the limit but not in the spend, so a share derived
+ * from this errs LOW, and the caller's note says the estimate is this desktop's.
+ */
+export declare function weekUsdPerPct(weekCostUsd: number | null | undefined, weeklyPct: number | null | undefined): number | null;
+/** A dollar figure as a share of the weekly limit — `≈0.4% of week` — or null
+ *  without a calibration or a figure. Below a thousandth it says so rather
+ *  than printing a zero. */
+export declare function weekShareText(costUsd: number | null | undefined, usdPerPct: number | null | undefined): string | null;
+/**
+ * The reader's line under one turn: what that prompt cost, what of it its
+ * subagents spent, the conversation's running total by then, and the context
+ * its last request carried — or null when none was measured.
+ *
+ * Each part is absent rather than `$0` / `0` (see `TranscriptTurn`), and the
+ * money parts end on the counterfactual in words, because a bare dollar figure
+ * under every turn reads as a bill.
+ *
+ * **Subagents are IN the figures when the host placed them** (`agentCostUsd`,
+ * `cumAgentCostUsd`) and the turn's figure then never stands without its split
+ * (`agents`: how much of it they spent). An agent can still be running when
+ * this is drawn — its call returned at once — so the figure then says "so far"
+ * and how many are still at it. Where the host could not place them (an older
+ * host, an unreadable agent directory, an agent it could not attribute) the
+ * figure is the conversation's own and the note SAYS subagents are not in it:
+ * `agents` (how many the turn started, by any evidence the caller has) and
+ * `agentsSoFar` (one was started at or before this turn) are that evidence.
+ *
+ * `usdPerWeekPct` (`weekUsdPerPct`) adds each money figure's share of the
+ * weekly limit beside it, and the note says where that share comes from.
+ */
+export declare function turnCostParts(t: {
+    costUsd?: number;
+    cumCostUsd?: number;
+    ctxTok?: number;
+    agents?: number;
+    agentsSoFar?: boolean;
+    agentCostUsd?: number;
+    cumAgentCostUsd?: number;
+    agentsRunning?: number;
+    agentUnpricedTok?: number;
+    usdPerWeekPct?: number | null;
+    /** What that calibration counted beyond this desktop (`peerWeekSpend`'s `incl. $0.84 on pc`). */
+    weekIncl?: string | null;
+}): {
+    turn: string | null;
+    agents: string | null;
+    total: string | null;
+    ctx: string | null;
+    note: string | null;
+} | null;
+/**
+ * A turn's own tokens, total FIRST and its split beside it — the ONE wording
+ * for the reader's turn foot (`TranscriptTurn.tokens`): `52k tokens — 1.2k in ·
+ * 830 out · 46k cache read · 3.2k cache write`. A total is never printed
+ * without its split, because nearly all of it is usually a cache read at a
+ * tenth of the input rate and "52k" alone overstates what was typed by orders
+ * of magnitude.
+ *
+ * A kind that is zero is left out (a measured zero is not news on a phone
+ * line); null when the field is absent or every kind is zero — never "0 tokens".
+ */
+export declare function turnTokensText(t: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+} | null | undefined): string | null;
+/**
+ * What the NEXT prompt here costs against a fresh session — one line under the
+ * newest finished turn, from the same reading the header chip and the context
+ * sheet use (`sessionCostOf`), so the three cannot disagree.
+ *
+ * Tokens and the multiple, never a dollar figure: the next turn's price needs
+ * the model's rate AND whether the cache is still warm, and a figure built on a
+ * guess at either would be a plausible wrong number. With no first reading
+ * (a log the host tail-read) the comparison is ABSENT and the line says only
+ * what the next prompt re-reads.
+ */
+export declare function nextTurnText(r: SessionCostReading | null | undefined): string | null;
+/**
+ * Why a dollar figure is on screen at all for someone on a flat-fee plan —
+ * the ONE wording, shown wherever a list-price figure can be tapped or
+ * expanded (the per-prompt card, the context & cost sheet, token statistics).
+ *
+ * `costText` says what the number is NOT (a bill). This says what it IS for:
+ * a plan's session and weekly limits do not count every token the same, and
+ * the kinds differ by up to 100× in price on one model (Opus 5.5: a cache read
+ * $0.20/MTok, an output token $20/MTok). A token total adds those up as if
+ * equal, so it says almost nothing about how much of a limit a turn used; the
+ * API list price weighs each kind by its own rate, which makes it the one
+ * number that can be compared across turns, sessions and models.
+ */
+export declare const DOLLARS_WHY_HEAD = "Why dollars on a subscription?";
+export declare const DOLLARS_WHY: string;
+/** Where the per-prompt cost card is drawn, and why the two views differ — said
+ *  under the same "?" as `DOLLARS_WHY`, in both views, so the difference is
+ *  explained wherever the card is. */
+export declare const COST_WHERE_HEAD = "Why only the last prompt in the CLI view?";
+export declare const COST_WHERE: string;
+/**
+ * What a session has cost, in one sentence — the ONE wording, and the framing
+ * is not optional.
+ *
+ * A dollar figure with nothing around it is read as a bill. This one is a
+ * COUNTERFACTUAL: what the same traffic would have cost billed through the API
+ * at list prices, while the CLI this app drives is usually running on a
+ * subscription, which is a flat fee no matter how many tokens go through it.
+ * `pricing.ts` states the whole argument; this is the sentence it produces.
+ *
+ * "so far" for the same reason `usageText` says it — every input is a floor —
+ * and the subagent clause only where there is one. Unpriced tokens are named
+ * rather than quietly charged at zero, because a model missing from the rate
+ * table is the one way this figure goes silently low.
+ */
+export declare function costText(costUsd: number, agentCostUsd: number | null, unpricedTok?: number | null): string;