waterplane 0.0.1 → 0.1.6

package/packages/host/dist/sessions/knobs.d.ts

@@ -0,0 +1,315 @@
+import type { LimitLogVerdict } from "../limitlog.js";
+export declare const SCROLLBACK_LIMIT: number;
+export declare const HISTORY_LIMIT = 200;
+export declare const OUTPUT_CAP: number;
+export declare const RAW_CAPTURE_CAP: number;
+export declare const NAME_INPUT_CHARS = 1000;
+export declare const RENAME_RECENT_PROMPTS = 4;
+export declare const RENAME_RECENT_CHARS = 400;
+/**
+ * The tab-name call runs on the CHEAPEST thing that can do it, with none of the
+ * context a coding session needs — because it is not a coding session.
+ *
+ * Measured on this host, one call, same transcript:
+ *
+ *   opus + project settings + tools    83,529 tok   (what this used to be)
+ *   haiku + project settings + tools   70,690
+ *   haiku, user settings only          27,642   <- the project CLAUDE.md, gone
+ *   haiku, user settings, no tools      9,025   <- the default system prompt, gone
+ *   haiku, user settings, no tools,
+ *     own system prompt                 1,867   <- 45x
+ *
+ * Each flag removes something this task provably does not use. `--setting-sources
+ * user` drops the project's own `CLAUDE.md` — 37k tokens of repo rules, loaded to
+ * paraphrase a terminal screen. `--tools ""` drops the tool definitions: the
+ * transcript is already IN the prompt and there is nothing to go and read.
+ * `--system-prompt` replaces Claude Code's own, which is the agent harness for a
+ * job that is one sentence of prose. Quality did not drop — on the same input the
+ * cheap run produced a better summary than the expensive one.
+ */
+export declare const SUMMARY_MODEL: string;
+/**
+ * The ≤4-word tab name, and what it is asked ABOUT.
+ *
+ * The cheapest call in the daemon, by construction: its whole input is the
+ * session's FIRST PROMPT (≤ `NAME_INPUT_CHARS`), never the screen, a summary or
+ * a later prompt. Same model, same three flags, so it inherits every
+ * measurement above; it is one call PER SESSION, once. (The per-turn AI summary
+ * these measurements were taken on is gone — this is the only unattended call
+ * of its kind left.)
+ *
+ * No thinking is asked for and none is useful: naming four words off one
+ * prompt is a compression, not a decision, and a model that reasons about it
+ * spends tokens to arrive at the same label.
+ *
+ * FOUR and not three because the tab is not the only place these words are
+ * read: the session screen shows them in full when you open it, where a fourth
+ * word is the difference between a category and a description. The tab clips to
+ * its own width either way.
+ */
+export declare const TAB_TITLE_SYSTEM = "You name things in at most four words. Output only the name.";
+export declare const TAB_TITLE_PROMPT: string;
+/**
+ * The hand-asked rename (`record.nameNow`) — the sparkle on the session header.
+ * A person taps it because the name the opening prompt bought no longer says
+ * what the session is DOING, so the opening prompt alone is the one input that
+ * cannot answer it: a session opened on "continue" or a bare command came back
+ * "(none)" every time. It is shown the opening prompt plus the last few, the
+ * recent ones weighing most. Still toolless, still prompts only — never the
+ * screen or output — and bounded to ~3k characters.
+ */
+export declare const RENAME_PROMPT: string;
+export declare const REMOTE_URL_RE: RegExp;
+export declare const PROMPT_CHECK_MS = 600;
+export declare const PROMPT_MAX_STALE_MS = 1200;
+export declare const PROMPT_MISS_MAX = 3;
+/**
+ * How soon a strict pass that read a NEW box (or a change to the published
+ * one) looks again before publishing it. A box is published only once two
+ * consecutive reads agree (`boxes.ts`'s `readTwice`): tmux hands its client a
+ * screen in chunks, and a read between two of them is a box cut mid-label —
+ * which `mergeBox`, never rewriting a published label, then kept for the life
+ * of the box. Short, because it is added to every box's first appearance;
+ * long enough to span the gap between two chunks of one paint.
+ */
+export declare const PROMPT_SETTLE_MS = 300;
+/**
+ * How long after a resize a capture is presumed half-drawn.
+ *
+ * Generous on purpose: the cost of being wrong here is that a box which really
+ * did close stays published for one extra check (it is retired the moment the
+ * screen carries no dialog footer, which needs no budget at all), and the cost
+ * of being too tight is the blink this constant exists to stop. Two checks'
+ * worth.
+ */
+export declare const RESIZE_REPAINT_MS = 1500;
+export declare const PROMPT_GATE_BYTES = 12000;
+export declare const QUESTION_TAIL_BYTES = 4000;
+export declare const SUBMIT_NAV_TRIES = 6;
+export declare const SUBMIT_NAV_MAX_KEYS = 8;
+export declare const SUBMIT_NAV_LINES = 60;
+export declare const SUBMIT_NAV_SETTLE_MS = 160;
+export declare const MODE_MAX_PRESSES = 6;
+export declare const MODE_PRESS_WAIT_MS = 1500;
+export declare const MODE_POLL_MS = 60;
+/**
+ * Placing the selection on an UNNUMBERED option (`choosePromptBox`), and the
+ * rows an attributed replay reads back for it.
+ *
+ * One key per pass, so the tries are the steps: three options measured, and the
+ * ring wraps, so two moves is the worst case and the rest is headroom for a
+ * repaint that swallowed one. The settle is longer than the checkbox walk's
+ * because opencode's repaint lag was measured between 0.3 s and 2 s, and a
+ * re-read taken before the redraw lands reads the OLD armed option — which
+ * would walk the selection straight past the one that was asked for.
+ */
+export declare const CHOOSE_NAV_TRIES = 8;
+export declare const CHOOSE_NAV_SETTLE_MS = 400;
+/** Rows of the grid an attributed replay reads back. The dialog is drawn at the
+ *  bottom of an alternate screen that is exactly the terminal's height, so this
+ *  only has to cover a tall box plus the rows it is anchored against. */
+export declare const PROMPT_CELL_ROWS = 60;
+export declare const IDLE_PING_MS: number;
+/**
+ * How long a `Stop` hook is treated as a CLAIM before it is believed.
+ *
+ * A Stop hook is not the end of a turn — it is the CLI asking whether the turn
+ * may end. A hook that answers "no" (`decision: block`, which is how every
+ * keep-going loop is built: a /goal hook, a checklist driver, anything that
+ * feeds work back in) makes the CLI carry straight on with NO
+ * `UserPromptSubmit` to follow, because no prompt was submitted — the
+ * continuation arrives in the conversation as a meta message. So the exact
+ * signal fires, the turn does not end, and this host believed it: a session
+ * spinning "✻ Crafting… (9m 35s · ↓ 34.5k tokens)" published
+ * `turnActive: false`, the reader said "idle — nothing running" over a live
+ * turn, and the queue typed a prompt into it that was never confirmed and had
+ * to be retried four times.
+ *
+ * So the Stop is settled against the screen a moment later: the CLI's own
+ * working line (`shared/working.ts`, the same matcher the phone's reader uses)
+ * printed AFTER the Stop is the one thing that can contradict it. Nothing is
+ * recorded on the health board for this — the hook did not fail, it was
+ * answered, and a signal that reads "broken" for every session with a
+ * keep-going hook is a permanent amber nobody reads.
+ *
+ * 0 disables the check: the Stop is believed immediately, as it was.
+ */
+export declare const STOP_VERIFY_MS: number;
+/** Ceiling on the bytes one settle pass scans. The window is normally "what the
+ *  CLI printed since the last pass" (one repaint); the cap is only there so a
+ *  session that dumped a megabyte in that gap costs a regex over the tail of it
+ *  and not over the whole ring. */
+export declare const STOP_VERIFY_BYTES = 64000;
+/**
+ * How long after output lands on an IDLE session the screen is read to decide
+ * whether that output was work or a redraw (`idlewatch.ts`'s `noteOutput`). Only a
+ * parse lag: the recorder's headless VT applies a write asynchronously, so the
+ * grid read on the chunk's own tick can be the frame before it. One pending
+ * read per session; a spinner repaints several times a second, so a turn that
+ * starts is seen within one or two of these.
+ */
+export declare const IDLE_WATCH_MS = 250;
+/**
+ * How long after a spawn the hook pipe and the conversation log are allowed to
+ * be missing without it counting against them.
+ *
+ * Both are legitimately absent for the first seconds of a session's life: the
+ * `SessionStart` hook is a curl that has to run, and the CLI writes its
+ * conversation log when it accepts the first prompt. Without this grace every
+ * fresh session would record one fallback for each — a steady drip of misses
+ * that says nothing except "sessions start", and one that would drag both
+ * signals to `degraded` on an ordinary busy morning.
+ *
+ * Env-settable because it is the one health rule an e2e cannot wait out: a
+ * minute per assertion is a minute per assertion, so the rule that a fresh
+ * session records nothing went unchecked, and the rule NEXT to it — that a
+ * re-attached session records nothing either — shipped wrong (see
+ * `noteHookFallback`). A knob nobody sets in production is cheaper than a rule
+ * nobody tests.
+ */
+export declare const HEALTH_SPAWN_GRACE_MS: number;
+/** Rows of a rendered screen kept as a `line` sample. Enough to hold a dialog's
+ *  footer and the option rows above it, which is what a stale matcher is read
+ *  against; the redaction and the 240-char cap do the rest. */
+export declare const HEALTH_SAMPLE_ROWS = 6;
+export declare const LIMIT_RETRY_MS: number;
+export declare const LIMIT_RESET_BUFFER_MS: number;
+/** The verdict when there is nothing to read — never a claim, see `limitlog.ts`. */
+export declare const LIMIT_LOG_UNKNOWN: LimitLogVerdict;
+/**
+ * Churn guard, and ONLY that.
+ *
+ * It used to be the thing that ended a wait, which is why every weekly wall
+ * gave up on the afternoon it started: 24 attempts on a ten-minute cadence is
+ * under four hours against a window that resets days later. `limitretry.ts`
+ * widens the delay instead, so the same cap now spans days — and how long a
+ * wall may last is `LIMIT_GIVEUP_MS`'s question, not this one. Raised with the
+ * ladder because a week of six-hourly attempts is ~30 of them.
+ */
+export declare const LIMIT_MAX_ATTEMPTS: number;
+/**
+ * How long one continuous block may last before this desktop stops waiting.
+ *
+ * Eight days: a weekly window is seven, so the bound is "a window and a bit"
+ * rather than a number picked to feel patient. Past it the session is left
+ * closed and says so — `gaveup` — which is the honest end of a wait nobody can
+ * see the end of.
+ */
+export declare const LIMIT_GIVEUP_MS: number;
+/**
+ * How long a reopened conversation may take to re-hit the wall it was reopened
+ * into and still count as the SAME block (`Session.limitCarried`).
+ *
+ * A resurrection that lands on a live wall re-blocks within seconds. Five
+ * minutes is that with room to spare, and short enough that a session which
+ * came back, worked, and met a fresh wall later is treated as what it is.
+ */
+export declare const LIMIT_CARRY_MS: number;
+/** The first rung of the backoff, shortened only by tests that cannot sit one
+ *  out (`limitretry.ts`'s `probeMs`). */
+export declare const LIMIT_PROBE_MS: number;
+/** …and the whole ladder, for the tests that cannot sit out the rungs behind the
+ *  first either. Empty (the default) means `limitretry.ts`'s own. */
+export declare const LIMIT_LADDER_MS: number[];
+export declare const LIMIT_SWEEP_MS: number;
+/** How often the running-agent list is re-read while any agent is running. A
+ *  readdir plus a stat per agent, and armed only while there is something to
+ *  re-read — see `checkAgents`. */
+export declare const AGENT_POLL_MS: number;
+/** How many submitted prompts a session remembers. A delivery asks about the
+ *  seconds it has just been waiting through, and a turn takes minutes — this is
+ *  a short queue against a race, not a history (the transcript is that). */
+export declare const SUBMIT_RING = 8;
+/** How long a turn must have been IN FLIGHT before it counts as the account
+ *  serving this session again. A rejected turn dies in seconds — the wall is
+ *  the CLI's answer to it — so a turn still running well past that is the one
+ *  dated fact a screen scan cannot argue with. */
+export declare const SERVING_TURN_MS: number;
+export declare const LIMIT_RESUME_GAP_MS: number;
+export declare const LIMIT_RESUME_SETTLE_MS: number;
+export declare const CLAUDE_ID_POLL_MS = 5000;
+export declare const CLAUDE_ID_POLL_MAX = 60;
+/**
+ * How stale a per-session file must be before the orphan sweep may delete it.
+ *
+ * Load-bearing, but for a narrower case than it looks. The alive set is the live
+ * session map UNION the `live/` store's filenames (`aliveSessionIds`) — there is
+ * no `tmux ls` in it. So what the age gate actually protects is a file whose
+ * session was ACTIVE RECENTLY while the alive set was momentarily short: a boot
+ * that crashed before `rediscover()` populated the map, a root mounted late.
+ *
+ * It does NOT protect a live tmux session that has been idle longer than the gate
+ * — this host accumulates those — because such a file is past the gate AND, if
+ * the map is empty, absent from it. The only thing standing between that session
+ * and a delete is the `live/` read succeeding, which is why `aliveSessionIds`
+ * distinguishes "no live store" from "the live store could not be read" and the
+ * sweep declines to run at all on the second.
+ *
+ * Seven days is far shorter than the leak it exists to bound: measured here, 436
+ * history files and 98 summaries against ~107 live sessions.
+ */
+export declare const ORPHAN_MAX_AGE_MS: number;
+/** Boot is not the moment to walk two directories; the sweep is deferred behind
+ *  this on an unref'd timer, so it can also never hold the process open. */
+export declare const ORPHAN_SWEEP_DELAY_MS = 30000;
+/** A store file is `<sessionId>.json` and a session id is a uuid prefix. Anything
+ *  else is refused and left alone rather than sanitised — `archive.ts`'s
+ *  `deleteArchived` regex, for the same reason: this function deletes. */
+export declare const STORE_FILE_RE: RegExp;
+export declare const TMUX_SERVER: string;
+export declare const TMUX_PREFIX: string;
+export declare const tmuxName: (id: string) => string;
+/**
+ * Which tmux server a `live/` record's pane was started on, as a string this
+ * host can compare against its own: the socket directory tmux itself would use
+ * (`$TMUX_TMPDIR`, else `/tmp`, then `tmux-<uid>`) and the `-L` name. Stamped on
+ * every record by `persistLive` so the boot reclaim (`staleLiveIds`) only ever
+ * judges a record against a listing of the server that record belongs to.
+ * It never has to equal tmux's own spelling of the path — only itself: a
+ * differently spelled but identical directory reads as a DIFFERENT server, and
+ * a record on a different server is kept.
+ */
+export declare const TMUX_SOCKET_ID: string;
+/**
+ * True when nothing overrides the socket this host would pick by itself — no
+ * `WATERPLANE_TMUX_SERVER`, no `TMUX_TMPDIR`. A record written before records
+ * were stamped (`LiveMeta.tmuxSocket` absent) can only be judged under this
+ * condition: the one way such a record's pane lives on ANOTHER server is a host
+ * that once ran with an override, and a host that runs with one now cannot tell
+ * that history from its own. So an unstamped record is reclaimable only by a
+ * default host, and kept by any other.
+ */
+export declare const TMUX_SOCKET_DEFAULT: boolean;
+/**
+ * How long a `live/` record must have gone unwritten before the boot reclaim may
+ * delete it for having no tmux session (`staleLiveIds`). `create()` writes the
+ * record and starts the tmux client in the same tick, but the `new-session` that
+ * makes the name appear in `tmux ls` runs in the tmux CLIENT, asynchronously — so
+ * a second host process booting on the same state dir (a dev host beside the
+ * service, a doctor run) can list the server between the two. An hour is many
+ * orders of magnitude past that window and costs nothing: a record young enough
+ * to be spared is reclaimed by a later boot. Only e2e shortens it.
+ */
+export declare const STALE_LIVE_MIN_AGE_MS: number;
+/** How often a backend's `sources.sweep` is asked to reap what a gone session left behind
+ *  (`sidechannel.ts`; opencode's seat servers and records). Also run once when plugins settle. */
+export declare const SEAT_SWEEP_MS: number;
+/**
+ * A source turn's `ended(at)` waits at most this long for the backend's `context` sample to be
+ * stamped at or after `at` (`sidechannel.ts`), so the turn-end context read is THIS turn's fill.
+ * Absent or still stale past it ⇒ the end settles as before: the reading stays what it was or
+ * absent, never a guessed number. In-band channels (claude's hooks) never wait.
+ */
+export declare const CONTEXT_FRESH_MS = 1500;
+/** How often that wait asks `sample()` again when the source has no `watch()` to wake it. */
+export declare const CONTEXT_FRESH_POLL_MS = 50;
+/**
+ * Bytes typed INTO a pane through our tmux client: tmux reads ctrl+b (`\x02`)
+ * as its PREFIX and the key after it as a tmux command (`d` detaches, `x` kills
+ * the pane), so a lone ctrl+b from the phone never reached claude, which binds
+ * it to "background the running task". The default `C-b C-b` binding is
+ * `send-prefix`: doubling every `\x02` hands exactly one to the pane — what
+ * claude itself says under tmux ("ctrl+b ctrl+b (twice)"). The prefix is left
+ * as it is, for a person who attaches to this server at the desk.
+ */
+export declare function tmuxLiteral(data: string): string;