waterplane 0.0.1 → 0.1.6

package/packages/host/dist/backends/index.js

@@ -0,0 +1,328 @@
+import { claudeBackend } from "./claude.js";
+import { claudeLocalBackend } from "./claude-local.js";
+import { claudeEndpointBackend } from "./claude-endpoint.js";
+import { shellBackend } from "./shell.js";
+import { BACKENDS, liveIds, registerCore } from "./registry.js";
+import { derive } from "./derive.js";
+export * from "./types.js";
+export * from "./registry.js";
+export { PROMPT_READERS, TRANSCRIPT_READERS, contributedReaders, registerScreenReader, registerStoreReader, screenReaderFor, storeReaderFor, namesStoreReader } from "./readers.js";
+export { derive, walk, factProblems, CORE_SCREEN, CORE_STORE } from "./derive.js";
+export { claudeBackend, claudeBin, hookSettingsArg, CLAUDE_FACTS, ACCOUNTLESS_CLAUDE_FACTS, CLAUDE_EFFORTS } from "./claude.js";
+export { claudeLocalBackend, claudeLocalEnv, claudeLocalUrl, claudeLocalLeanArgs, claudeLocalKeepAlive, leanArgs, LEAN_TOOLS, windowFromShow } from "./claude-local.js";
+export { claudeEndpointBackend, endpointConfig } from "./claude-endpoint.js";
+export { shellBackend, shellBin, ensureBrowserShim, browserShimText, BROWSER_SHIM, SHELL_DROP_ENV } from "./shell.js";
+// Core's, in the order a person is offered them. Plugin backends join the same
+// list through `registerBackend` (`registry.ts`) and leave it again — opencode
+// among them, from its in-repo extension (`packages/extensions/opencode/`).
+registerCore(claudeBackend);
+registerCore(claudeLocalBackend);
+registerCore(claudeEndpointBackend);
+// A plain login shell (`shell.ts`): no turns, no model — `BackendInfo.kind: "shell"`.
+registerCore(shellBackend);
+/** The one a session gets when it says nothing about backends. */
+export const DEFAULT_BACKEND = claudeBackend;
+/** Is this a backend id this host knows? Answers without throwing. */
+export function knownBackend(id) {
+    return BACKENDS.some((b) => b.id === id);
+}
+/**
+ * Resolve a backend id to its descriptor.
+ *
+ * Absent ⇒ claude. Unknown ⇒ **throws**, with a sentence naming the id and the
+ * ids that would have worked. See the file header for why this is not a
+ * fallback.
+ */
+export function resolveBackend(id) {
+    if (!id)
+        return DEFAULT_BACKEND;
+    const found = BACKENDS.find((b) => b.id === id);
+    if (found)
+        return found;
+    throw new Error(`This host has no backend called "${id}". It can run: ${liveIds()}.`);
+}
+/**
+ * The model catalogues, asked ONCE at boot.
+ *
+ * A catalogue is a subprocess (`opencode models`), and the frame that carries it
+ * goes out on every socket that connects — so it is read once and remembered,
+ * never per hello. Unprimed and failed look the same on purpose: an EMPTY
+ * catalogue, which the phone renders as a free-text field. That is the honest
+ * answer in both cases, and it is the one shape that cannot offer a model this
+ * install does not have.
+ */
+const MODEL_CACHE = new Map();
+/**
+ * The running CLI version of each backend that declares `measured` (plugins), asked beside the
+ * catalogue and remembered the same way: `null` = the binary could not tell. Absent = never asked
+ * or no `measured` at all.
+ */
+const RUNNING_VERSION = new Map();
+/**
+ * "measured on X, running Y" as the sentence a person reads (review R6; plan §3.6): present only
+ * when the plugin named the versions it was measured on AND the running binary answered with one
+ * that is none of them. Never a refusal — the backend still launches; the sentence says what may
+ * be misread. Pure.
+ */
+export function measuredDriftText(label, versions, running) {
+    if (!running || !versions.length || versions.includes(running))
+        return null;
+    const on = versions.length === 1 ? versions[0] : `${versions.slice(0, -1).join(", ")} or ${versions[versions.length - 1]}`;
+    return `${label} was measured on ${on}, and this desktop is running ${running} — its screens or records may read differently until the plugin is measured on ${running}. It still starts.`;
+}
+/** Ask one backend for its running version, when it declares `measured`. Never throws. */
+async function askRunning(b) {
+    if (!b.measured) {
+        RUNNING_VERSION.delete(b.id);
+        return;
+    }
+    let v = null;
+    try {
+        v = await b.measured.version();
+    }
+    catch {
+        v = null;
+    }
+    if (!BACKENDS.includes(b))
+        return; // removed while it was being asked
+    RUNNING_VERSION.set(b.id, v);
+    const drift = measuredDriftText(b.label, b.measured.versions, v);
+    if (drift)
+        console.log(`[backend] ${b.id}: ${drift}`);
+}
+/** Ask every backend for its catalogue (and a plugin for its running version). Never throws; never rejects. */
+export async function primeBackendModels() {
+    await Promise.all(BACKENDS.map(async (b) => {
+        try {
+            MODEL_CACHE.set(b.id, await b.models());
+        }
+        catch {
+            MODEL_CACHE.set(b.id, { aliases: [], ids: [] });
+        }
+        await askRunning(b);
+    }));
+}
+/**
+ * After the list changed (a plugin registered or removed a backend): forget
+ * the catalogues of backends that left, ask only the ones never asked. A
+ * backend that registers after boot would otherwise stay an empty catalogue
+ * for ever. Never throws; never rejects. True when anything was asked.
+ */
+export async function primeNewBackendModels() {
+    const live = new Set(BACKENDS.map((b) => b.id));
+    for (const id of [...MODEL_CACHE.keys()])
+        if (!live.has(id))
+            MODEL_CACHE.delete(id);
+    for (const id of [...RUNNING_VERSION.keys()])
+        if (!live.has(id))
+            RUNNING_VERSION.delete(id);
+    const fresh = BACKENDS.filter((b) => !MODEL_CACHE.has(b.id));
+    // Marked first, so two changes in a row do not ask one backend twice.
+    for (const b of fresh)
+        MODEL_CACHE.set(b.id, { aliases: [], ids: [] });
+    await Promise.all(fresh.map(async (b) => {
+        let m;
+        try {
+            m = await b.models();
+        }
+        catch {
+            m = { aliases: [], ids: [] };
+        }
+        // Removed (or replaced) while it was being asked: the answer is about nobody.
+        if (BACKENDS.includes(b))
+            MODEL_CACHE.set(b.id, m);
+        await askRunning(b);
+    }));
+    return fresh.length > 0;
+}
+/** When each backend's catalogue was last RE-asked because it said unavailable. */
+const RECHECKED_AT = new Map();
+/**
+ * A catalogue that said "unavailable" (Ollama not reachable) was true at boot and
+ * stays that way for ever unless somebody asks again — and the phone removes the
+ * Start button on it. So: re-ask exactly the backends currently UNAVAILABLE, at
+ * most once per `minGapMs` each (a hello from every reconnecting socket must not
+ * become a probe per hello). Healthy catalogues are never re-asked here.
+ * Never throws. True when an answer changed what the phone is told.
+ */
+export async function recheckUnavailableBackends(minGapMs, now = Date.now()) {
+    const due = BACKENDS.filter((b) => MODEL_CACHE.get(b.id)?.unavailable && now - (RECHECKED_AT.get(b.id) ?? 0) >= minGapMs);
+    for (const b of due)
+        RECHECKED_AT.set(b.id, now);
+    let changed = false;
+    await Promise.all(due.map(async (b) => {
+        let m;
+        try {
+            m = await b.models();
+        }
+        catch {
+            return;
+        }
+        if (!BACKENDS.includes(b))
+            return;
+        const before = MODEL_CACHE.get(b.id);
+        if (before?.unavailable !== m.unavailable || before?.ids.length !== m.ids.length)
+            changed = true;
+        MODEL_CACHE.set(b.id, m);
+    }));
+    return changed;
+}
+/**
+ * How many tokens of context one model is CONFIGURED to hold, per the backend
+ * that offers it. Null when nobody said.
+ *
+ * Read out of the same cache the catalogue lives in, because it came out of the
+ * same probe (`backends/opencode.ts`'s `providerHosting`) and a second store
+ * would be a second thing to prime and a second thing to be stale. A backend
+ * that never answered, a model missing from the map, an unprimed cache: all of
+ * them are null, and null is what makes `ContextSeriesDoc.windowTok` absent and
+ * `windowFrom: "none"` — the graph then plots tokens on their own axis and says
+ * so, which is the shape it already had.
+ *
+ * **Never a fallback to another model's window, and never to claude's.** The
+ * caller asks about the model that actually ran.
+ */
+export function backendContextWindow(backendId, model) {
+    if (!model)
+        return null;
+    const id = backendId || DEFAULT_BACKEND.id;
+    const w = MODEL_CACHE.get(id)?.contextWindow?.[model];
+    return typeof w === "number" && w > 0 ? w : null;
+}
+/**
+ * Where one model of one backend RUNS, per the catalogue the backend gave
+ * (`models.where`) — `null` when nobody said. Never inferred from the id's
+ * spelling. The local-model gate's locality fact for a backend that has no
+ * `localRunner` of its own (opencode's local providers).
+ */
+export function backendModelWhere(backendId, model) {
+    if (!model)
+        return null;
+    const w = MODEL_CACHE.get(backendId || DEFAULT_BACKEND.id)?.where?.[model];
+    return w === "local" || w === "hosted" ? w : null;
+}
+/**
+ * May a "fork this conversation at turn N" be attempted against this backend?
+ * A sentence when it may not, null when it may.
+ *
+ * **The refusal is in WORDS, before anything happens.** `convfork.ts` forks a
+ * conversation by copying claude's jsonl up to a turn and writing a new one; run
+ * against an opencode session it is handed a `ses_…` id and a cwd, builds a path
+ * under `~/.claude/projects` that cannot exist, and fails with a file-not-found
+ * — a sentence about a path nobody asked about, for a verb the person did ask
+ * for. And there is no version of it that could succeed: the record is rows in a
+ * live database this app must never write to.
+ *
+ * So it is refused where the request arrives, the op comes back `ok:false`
+ * carrying this sentence onto the queue row, and NOTHING is spawned and nothing
+ * is written. `caps.fork` already keeps the button off the phone; this is the
+ * guard for every other caller, which is the same division of labour
+ * `launchArgs`'s `"pick"` refusal has.
+ */
+export function forkAtTurnRefusal(backendId) {
+    let backend;
+    // An unknown id is not this function's to refuse — `create()` throws on it a
+    // moment later with a sentence naming the known ids, and answering here would
+    // replace that sentence with a less useful one.
+    try {
+        backend = resolveBackend(backendId);
+    }
+    catch {
+        return null;
+    }
+    if (backend.forkVia === "server")
+        return null; // the backend forks it itself; `convfork.ts` never sees it
+    // claude's jsonl is cut by `convfork.ts` — and ONLY claude's: every other backend is refused
+    // here, before `routes/session.ts` reaches `forkConversationFile` with an id that is not a
+    // claude conversation — unless its own source cuts it (`conversations.fork`, `forkViaSource`).
+    const d = derive(backend);
+    if (d.keepsClaudeLog || d.sourceForks)
+        return null;
+    if (d.store("transcript") !== null)
+        return `${backend.label} keeps its conversation in a live database this host only ever reads, so a conversation cannot be cut at a turn and re-opened as a new one. Resume this conversation instead, or start a fresh session.`;
+    return `${backend.label} keeps no conversation file this host can copy, so a conversation cannot be cut at a turn and re-opened as a new one. Resume this conversation instead, or start a fresh session.`;
+}
+/**
+ * **A job never opens a shell** (R-shell-004). A backend with no turns
+ * (`caps.turns === false`, the shell) is opened only by a person's tap — the
+ * `session.create` op stamps `origin.kind: "hand"`. Every other opener (the
+ * intent tick, a parked create, the fan-out, the backlog, an agent's post) is
+ * refused HERE, in `SessionManager.create`, the one point all of them pass,
+ * before a spawn — so no new opener can forget it. A fork of a shell is
+ * `launchArgs`'s own refusal ("no conversation to continue").
+ */
+export function shellOpenRefusal(backend, origin) {
+    if (backend.caps.turns !== false)
+        return null;
+    if (origin?.kind === "hand" || origin?.kind === "fork")
+        return null;
+    return "a job never opens a shell — open one from the repo's menu";
+}
+/** Does this backend fork a conversation on its own server (`forkVia: "server"`)?
+ *  An unknown id answers false — `create()` refuses it in words a moment later. */
+export function backendForksOnServer(backendId) {
+    try {
+        return resolveBackend(backendId).forkVia === "server";
+    }
+    catch {
+        return false;
+    }
+}
+/** The descriptor when its own source cuts a conversation at a turn (`derive`'s `sourceForks`), else null. */
+export function backendForkingSource(backendId) {
+    try {
+        const b = resolveBackend(backendId);
+        return derive(b).sourceForks ? b : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The wire document for every backend this host can spawn — DERIVED from the
+ * descriptors, never hand-written.
+ *
+ * A second table of capabilities would be a second opinion about what a backend
+ * can do, and the one that was wrong would be the one the phone believes. The
+ * translation is `derive.ts`'s `wireCaps`: the host's provider lists (which reader, which
+ * channel) become the simpler question a client can act on (is there one at all).
+ */
+function measuredInfo(label, versions, running) {
+    const drift = measuredDriftText(label, versions, running);
+    return { versions: [...versions], ...(running ? { running } : {}), ...(drift ? { drift } : {}) };
+}
+export function backendInfos() {
+    return BACKENDS.map((b) => {
+        const m = MODEL_CACHE.get(b.id) ?? { aliases: [], ids: [] };
+        return {
+            id: b.id,
+            label: b.label,
+            // A backend with no turns is a SHELL to the phone — offered as "open a
+            // shell here", never in the model picker. Absent for every agent.
+            ...(b.caps.turns === false ? { kind: "shell" } : {}),
+            // Every boolean is DERIVED from the provider table (`derive.ts`), so a cap and a source
+            // can never disagree; the bytes are pinned (`backendinfos.pin.test.mjs`).
+            caps: derive(b).wireCaps(),
+            // `where` rides along only when the backend could actually determine it.
+            // Spread rather than `where: m.where` so an absent map stays ABSENT on
+            // the wire instead of becoming an explicit `undefined` key — the phone
+            // reads "no map" as "this host cannot say", which is a different claim
+            // from "no model is local".
+            models: { aliases: [...m.aliases], ids: [...m.ids], ...(m.where ? { where: { ...m.where } } : {}), ...(m.zeroCost?.length ? { zeroCost: [...m.zeroCost] } : {}),
+                // Per-model window and MEASURED first-request overhead: the picker's
+                // window sentence (`windowAdviceText`). Absent stays absent.
+                ...(m.contextWindow && Object.keys(m.contextWindow).length ? { contextWindow: { ...m.contextWindow } } : {}),
+                ...(m.overheadTok && Object.keys(m.overheadTok).length ? { overheadTok: { ...m.overheadTok } } : {}),
+                ...(m.note ? { note: m.note } : {}) },
+            ...(m.unavailable ? { unavailable: m.unavailable } : {}),
+            ...(b.experimental ? { experimental: true } : {}),
+            // The versions a plugin was measured on, the running one, and the drift sentence (R6).
+            // Absent for a backend that declares no `measured` — every core backend (the pin holds).
+            ...(b.measured ? { measured: measuredInfo(b.label, b.measured.versions, RUNNING_VERSION.get(b.id)) } : {}),
+            // `contextWindowTokens` is deliberately never set: no backend here has a
+            // window size that is a fixed fact about the BACKEND rather than about a
+            // model on somebody's disk, and absent is what that must read as.
+        };
+    });
+}
+//# sourceMappingURL=index.js.map

package/packages/host/dist/backends/index.js.map

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

package/packages/host/dist/backends/overhead.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The first assistant row of one conversation log's head: which model answered
+ * it and how many input tokens that first request carried (fresh + cache read
+ * + cache write — the whole prompt, however it was billed). Null when the head
+ * holds no such row or its usage is not a positive number. A torn last line is
+ * skipped, never guessed. Pure.
+ */
+export declare function firstRequestOf(head: string): {
+    model: string;
+    tok: number;
+} | null;
+/**
+ * For each wanted model id, the first-request input of the NEWEST conversation
+ * that ran it. Ids never found are left out. Never throws.
+ */
+export declare function measuredOverhead(wanted: readonly string[]): Promise<Record<string, number>>;

package/packages/host/dist/backends/overhead.js

@@ -0,0 +1,124 @@
+/**
+ * What Claude Code's own prompt costs a model's window, MEASURED — the input of
+ * the first request of the newest conversation that ran it, off the CLI's log.
+ *
+ * Feeds `BackendModels.overheadTok` for the claude-on-another-runner backends
+ * (`claude-local`, `claude-endpoint`), which `@waterplane/shared`'s
+ * `windowAdviceText` turns into the picker's sentence. Absent beats borrowed:
+ * a model no conversation was found for has NO entry, never a neighbour's.
+ *
+ * Cheap on purpose, because it runs with every catalogue read: the newest
+ * `MAX_DIRS` project directories by mtime (a new conversation file bumps its
+ * directory), their top-level `*.jsonl` newest first, at most `MAX_FILES` of
+ * them, and only the first `HEAD_BYTES` of each — the first assistant row is
+ * near the top. Subagent logs (`subagents/`) are never read: their first
+ * request is a different prompt. Any failure reads as "not found".
+ */
+import { open, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { claudeConfigDir } from "../claudeconfig.js";
+const MAX_DIRS = 40;
+const MAX_FILES = 300;
+const HEAD_BYTES = 256 * 1024;
+/**
+ * The first assistant row of one conversation log's head: which model answered
+ * it and how many input tokens that first request carried (fresh + cache read
+ * + cache write — the whole prompt, however it was billed). Null when the head
+ * holds no such row or its usage is not a positive number. A torn last line is
+ * skipped, never guessed. Pure.
+ */
+export function firstRequestOf(head) {
+    for (const line of head.split("\n")) {
+        if (!line.includes('"assistant"'))
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (row.type !== "assistant" || row.isSidechain === true)
+            continue;
+        const model = row.message?.model;
+        const u = row.message?.usage;
+        if (typeof model !== "string" || !model || !u)
+            return null;
+        const n = (k) => (typeof u[k] === "number" && Number.isFinite(u[k]) && u[k] > 0 ? u[k] : 0);
+        const tok = n("input_tokens") + n("cache_read_input_tokens") + n("cache_creation_input_tokens");
+        return tok > 0 ? { model, tok } : null;
+    }
+    return null;
+}
+async function head(path) {
+    const fh = await open(path, "r");
+    try {
+        const buf = Buffer.alloc(HEAD_BYTES);
+        const { bytesRead } = await fh.read(buf, 0, HEAD_BYTES, 0);
+        return buf.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * For each wanted model id, the first-request input of the NEWEST conversation
+ * that ran it. Ids never found are left out. Never throws.
+ */
+export async function measuredOverhead(wanted) {
+    const out = {};
+    const want = new Set(wanted);
+    if (!want.size)
+        return out;
+    try {
+        const root = join(claudeConfigDir(), "projects");
+        const dirs = await Promise.all((await readdir(root)).map(async (d) => {
+            try {
+                const s = await stat(join(root, d));
+                return s.isDirectory() ? { p: join(root, d), m: s.mtimeMs } : null;
+            }
+            catch {
+                return null;
+            }
+        }));
+        const newestDirs = dirs.filter((d) => !!d).sort((a, b) => b.m - a.m).slice(0, MAX_DIRS);
+        const files = [];
+        for (const d of newestDirs) {
+            let names;
+            try {
+                names = await readdir(d.p);
+            }
+            catch {
+                continue;
+            }
+            for (const n of names) {
+                if (!n.endsWith(".jsonl"))
+                    continue;
+                try {
+                    const s = await stat(join(d.p, n));
+                    if (s.isFile())
+                        files.push({ p: join(d.p, n), m: s.mtimeMs });
+                }
+                catch { /* gone */ }
+            }
+        }
+        files.sort((a, b) => b.m - a.m);
+        for (const f of files.slice(0, MAX_FILES)) {
+            let first = null;
+            try {
+                first = firstRequestOf(await head(f.p));
+            }
+            catch {
+                continue;
+            }
+            if (first && want.has(first.model) && !(first.model in out)) {
+                out[first.model] = first.tok;
+                if (Object.keys(out).length === want.size)
+                    break;
+            }
+        }
+    }
+    catch { /* no log directory: nothing measured */ }
+    return out;
+}
+//# sourceMappingURL=overhead.js.map

package/packages/host/dist/backends/overhead.js.map

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

package/packages/host/dist/backends/readers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The screen/log readers a descriptor's `facts` may point at, by NAME
+ * (`docs/analysis/backends-design.md` §1.2).
+ *
+ * A reader is measured against ONE binary's TUI or store and pinned by fixtures,
+ * so a descriptor never carries code for one: it NAMES one, and a name this host
+ * does not have is refused in words at registration (`registry.ts`) — a reader
+ * can therefore never be armed against a TUI it was not written for, and a
+ * misspelling in a plugin is a listed-broken plugin, not a silent `false`.
+ *
+ * Two kinds of name:
+ *  - CORE's, in the two tables below — claude's, dispatched where they always
+ *    were (`sessions/boxes.ts`, `sessions/ctxseries.ts`, `sessions/record.ts`),
+ *    each asking for the exact name it was written for;
+ *  - CONTRIBUTED ones, registered by a plugin through `api.screenReader` /
+ *    `api.storeReader` (`shared/plugin.ts`'s `PluginScreenReader` /
+ *    `PluginStoreReader`) BEFORE its backend names them. The core keeps the
+ *    shape every reader has (the gate, the miss budget, the re-reading walk, the
+ *    poll contract, "exactly one candidate or none") and asks the contributed
+ *    reader only the questions about its own binary. This is how the opencode
+ *    extension brings its readers without core knowing opencode exists.
+ * A contributed reader that leaves (its plugin switched off) answers nothing:
+ * every lookup is by name at CALL time, so a session still running on it reads
+ * as having no box and no record — absent, never stale.
+ */
+import type { BackendFacts, PluginScreenReader, PluginStoreReader } from "@waterplane/shared";
+export declare const PROMPT_READERS: {
+    /** `prompt.ts`: numbered rows, a cursor glyph, an "Enter to confirm" footer; answered by its digit. */
+    readonly "claude-numbered": "prompt.ts";
+};
+export declare const TRANSCRIPT_READERS: {
+    /** `~/.claude/projects/**\/*.jsonl`, read by `transcript.ts` and the ledgers. */
+    readonly "claude-jsonl": "claude's jsonl conversation log";
+};
+/** A core name, or one a plugin contributed (checked at registration, not by the compiler). */
+export type PromptReaderName = keyof typeof PROMPT_READERS | (string & {});
+export type TranscriptReaderName = keyof typeof TRANSCRIPT_READERS | (string & {});
+/** Register a contributed screen reader. Throws a sentence on a bad or taken name. */
+export declare function registerScreenReader(name: string, reader: PluginScreenReader): () => void;
+/** Register a contributed store reader. Throws a sentence on a bad or taken name. */
+export declare function registerStoreReader(name: string, reader: PluginStoreReader): () => void;
+/** What `screenReaderFor` & co. read: a descriptor's `facts` (`derive.ts` owns the provider rules). */
+type WithFacts = {
+    facts?: BackendFacts;
+};
+/** The CONTRIBUTED screen reader a descriptor's `facts.dialogs` names — null for core's, none, or a name that left. */
+export declare function screenReaderFor(b: WithFacts): PluginScreenReader | null;
+/** The CONTRIBUTED store reader a descriptor's `facts.transcript` names — null for `claude-jsonl`, none, or a name that left. */
+export declare function storeReaderFor(b: WithFacts): PluginStoreReader | null;
+/** Does `facts.transcript` name a CONTRIBUTED store reader (whether or not it is registered right now)? */
+export declare function namesStoreReader(b: WithFacts): boolean;
+/** The names plugins have contributed right now — `derive.ts`'s `factProblems` checks a descriptor against them. */
+export declare function contributedReaders(): {
+    screen: ReadonlySet<string>;
+    store: ReadonlySet<string>;
+};
+export {};

package/packages/host/dist/backends/readers.js

@@ -0,0 +1,74 @@
+import { PLUGIN_READER_NAME_RE } from "@waterplane/shared";
+export const PROMPT_READERS = {
+    /** `prompt.ts`: numbered rows, a cursor glyph, an "Enter to confirm" footer; answered by its digit. */
+    "claude-numbered": "prompt.ts",
+};
+export const TRANSCRIPT_READERS = {
+    /** `~/.claude/projects/**\/*.jsonl`, read by `transcript.ts` and the ledgers. */
+    "claude-jsonl": "claude's jsonl conversation log",
+};
+const SCREEN = new Map();
+const STORE = new Map();
+function register(kind, name, reader, core, map) {
+    if (typeof name !== "string" || !PLUGIN_READER_NAME_RE.test(name)) {
+        throw new Error(`a ${kind} reader name must be a short lowercase word (letters, digits, dashes); got ${JSON.stringify(name)}`);
+    }
+    if (Object.hasOwn(core, name) || map.has(name)) {
+        throw new Error(`a ${kind} reader called \`${name}\` already exists; this host has: ${names(core, map).join(", ")}`);
+    }
+    if (!reader || typeof reader !== "object")
+        throw new Error(`the ${kind} reader \`${name}\` is not an object`);
+    map.set(name, reader);
+    return () => { if (map.get(name) === reader)
+        map.delete(name); };
+}
+/** Register a contributed screen reader. Throws a sentence on a bad or taken name. */
+export function registerScreenReader(name, reader) {
+    for (const k of ["candidate", "read", "prompt", "stillUp", "navTo"]) {
+        if (typeof reader?.[k] !== "function")
+            throw new Error(`the screen reader \`${name}\` has no ${k}()`);
+    }
+    return register("screen", name, reader, PROMPT_READERS, SCREEN);
+}
+/** Register a contributed store reader. Throws a sentence on a bad or taken name. */
+export function registerStoreReader(name, reader) {
+    for (const k of ["updatedAt", "pollUnchanged", "transcript", "toolDetails", "contextSeries", "discover"]) {
+        if (typeof reader?.[k] !== "function")
+            throw new Error(`the store reader \`${name}\` has no ${k}()`);
+    }
+    return register("store", name, reader, TRANSCRIPT_READERS, STORE);
+}
+const firstNamed = (b, fact, key) => {
+    const list = b.facts?.[fact];
+    if (!Array.isArray(list))
+        return null;
+    for (const p of list) {
+        const n = p[key];
+        if (typeof n === "string")
+            return n;
+    }
+    return null;
+};
+/** The CONTRIBUTED screen reader a descriptor's `facts.dialogs` names — null for core's, none, or a name that left. */
+export function screenReaderFor(b) {
+    const n = firstNamed(b, "dialogs", "screen");
+    return n ? SCREEN.get(n) ?? null : null;
+}
+/** The CONTRIBUTED store reader a descriptor's `facts.transcript` names — null for `claude-jsonl`, none, or a name that left. */
+export function storeReaderFor(b) {
+    const n = firstNamed(b, "transcript", "store");
+    return n ? STORE.get(n) ?? null : null;
+}
+/** Does `facts.transcript` name a CONTRIBUTED store reader (whether or not it is registered right now)? */
+export function namesStoreReader(b) {
+    const n = firstNamed(b, "transcript", "store");
+    return n !== null && !Object.hasOwn(TRANSCRIPT_READERS, n);
+}
+/** The names plugins have contributed right now — `derive.ts`'s `factProblems` checks a descriptor against them. */
+export function contributedReaders() {
+    return { screen: new Set(SCREEN.keys()), store: new Set(STORE.keys()) };
+}
+function names(core, map) {
+    return [...Object.keys(core), ...map.keys()];
+}
+//# sourceMappingURL=readers.js.map

package/packages/host/dist/backends/readers.js.map

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