waterplane 0.0.1 → 0.1.6

package/packages/host/dist/acks.js

@@ -0,0 +1,268 @@
+/**
+ * The ack ledger — "have I already done this one?".
+ *
+ * Every durable client action carries an `ackId`, and the phone re-sends the
+ * SAME id when it never saw the receipt (a dead socket, a reload, the tunnel
+ * flapping). Without a memory of what has already been handled, that retry
+ * types the prompt a second time / adds the work item twice / spawns a second
+ * 12-repo fan-out. This module is that memory: a repeat is re-ACKed with the
+ * ORIGINAL verdict and the action is not re-run. It is the client-retry twin of
+ * the at-most-once rule `deliver.ts` enforces on the PTY side.
+ *
+ * Two things about it are load-bearing and were wrong when it lived inline in
+ * main.ts:
+ *
+ *   • The TTL outlives the client's queue. It was 15 min while the phone's
+ *     `QUEUE_TTL_MS` (web/outbox.ts) is 30 — so an entry could still be sitting
+ *     in localStorage, eligible for one more retry, after the host had already
+ *     forgotten it. That is a double-type hole, not a theoretical one. 45 min
+ *     keeps the host's memory strictly longer than anything the client will
+ *     still send.
+ *
+ *   • It survives a restart. `npm run restart` is routine (every host edit), and
+ *     an in-memory-only ledger forgets everything across it — so a queued
+ *     `fanout.run` re-sent after a restart would start the whole sweep again.
+ *     The map is therefore persisted to <STATE_DIR>/acks.json:
+ *
+ *       { "updatedAt": …, "acks": { "<ackId>": { ts, ok, reason?, itemId?, sessionId?, runId?, op? } } }
+ *
+ * Three details of HOW it is persisted are load-bearing, because the window they
+ * cover is exactly the window a restart lands in:
+ *
+ *   • OP verdicts are written SYNCHRONOUSLY, not debounced. `npm run restart`
+ *     goes through launchd `kickstart -k` — an immediate SIGTERM — so a 500 ms
+ *     debounce is long enough to lose the one record that matters: the phone
+ *     sends `fanout.run {ackId}`, the host spawns 12 sessions, the socket dies
+ *     before `op.ack` lands, the restart happens inside the debounce window, and
+ *     the retry runs the whole sweep again. Ops are rare (a tap each); only the
+ *     keystroke-frequency `input.ack` receipts need the debounce.
+ *
+ *   • `flush()` runs on SIGTERM/SIGINT (wired in server/shutdown.ts) so whatever IS still
+ *     debounced reaches the disk before the process goes.
+ *
+ *   • The write is atomic (tmp file + rename). A kill mid-`writeFileSync` leaves
+ *     truncated JSON, the constructor's catch silently starts empty, and the
+ *     result is the same duplicate sweep the file exists to prevent.
+ *
+ * Persistence is best-effort throughout — a read or write that fails degrades to
+ * the old in-memory behaviour and must never throw into the request path. But a
+ * failed WRITE is not silent: it is logged, kept (`lastWriteError()`) and told
+ * once (`onWriteError` → a feed row and a doctor row), because a receipt that
+ * never reached the disk is a retry a restart lets run twice.
+ *
+ * A file that is PRESENT and does not parse is not "start empty" any more: it is
+ * moved aside (`jsonstore.ts`, `acks.json.corrupt-<ts>`), logged, and the loss
+ * is held in `lost` for one TTL so `main.ts` can tell a person. Inside that
+ * window an UNKNOWN ackId whose message says it was first sent before the loss
+ * (`firstSentAt`/`sentAt`, `shared/sendstamp.ts`) is REFUSED, never run —
+ * `preLossRefusal` below, asked by every ackId path (`durableOp`,
+ * `session.input`, `backlog.add`) after the known/in-flight checks — and the
+ * refusal is remembered like any verdict, so its retries hear the same thing.
+ * An ackId is random, so without the stamp a pre-loss retry and a fresh op are
+ * the same bytes: a message with no `firstSentAt` (an older client) still runs,
+ * exactly as before, because refusing every unknown ackId for the TTL would
+ * refuse every new send for 45 minutes. A fresh send (first sent after the
+ * loss) runs normally.
+ *
+ * Bounded both ways: entries expire, and the map is capped, so a long-lived
+ * daemon never accumulates one entry per message ever sent.
+ */
+import { join } from "node:path";
+import { readJsonGuardedDetail, writeJsonAtomic } from "./jsonstore.js";
+import { hostStateDir } from "./branddirs.js";
+import { preLossRefusal } from "@waterplane/shared";
+/** Must stay > the client's QUEUE_TTL_MS (30 min) — see the header. */
+export const ACK_TTL_MS = 45 * 60_000;
+const ACK_MAX = 1000;
+/** Debounce for the high-frequency records only (`input.ack`). Op verdicts skip
+ *  it entirely — see the header: a restart lands INSIDE this window. */
+const SAVE_DEBOUNCE_MS = 500;
+/**
+ * The feed row for a lost ledger (`main.ts` fires it at boot; the in-app feed
+ * is replayed on hello, so it waits for the first phone). It says what the
+ * host can no longer promise and what to check — never that nothing ran.
+ */
+export function lostLedgerNotice(lost) {
+    return {
+        title: "Host lost its record of recent sends",
+        body: "Its at-most-once ledger was unreadable at start-up, so a prompt or action retried from before this restart " +
+            "may run a second time. Check the session before re-sending anything that looked unanswered." +
+            (lost.movedTo ? ` The damaged file is kept as ${lost.movedTo}.` : ""),
+        tag: "acks-lost",
+    };
+}
+/** The words a person reads when receipts stop reaching the disk — the feed row and the log line say the same thing. */
+export const ACK_WRITE_FAILED = "receipts not reaching disk — a retry after a restart may run twice";
+/**
+ * The feed row for a ledger that can no longer be WRITTEN (`onWriteError`,
+ * wired in `main.ts`). Not a refusal: the op it was remembering has already
+ * run and cannot be un-run, so its verdict still goes out — what changes is
+ * that a restart forgets it, and that is what a person has to hear.
+ */
+export function ackWriteNotice(message) {
+    return {
+        title: "Host cannot save its record of sends",
+        body: `${ACK_WRITE_FAILED[0].toUpperCase()}${ACK_WRITE_FAILED.slice(1)} (${message}). ` +
+            "Until it can, check a session before re-sending anything after a host restart; check free disk space and that the host's state folder is writable.",
+        tag: "acks-write",
+    };
+}
+/** How often a STILL-failing write is logged again, and the floor between two feed rows. */
+const WRITE_ERROR_LOG_MS = 10 * 60_000;
+const WRITE_ERROR_NOTICE_MS = 30 * 60_000;
+export class AckLedger {
+    path;
+    acks = new Map();
+    /** Why the last write failed (null once one landed). See `persist()`. */
+    writeError = null;
+    writeErrorLoggedAt = 0;
+    writeErrorToldAt = 0;
+    /**
+     * Told when the ledger stops reaching the disk — once per failing streak and
+     * never twice inside `WRITE_ERROR_NOTICE_MS` (a nearly-full disk flaps).
+     * `main.ts` turns it into a feed row (`ackWriteNotice`). Never throws into
+     * the request path: a listener's failure is swallowed.
+     */
+    onWriteError = null;
+    timer = null;
+    /** Set when the persisted ledger was present but unreadable at boot: when,
+     *  where its bytes were kept, and until when a re-send of a pre-loss op may
+     *  still arrive (one TTL — after that nothing it held could be replayed). */
+    lost = null;
+    constructor(root) {
+        this.path = join(hostStateDir(root), "acks.json");
+        const isDoc = (v) => !!v && typeof v === "object" && typeof v.acks === "object" && v.acks !== null;
+        const read = readJsonGuardedDetail(this.path, null, isDoc);
+        const now = Date.now();
+        if (read.corrupt) {
+            this.lost = { at: now, movedTo: read.corrupt.movedTo, until: now + ACK_TTL_MS };
+            console.error(`[acks] the at-most-once ledger was unreadable (${read.corrupt.error}). Any send retried from before this boot ` +
+                "can no longer be recognised as a repeat and may run a second time." +
+                (read.corrupt.movedTo ? ` Its bytes are kept at ${read.corrupt.movedTo}.` : ""));
+        }
+        for (const [id, rec] of Object.entries(read.value?.acks ?? {})) {
+            // Drop anything already stale on load: replaying a day-old verdict to a
+            // client that has long since given up is worse than re-running.
+            if (rec && typeof rec.ts === "number" && now - rec.ts <= ACK_TTL_MS)
+                this.acks.set(id, rec);
+        }
+    }
+    /**
+     * The sentence refusing an UNKNOWN ackId that was first sent before this
+     * ledger was lost — null when nothing was lost, the window has passed, or the
+     * message cannot say when it was first sent (an older client: it runs, as it
+     * always did). The caller has already asked `get` and the in-flight map; a
+     * known ackId is re-acked, never judged here. Skew and margins: `sendstamp.ts`.
+     */
+    preLossRefusal(stamp, receivedAt = Date.now()) {
+        return preLossRefusal(this.lost, stamp, receivedAt);
+    }
+    /** The stored verdict for an ackId, or undefined if unknown/expired. */
+    get(ackId) {
+        const rec = this.acks.get(ackId);
+        if (!rec)
+            return undefined;
+        if (Date.now() - rec.ts > ACK_TTL_MS) {
+            this.acks.delete(ackId);
+            return undefined;
+        }
+        return rec;
+    }
+    /** Record what this ackId did, so a retry re-acks instead of re-running. */
+    remember(ackId, rec) {
+        const now = Date.now();
+        this.acks.set(ackId, { ...rec, ts: now });
+        if (this.acks.size > ACK_MAX) {
+            for (const [k, v] of this.acks) {
+                if (now - v.ts > ACK_TTL_MS)
+                    this.acks.delete(k);
+            }
+            // Still over budget after expiry ⇒ evict by insertion order (Map keeps
+            // it), but NON-OP records first. The cap is shared between two very
+            // different populations: keystroke-frequency `input.ack` receipts and the
+            // handful of op verdicts. Plain oldest-first eviction means enough acked
+            // sends inside the client's 30-minute retry window push a still-retryable
+            // fan-out verdict out of the ledger — and the next retry re-runs the whole
+            // sweep. So op verdicts survive to their TTL; a lost input receipt costs
+            // at most one retyped line.
+            this.evictOldest((v) => !v.op);
+            this.evictOldest(() => true);
+        }
+        // An op verdict is the expensive one to forget and rare enough to afford a
+        // synchronous write; everything else rides the debounce. See the header.
+        if (rec.op)
+            this.flush();
+        else
+            this.schedulePersist();
+    }
+    /** Drop oldest-inserted entries matching `pick` until we're back under the cap. */
+    evictOldest(pick) {
+        for (const [k, v] of this.acks) {
+            if (this.acks.size <= ACK_MAX)
+                return;
+            if (pick(v))
+                this.acks.delete(k);
+        }
+    }
+    /** Write any debounced changes now. `false` ⇒ the write failed (`lastWriteError()`). */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        return this.persist();
+    }
+    /** Why the last write failed, or null when it landed (or none was tried). */
+    lastWriteError() { return this.writeError?.message ?? null; }
+    schedulePersist() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => { this.timer = null; this.persist(); }, SAVE_DEBOUNCE_MS);
+        this.timer.unref?.(); // never hold the daemon open for a receipt file
+    }
+    /**
+     * Atomic write (`writeJsonAtomic`: tmp + fsync + rename). A plain
+     * `writeFileSync` truncates first, so a SIGTERM landing mid-write leaves half
+     * a JSON document — exactly the loss this file exists to prevent.
+     *
+     * A failed write still never breaks a send — the op it records has already
+     * RUN by the time `remember` is called, and refusing its verdict cannot
+     * un-run it — but it is no longer silent: the reason is kept
+     * (`lastWriteError()`), logged once per streak (then every
+     * `WRITE_ERROR_LOG_MS`), and handed to `onWriteError` so a person hears that
+     * a restart will forget these receipts. Answers whether the bytes landed.
+     */
+    persist() {
+        try {
+            const doc = { updatedAt: Date.now(), acks: Object.fromEntries(this.acks) };
+            writeJsonAtomic(this.path, doc);
+        }
+        catch (e) {
+            this.noteWriteFailed(String(e?.message ?? e));
+            return false;
+        }
+        if (this.writeError) {
+            console.log(`[acks] ${this.path} is being written again (it had failed since ${new Date(this.writeError.at).toISOString()}: ${this.writeError.message})`);
+            this.writeError = null;
+            this.writeErrorLoggedAt = 0;
+        }
+        return true;
+    }
+    noteWriteFailed(message) {
+        const now = Date.now();
+        const first = !this.writeError;
+        this.writeError = { at: this.writeError?.at ?? now, message };
+        if (first || now - this.writeErrorLoggedAt >= WRITE_ERROR_LOG_MS) {
+            this.writeErrorLoggedAt = now;
+            console.error(`[acks] could not write ${this.path} (${message}): ${ACK_WRITE_FAILED}`);
+        }
+        if (first && this.onWriteError && (this.writeErrorToldAt === 0 || now - this.writeErrorToldAt >= WRITE_ERROR_NOTICE_MS)) {
+            this.writeErrorToldAt = now;
+            try {
+                this.onWriteError(message);
+            }
+            catch { /* telling must never break a send */ }
+        }
+    }
+}
+//# sourceMappingURL=acks.js.map

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

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

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

