waterplane 0.0.1 → 0.1.6

package/packages/host/dist/turnagents.js

@@ -0,0 +1,205 @@
+/**
+ * **What each reader turn's subagents spent, on the turn that started them.**
+ *
+ * The header's session total has always counted the subagents (`ctxlog.ts`'s
+ * `agentUsage`); the reader's per-turn footer never did, so one prompt that fanned
+ * out five agents read "$1.12 this prompt" under a header saying $9.22, and
+ * nothing on screen said which one was wrong. Neither was — they were two
+ * different sums with the same name.
+ *
+ * The CLI writes each agent's log beside the parent
+ * (`<conversation>/subagents/agent-<id>.jsonl`) with a `.meta.json` naming the
+ * `toolUseId` of the call that started it, and — for an agent an agent started —
+ * the `parentAgentId`. So attribution is a lookup, never a guess by time: the
+ * call's id is on exactly one turn's tool block, and a nested agent goes where
+ * its root went.
+ *
+ * The spend is `agentUsage`'s per-file ledger, READ, never re-tallied: the same
+ * records, dedupe and per-record pricing as the header, so the last turn's
+ * running total and the header's total are one number.
+ *
+ * **An agent can still be running when the footer is drawn** — a background
+ * agent's tool call returns at once and its turn "ends" long before it does. So
+ * a turn also says how many of its agents are still running, and the figure is
+ * then a floor that says so. Running = not retired: the parent wrote a
+ * task-notification or hand-back for it after its last write (`agents.ts`'s
+ * rule), or — a foreground call — its tool result came back. Past
+ * `AGENT_LIVE_MS` of silence with neither, it is called ended: a killed CLI
+ * writes no ending, and "still running" for ever is the worse lie.
+ *
+ * Degrades to ABSENT: a directory that could not be read publishes no agent
+ * figure (and the footer keeps saying subagents are not included); one agent
+ * that cannot be placed withholds every running total, because a total missing
+ * it would read as complete.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_LIVE_MS, normalizeModel } from "@waterplane/shared";
+import { agentUsage } from "./ctxlog.js";
+import { readMeta } from "./agents.js";
+/** Per-directory ledgers, kept so a poll re-reads only the agent logs that
+ *  grew — `agentUsage` is incremental given its previous result. */
+const cache = new Map();
+const CACHE_MAX = 32;
+/** `<conversation>.jsonl` → `<conversation>/subagents`. */
+export function subagentsDirOf(logPath) {
+    return join(logPath.replace(/\.jsonl$/, ""), "subagents");
+}
+/** Newest write under the agent directory, 0 when there is none — what the
+ *  reader's "unchanged" poll must also compare, since an agent writes while
+ *  the parent log sleeps. */
+export function agentsMtime(logPath) {
+    const dir = subagentsDirOf(logPath);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    let max = 0;
+    for (const n of names) {
+        if (!n.startsWith("agent-") || !n.endsWith(".jsonl"))
+            continue;
+        try {
+            max = Math.max(max, statSync(join(dir, n)).mtimeMs);
+        }
+        catch { /* vanished */ }
+    }
+    return max;
+}
+const TASK_ID_RE = /<task-id>([A-Za-z0-9_-]+)<\/task-id>/g;
+const HAND_BACK_RE = /<agent-message from=\\?"([A-Za-z0-9_-]+)\\?"/g;
+/** The ids a raw parent-log line retires (a task-notification or a hand-back),
+ *  folded into `into` as "latest mention wins". */
+export function noteRetired(line, at, into) {
+    if (!line.includes("<task-id>") && !line.includes("<agent-message from="))
+        return;
+    for (const re of [TASK_ID_RE, HAND_BACK_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(line))) {
+            const prev = into.get(m[1]);
+            if (prev === undefined || at > prev)
+                into.set(m[1], at);
+        }
+    }
+}
+/**
+ * Put each agent's spend on the turn that started it, in place.
+ *
+ * `partial`: the parent log was tail-read, so earlier turns — and the calls of
+ * agents started there — are missing; no running total is published.
+ */
+export function attachAgentSpend(turns, logPath, retired, partial, now = Date.now()) {
+    const dir = subagentsDirOf(logPath);
+    const use = agentUsage(dir, cache.get(dir) ?? null);
+    if (!use)
+        return; // unreadable — absent, and the footer keeps its caveat
+    cache.delete(dir);
+    cache.set(dir, use);
+    if (cache.size > CACHE_MAX)
+        cache.delete(cache.keys().next().value);
+    // Which turn holds which call, and whether its result has come back.
+    const turnOfCall = new Map();
+    const answered = new Set();
+    for (const t of turns) {
+        for (const b of t.blocks) {
+            if (b.kind !== "tool")
+                continue;
+            if (b.name === "Task" || b.name === "Agent")
+                turnOfCall.set(b.id, t);
+            if (b.ok !== undefined)
+                answered.add(b.id);
+        }
+    }
+    const metas = new Map();
+    for (const name of use.files.keys()) {
+        const id = name.slice("agent-".length, -".jsonl".length);
+        metas.set(id, readMeta(join(dir, `agent-${id}.meta.json`)));
+    }
+    /** The top-level agent an agent descends from; itself when it is one. Null
+     *  on a broken or cyclic chain. */
+    const rootOf = (id) => {
+        let cur = id;
+        for (let i = 0; i < 8; i++) {
+            const p = metas.get(cur)?.parentAgentId;
+            if (!p)
+                return cur;
+            cur = p;
+        }
+        return null;
+    };
+    const runningTop = (id, lastWrite) => {
+        if (now - lastWrite > AGENT_LIVE_MS)
+            return false;
+        const stop = retired.get(id);
+        if (stop !== undefined && stop >= lastWrite)
+            return false;
+        const m = metas.get(id);
+        if (m?.requestShape !== "background" && m?.toolUseId && answered.has(m.toolUseId))
+            return false;
+        return true;
+    };
+    let unplaced = false;
+    const agentTurn = new Map(); // turn → index, for the running total
+    turns.forEach((t, i) => agentTurn.set(t, i));
+    const perTurn = new Array(turns.length).fill(0);
+    const seenCalls = new Set();
+    for (const [name, f] of use.files) {
+        const id = name.slice("agent-".length, -".jsonl".length);
+        const root = rootOf(id);
+        const call = root ? metas.get(root)?.toolUseId : undefined;
+        const t = call ? turnOfCall.get(call) : undefined;
+        if (!t || !root) {
+            if (f.tok > 0)
+                unplaced = true;
+            continue;
+        }
+        if (call)
+            seenCalls.add(call);
+        const rootFile = use.files.get(`agent-${root}.jsonl`);
+        const live = root === id
+            ? runningTop(id, f.mtime)
+            : now - f.mtime <= AGENT_LIVE_MS && !!rootFile && runningTop(root, Math.max(rootFile.mtime, f.mtime));
+        if (live)
+            t.agentsRunning = (t.agentsRunning ?? 0) + 1;
+        if (f.cost.total > 0) {
+            t.agentCostUsd = (t.agentCostUsd ?? 0) + f.cost.total;
+            perTurn[agentTurn.get(t)] += f.cost.total;
+        }
+        if (f.unpriced > 0)
+            t.agentUnpricedTok = (t.agentUnpricedTok ?? 0) + f.unpriced;
+        if (f.tok > 0) {
+            const mid = f.model ? normalizeModel(f.model) ?? f.model : "(unknown)";
+            let m = (t.agentModels ??= []).find((x) => x.id === mid);
+            if (!m) {
+                m = { id: mid, tok: 0 };
+                t.agentModels.push(m);
+            }
+            m.tok += f.tok;
+            if (f.cost.total > 0)
+                m.costUsd = (m.costUsd ?? 0) + f.cost.total;
+        }
+    }
+    // A call made moments ago whose log the CLI has not created yet is running
+    // with nothing spent — counted, so the footer does not claim the turn is done.
+    for (const [call, t] of turnOfCall) {
+        if (seenCalls.has(call) || answered.has(call))
+            continue;
+        // …but an old call with no log and no result (an interrupted turn, an
+        // agent directory cleaned up) is history, not a running agent.
+        if (now - (t.endedAt ?? t.sentAt ?? 0) > AGENT_LIVE_MS)
+            continue;
+        t.agentsRunning = (t.agentsRunning ?? 0) + 1;
+    }
+    if (partial || unplaced)
+        return;
+    let cum = 0;
+    turns.forEach((t, i) => {
+        cum += perTurn[i];
+        if (t.cumCostUsd != null)
+            t.cumAgentCostUsd = cum;
+    });
+}
+//# sourceMappingURL=turnagents.js.map

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

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

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

