waterplane 0.0.1 → 0.1.6

package/packages/host/dist/localledger.js

@@ -0,0 +1,214 @@
+/**
+ * claude-local's token ledger, and the person's own price table — the two
+ * halves of `GET /api/tokenstats/claude-local`.
+ *
+ * Beside `tokenstats.ts` rather than in it: that store is the ledger; this is
+ * a CUT of what it already answers (no rescan, no second tally) plus the disk
+ * half of `shared/pricing.ts`'s user table. Reasoning:
+ * docs/notes/token-stats-architecture.md#local-models-all-backends-and-your-own-prices.
+ */
+import { mkdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { addTotals, costOfAny, dayToMs, emptyUserPrices, isAnthropicModel, isPriceGap, parseUserPrices, priceGapText, tokenTotal, zeroTotals, } from "@waterplane/shared";
+import { env } from "./env.js";
+import { configDir } from "./branddirs.js";
+import { writeJsonAtomic } from "./jsonstore.js";
+// ── The person's own prices, for models Anthropic's list does not name ───────
+//
+// `shared/pricing.ts` has the rules (`costOfAny`: the list first, the file only
+// fills a gap, a kind with no rate is a gap, one currency per entry). This is
+// the disk half: WHICH file, re-read when its mtime moves, and every failure a
+// sentence in `problems` rather than a throw — a typo in a price file must not
+// take the statistics screen with it.
+/** `WATERPLANE_PRICES` (a path), else `<config dir>/prices.json`. */
+export function pricesFilePath() {
+    const o = (env("PRICES") || "").trim();
+    return o || join(configDir(), "prices.json");
+}
+let pricesCache = null;
+/** The parsed table, its path, and what in it was refused. A missing file is an
+ *  empty table and NO problem — not having one is the normal case. */
+export function readUserPrices() {
+    const file = pricesFilePath();
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(file).mtimeMs;
+    }
+    catch {
+        return { table: emptyUserPrices(), file };
+    }
+    if (pricesCache && pricesCache.file === file && pricesCache.mtimeMs === mtimeMs)
+        return { table: pricesCache.table, file };
+    let table;
+    try {
+        table = parseUserPrices(JSON.parse(readFileSync(file, "utf8")));
+    }
+    catch (e) {
+        table = { entries: [], problems: [`${file} could not be read as JSON: ${e?.message || String(e)}`] };
+    }
+    pricesCache = { file, mtimeMs, table };
+    return { table, file };
+}
+const LEDGER_KINDS = (t) => ({ input: t.input, output: t.output, cacheRead: t.cacheRead, cacheWrite: t.cacheWrite });
+/**
+ * The NON-Anthropic models in Claude Code's own ledger, as a backend ledger —
+ * what `GET /api/tokenstats/claude-local` answers.
+ *
+ * claude-local is the same binary pointed at another runner, so its tokens are
+ * in the SAME jsonl logs this store reads: there is no second ledger to open,
+ * and a second tally would drift. This is a CUT of the one ledger by model id
+ * (`isAnthropicModel`), off the per-model buckets the store already keeps —
+ * `models` for the all-time split, `TokenDay.byModel` for the days. The Claude
+ * Code tab makes the complementary cut, so between them every token is shown
+ * exactly once and never summed across the two.
+ *
+ * `sessions` is ABSENT: a conversation is not per model, and a count of the
+ * logs a model appeared in is a different fact from what the field means.
+ *
+ * Money, per model, in this order: the backend's own catalogue says it runs on
+ * this machine (`zeroCost`) ⇒ 0 (`source: "local"`) — first, so a price glob
+ * written for a hosted twin cannot charge a loopback model; else `costOfAny`
+ * (the list, then the person's file); else a SENTENCE saying how to add a
+ * price. Never a guessed rate, never a $0 for "unknown".
+ */
+export function localSliceLedger(doc, opts) {
+    const mine = (m) => !isAnthropicModel(m) && (opts.keep ? opts.keep(m) : true);
+    const local = doc.models.filter((g) => mine(g.key) && tokenTotal(g) > 0);
+    if (local.length === 0) {
+        return {
+            available: false,
+            reason: opts.keep
+                ? `No model of ${opts.label}'s has run through Claude Code on this desktop yet — its tokens appear here once one has.`
+                : `No non-Anthropic model has run through Claude Code on this desktop yet — every model in its logs is Claude's, and those are on the Claude Code tab.`,
+        };
+    }
+    const totals = zeroTotals();
+    for (const g of local)
+        addTotals(totals, g);
+    const days = [];
+    for (const d of doc.days) {
+        const slices = (d.byModel ?? []).filter((s) => mine(s.model) && tokenTotal(s.totals) > 0);
+        if (slices.length === 0)
+            continue;
+        const dt = zeroTotals();
+        for (const s of slices)
+            addTotals(dt, s.totals);
+        days.push({
+            day: d.day, kinds: LEDGER_KINDS(dt), turns: dt.turns,
+            byModel: slices
+                .map((s) => ({ key: s.model, kinds: LEDGER_KINDS(s.totals), turns: s.totals.turns }))
+                .sort((a, b) => tokenTotalOfKinds(b.kinds) - tokenTotalOfKinds(a.kinds) || a.key.localeCompare(b.key)),
+        });
+    }
+    const sums = new Map();
+    const models = local.map((g) => {
+        if (opts.zeroCost.has(g.key)) {
+            sums.set("USD", sums.get("USD") ?? 0);
+            return { key: g.key, currency: "USD", total: 0, source: "local" };
+        }
+        const p = costOfAny(g, g.key, undefined, opts.prices);
+        if (isPriceGap(p))
+            return { key: g.key, unpriced: priceGapText(p, opts.pricesFile) };
+        sums.set(p.currency, (sums.get(p.currency) ?? 0) + p.cost.total);
+        return { key: g.key, currency: p.currency, total: p.cost.total, source: p.source, ...(p.pattern ? { pattern: p.pattern } : {}) };
+    });
+    const cost = {
+        totals: [...sums].map(([currency, total]) => ({ currency, total })).sort((a, b) => a.currency.localeCompare(b.currency)),
+        models,
+        pricesFile: opts.pricesFile,
+        ...(opts.prices.problems.length ? { problems: [...opts.prices.problems] } : {}),
+    };
+    return {
+        available: true,
+        totals: { kinds: LEDGER_KINDS(totals), turns: totals.turns },
+        days,
+        models: local.map((g) => ({ key: g.key, label: g.label || g.key, kinds: LEDGER_KINDS(g), turns: g.turns })),
+        sliceOf: `the non-Anthropic models in Claude Code's own logs — the same ledger as the Claude Code tab, which leaves them out`,
+        cost,
+        firstAt: days.length ? dayToMs(days[0].day) : null,
+        lastAt: days.length ? dayToMs(days[days.length - 1].day) : null,
+        scannedAt: doc.scannedAt,
+    };
+}
+function tokenTotalOfKinds(k) {
+    return (k.input ?? 0) + (k.output ?? 0) + (k.cacheRead ?? 0) + (k.cacheWrite ?? 0);
+}
+/**
+ * Which claude-jsonl backend a non-Anthropic model's tokens belong to, when
+ * several write into Claude Code's one set of logs (claude-local, claude-endpoint).
+ *
+ * The first backend, in registry order, whose LIVE catalogue lists the model
+ * owns it; else the first whose REMEMBERED catalogue (`known`, what it listed
+ * before — `rememberCatalogues`) does; else the FIRST backend (claude-local: a
+ * model Ollama no longer has still ran somewhere other than Anthropic). The
+ * memory is what stops an endpoint's tokens migrating to the claude-local tab
+ * whenever that endpoint is unreachable and its live list is empty. So every
+ * token lands on exactly one tab — never on two, never summed.
+ */
+export function modelOwner(model, backends) {
+    if (backends.length === 0)
+        return null;
+    return backends.find((b) => b.ids.includes(model))?.id
+        ?? backends.find((b) => b.known?.includes(model))?.id
+        ?? backends[0].id;
+}
+// ── The catalogues, remembered ──────────────────────────────────────────────
+//
+// A catalogue is LIVE (`backendInfos()`), and an endpoint that is down lists
+// nothing. Every id a backend's catalogue has ever listed is kept here, per
+// backend, so ownership survives the outage. Small, bounded (`KNOWN_CAP` per
+// backend, newest first), written only when it changes, tmp+rename.
+const CATALOGUE_FILE = "backend-catalogue.json";
+const KNOWN_CAP = 500;
+let catalogueCache = null;
+function readCatalogueFile(file) {
+    if (catalogueCache?.file === file)
+        return catalogueCache.ids;
+    let ids = {};
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        if (raw?.v === 1 && raw.ids && typeof raw.ids === "object") {
+            for (const [k, v] of Object.entries(raw.ids)) {
+                if (Array.isArray(v))
+                    ids[k] = v.filter((x) => typeof x === "string" && x !== "").slice(0, KNOWN_CAP);
+            }
+        }
+    }
+    catch {
+        ids = {}; /* absent or unreadable ⇒ nothing remembered, never a throw */
+    }
+    catalogueCache = { file, ids };
+    return ids;
+}
+/**
+ * Fold each backend's live catalogue into the remembered one (live ids first,
+ * then the older ones, capped) and hand back the sharers with `known` filled.
+ * A failed write keeps the in-memory memory and degrades to "remembered until
+ * restart" — never a throw on a statistics read.
+ */
+export function rememberCatalogues(stateDir, sharers) {
+    const file = join(stateDir, CATALOGUE_FILE);
+    const mem = readCatalogueFile(file);
+    let changed = false;
+    for (const b of sharers) {
+        if (b.ids.length === 0)
+            continue;
+        const before = mem[b.id] ?? [];
+        const next = [...new Set([...b.ids, ...before])].slice(0, KNOWN_CAP);
+        if (next.length !== before.length || next.some((x, i) => x !== before[i])) {
+            mem[b.id] = next;
+            changed = true;
+        }
+    }
+    if (changed) {
+        try {
+            mkdirSync(stateDir, { recursive: true });
+            writeJsonAtomic(file, { v: 1, ids: mem });
+        }
+        catch { /* kept in memory */ }
+    }
+    return sharers.map((b) => ({ ...b, known: [...(mem[b.id] ?? [])] }));
+}
+/** Test seam: forget the in-memory copy so the next read goes to disk. */
+export function forgetCatalogueCache() { catalogueCache = null; }
+//# sourceMappingURL=localledger.js.map

