waterplane 0.0.1 → 0.1.6

package/packages/host/dist/context.js

@@ -0,0 +1,92 @@
+/**
+ * Context-window figure detection.
+ *
+ * Works on ANSI-stripped PTY tail text, like prompt.ts / limit.ts, and is
+ * equally heuristic: the phrasings are pinned to what the Claude Code TUI
+ * prints for its context indicator (the auto-compact note, the "context left"
+ * footer, a "128k/200k tokens" gauge, the /context breakdown). TUI copy
+ * changes can break this — it degrades to "unknown" (null), never a wrong
+ * number, so a miss just hides the badge.
+ */
+/** Percent-remaining phrasings, most specific first. Each capture is the number. */
+const PCT_RES = [
+    /context left until auto-?compact:?\s*(\d{1,3})%/i, // "Context left until auto-compact: 42%"
+    /(\d{1,3})%\s*context (?:left|remaining|free)/i, // "42% context left"
+    /context (?:left|remaining|free):?\s*(\d{1,3})%/i, // "Context remaining: 42%"
+];
+/** "123k/200k tokens" style → absolute used/total. */
+const RATIO_RE = /(\d+(?:\.\d+)?)\s*(k|m)?\s*\/\s*(\d+(?:\.\d+)?)\s*(k|m)?\s*(?:tokens|token|ctx|context)/i;
+function scale(n, unit) {
+    const u = (unit || "").toLowerCase();
+    return u === "m" ? n * 1_000_000 : u === "k" ? n * 1_000 : n;
+}
+/**
+ * A row that is unmistakably the CLI's context indicator, whatever number it
+ * carries — the word "context" plus one of the words the indicator is built
+ * from, on one line.
+ *
+ * This exists for the health readout and for nothing else, and it is narrow on
+ * purpose. "The meter returned null" is worthless as a signal on its own: most
+ * sessions most of the time print no context indicator at all, so a session
+ * that never shows one would log a miss on every scan and bury the sessions
+ * where the indicator IS on screen and the number no longer comes out of it.
+ * The gate is what separates "there is nothing to read" from "there is
+ * something to read and the parse no longer reads it" — which is the only one
+ * of the two that says a regex has gone stale.
+ *
+ * Deliberately not built from `PCT_RES`/`RATIO_RE`: a gate derived from the
+ * matchers it is meant to check on can never disagree with them.
+ */
+const METER_GATE_RE = /[^\n]*\bcontext\b[^\n]*\b(?:left|remaining|free|window|used|auto-?compact)\b[^\n]*/gi;
+/**
+ * The words alone are not enough: the agent's own prose talks about "the
+ * Context window" and "/compact" all day, and every such line passed the gate
+ * and filed a miss — 18 of them, 0 good, a BROKEN chip over a meter that was
+ * never on screen. An indicator always carries a figure (`42%`, `123k`), and
+ * it is never a row of the conversation: `⏺` opens an assistant line, `⎿` a
+ * tool result, `>`/`❯` the person's own words.
+ */
+const METER_FIGURE_RE = /\d\s*%|\d(?:\.\d+)?\s*[km]\b/i;
+const CONVERSATION_ROW_RE = /^\s*[⏺⎿>❯]/;
+/** The last context-indicator row in the text, or null when there is none.
+ *  Last, because a repaint-based TUI leaves older frames above the fresh one. */
+export function contextMeterRow(text) {
+    const re = new RegExp(METER_GATE_RE.source, METER_GATE_RE.flags);
+    let hit = null;
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+        const row = m[0].trim();
+        if (row && METER_FIGURE_RE.test(row) && !CONVERSATION_ROW_RE.test(m[0]))
+            hit = row;
+    }
+    return hit;
+}
+export function detectContext(text) {
+    const out = { leftPct: null };
+    // Absolute token gauge — take the LAST match (freshest redraw wins).
+    const rg = new RegExp(RATIO_RE.source, "gi");
+    for (let m = rg.exec(text); m; m = rg.exec(text)) {
+        const used = scale(Number(m[1]), m[2]);
+        const total = scale(Number(m[3]), m[4]);
+        if (total > 0 && used >= 0 && used <= total) {
+            out.usedTok = Math.round(used);
+            out.totalTok = Math.round(total);
+            out.leftPct = Math.round((1 - used / total) * 100);
+        }
+    }
+    // Explicit percent phrasing overrides the derived one (more direct signal).
+    for (const re of PCT_RES) {
+        const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+        let hit = null;
+        for (let m = g.exec(text); m; m = g.exec(text)) {
+            const n = Number(m[1]);
+            if (n >= 0 && n <= 100)
+                hit = n; // last wins
+        }
+        if (hit != null) {
+            out.leftPct = hit;
+            break;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=context.js.map

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

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

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

@@ -0,0 +1,31 @@
+import type { ContextWeightLimits } from "@waterplane/shared";
+/** One repo's override, plus when it was set — the stamp is only ever shown
+ *  ("set 3 days ago"), never used to decide anything. */
+export interface ContextLimitEntry {
+    limits: Partial<ContextWeightLimits>;
+    setAt: number;
+}
+export declare class ContextLimitsStore {
+    private path;
+    private doc;
+    constructor(root: string);
+    /** This repo's override, or null. Null means "nothing on file", which is a
+     *  different thing from "all three at their defaults" and must stay so: the
+     *  editor opens on what was saved. */
+    get(worktree: string): Partial<ContextWeightLimits> | null;
+    /** When this repo's override was last written, or null when it has none. */
+    setAt(worktree: string): number | null;
+    /**
+     * Replace this repo's override. An empty patch CLEARS the entry — "back to
+     * the host's line" is a state the user must be able to get back to, and a
+     * lingering `{}` would keep answering `null` anyway while cluttering the file.
+     */
+    set(worktree: string, limits: Partial<ContextWeightLimits>): void;
+    clear(worktree: string): void;
+    private save;
+}
+export declare function setContextLimitsStore(store: ContextLimitsStore | null): void;
+export declare function contextLimitsStore(): ContextLimitsStore | null;
+/** This repo's override, or null when there is none — or when no store has been
+ *  installed at all, which reads the same way on purpose. */
+export declare function repoContextLimits(worktree: string): Partial<ContextWeightLimits> | null;

package/packages/host/dist/contextlimits.js

@@ -0,0 +1,128 @@
+/**
+ * Per-repo overrides for the context-weight thresholds.
+ *
+ * `compliance.ts`'s `context-weight` row asks what a repo costs to have OPEN,
+ * and compares it to a line. Until now that line was three env vars
+ * (`WATERPLANE_CONTEXT_WARN_CHARS` / `_HARD_CHARS` / `_MAX_SKILLS`), host-wide and
+ * invisible from the phone — so the only way to disagree with it was to export
+ * a variable on the desktop and restart, which changed the line for *every*
+ * repo at once. The two repos that most need a different number are exactly the
+ * ones that must not share one: a scratch project where 16k of instructions is
+ * already absurd, and a repo whose invariants are genuinely load-bearing and
+ * which will sit amber for ever otherwise.
+ *
+ * Deliberate shape:
+ *
+ *  - **A host store, keyed by worktree — never a file written into the repo.**
+ *    `setupwatch.ts` sweeps repos the user has not opened, and the one rule that
+ *    path holds is that it never writes into a repo. A threshold is also not a
+ *    fact about the source tree: it is this desktop's opinion about a directory
+ *    on it. `<STATE_DIR>/contextlimits.json`, beside `setup.json`.
+ *  - **The key is the REALPATH**, the same spelling rule and for the same reason
+ *    as `setupwatch.ts`: a worktree arrives spelled two ways (`git worktree
+ *    list` resolves symlinks, a session's `cwd` does not) and two spellings
+ *    would mean the override you just saved is not the one the sweep reads.
+ *  - **A partial is a partial.** An entry holds only the fields that were set;
+ *    the rest keep falling through to env and then to the default. Storing all
+ *    three would freeze the other two at whatever today's default happens to be,
+ *    so a later change to a shipped default would silently not reach the repo.
+ *  - **Unset is a silent no-op**, like `clihealth.ts`: `inspectRepo()` is a free
+ *    function with no root in hand, and a test or a tool that calls it without
+ *    booting a daemon must get env+defaults, never a throw.
+ */
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { sanitizeContextLimits } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+/** The one spelling of a worktree path. Falls back to the given path when the
+ *  directory is gone — a stale entry keyed on a name we can still read beats
+ *  throwing inside a checklist. */
+function key(worktree) {
+    try {
+        return realpathSync(worktree);
+    }
+    catch {
+        return worktree;
+    }
+}
+export class ContextLimitsStore {
+    path;
+    doc = {};
+    constructor(root) {
+        this.path = join(hostStateDir(root), "contextlimits.json");
+        try {
+            if (existsSync(this.path)) {
+                const parsed = readJsonGuarded(this.path, null);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    for (const [k, v] of Object.entries(parsed)) {
+                        const rec = v;
+                        // Sanitise on the way IN as well as out: this file is plain JSON and
+                        // a hand-edit must not be able to put a zero or a string where a
+                        // threshold goes and have every reading taken against it.
+                        const { limits } = sanitizeContextLimits(rec?.limits);
+                        if (Object.keys(limits).length) {
+                            this.doc[k] = { limits, setAt: Number(rec?.setAt) || Date.now() };
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* corrupt or unreadable → no overrides, which is the safe reading */ }
+    }
+    /** This repo's override, or null. Null means "nothing on file", which is a
+     *  different thing from "all three at their defaults" and must stay so: the
+     *  editor opens on what was saved. */
+    get(worktree) {
+        const e = this.doc[key(worktree)];
+        return e && Object.keys(e.limits).length ? { ...e.limits } : null;
+    }
+    /** When this repo's override was last written, or null when it has none. */
+    setAt(worktree) {
+        const e = this.doc[key(worktree)];
+        return e ? e.setAt : null;
+    }
+    /**
+     * Replace this repo's override. An empty patch CLEARS the entry — "back to
+     * the host's line" is a state the user must be able to get back to, and a
+     * lingering `{}` would keep answering `null` anyway while cluttering the file.
+     */
+    set(worktree, limits) {
+        const k = key(worktree);
+        if (!limits || !Object.keys(limits).length)
+            delete this.doc[k];
+        else
+            this.doc[k] = { limits: { ...limits }, setAt: Date.now() };
+        this.save();
+    }
+    clear(worktree) {
+        this.set(worktree, {});
+    }
+    save() {
+        try {
+            mkdirSync(join(this.path, ".."), { recursive: true });
+            writeJsonAtomic(this.path, this.doc, { space: 2 });
+        }
+        catch { /* a threshold that could not be persisted is not worth a crash */ }
+    }
+}
+// ── The module-level singleton ──────────────────────────────────────────────
+//
+// `inspectRepo(worktree)` takes a path and nothing else, and is called from the
+// sweep, from the HTTP route and from tests. Threading a store through all of
+// them to reach one row would be the wrong trade; `clihealth.ts` already
+// established the shape here — a settable singleton whose unset state is a
+// silent no-op.
+let current = null;
+export function setContextLimitsStore(store) {
+    current = store;
+}
+export function contextLimitsStore() {
+    return current;
+}
+/** This repo's override, or null when there is none — or when no store has been
+ *  installed at all, which reads the same way on purpose. */
+export function repoContextLimits(worktree) {
+    return current?.get(worktree) ?? null;
+}
+//# sourceMappingURL=contextlimits.js.map

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

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

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

@@ -0,0 +1,67 @@
+import type { BackendDescriptor } from "./backends/types.js";
+export type ForkOk = {
+    /** The conversation id of the file just written. `--resume <newId>` opens it. */
+    newId: string;
+    /** Records copied. Useful in a log line; the caller has no other cheap count. */
+    records: number;
+    /** Lines that would not parse and were therefore dropped. Normally 0. */
+    dropped: number;
+    /** Bookkeeping records about the turn after the cut, removed by
+     *  `pruneStranded()`. Fires on roughly one fork in twenty. */
+    pruned: number;
+};
+export type ForkResult = ForkOk | {
+    error: string;
+};
+/**
+ * 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 declare function forkConversationFile(cwd: string, sourceId: string, atTurnUuid: string): ForkResult;
+/**
+ * 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 declare const FORK_SOURCE_WAIT_MS = 20000;
+/**
+ * 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 declare function forkViaSource(b: Pick<BackendDescriptor, "label" | "sources">, sourceId: string, atTurn: string, waitMs?: number): Promise<{
+    newId: string;
+} | {
+    error: string;
+}>;