@@ -0,0 +1,18 @@
+import type { UiUsageDoc } from "@waterplane/shared";
+export declare class UiStats {
+    private path;
+    private doc;
+    private timer;
+    constructor(root: string);
+    /** Merge a client delta ({ featureId: increment }). Returns the ids accepted. */
+    merge(counts: Record<string, unknown>, at?: number): number;
+    /** The whole document (what the phone renders and an agent reads). */
+    get(): UiUsageDoc;
+    /** Wipe all counters (start a fresh observation window). */
+    reset(): void;
+    /** Write any debounced changes now (host shutdown). */
+    flush(): void;
+    private prune;
+    private schedulePersist;
+    private persist;
+}

package/packages/host/dist/uistats.js

@@ -0,0 +1,105 @@
+/**
+ * UI feature-usage counters — "which parts of this app do I actually use?".
+ *
+ * The phone tracks every feature invocation locally (instant, so the toolbar can
+ * sort itself by frequency without a round-trip) and flushes deltas here; this
+ * module merges them into one plain JSON file at <STATE_DIR>/ui-usage.json:
+ *
+ *   { "updatedAt": …, "since": …, "features": { "toolbar:diff": { count, first, last } } }
+ *
+ * The file is the point: a coding agent can read it and see which features are
+ * hot, which are cold, and which have never fired at all — the input for
+ * "delete what I never use". Nothing leaves the host; there is no network sink.
+ *
+ * Ids are opaque namespaced strings the client picks ("toolbar:<id>",
+ * "overlay:<name>", "action:<name>"). Unknown ids are kept, not rejected, so
+ * adding a `track()` call needs no host change — but they're sanity-capped so a
+ * buggy/hostile client can't grow the file without bound.
+ */
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+import { join } from "node:path";
+import { hostStateDir } from "./branddirs.js";
+const MAX_FEATURES = 1000; // distinct ids retained (least-used dropped past this)
+const MAX_ID_LEN = 80;
+const MAX_DELTA = 10_000; // per-id increment accepted in one flush
+const SAVE_DEBOUNCE_MS = 3000; // batch bursty flushes into one write
+const ID_OK = /^[a-zA-Z0-9:._/-]+$/;
+export class UiStats {
+    path;
+    doc;
+    timer = null;
+    constructor(root) {
+        this.path = join(hostStateDir(root), "ui-usage.json");
+        this.doc = { updatedAt: 0, since: Date.now(), features: {} };
+        const d = readJsonGuarded(this.path, null);
+        if (d && typeof d === "object" && d.features)
+            this.doc = { since: d.since || Date.now(), updatedAt: d.updatedAt || 0, features: d.features };
+    }
+    /** Merge a client delta ({ featureId: increment }). Returns the ids accepted. */
+    merge(counts, at = Date.now()) {
+        if (!counts || typeof counts !== "object")
+            return 0;
+        let n = 0;
+        for (const [rawId, rawN] of Object.entries(counts)) {
+            const id = String(rawId).slice(0, MAX_ID_LEN);
+            if (!ID_OK.test(id))
+                continue;
+            const inc = Math.min(Math.max(Math.floor(Number(rawN) || 0), 0), MAX_DELTA);
+            if (!inc)
+                continue;
+            const e = this.doc.features[id];
+            if (e) {
+                e.count += inc;
+                e.last = at;
+            }
+            else
+                this.doc.features[id] = { count: inc, first: at, last: at };
+            n++;
+        }
+        if (!n)
+            return 0;
+        this.doc.updatedAt = at;
+        this.prune();
+        this.schedulePersist();
+        return n;
+    }
+    /** The whole document (what the phone renders and an agent reads). */
+    get() {
+        return { ...this.doc, features: { ...this.doc.features } };
+    }
+    /** Wipe all counters (start a fresh observation window). */
+    reset() {
+        this.doc = { updatedAt: Date.now(), since: Date.now(), features: {} };
+        this.persist();
+    }
+    /** Write any debounced changes now (host shutdown). */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+            this.persist();
+        }
+    }
+    prune() {
+        const ids = Object.keys(this.doc.features);
+        if (ids.length <= MAX_FEATURES)
+            return;
+        // Drop the least-used, oldest-touched ids first.
+        ids.sort((a, b) => this.doc.features[b].count - this.doc.features[a].count || this.doc.features[b].last - this.doc.features[a].last);
+        for (const id of ids.slice(MAX_FEATURES))
+            delete this.doc.features[id];
+    }
+    schedulePersist() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => { this.timer = null; this.persist(); }, SAVE_DEBOUNCE_MS);
+        this.timer.unref?.();
+    }
+    persist() {
+        try {
+            writeJsonAtomic(this.path, this.doc, { space: 2 });
+        }
+        catch { /* telemetry must never break the host */ }
+    }
+}
+//# sourceMappingURL=uistats.js.map

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

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

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

