waterplane 0.0.1 → 0.1.6

package/packages/host/dist/naming.js

@@ -0,0 +1,387 @@
+import { cleanNamingDoc, typedName } from "@waterplane/shared";
+import { ASSESSABLE_STATES } from "./assess.js";
+import { runNameTask } from "./sidecar.js";
+import { env } from "./env.js";
+import { promptText } from "./prompts.js";
+// ── The knobs ───────────────────────────────────────────────────────────────
+/** The model the claude engine runs on. `.env.example` carries the why. */
+export const NAME_MODEL = env("NAME_MODEL") || "haiku";
+/**
+ * How long one batch may take.
+ *
+ * A plain constant and not an environment knob, deliberately: unlike the smart
+ * pick, nothing is HELD behind this call — no item is waiting to fire, no
+ * session is blocked, a person tapped a button and the backlog is still theirs
+ * to use while it thinks. So the sidecar's own generous default is the right
+ * number for the same reason it is the right number there (ollama cold-loads an
+ * idle model), and a second variable to tune it would be a knob nobody has a
+ * reason to turn.
+ */
+export const NAME_TIMEOUT_MS = 120_000;
+/** How many items go in one call. */
+export const NAME_BATCH_ITEMS = 20;
+/**
+ * …and how many characters, which is the cap that actually bites.
+ *
+ * Twenty prompts of ordinary length is a few thousand tokens; twenty prompts
+ * from the repo that writes essays into its backlog is not. The count is the
+ * cheap bound and this is the honest one.
+ */
+export const NAME_BATCH_CHARS = 40_000;
+/**
+ * The contract, pinned.
+ *
+ * Every clause is enforced somewhere else as well — the shape by
+ * `cleanNamingDoc`, the caps by `cleanHeadline`, the four kinds by
+ * `cleanCategory`, the id by the batch it was sent — so nothing here is the
+ * only thing standing between a wrong answer and a written row. What it buys is
+ * the answer being right the FIRST time, which is the difference between a pass
+ * that titles eleven rows and one that titles none and writes four notes.
+ *
+ * The last line (*answer straight away*) is there for the measured reason:
+ * cost is thinking, not input.
+ */
+export const NAME_SYSTEM = [
+    "You title backlog items. For each item answer JSON only:",
+    '{"items":[{"id":…,"headline":"3–8 words, not the item\'s first words","category":"bug|feature|enhancement|chore"}]}.',
+    "Omit category when none fits.",
+    "Answer straight away.",
+].join("\n");
+/**
+ * Is there a field on this row a MACHINE is allowed to write?
+ *
+ * Both halves are asked separately, because a row whose title a person typed
+ * and whose kind nobody ever set is the ordinary case: refusing the whole row
+ * on one `hand` field would leave that kind unset for ever.
+ *
+ * The author clause reads as redundant today — the store drops the pair
+ * together, so an absent value already means an absent author — and it is kept
+ * because it is the RULE rather than a consequence of how the store happens to
+ * clean. If a value ever survives without its author, this line is what keeps a
+ * person's name out of a machine's reach.
+ *
+ * ── A typed `label` IS a title, and this has to agree with the display ──────
+ *
+ * `itemHeadline` is the ONE display rule and it says a typed `label` beats a
+ * headline, ALWAYS. So a row whose label a person typed already has a title on
+ * every screen, and a headline bought for it is a headline nothing will ever
+ * show. With the phone's own `ids` the two agreed by accident — the cut was
+ * computed under the display rule — but a pass with `ids: []`, or one run
+ * against a cut a moment out of date, spent real money on rows that were
+ * already named. The test is `itemHeadline`'s own (`typedName(label, text, 40)`,
+ * the backlog's slice length), because two spellings of "does this row have a
+ * title" is exactly the disagreement this is fixing.
+ */
+function needsName(i) {
+    const text = i.payload.kind === "prompt" ? i.payload.steps[0] ?? "" : "";
+    const titled = !!i.headline || !!typedName(i.label, text, 40);
+    const wantsHeadline = !titled && i.headlineBy !== "hand";
+    const wantsCategory = !i.category && i.categoryBy !== "hand";
+    return wantsHeadline || wantsCategory;
+}
+/**
+ * The repo's untitled rows, cut into calls.
+ *
+ * `ids`, when given, is the cut a person asked about; every row in it is still
+ * put through the same four filters, so a scope naming another repo's rows, a
+ * finished row or an already-titled one simply produces fewer batches rather
+ * than a pass that titles things nobody asked about.
+ *
+ * Order is the store's own (`list()` is newest first), which is the order the
+ * phone shows — so a person watching a pass sees it work down the list they are
+ * looking at rather than through an order only this file knows.
+ */
+export function buildNamingInput(intents, cwd, ids) {
+    const scope = ids?.length ? new Set(ids) : null;
+    const rows = [];
+    for (const i of intents.list()) {
+        if (i.cwd !== cwd)
+            continue;
+        if (i.payload.kind !== "prompt")
+            continue;
+        if (!ASSESSABLE_STATES.has(i.state))
+            continue;
+        if (scope && !scope.has(i.id))
+            continue;
+        if (!needsName(i))
+            continue;
+        rows.push({
+            id: i.id,
+            text: i.payload.steps[0] ?? "",
+            handHeadline: i.headlineBy === "hand",
+            handCategory: i.categoryBy === "hand",
+        });
+    }
+    const batches = [];
+    let cur = [];
+    let chars = 0;
+    const flush = () => {
+        if (!cur.length)
+            return;
+        batches.push({ rows: cur, chars });
+        cur = [];
+        chars = 0;
+    };
+    for (const r of rows) {
+        // Flushed BEFORE the row is added, and only when there is something to
+        // flush: that is what puts an over-budget item in a batch of its own at
+        // full length instead of clipping it or refusing it.
+        if (cur.length && (cur.length >= NAME_BATCH_ITEMS || chars + r.text.length > NAME_BATCH_CHARS))
+            flush();
+        cur.push(r);
+        chars += r.text.length;
+    }
+    flush();
+    return batches;
+}
+/** One batch, as the JSON the model reads. The words go in whole. */
+export function namingPrompt(batch) {
+    return JSON.stringify({
+        items: batch.rows.map((r) => ({ id: r.id, text: r.text })),
+    });
+}
+// ── What came back ──────────────────────────────────────────────────────────
+/**
+ * The JSON inside whatever the model actually answered.
+ *
+ * `assess/hassutil.ts`'s `parseLoose` in spirit (a fence is unwrapped, not
+ * refused), plus the outermost `{…}`/`[…]` slice, and a bare ARRAY is
+ * accepted: an array of `{id, headline}` objects is
+ * unambiguous, `cleanNamingDoc` already reads that shape, and every entry in it
+ * still has to name an id that was in the batch before anything is written.
+ */
+export function parseNamingText(raw) {
+    const text = typeof raw === "string" ? raw.trim() : "";
+    if (!text)
+        return null;
+    const tries = [text];
+    const fence = /```(?:json|JSON)?\s*\n?([\s\S]*?)```/.exec(text);
+    if (fence)
+        tries.push(fence[1].trim());
+    const open = text.search(/[{[]/);
+    const close = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
+    if (open >= 0 && close > open)
+        tries.push(text.slice(open, close + 1));
+    for (const t of tries) {
+        try {
+            const v = JSON.parse(t);
+            if (v && typeof v === "object")
+                return v;
+        }
+        catch { /* next shape */ }
+    }
+    return null;
+}
+/**
+ * **The sentences, in one pure function.**
+ *
+ * Here rather than inline in `run()` because it is the whole of what a person
+ * sees of this feature, and a string assembled inside an async method is a
+ * string that can only be checked by running a pass. Every wording rule this
+ * app already has is in it: a count that is zero is not mentioned, a failure
+ * says what failed rather than that something did, and nothing claims a number
+ * it did not measure.
+ */
+export function namingSentence(r) {
+    // A pass that wrote nothing says why, and only why: "named 0" is a sentence
+    // that reads like a result when it is an explanation that went missing.
+    if (!r.named) {
+        return `nothing written — ${r.detail || (r.unnamed
+            ? "the model gave no usable title"
+            : "nothing here needed a title")}`;
+    }
+    const parts = [`named ${r.named}`];
+    if (r.unnamed)
+        parts.push(`${r.unnamed} left unnamed — the model gave no usable title`);
+    if (r.kept)
+        parts.push(`${r.kept} kept the name you typed`);
+    // A pass that wrote SOME rows and then hit a wall says both: the rows it
+    // wrote are real, and the reason the rest are missing is the only thing that
+    // explains a half-titled list.
+    if (r.detail)
+        parts.push(r.detail);
+    return parts.join(" · ");
+}
+/**
+ * What the ACK says, now that the ack no longer waits for the pass.
+ *
+ * Here beside `namingSentence` and not inline in the route, for
+ * `namingSentence`'s reason: it is what a person reads, so it is checkable
+ * without spawning anything. It says the NUMBER because that is the one fact
+ * the tap does not already carry — "it started" is visible in the list, "it is
+ * working on eleven of these" is not — and it promises the sentence that
+ * follows, because a screen that goes quiet for two minutes after a tap is a
+ * screen nobody taps twice.
+ */
+export function namingStartedNote(rows) {
+    return `titling ${rows} item${rows === 1 ? "" : "s"} — this runs on, and will say what it wrote`;
+}
+/**
+ * One naming pass per repo at a time, and the rows each one is working on.
+ *
+ * `running` is the map the backlog snapshot reads: it is TRANSIENT, exactly as
+ * `waiting` is — memory only, gone with a restart, and meaning "right now",
+ * never "this row is being renamed and you may not touch it". Nothing is locked
+ * while a pass thinks; the worst an edit mid-pass can do is have its row titled
+ * a second later, and `IntentManager.name()` re-reads the live row before it
+ * writes, so a title a person types in that window is `hand` by the time the
+ * answer lands and is refused.
+ */
+export class NamingManager {
+    deps;
+    /** repoDir → the ids a live pass is working on. */
+    running = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Every row any live pass is working on, flattened — the snapshot's shape. */
+    runningIds() {
+        const out = [];
+        for (const set of this.running.values())
+            for (const id of set)
+                out.push(id);
+        return out;
+    }
+    /**
+     * Title what is untitled in this repo.
+     *
+     * **Both refusals are SENTENCES**, because both are answers a person needs
+     * rather than errors: "one is already running" and "there is nothing here to
+     * title" are different facts, and a tap that produced silence would be a
+     * button that sometimes does nothing for reasons nobody can see
+     * (`Unavailable.tsx`'s rule, reached through a verb).
+     *
+     * One at a time per repo, for `startAssessment`'s reason narrowed to one
+     * field: two passes over one list write two titles onto the same rows in an
+     * order nobody chose, and the second one wins by accident.
+     */
+    async start(repoDir, ids) {
+        const r = this.begin(repoDir, ids);
+        return "refusal" in r ? r.refusal : r.finished;
+    }
+    /**
+     * **The refusals, decided while there is still a socket to refuse on — and
+     * the pass itself, handed back rather than awaited.**
+     *
+     * `startAssessment`'s shape, for the reason a review measured here: the route
+     * is `durable: true`, so the phone is holding an op open across this call. A
+     * pass is up to ten SEQUENTIAL batches at up to `NAME_TIMEOUT_MS` (120 s)
+     * each; the phone's ack deadline is 20 s and it gives up after 8 attempts.
+     * So a pass that was working perfectly was re-sent eight times (suppressed by
+     * `opsInFlight`, so nothing was bought twice) and then shown as FAILED while
+     * it was still running — after which the host sent up to eight acks for it.
+     *
+     * The split is therefore not cosmetic. Everything that can answer a person
+     * NOW — one already running, nothing here to title — answers now, and the
+     * pass's own sentence goes back as the toast it always was, whenever it
+     * lands. The rows being worked on ride the snapshot as a transient
+     * (`running`), which is what the list shows in the meantime.
+     */
+    begin(repoDir, ids) {
+        if (this.running.has(repoDir)) {
+            return { refusal: "a naming pass is already running for this repo — two of them would write different titles onto the same rows" };
+        }
+        const batches = buildNamingInput(this.deps.intents, repoDir, ids);
+        if (!batches.length) {
+            return {
+                refusal: ids?.length
+                    ? "nothing in that cut needs a title — those rows are finished, not this repo's, or already named"
+                    : "nothing here needs a title — every open item already has one",
+            };
+        }
+        const live = new Set();
+        for (const b of batches)
+            for (const r of b.rows)
+                live.add(r.id);
+        this.running.set(repoDir, live);
+        this.deps.onChange();
+        const finished = this.run(repoDir, batches)
+            .then((r) => namingSentence(r))
+            // A throw out of the pass is the empty result this module treats every
+            // other failure as — and it must reach the same sentence, or the only
+            // thing a person sees of a pass that died is the row-set going quiet.
+            .catch((e) => namingSentence({
+            named: 0, unnamed: live.size, kept: 0,
+            detail: e?.message || "the naming pass could not be run",
+        }))
+            .finally(() => {
+            // In a `finally` because a throw anywhere below must not leave the repo
+            // holding a pass nothing will ever release — the refusal above would
+            // then be permanent, and the only way back would be a restart.
+            this.running.delete(repoDir);
+            this.deps.onChange();
+        });
+        return { rows: live.size, finished };
+    }
+    /**
+     * The batches, one after another.
+     *
+     * SEQUENTIAL and not parallel: the point of the batches is that one call is
+     * small, and three of them at once is one large call with extra sockets. It
+     * also makes the account block below mean something — the first batch to come
+     * back limited stops the rest, instead of four more calls being spent finding
+     * out the same thing.
+     */
+    async run(repoDir, batches) {
+        const runner = this.deps.run ?? runNameTask;
+        const out = { named: 0, unnamed: 0, kept: 0 };
+        let detail;
+        for (const batch of batches) {
+            let run;
+            try {
+                run = await runner({
+                    cwd: repoDir,
+                    prompt: namingPrompt(batch),
+                    system: promptText("tab-name", NAME_SYSTEM),
+                    model: NAME_MODEL,
+                    timeoutMs: NAME_TIMEOUT_MS,
+                });
+            }
+            catch (e) {
+                // The empty result, the way every other sidecar caller treats one: a
+                // throw out of the runner is not different in kind from a server that
+                // answered nothing, and nothing here is half-written.
+                detail = e?.message || "the naming pass could not be run";
+                out.unnamed += batch.rows.length;
+                break;
+            }
+            if (run.limited) {
+                detail = run.detail || "the account is out of quota";
+                out.unnamed += batch.rows.length;
+                break;
+            }
+            if (run.failed || !run.text) {
+                detail = run.detail || "the model answered nothing";
+                out.unnamed += batch.rows.length;
+                continue;
+            }
+            // `{id, text}` and nothing else: the words are what lets the "this title
+            // is only the item's first line" rule run at all, and the hand flags are
+            // this module's bookkeeping, not part of the judgement.
+            const { names } = cleanNamingDoc(parseNamingText(run.text), batch.rows.map((r) => ({ id: r.id, text: r.text })));
+            for (const row of batch.rows) {
+                const n = names[row.id];
+                if (!n) {
+                    out.unnamed++;
+                    continue;
+                }
+                // Counted BEFORE the write, off what the pass OFFERED and what the row
+                // already had: after the write both look the same, and "your title was
+                // kept" is the only place this feature's one rule is visible.
+                if (n.headline !== undefined && row.handHeadline)
+                    out.kept++;
+                if (n.category !== undefined && row.handCategory)
+                    out.kept++;
+                const wrote = this.deps.intents.name(row.id, n, "name");
+                if (wrote.headline || wrote.category)
+                    out.named++;
+                else
+                    out.unnamed++;
+            }
+        }
+        if (detail)
+            out.detail = detail;
+        return out;
+    }
+}
+//# sourceMappingURL=naming.js.map

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

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

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

@@ -0,0 +1,78 @@
+/**
+ * Find the local Tailscale IPv4 (100.64.0.0/10 CGNAT range) if present.
+ * Mirrors the trick the Python drop server uses: enumerate interfaces and
+ * also probe via a dummy UDP "connect" to a tailnet-reachable address.
+ */
+/**
+ * All non-internal LAN IPv4s of this host (excludes loopback and the Tailscale
+ * 100.64/10 range). These are the addresses the phone can hit directly on the
+ * same WiFi — `http://<lanIp>:8770` — to bypass the Tailscale tunnel entirely.
+ */
+export type PeerKind = "loopback" | "tailscale" | "lan" | "public" | "unknown";
+/**
+ * Classify a socket's remote address into the trust tiers the auth gate uses.
+ * Strips the IPv4-mapped-IPv6 prefix. loopback = this machine; tailscale =
+ * 100.64/10 CGNAT; lan = RFC1918 private; anything else public/unknown.
+ */
+export declare function peerKind(addr: string | undefined | null): PeerKind;
+/**
+ * The headers a reverse proxy adds — the ONE list. `tailscale serve` terminates
+ * HTTPS and forwards to 127.0.0.1, so every tailnet request it carries arrives
+ * from LOOPBACK; these headers are what tell it apart from a process on this
+ * desktop. A local curl, a hook, the `$BROWSER` shim sends none of them.
+ */
+export declare const PROXY_HEADERS: readonly string[];
+/** Whether the request carries a proxy header (came through `tailscale serve`/Funnel) — the one implementation. */
+export declare function isProxied(headers: Record<string, unknown> | undefined): boolean;
+/** Whether a `Host` header names this machine itself (port and brackets stripped); absent counts as local. */
+export declare function hostHeaderIsLocal(h: string | string[] | undefined): boolean;
+/**
+ * Why this request is not a process on THIS desktop, or null when it is: the
+ * socket peer is loopback AND no proxy header is present. The gate of every
+ * local-process-only route (`/api/hook`, `/api/plugin/:id/hook`,
+ * `/api/shell/open`) and the first two tests of `agentCallerRefusal`.
+ * Loopback alone is not enough — see `PROXY_HEADERS`.
+ */
+export declare function localProcessRefusal(remoteAddress: string | undefined, headers: Readonly<Record<string, string | string[] | undefined>>): string | null;
+/**
+ * The trust tier of a REQUEST, not just its socket: a loopback socket carrying
+ * a proxy header came through `tailscale serve` from another tailnet device,
+ * so it is `tailscale` — gated when "gate Tailscale" is on, which before this
+ * never applied to anyone using the https address. Only ever a DOWNGRADE from
+ * loopback (a local process adding the header loses its exemption, nothing
+ * more), and never touches a non-loopback peer. The token gate (`server/http.ts`,
+ * `server/wsops.ts`) asks this; `localProcessRefusal` keeps its own stricter test.
+ */
+export declare function requestPeerKind(remoteAddress: string | undefined | null, headers: Readonly<Record<string, string | string[] | undefined>>): PeerKind;
+/** This desktop's name as a person would call it: the OS hostname, minus the
+ *  `.local` mDNS suffix macOS appends. */
+export declare function hostName(): string;
+export declare function lanIps(): string[];
+export declare function tailscaleIp(): Promise<string | null>;
+/**
+ * Resolve a usable `tailscale` CLI invocation. On macOS the GUI/App-Store app
+ * ships the CLI inside its bundle and does NOT put it on PATH, so the bare
+ * `tailscale …` command we suggest fails with `command not found`. Prefer a
+ * PATH hit, then the known bundle location; return null if neither exists.
+ * The returned string is a shell-ready path (quoted if it contains spaces).
+ */
+export declare function tailscaleBin(): Promise<string | null>;
+/**
+ * MagicDNS FQDN of this host (e.g. `mac.tailnet.ts.net`), read from
+ * `tailscale status --json` → Self.DNSName. This is the name a
+ * `tailscale serve --https=443` cert is issued for, so it's the HTTPS base URL
+ * the phone should use to get a secure context (Web Push / service worker).
+ * Null if no tailscale CLI or not on a tailnet.
+ */
+export declare function tailscaleDnsName(): Promise<string | null>;
+/**
+ * The HTTPS URL `tailscale serve` fronts a local port with, or null.
+ *
+ * Keyed on the PROXY TARGET, not on a substring of the status text: the target
+ * (`http://127.0.0.1:8770`) contains the port number too, so a naive match read
+ * "we are fronted" from any serve config at all — and then reported the bare
+ * `https://<name>`, silently assuming the listener is on 443. That is wrong
+ * whenever 443 already serves something else, and it sent the phone's
+ * Connection shortcut to a different app entirely.
+ */
+export declare function serveHttpsUrl(port: number): Promise<string | null>;