waterplane 0.0.1 → 0.1.6

package/packages/host/dist/convfork.js

@@ -0,0 +1,372 @@
+/**
+ * Forking a conversation: a second log file holding the first N turns of an
+ * existing one, so a session can be reopened at the point BEFORE it went wrong.
+ *
+ * A session misreads the request and spends an hour down a wrong path. Today the
+ * only moves are to let it finish, interject, or kill it and lose the good half
+ * with it — all three expensive on a phone. What is missing is a way to say
+ * "start again from turn 7", and the CLI does not offer one non-interactively:
+ * `--fork-session` forks from the END, and `/rewind` is a TUI picker.
+ *
+ * So we write the file ourselves. That is only defensible because of two facts
+ * about the format, both checked against real logs on this machine rather than
+ * assumed:
+ *
+ * 1. **The message CHAIN points backward, but the bookkeeping does not.** Over
+ *    132,320 `parentUuid` values in three projects' logs, not one names a record
+ *    that appears later in its file; the same holds for `leafUuid`,
+ *    `snapshotMessageId`, `logicalParentUuid` and the compact metadata's
+ *    `headUuid`/`tailUuid`. So the conversation itself is a prefix-safe
+ *    structure and there is no `parentUuid` to re-point and no `last-prompt` to
+ *    patch.
+ *
+ *    What is NOT true — and the design note that preceded this file said it was,
+ *    on the strength of one 399-record sample — is that *nothing* points
+ *    forward. Two record kinds are written slightly AHEAD of the message they
+ *    name, because the CLI writes them when a turn begins rather than when it
+ *    lands: `file-history-snapshot.messageId`, and the `system` record that
+ *    opens a compact, whose `compactMetadata.preservedSegment.anchorUuid` names
+ *    the compact SUMMARY record that follows it. Simulating this function's cut
+ *    at all 7,076 turn boundaries in four projects' logs, 4.8% of them left at
+ *    least one such reference naming a record the cut had removed.
+ *    `pruneStranded()` is the answer, and the note there explains why it is not
+ *    cosmetic.
+ *
+ *    With that pruning, the prefix we keep is exactly the state the file was in
+ *    when that line was its tail — a state the CLI itself wrote and has resumed
+ *    before.
+ *
+ * 2. **The CLI's own `--fork-session` output is the template.** Three logs in
+ *    `~/.claude/projects/-Users-me-dev-Tiptoi/` are one parent and two
+ *    independent forks of it. Diffing the 1,241 records all three share, keyed
+ *    by `uuid`:
+ *
+ *      - `sessionId` is rewritten on every copied record — 1,241 of 1,241.
+ *      - `session_id` (the other spelling, which really does occur alongside it
+ *        on `user`/`assistant`/`attachment`/`system` records) is NOT rewritten:
+ *        all 1,226 copied records that carry it still name the PARENT in both
+ *        forks. See the note on `rewriteInto()` — this is the one place where
+ *        this module deliberately does less than a naive reading of "rewrite
+ *        the session id" would do.
+ *      - `uuid`, `parentUuid` and `timestamp` are untouched. That is what makes
+ *        the backward-pointing property survive the copy at all: rewriting a
+ *        uuid would orphan every reference to it.
+ *      - The two sibling forks differ from EACH OTHER in exactly two keys:
+ *        `sessionId` (by construction) and `promptId` (regenerated per fork on
+ *        357 user records). We leave `promptId` alone — see below.
+ *
+ * The failure mode is contained by construction, which is the other half of why
+ * this is allowed to be tried at all: **the source is opened read-only and is
+ * never modified**, a fresh uuid is minted for the output, and so a malformed
+ * result is a NEW file under a new id that nothing yet points at. The original
+ * conversation is never the file we wrote. Two forks from one turn are simply
+ * two files. `deleteArchived` stays the only way to lose a conversation.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { claudeProjectDir, promptOf, transcriptPath } from "./transcript.js";
+/**
+ * The same bare-id regex `deleteArchived` uses, for the same reason: an id
+ * reaches `transcriptPath`, which is a `join` and would take `../../…`
+ * perfectly happily. A traversal-shaped id is REFUSED rather than sanitised —
+ * stripping the dots would silently fork some other directory's conversation,
+ * and a refusal is a bug report where a sanitisation is a mystery.
+ */
+const BARE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/**
+ * Refuse to fork a source larger than this. `parseTranscript` gets to tail-read
+ * a huge log because it only shows the newest turns; a fork needs the HEAD, so
+ * it has to hold the whole file. 256 MB is far past any real conversation (the
+ * largest here is single-digit MB) and exists so that a corrupted or
+ * runaway file becomes an error message instead of an out-of-memory kill of the
+ * daemon that is driving every other session on this machine.
+ */
+const MAX_SOURCE_BYTES = 256 * 1024 * 1024;
+/**
+ * Rewrite one parsed record for the new conversation, and serialise it.
+ *
+ * Only `sessionId` moves. The evidence for leaving `session_id` alone is in the
+ * header; the ARGUMENT for it, which is what makes it more than cargo-culting
+ * the CLI's output, is that the two fields answer different questions. On a
+ * natively forked log, `sessionId` is uniform across the whole file and
+ * `session_id` is not: copied records keep the parent's, records the fork itself
+ * produced carry the fork's. So `sessionId` is "which conversation file is this
+ * record part of" — a property of the file, which must be rewritten or the
+ * records do not belong to it — while `session_id` is "which session actually
+ * produced this record", which is provenance, and for the records we copy the
+ * honest answer is still the source session. Rewriting it would make the fork
+ * claim it produced turns it did not.
+ *
+ * `promptId` is left alone too, where the CLI mints a fresh one. Nothing in the
+ * format points at a `promptId` — every backward reference names a `uuid` — so
+ * regenerating it buys no consistency, and it would put nondeterminism in the
+ * output of a function whose whole safety story is that you can diff its result
+ * against the source and see that only one field moved.
+ *
+ * `JSON.stringify` on a `JSON.parse` result is byte-identical to the input for
+ * everything the CLI writes: key insertion order is preserved, the CLI's own
+ * lines are compact (no spaces), and `JSON.parse` can produce no value —
+ * `undefined`, `NaN`, a function — that would serialise differently. Verified
+ * over a real 197-record log, all 197 round-tripping exactly.
+ */
+/**
+ * Keys whose value is the `uuid` of another RECORD in the same log.
+ *
+ * The list is short and closed on purpose, because the format is full of ids
+ * from other namespaces that look identical and resolve to nothing: `id`,
+ * `tool_use_id` and `toolUseID` are API message and tool-call ids, and across
+ * 100,808 of them in three projects' logs not one named a record uuid. Treating
+ * those as references would make `pruneStranded()` delete most of the
+ * conversation. The eight below resolve essentially always — 146,849 hits, 8
+ * misses, all of them `messageId` on a snapshot whose message is not in the file
+ * at all — which is what makes "not in the prefix" a sound reading of "the cut
+ * removed it" without a second parse of everything past the cut.
+ */
+const REF_KEYS = new Set([
+    "parentUuid", "logicalParentUuid", "leafUuid", "snapshotMessageId",
+    "messageId", "headUuid", "tailUuid", "anchorUuid",
+]);
+/**
+ * Subtrees never walked when collecting references. `message` and
+ * `toolUseResult` hold the API payload — every `id`/`tool_use_id` above lives
+ * there, none of the eight keys does, and between them they are ~all the bytes
+ * of a log. Skipping them is a correctness rule first and a cost rule second.
+ */
+const REF_SKIP = new Set(["message", "toolUseResult"]);
+/** Every record-uuid this record names, at any depth outside the skipped subtrees. */
+function referencedUuids(o, out = [], depth = 0) {
+    if (depth > 8 || o == null || typeof o !== "object")
+        return out;
+    if (Array.isArray(o)) {
+        for (const v of o)
+            referencedUuids(v, out, depth + 1);
+        return out;
+    }
+    for (const [k, v] of Object.entries(o)) {
+        if (REF_SKIP.has(k))
+            continue;
+        if (REF_KEYS.has(k) && typeof v === "string")
+            out.push(v);
+        referencedUuids(v, out, depth + 1);
+    }
+    return out;
+}
+/**
+ * Drop the records in the prefix that are ABOUT a turn the cut removed.
+ *
+ * This exists because of one measured case, and it is worth stating in full
+ * because the obvious reading — "a dangling id in a bookkeeping record, who
+ * cares" — is wrong in exactly the situation the feature is for.
+ *
+ * A `/compact` writes a `system` record carrying `compactMetadata`, and then a
+ * `user` record carrying the SUMMARY of everything it dropped. `promptOf`
+ * accepts that summary as a real prompt — correctly; it is what the reader shows
+ * as a turn — so a fork at the last turn BEFORE a compact cuts between the two.
+ * The prefix then keeps the instruction to discard the pre-compact history and
+ * loses the summary that was standing in for it. Observed, not reasoned: a
+ * two-turn conversation forked that way could name only its second turn, where
+ * the same fork with this `system` record pruned named both. So the pruning is
+ * the difference between "fork from turn N" meaning what it says and a fork that
+ * silently arrives with less history than either the original or the turn number
+ * promises.
+ *
+ * The other 99% of the class is `file-history-snapshot`, whose `messageId` names
+ * the first message of the turn we cut away. Those are harmless — a resume with
+ * one dangling was verified to work — but they are the same fact (a record about
+ * a turn that is no longer here), so they go the same way rather than by a
+ * second rule.
+ *
+ * Bounded and conservative: only a record naming a uuid that is absent from the
+ * prefix is dropped, so a chain record can never be — `parentUuid` always points
+ * backward, and everything backward is in the prefix by construction. Over 7,076
+ * simulated cuts this removed only `file-history-snapshot` (838) and compact
+ * `system` (8) records, never a `user`, `assistant` or `attachment`, left zero
+ * stranded references behind, never lost the turn the cut was aimed at, and
+ * reached a fixed point in a single pass every time. The loop is capped anyway: a rule
+ * that can delete records must not be able to delete all of them because of a
+ * format change nobody has seen yet.
+ */
+function pruneStranded(recs) {
+    let kept = recs;
+    let pruned = 0;
+    for (let pass = 0; pass < 4; pass++) {
+        const have = new Set(kept.map((r) => r?.uuid).filter((u) => typeof u === "string"));
+        const next = kept.filter((r) => !referencedUuids(r).some((u) => !have.has(u)));
+        if (next.length === kept.length)
+            break;
+        pruned += kept.length - next.length;
+        kept = next;
+    }
+    return { kept, pruned };
+}
+function rewriteInto(rec, newId) {
+    if (rec && typeof rec === "object" && typeof rec.sessionId === "string") {
+        rec.sessionId = newId;
+    }
+    return JSON.stringify(rec);
+}
+/**
+ * Write a new conversation log holding `sourceId`'s history up to and including
+ * the turn whose prompt record has uuid `atTurnUuid`, and return its new id.
+ *
+ * **The cut point is a TURN boundary, not a record.** We find the record with
+ * that uuid — which for a turn is the prompt record, since `parseTranscript`
+ * names a turn after exactly that — and then keep going until the next record
+ * `promptOf()` accepts as a real user prompt (or EOF), cutting immediately
+ * BEFORE it. That is what makes the fork resumable rather than merely
+ * well-formed: everything the turn produced after its prompt — the assistant's
+ * response, its tool calls, the `tool_result` records that answer them, the
+ * attachments, the `file-history-*` bookkeeping — rides along, so the kept
+ * prefix ends on a completed exchange instead of a dangling `tool_use` the
+ * model would be asked to resume in the middle of.
+ *
+ * `promptOf` is IMPORTED, never re-implemented. It is the rule that already
+ * decides what counts as a real prompt rather than a hook echo, a slash-command
+ * envelope, a tool result or a resume caveat, and `archive.ts`'s header explains
+ * at length what a second copy of it costs: the visible symptom of the drift is
+ * an archive row titled `<command-name>`, and the symptom here would be a fork
+ * cut in the middle of a turn because a `<system-reminder>` read as a prompt.
+ *
+ * A line that will not parse is DROPPED rather than aborting the fork. The one
+ * way that happens in practice is a half-written tail: a live session is
+ * appending to this file while we read it, and we caught it mid-line. Dropping
+ * is safe for exactly the reason the whole feature is safe — every reference
+ * points backward, so a record nobody has written yet is a record nobody can
+ * reference — and it is the right call over aborting because the alternative is
+ * a feature that fails whenever the session you want to fork is busy, which is
+ * precisely when you want to fork it.
+ */
+export function forkConversationFile(cwd, sourceId, atTurnUuid) {
+    if (!BARE_ID.test(sourceId))
+        return { error: "bad id" };
+    // The turn uuid never reaches the filesystem — it is compared against record
+    // uuids — but a shape check turns "some id from a stale cached transcript"
+    // into an immediate refusal instead of a full read of a multi-MB log that was
+    // never going to match.
+    if (!BARE_ID.test(atTurnUuid))
+        return { error: "bad turn" };
+    const path = transcriptPath(cwd, sourceId);
+    let st;
+    try {
+        st = statSync(path);
+    }
+    catch {
+        return { error: "no such conversation" };
+    }
+    if (!st.isFile())
+        return { error: "not a conversation" };
+    if (st.size > MAX_SOURCE_BYTES)
+        return { error: "conversation too large to fork" };
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return { error: "read failed" };
+    }
+    const newId = randomUUID();
+    const prefix = [];
+    let found = false;
+    let dropped = 0;
+    for (const raw of text.split("\n")) {
+        const ln = raw.trim();
+        if (!ln)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(ln);
+        }
+        catch {
+            dropped += 1;
+            continue;
+        } // half-written tail of a live turn
+        // The break is checked BEFORE the push and only once the target has been
+        // seen, so a prompt record earlier in the file cannot end the copy and the
+        // target's own prompt record cannot end it either.
+        if (found && promptOf(rec) != null)
+            break;
+        prefix.push(rec);
+        if (!found && rec?.uuid === atTurnUuid)
+            found = true;
+    }
+    // A uuid that is not in this file is an error, never an empty (or whole-file)
+    // fork. Silently forking everything would be the worst possible answer to
+    // "fork at turn 7": it looks like it worked.
+    if (!found)
+        return { error: "turn not found" };
+    const { kept: keptRecs, pruned } = pruneStranded(prefix);
+    const kept = keptRecs.map((r) => rewriteInto(r, newId));
+    const dir = claudeProjectDir(cwd);
+    const out = join(dir, newId + ".jsonl");
+    // Astronomically unlikely, and checked anyway because the one invariant this
+    // module sells is that it never writes over a conversation that already exists.
+    if (existsSync(out))
+        return { error: "id collision" };
+    // tmp+rename, the house discipline: the CLI or `archive.ts` may `readdir` this
+    // directory at any moment, and a partially written `<id>.jsonl` is an archive
+    // row that resumes into a truncated conversation. The tmp name deliberately
+    // does not end in `.jsonl`, so it is invisible to that listing even in the
+    // window before the rename.
+    const tmp = join(dir, `.${newId}.jsonl.tmp`);
+    try {
+        writeFileSync(tmp, kept.join("\n") + "\n", "utf8");
+        renameSync(tmp, out);
+    }
+    catch {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* never existed, or already gone */ }
+        return { error: "write failed" };
+    }
+    return { newId, records: kept.length, dropped, pruned };
+}
+// ── A backend that cuts its OWN conversation (plugin contract 2.2 consumer) ────────────────────
+/**
+ * How long a backend's `conversations.fork` may take. Past it the create is refused in words and
+ * nothing is launched; a fork that lands later is an extra row in that backend's conversation list
+ * — the same bounded orphan a crash between `forkConversationFile` and the ack leaves.
+ */
+export const FORK_SOURCE_WAIT_MS = 20_000;
+/**
+ * Fork through the backend's own source (`sources.conversations.fork(id, atTurn)`): the cut is the
+ * BACKEND's, made in its own store, and this host only asks and checks the answer. `atTurn` is the
+ * turn id the phone took from that backend's transcript, handed over untouched — the same "keep
+ * everything up to and including this turn" `forkConversationFile` keeps. Every failure is a
+ * sentence naming the backend: a throw, null, a late answer, an id that is not a bare id, or the
+ * SAME id back (that is the conversation, not a fork of it). `records`/`dropped`/`pruned` are a file
+ * copy's counts and are not claimed here.
+ */
+export async function forkViaSource(b, sourceId, atTurn, waitMs = FORK_SOURCE_WAIT_MS) {
+    const fork = b.sources?.conversations?.fork;
+    if (typeof fork !== "function")
+        return { error: `${b.label} cannot fork a conversation` };
+    if (!BARE_ID.test(sourceId))
+        return { error: "bad id" };
+    if (!atTurn || atTurn.length > 256)
+        return { error: "that turn is not one this conversation can be cut at" };
+    let timer;
+    const late = new Promise((r) => { timer = setTimeout(() => r("late"), waitMs); });
+    let answer;
+    try {
+        answer = await Promise.race([fork.call(b.sources.conversations, sourceId, atTurn), late]);
+    }
+    catch (e) {
+        return { error: `${b.label} could not fork it: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (answer === "late")
+        return { error: `${b.label} did not fork it in time — nothing was opened` };
+    if (answer === null || answer === undefined)
+        return { error: `${b.label} did not fork it — nothing was opened` };
+    const id = answer.id;
+    if (typeof id !== "string" || !BARE_ID.test(id))
+        return { error: `${b.label} answered a fork with no usable conversation id — nothing was opened` };
+    if (id === sourceId)
+        return { error: `${b.label} answered the same conversation, not a fork of it — nothing was opened` };
+    return { newId: id };
+}
+//# sourceMappingURL=convfork.js.map

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * Reading the CLI's own conversation jsonl: the two decoders both readers need.
+ *
+ * `limitlog.ts` asks that file what the account is doing; `ctxlog.ts` asks it
+ * how full the context window has been. They walk it differently — one
+ * backwards to the newest of two row kinds, one forwards and incrementally —
+ * but they decode the SAME two fields off the same records, and they had a
+ * byte-identical copy each. `ctxlog.ts`'s copy carried the argument for this
+ * file in its own comment: *one of the two will move first and the other must
+ * not quietly disagree.*
+ */
+/**
+ * A record's `timestamp`, as epoch ms, or null when it has none we can read.
+ *
+ * Null rather than `Date.now()`: an undated row is not a row that happened now,
+ * and a series that silently stamps unparseable records with the current clock
+ * draws a cliff wherever the log format shifted.
+ */
+export declare function stamp(row: {
+    timestamp?: unknown;
+}): number | null;
+/**
+ * An instant that may be seconds or milliseconds, as ms.
+ *
+ * `resetsAt` is seconds in every row seen so far. Accepting ms too costs one
+ * comparison and is what stops a unit change upstream from becoming a reset
+ * 56 000 years out — a wall the app would then wait at for ever.
+ */
+export declare function toMs(v: unknown): number | null;
+/**
+ * `YYYY-MM-DD` in the LOCAL zone — the day a rate is asked for.
+ *
+ * Local rather than the ISO string's prefix, and the same rule (and the same
+ * reason) as `tokenstats.ts`'s `localHour`: slicing the ISO would file a 01:30
+ * turn under the previous UTC day. It only ever decides which side of a rate
+ * change a record falls on, so being off by a day is only visible on the day a
+ * price moves — which is exactly the day it would be wrong on both screens in
+ * different directions if they disagreed about the zone.
+ */
+export declare function localDay(ms: number): string;

package/packages/host/dist/convlog.js

@@ -0,0 +1,52 @@
+/**
+ * Reading the CLI's own conversation jsonl: the two decoders both readers need.
+ *
+ * `limitlog.ts` asks that file what the account is doing; `ctxlog.ts` asks it
+ * how full the context window has been. They walk it differently — one
+ * backwards to the newest of two row kinds, one forwards and incrementally —
+ * but they decode the SAME two fields off the same records, and they had a
+ * byte-identical copy each. `ctxlog.ts`'s copy carried the argument for this
+ * file in its own comment: *one of the two will move first and the other must
+ * not quietly disagree.*
+ */
+/**
+ * A record's `timestamp`, as epoch ms, or null when it has none we can read.
+ *
+ * Null rather than `Date.now()`: an undated row is not a row that happened now,
+ * and a series that silently stamps unparseable records with the current clock
+ * draws a cliff wherever the log format shifted.
+ */
+export function stamp(row) {
+    if (typeof row.timestamp !== "string")
+        return null;
+    const t = Date.parse(row.timestamp);
+    return Number.isFinite(t) ? t : null;
+}
+/**
+ * An instant that may be seconds or milliseconds, as ms.
+ *
+ * `resetsAt` is seconds in every row seen so far. Accepting ms too costs one
+ * comparison and is what stops a unit change upstream from becoming a reset
+ * 56 000 years out — a wall the app would then wait at for ever.
+ */
+export function toMs(v) {
+    if (typeof v !== "number" || !Number.isFinite(v) || v <= 0)
+        return null;
+    return v < 1e11 ? v * 1000 : v;
+}
+/**
+ * `YYYY-MM-DD` in the LOCAL zone — the day a rate is asked for.
+ *
+ * Local rather than the ISO string's prefix, and the same rule (and the same
+ * reason) as `tokenstats.ts`'s `localHour`: slicing the ISO would file a 01:30
+ * turn under the previous UTC day. It only ever decides which side of a rate
+ * change a record falls on, so being off by a day is only visible on the day a
+ * price moves — which is exactly the day it would be wrong on both screens in
+ * different directions if they disagreed about the zone.
+ */
+export function localDay(ms) {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+//# sourceMappingURL=convlog.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"convlog.js","sourceRoot":"","sources":["../src/convlog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,GAA4B;IAChD,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC"}

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

@@ -0,0 +1,77 @@
+/**
+ * The cost WINDOW: the token ledger folded over an arbitrary `[from, to)` span,
+ * by hour, by repo and by conversation — `GET /api/costwindow`.
+ *
+ * ── Why a fold of its own and not a field on `TokenStatsDoc` ─────────────
+ *
+ * The all-time document cannot answer "where did THIS week go": its repo rows
+ * and its costliest list are all-time, and its hour rows carry no
+ * conversation. The store (`tokenstats.ts`) keeps every hour of every file
+ * crossed by model, so any span can be cut out of it here, priced per (model,
+ * day) exactly as `aggregate()` prices it — the two folds must agree to the
+ * cent over a span that covers everything.
+ *
+ * ── The one edge rule ────────────────────────────────────────────────────
+ *
+ * An hour is the finest bucket on record, so an hour whose top is `h` is in iff
+ * `h >= hourFloor(from) && h < to`. Where a WINDOW starts is not decided here:
+ * the phone sends `from` = `windowStartHour(openedAt)` (shared — the nearest
+ * hour boundary, `windowCells`' rule and the live cut's), already on the hour,
+ * so the floor is the identity and both ends agree on the edge by construction.
+ * The floor only bites for a caller that asks from a raw instant (the burn
+ * push's stretch), and the document says how much wider than asked that is
+ * (`fromHour`).
+ *
+ * ── What it never does ───────────────────────────────────────────────────
+ *
+ * It never charges an unpriced model zero (those tokens go to `unpriced`), it
+ * never drops a conversation nobody can name (title and launch are JOINED from
+ * what the host holds and are absent when it holds nothing), and a lookup that
+ * throws leaves its field absent rather than failing the read.
+ */
+import { type ClosedSession, type CostLaunch, type CostWindowDoc, type Intent, type SessionInfo, type SessionOrigin } from "@waterplane/shared";
+import { type FileSummary } from "./tokenscan.js";
+/** slug (project dir name) → path below it, no extension → summary (`tokenstats.ts`' store). */
+export type Files = Record<string, Record<string, FileSummary>>;
+/** What the host knows about a conversation beyond its ledger, keyed by the CLI's conversation id. */
+export interface CostMeta {
+    byConv: Map<string, {
+        title?: string;
+        live: boolean;
+        launch?: CostLaunch;
+    }>;
+}
+/**
+ * The repo a worktree belongs to. An agent worktree the CLI makes under
+ * `<repo>/.claude/worktrees/<name>` is that repo's work — counted apart it
+ * printed `agent-aae5b06d449c4da1a` as a repo of its own in the by-repo list,
+ * beside the repo it was spending for. Lives here (re-exported by
+ * `tokenstats.ts`) so this module and that one import each other in one
+ * direction only.
+ */
+export declare function repoOfWorktree(w: string): string;
+/**
+ * Fold the store over `[from, to)`. Pure: no clock, no disk.
+ *
+ * The tally loop is `aggregate()`'s — uncross, `tallyToTotals`, `costOf` per
+ * (model, day) — so a cent here is a cent there. An agent transcript folds into
+ * the conversation `fileKey.split("/")[0]` names; a conversation whose logs
+ * named no cwd is the "" repo ("unknown repo"); a record with no parseable
+ * timestamp has no hour and is in no window.
+ */
+export declare function foldCostWindow(files: Files, from: number, to: number, meta: CostMeta, scannedAt: number, cap?: number): CostWindowDoc;
+/**
+ * Join titles and launches from what the host already holds: the live
+ * sessions (and how each was opened), the closed stack, and the intent rows a
+ * fan-out run left behind. Live wins over closed; among closed rows the newest
+ * (first in the stack) wins. Never throws — a lookup that throws leaves its
+ * field absent, because a missing name is a row labelled `repo · id8` and a
+ * failed read is a card with nothing on it.
+ */
+export declare function costMeta(sessions: {
+    list(): SessionInfo[];
+    originOf(id: string): SessionOrigin | undefined;
+    listClosed(): ClosedSession[];
+}, intents: {
+    get(id: string): Intent | undefined;
+}): CostMeta;