@@ -0,0 +1,100 @@
+import type { InstallRoute, UpdateInfo } from "@waterplane/shared";
+import { cmpCliVersion } from "@waterplane/shared";
+/** Detect the CLI's "Update available!" banner. Pass ANSI-stripped text. */
+export declare function detectUpdateBanner(text: string): {
+    available: boolean;
+    latest?: string;
+};
+/**
+ * Which package manager owns the binary at this REALPATH-resolved path.
+ *
+ * Pure, and deliberately path-shaped rather than "ask each manager whether it
+ * has claude-code": both can answer yes at once (a leftover cask beside an npm
+ * global), and only one of them is on the PATH the host actually spawns.
+ */
+export declare function routeFromPath(p: string | undefined): InstallRoute;
+/** `a` vs `b` as dotted numbers — the one comparison lives in shared, beside
+ *  the per-session restart rule that must agree with it. */
+export declare const cmpVersion: typeof cmpCliVersion;
+/**
+ * The npm dist-tag a native install follows: claude's own `autoUpdatesChannel`
+ * setting ("latest" by default, or "stable"). Both are npm dist-tags, and asking
+ * `latest` for a stable-channel install would show an update `claude update`
+ * never takes — a nag nothing can clear. An unreadable or unknown value is "latest".
+ */
+export declare function nativeChannel(settingsJson: string | undefined): "latest" | "stable";
+export interface ApplyStep {
+    cmd: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface ApplyPlan {
+    label: string;
+    steps: ApplyStep[];
+}
+/**
+ * The upgrade this route would run. `label` is what the phone prints on the
+ * button, so the UI never re-derives which manager owns the binary — kept to
+ * a button's worth of words, because the exact command line is echoed into the
+ * log above it (`==> npm install -g …`) the moment it runs.
+ *
+ * `unknown` returns null: no command is better than someone else's command.
+ */
+export declare function applyPlan(route: InstallRoute, bin: string): ApplyPlan | null;
+export declare class UpdateChecker {
+    private onChange;
+    private info;
+    private timer;
+    /** While a CLI banner is live, re-read the installed version on a short cadence
+     *  so the button disappears promptly after an upgrade (by ANY route), instead
+     *  of waiting for the hourly poll. */
+    private reconcileTimer;
+    private applying;
+    /** True when the route's own index reports the install is behind. */
+    private indexOutdated;
+    /** Set when the CLI banner is seen; cleared once the install version moves. */
+    private banner;
+    private route;
+    private binTimer;
+    /** mtime+inode of `info.binPath` when last looked at; a change re-reads the version. */
+    private binKey;
+    constructor(onChange: (info: UpdateInfo) => void);
+    get(): UpdateInfo;
+    start(): void;
+    /**
+     * Re-read the installed version when the binary on disk changes. npm and the
+     * native installer replace the file (new inode, new mtime) at the same
+     * realpath; a route swap moves the realpath, which `check` re-resolves.
+     */
+    private watchBinary;
+    stop(): void;
+    /**
+     * Record the CLI's on-screen update nag (scraped from a session's PTY output).
+     * Surfaces the button immediately even when the route's index still lags the
+     * registry the CLI checks.
+     */
+    noteBanner(latest?: string): void;
+    /** Poll the installed version while a banner is live, so it clears promptly. */
+    private armReconcile;
+    private reconcileBanner;
+    private clearBanner;
+    /**
+     * Resolve the binary the host actually spawns, and read the install route off
+     * it. `which` for a bare name, the path itself when one was configured, then
+     * realpath — the route lives at the far end of the symlink, never at the near
+     * end (`/opt/homebrew/bin/claude` is the SAME path under both brew and npm).
+     */
+    private detectRoute;
+    check(refresh?: boolean): Promise<void>;
+    /** Fold the index + banner signals into `info.available` and broadcast. */
+    private recompute;
+    apply(): Promise<void>;
+    /**
+     * The version actually running — `claude --version`. Authoritative regardless
+     * of install route (brew cask, npm global, native installer), so the banner
+     * clears after an upgrade even when one manager's listing is blind to it.
+     * Falls back to the brew cask version only when the binary can't be queried
+     * at all, which is the one case where a stale number beats no number.
+     */
+    private installedVersion;
+}