package/packages/host/dist/localledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localledger.js","sourceRoot":"","sources":["../src/localledger.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/localrt.d.ts

@@ -0,0 +1,164 @@
+import type { LocalRuntimeSample, LoadedModel } from "@waterplane/shared";
+/**
+ * The shapes and the pressure sentence moved to `@waterplane/shared` the moment the
+ * PHONE had to draw them — a fact the host measures and the phone renders is a
+ * fact both ends must word identically. Re-exported here so every existing
+ * import of this module, and `packages/host/test/localrt.test.mjs`, keep
+ * working unchanged.
+ */
+export type { LocalRuntimeSample, LoadedModel };
+export { memoryPressureNote } from "@waterplane/shared";
+/** Where the local runner lives. One place it is read, per this repo's rule for
+ *  every other binary/env pair. */
+export declare const ollamaUrl: () => string;
+/** Off entirely — for a desktop that runs no local models and wants no poll. */
+export declare const localRuntimeEnabled: () => boolean;
+export declare function installSessionModels(fn: () => readonly (string | undefined)[]): void;
+/**
+ * Parse `/api/ps`.
+ *
+ * Exported so the shape is pinned without a runner installed — the same reason
+ * `parseModelList` is exported from the opencode descriptor.
+ *
+ * **Every field degrades independently.** A row with no name is dropped (it
+ * cannot be shown or matched to a session); a row with an unparsable size
+ * contributes 0 bytes rather than `NaN`, which would poison every total drawn
+ * from it; an unparsable `expires_at` is ABSENT rather than a guessed instant.
+ */
+export declare function parsePs(body: unknown): LoadedModel[];
+/**
+ * Take one sample.
+ *
+ * A runner that is not there answers `reachable: false` and NOT an empty model
+ * list — "nothing is loaded" and "nobody asked" are opposite facts, and the bar
+ * words them differently.
+ */
+export declare function sampleLocalRuntime(timeoutMs?: number): Promise<LocalRuntimeSample>;
+/**
+ * Unload one resident model right now, instead of waiting for its own
+ * `keep_alive` to expire.
+ *
+ * Ollama's own way to force this is a generate call with no prompt and
+ * `keep_alive: 0` — there is no dedicated "unload" endpoint. `error` is the
+ * runner's own sentence (an HTTP status, or the fetch failure's message),
+ * never a translated code: there is no richer vocabulary for "why" than what
+ * the runner or the network already said, and inventing one would be a
+ * plausible wrong reason standing in for an honest unknown one.
+ */
+export declare function evictLocalModel(name: string, timeoutMs?: number): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Load one model now and ask the runner to hold it for `keepAlive` — the
+ * mirror of `evictLocalModel`: a generate call with no prompt loads the model
+ * and returns, and its `keep_alive` sets how long it stays resident.
+ *
+ * Used when a `claude-local` session starts (`backends/claude-local.ts`), so the
+ * cold load (measured: most of a 67-81 s first turn) overlaps the person typing
+ * instead of following it. Fire-and-forget at the call site: the launch never
+ * waits on it, and a failure is only the runner's own sentence.
+ * `keepAlive` is passed through as Ollama spells it ("30m", "-1", seconds).
+ */
+export declare function warmLocalModel(name: string, keepAlive: string, timeoutMs?: number): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Why a load did not finish — `loadLocalModel`'s failure vocabulary. */
+export type LocalLoadFailure = "unreachable" | "missing" | "timeout" | "error";
+/**
+ * Load one model and WAIT for it — `warmLocalModel` with the failure told
+ * apart, for the local-model gate (`localslot.ts`) that holds an automatic
+ * item until the model it opens on is resident. A 404 is Ollama saying it has
+ * no such model (never "unreachable"); an abort past `timeoutMs` is `timeout`;
+ * a refused connection is `unreachable`. `error` is the runner's own sentence.
+ */
+export declare function loadLocalModel(name: string, keepAlive: string, timeoutMs: number): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    kind: LocalLoadFailure;
+    error: string;
+}>;
+/**
+ * How long one `localrt.watch` buys.
+ *
+ * **Why a lease and not a subscription.** The route table has no socket-close
+ * hook: a handler is handed its `ws` and nothing tells this module when that
+ * socket dies. A set the host prunes on close is therefore a leak the first day
+ * a close event is missed — a phone that went through a tunnel drop keeps a
+ * desktop polling its runner for ever, and nothing on either end can see it.
+ * A lease cannot do that: it expires by itself. A client that stops renewing
+ * lapses within a minute, costing at most one lease period of loopback GETs,
+ * which is the cheap direction to be wrong in.
+ *
+ * Sixty seconds against the client's 25 s renewal is deliberately two renewals
+ * of slack: a phone that misses one pump tick (a backgrounded WebView, a
+ * reconnect) must not lose the readout it is looking at.
+ */
+export declare const LEASE_MS = 60000;
+export declare function localRtPollMs(): number;
+/** A socket, as much of one as this module has any business knowing about.
+ *  Structural so the manager can be driven with no `ws` and no daemon. */
+export interface WatchSocket {
+    /** `1` is OPEN in every WebSocket implementation and in the standard. */
+    readonly readyState: number;
+}
+/** What a lease is, reduced to the two facts that decide its fate. */
+export interface WatchLease {
+    /** ms epoch the lease runs out at. */
+    until: number;
+    /** Is the socket that took it still open? */
+    open: boolean;
+}
+/** The split `pollTick` acts on: who gets this sample, and who is dropped. */
+export interface WatchSplit<K> {
+    live: K[];
+    lapsed: K[];
+}
+/**
+ * **The lease bookkeeping, pure.**
+ *
+ * Extracted so the rules below can be pinned with no daemon, no socket and no
+ * clock, because all three of them fail silently:
+ *
+ *  - a renewal that does not actually extend the lease drops the readout every
+ *    minute, which on a phone looks like a flaky desktop;
+ *  - a lapsed or closed entry that is not dropped is the leak the lease exists
+ *    to prevent;
+ *  - **an empty result is the STOP condition.** The timer must go away with its
+ *    last watcher — a daemon that keeps polling a local HTTP endpoint for ever
+ *    because somebody once opened a strip is exactly the cost this readout is
+ *    supposed to be measuring, not paying.
+ *
+ * A closed socket lapses even with time left on its lease: the clock is the
+ * backstop for a close nobody saw, not a reason to keep writing into a dead one.
+ */
+export declare function dueWatchers<K>(entries: Iterable<readonly [K, WatchLease]>, now: number): WatchSplit<K>;
+/** What the manager is allowed to say. Structural for `WatchSocket`'s reason —
+ *  the route hands over a closure, not a transport. */
+type WatchSend = (msg: {
+    t: "localrt.sample";
+    sample: LocalRuntimeSample;
+    disabled?: true;
+}) => void;
+/** How many leases are outstanding. Exported for the test, and for nothing
+ *  else: no route reads it, and no decision is taken on it. */
+export declare function localRtWatchCount(): number;
+/**
+ * A client asked to watch the local runner.
+ *
+ * **Answers immediately, always.** That is not a latency nicety: a host that
+ * predates this feature ignores an unknown `t` silently (the wire is
+ * versioned, and that is the correct behaviour), so from the phone's side
+ * "this desktop is old" and "this desktop is answering and the runner is quiet"
+ * are the same silence. One frame back on the spot is what separates them, and
+ * the phone says the two things differently — see `web/localRt.ts`.
+ *
+ * With polling switched off (`WATERPLANE_LOCAL_RUNTIME=0`) this takes NO lease and
+ * starts NO timer: it sends one `disabled: true` frame and stops. "Polling is
+ * off on this desktop" is a standing fact about the machine, not a reading that
+ * needs refreshing, and a lease would buy a poll loop that can only ever report
+ * the same nothing.
+ */
+export declare function localRtWatch(ws: WatchSocket, send: WatchSend): void;