@@ -0,0 +1,45 @@
+/**
+ * `POST /api/agent/followup` — an agent flags ITS OWN session for follow up
+ * with a one-line reason (R-sessions-044). It can set the flag and never clear
+ * it: there is no DELETE, and an empty reason is refused, so the only way a
+ * flag goes away stays a person's tap.
+ *
+ * Same caller gate as `agentintents.ts` (`agentCallerRefusal`): loopback, not
+ * proxied, not a browser. The session is named by `session`, or found from the
+ * agent's `$PWD` (`resolveFollowUpSession`, pure, pinned without a daemon).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type FollowUp, type SessionInfo } from "@waterplane/shared";
+/** The slice of a session this decision reads. */
+export type FollowUpCandidate = Pick<SessionInfo, "id" | "cwd" | "title" | "running" | "idle" | "turnActive">;
+export type FollowUpResolution = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/**
+ * Which live session is the caller. `session` wins when it names a live one;
+ * otherwise `dir` is matched against session cwds (the longest cwd that is
+ * `dir` or a parent of it), and among those exactly one mid-turn, or exactly
+ * one at all, is the answer. Anything else is a refusal that lists the
+ * candidates so the agent can retry with `session`. `real` compares paths
+ * (injected so a test needs no disk).
+ */
+export declare function resolveFollowUpSession(sessions: readonly FollowUpCandidate[], q: {
+    session?: unknown;
+    dir?: unknown;
+}, real?: (p: string) => string): FollowUpResolution;
+export interface AgentFollowUpDeps {
+    sessions: {
+        list(): SessionInfo[];
+        setFollowUp(id: string, f: FollowUp | null): boolean;
+    };
+    json(res: ServerResponse, data: unknown, status?: number): void;
+    readJson(req: IncomingMessage): Promise<any>;
+    now?: () => number;
+}
+/** `true` when the request was this route's (answered, or refused). */
+export declare function handleAgentFollowUp(req: IncomingMessage, res: ServerResponse, path: string, d: AgentFollowUpDeps): Promise<boolean>;

package/packages/host/dist/agentfollowup.js

@@ -0,0 +1,77 @@
+import { sep } from "node:path";
+import { clipFollowUpText } from "@waterplane/shared";
+import { agentCallerRefusal } from "./agentintents.js";
+import { realResolve } from "./paths.js";
+const PATH = "/api/agent/followup";
+const midTurn = (s) => s.turnActive ?? (s.idle === false);
+const label = (s) => `${s.id} (${s.title || "untitled"})`;
+/**
+ * Which live session is the caller. `session` wins when it names a live one;
+ * otherwise `dir` is matched against session cwds (the longest cwd that is
+ * `dir` or a parent of it), and among those exactly one mid-turn, or exactly
+ * one at all, is the answer. Anything else is a refusal that lists the
+ * candidates so the agent can retry with `session`. `real` compares paths
+ * (injected so a test needs no disk).
+ */
+export function resolveFollowUpSession(sessions, q, real = realResolve) {
+    const live = sessions.filter((s) => s.running);
+    const sid = typeof q.session === "string" ? q.session.trim() : "";
+    const dir = typeof q.dir === "string" ? q.dir.trim() : "";
+    if (sid) {
+        const hit = live.find((s) => s.id === sid);
+        if (hit)
+            return { ok: true, id: hit.id };
+        if (!dir)
+            return { ok: false, status: 404, error: `no live session "${sid}" — pass "dir": "$PWD" to find yours by folder` };
+    }
+    if (!dir)
+        return { ok: false, status: 400, error: 'say which session: "session": "<id>" or "dir": "$PWD"' };
+    const here = real(dir);
+    const within = live
+        .map((s) => ({ s, cwd: real(s.cwd) }))
+        .filter(({ cwd }) => here === cwd || here.startsWith(cwd.endsWith(sep) ? cwd : cwd + sep));
+    if (!within.length)
+        return { ok: false, status: 404, error: `no live session runs in ${dir} — nothing was flagged` };
+    const longest = Math.max(...within.map((x) => x.cwd.length));
+    const cands = within.filter((x) => x.cwd.length === longest).map((x) => x.s);
+    if (cands.length === 1)
+        return { ok: true, id: cands[0].id };
+    const busy = cands.filter(midTurn);
+    if (busy.length === 1)
+        return { ok: true, id: busy[0].id };
+    return {
+        ok: false,
+        status: 409,
+        error: `${cands.length} sessions run in that folder${busy.length > 1 ? ` and ${busy.length} are mid-turn` : " and none is mid-turn"}, so I cannot tell which is yours: ${cands.map(label).join(", ")} — retry with "session": "<id>"`,
+    };
+}
+/** `true` when the request was this route's (answered, or refused). */
+export async function handleAgentFollowUp(req, res, path, d) {
+    if (path !== PATH)
+        return false;
+    const refusal = agentCallerRefusal(req.socket.remoteAddress, req.headers);
+    if (refusal) {
+        d.json(res, { ok: false, error: refusal }, 403);
+        return true;
+    }
+    if (req.method !== "POST") {
+        d.json(res, { ok: false, error: `POST ${PATH} sets the flag; only the person can clear it` }, 405);
+        return true;
+    }
+    const body = await d.readJson(req);
+    const reason = clipFollowUpText(body?.reason);
+    if (!reason) {
+        d.json(res, { ok: false, error: 'a one-line "reason" is required — say what the person should read' }, 400);
+        return true;
+    }
+    const r = resolveFollowUpSession(d.sessions.list(), { session: body?.session, dir: body?.dir });
+    if (!r.ok) {
+        d.json(res, { ok: false, error: r.error }, r.status);
+        return true;
+    }
+    const followUp = { by: "agent", at: (d.now ?? Date.now)(), reason };
+    d.sessions.setFollowUp(r.id, followUp);
+    d.json(res, { ok: true, session: r.id, followUp });
+    return true;
+}
+//# sourceMappingURL=agentfollowup.js.map

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

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