@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/harness/prompt.js

@@ -0,0 +1,121 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The extension a saved attachment gets, so the client reads it as what it is. */
+export function extensionOf(mediaType, filename) {
+    const own = filename?.match(/\.([a-z0-9]{1,5})$/i)?.[1];
+    if (own) {
+        return own.toLowerCase();
+    }
+    const sub = mediaType.split("/")[1] ?? "bin";
+    return { jpeg: "jpg", "svg+xml": "svg", plain: "txt", markdown: "md" }[sub] ?? sub;
+}
+/**
+ * The conversation as a client takes it: one system prompt and one prompt on stdin. A single
+ * user message goes as it is; a longer thread is written out with its speakers, and the client
+ * is asked to answer its last message. Attachments are saved to `dir` and named in the prompt.
+ */
+export function renderPrompt(messages, dir) {
+    const warnings = [];
+    const files = [];
+    const system = [];
+    const turns = [];
+    const saveFile = (input) => {
+        // A file's content comes tagged: { type: "data", data } | { type: "url", url } | { type: "text", text }.
+        const tagged = input.data;
+        const data = tagged && typeof tagged === "object" && typeof tagged.type === "string"
+            ? tagged.type === "url"
+                ? tagged.url
+                : tagged.type === "text"
+                    ? Buffer.from(tagged.text ?? "", "utf8")
+                    : tagged.data
+            : input.data;
+        const part = { ...input, data };
+        if (part.data instanceof URL) {
+            return `[Attachment at ${part.data.href} (${part.mediaType})]`;
+        }
+        if (typeof part.data !== "string" && !(part.data instanceof Uint8Array)) {
+            warnings.push({ type: "unsupported", feature: "file parts" });
+            return `[Attachment: ${part.filename ?? part.mediaType}]`;
+        }
+        if (!dir) {
+            warnings.push({ type: "unsupported", feature: "file parts" });
+            return `[Attachment: ${part.filename ?? part.mediaType}]`;
+        }
+        const path = join(dir, `${files.length + 1}.${extensionOf(part.mediaType, part.filename)}`);
+        const bytes = typeof part.data === "string" ? Buffer.from(part.data, "base64") : part.data;
+        writeFileSync(path, bytes);
+        files.push(path);
+        return `[Attached file — open it to read it: ${path}]`;
+    };
+    for (const m of messages) {
+        if (m.role === "system") {
+            system.push(m.content);
+            continue;
+        }
+        const text = m.content
+            .map((part) => {
+            switch (part.type) {
+                case "text":
+                    return part.text;
+                case "file":
+                    return saveFile(part);
+                case "reasoning":
+                    return "";
+                case "tool-call":
+                    return `[Called ${part.toolName} with ${JSON.stringify(part.input)}]`;
+                case "tool-result": {
+                    const out = part.output;
+                    const value = out.type === "text" || out.type === "error-text"
+                        ? String(out.value)
+                        : out.type === "json" || out.type === "error-json"
+                            ? JSON.stringify(out.value)
+                            : out.type === "execution-denied"
+                                ? `denied${out.reason ? `: ${out.reason}` : ""}`
+                                : JSON.stringify(out.value ?? out);
+                    return `[Result of ${part.toolName}: ${value}]`;
+                }
+                default:
+                    return "";
+            }
+        })
+            .filter(Boolean)
+            .join("\n");
+        turns.push({ role: m.role, text });
+    }
+    const prompt = turns.length === 1 && turns[0].role === "user"
+        ? turns[0].text
+        : turns
+            .map((t) => `${t.role === "user" ? "User" : t.role === "tool" ? "Tool" : "Assistant"}:\n${t.text}`)
+            .join("\n\n");
+    if (turns.length > 1) {
+        system.push("The prompt holds the conversation so far, each message headed by its speaker. Answer the last message as the assistant — the answer only, no speaker label.");
+    }
+    return { system: system.join("\n\n"), prompt, files, warnings };
+}
+/** What a client without a schema option is told so its answer parses. */
+export function jsonInstruction(schema) {
+    return [
+        "Answer with one JSON value only — no prose, no code fence — that matches this JSON Schema:",
+        JSON.stringify(schema ?? { type: "object" }),
+    ].join("\n");
+}
+/** A client's answer as JSON: the fences and prose some wrap around it are taken off. */
+export function parseJsonAnswer(text) {
+    const trimmed = text.trim();
+    const unfenced = trimmed
+        .replace(/^\s*```(?:json)?\s*/i, "")
+        .replace(/\s*```\s*$/, "")
+        .trim();
+    try {
+        return JSON.parse(unfenced);
+    }
+    catch {
+        // Prose around the value: take the outermost object or array.
+        const start = unfenced.search(/[{[]/);
+        const end = Math.max(unfenced.lastIndexOf("}"), unfenced.lastIndexOf("]"));
+        if (start >= 0 && end > start) {
+            return JSON.parse(unfenced.slice(start, end + 1));
+        }
+        throw new Error("The answer is not JSON.");
+    }
+}

package/apps/runtime/dist/harness/terminal.js

@@ -0,0 +1,194 @@
+import { accessSync, chmodSync, constants } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { note } from "@engenty-wizards/shared/run";
+import { nanoid } from "nanoid";
+import { ServiceError } from "../services/errors.js";
+const BUFFER = 200_000;
+/** A session nobody looks at is ended after this long. */
+const IDLE_MS = 20 * 60_000;
+/** An ended session is kept this long for a page to read its last lines. */
+const LINGER_MS = 5 * 60_000;
+const sessions = new Map();
+/** The prebuilt helper node-pty forks must be executable; an install that skips scripts leaves it without the bit. */
+function ensureHelper() {
+    try {
+        const entry = createRequire(import.meta.url).resolve("node-pty");
+        const helper = join(dirname(entry), "..", "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper");
+        try {
+            accessSync(helper, constants.X_OK);
+        }
+        catch {
+            chmodSync(helper, 0o755);
+        }
+    }
+    catch {
+        // Not on this platform, or not ours to change: spawning tells.
+    }
+}
+async function ptyModule() {
+    try {
+        ensureHelper();
+        const mod = (await import("node-pty"));
+        const spawn = mod.spawn ?? mod.default?.spawn;
+        if (!spawn) {
+            throw new Error("node-pty has no spawn");
+        }
+        return { spawn };
+    }
+    catch {
+        throw new ServiceError("refused", note("builtTerminalNotAvailable"));
+    }
+}
+function emit(session, event) {
+    for (const listener of session.listeners) {
+        listener(event);
+    }
+}
+function forget(session) {
+    if (session.poll) {
+        clearInterval(session.poll);
+    }
+    if (session.reaper) {
+        clearTimeout(session.reaper);
+    }
+    sessions.delete(session.id);
+}
+function rearm(session) {
+    if (session.reaper) {
+        clearTimeout(session.reaper);
+    }
+    session.reaper = setTimeout(() => {
+        if (session.listeners.size) {
+            rearm(session);
+            return;
+        }
+        if (!session.exit) {
+            session.pty.kill();
+        }
+        forget(session);
+    }, session.exit ? LINGER_MS : IDLE_MS);
+    session.reaper.unref();
+}
+/** Starts a command in a new terminal; the id names it to the page. */
+export async function openTerminal(opts) {
+    const { spawn } = await ptyModule();
+    const id = nanoid(16);
+    let pty;
+    try {
+        pty = spawn(opts.bin, opts.args, {
+            name: "xterm-256color",
+            cols: opts.cols ?? 100,
+            rows: opts.rows ?? 28,
+            cwd: opts.cwd,
+            env: opts.env,
+        });
+    }
+    catch (err) {
+        throw new ServiceError("refused", note("commandNotStarted", { detail: err.message }));
+    }
+    const session = {
+        id,
+        pty,
+        buffer: "",
+        listeners: new Set(),
+        exit: null,
+        done: false,
+        poll: null,
+        reaper: null,
+    };
+    sessions.set(id, session);
+    pty.onData((data) => {
+        session.buffer = (session.buffer + data).slice(-BUFFER);
+        emit(session, { type: "data", data });
+    });
+    pty.onExit(({ exitCode }) => {
+        session.exit = { code: exitCode };
+        if (session.poll) {
+            clearInterval(session.poll);
+            session.poll = null;
+        }
+        emit(session, { type: "exit", code: exitCode });
+        rearm(session);
+    });
+    if (opts.until) {
+        const until = opts.until;
+        let asking = false;
+        session.poll = setInterval(() => {
+            if (asking || session.done) {
+                return;
+            }
+            asking = true;
+            void until()
+                .then((ok) => {
+                if (ok && !session.done) {
+                    session.done = true;
+                    emit(session, { type: "done" });
+                    opts.onDone?.();
+                    if (!session.exit) {
+                        // The command did its job; an app that stays open is ended for the person.
+                        setTimeout(() => {
+                            if (!session.exit) {
+                                session.pty.kill();
+                            }
+                        }, 1500).unref();
+                    }
+                }
+            })
+                .catch(() => undefined)
+                .finally(() => {
+                asking = false;
+            });
+        }, 3000);
+    }
+    rearm(session);
+    return id;
+}
+function sessionOf(id) {
+    const session = sessions.get(id);
+    if (!session) {
+        throw new ServiceError("not_found", note("terminalNoLongerExists"));
+    }
+    return session;
+}
+/** Follows a terminal: what it printed so far, then everything new, then its end. */
+export function subscribeTerminal(id, listener) {
+    const session = sessionOf(id);
+    if (session.buffer) {
+        listener({ type: "data", data: session.buffer });
+    }
+    if (session.done) {
+        listener({ type: "done" });
+    }
+    if (session.exit) {
+        listener({ type: "exit", code: session.exit.code });
+    }
+    session.listeners.add(listener);
+    rearm(session);
+    return () => {
+        session.listeners.delete(listener);
+        rearm(session);
+    };
+}
+export function writeTerminal(id, data) {
+    const session = sessionOf(id);
+    if (!session.exit) {
+        session.pty.write(data);
+    }
+}
+export function resizeTerminal(id, cols, rows) {
+    const session = sessionOf(id);
+    if (!session.exit && cols > 0 && rows > 0) {
+        session.pty.resize(Math.min(cols, 500), Math.min(rows, 200));
+    }
+}
+export function closeTerminal(id) {
+    const session = sessions.get(id);
+    if (!session) {
+        return;
+    }
+    if (!session.exit) {
+        session.pty.kill();
+    }
+    forget(session);
+}

package/apps/runtime/dist/harness/types.js

@@ -0,0 +1,7 @@
+/**
+ * A harness is an AI client installed on this machine — Claude Code, Codex, Antigravity, Cursor
+ * Agent — that answers on the person's own subscription or sign-in. The runtime runs it headless
+ * as a model (./model.ts) and signs it in through the inline terminal (./terminal.ts). Nothing of
+ * this process reaches it: no key of ours, no session of a parent client.
+ */
+export const HARNESS_IDS = ["claude", "codex", "antigravity", "cursor"];

package/apps/runtime/dist/index.js

@@ -0,0 +1,113 @@
+import { serve } from "@hono/node-server";
+import { localEntryUrl, purgeSessions } from "./auth/index.js";
+import { adoptLegacyData } from "./db/adopt.js";
+import { knownTenants, migrateAllTenants, migrateControlDb, openTenantDb, withTenant, } from "./db/client.js";
+import { startRunner, stopRunner } from "./engine/runner.js";
+import { basePath, env } from "./env.js";
+import { hookConsole } from "./log.js";
+import { managed } from "./manage.js";
+import { checkModelsAtStart, loadCatalog, loadLocalModels } from "./models.js";
+import { startJobs } from "./plugins/jobs.js";
+import { loadPlugins } from "./plugins/loader.js";
+import { loadEntitlement, startProChecks } from "./plugins/pro.js";
+import { closeBrowser } from "./render/chromium.js";
+import { clearRunning, writeRunning } from "./running.js";
+import { syncMarketplace } from "./services/marketplace.js";
+import { purgeExpiredRuns } from "./services/shares.js";
+import { purgeUnusedStores } from "./store/index.js";
+import { forgetRunner, registerRunner } from "./tenants/control.js";
+import { LOCAL_TENANT } from "./tenants/tenant.js";
+import { onRestart, RESTART_EXIT, startUpdateChecks } from "./update.js";
+// Before anything prints: the last lines stay in memory for a look from afar (debug.ts).
+hookConsole();
+await migrateControlDb();
+// What the linked account's plan confirmed last: the Pro modules it includes load with the rest.
+await loadEntitlement();
+// Before any tenant database opens: each gets the plugins' own tables as it does.
+await loadPlugins();
+startJobs();
+if (managed) {
+    // Every tenant database is brought to this release's schema; a new one migrates when first opened.
+    void migrateAllTenants().then(({ migrated, failed }) => {
+        console.log(`tenant databases: ${migrated} current${failed.length ? `, failed: ${failed}` : ""}`);
+    });
+}
+else {
+    await adoptLegacyData();
+    await openTenantDb(LOCAL_TENANT);
+    await loadLocalModels();
+    void loadCatalog();
+    void checkModelsAtStart().catch(() => undefined);
+    startProChecks();
+    // A newer release is downloaded beside this one and used from the next start.
+    startUpdateChecks();
+}
+// The marketplace's starters and the starred entries, kept for offline use; checked hourly.
+void syncMarketplace();
+setInterval(() => void syncMarketplace(), 3600_000).unref();
+const { default: app } = await import("./app.js");
+/** Behind a path (APP_URL ends in /w) the proxy may leave the prefix on; the routes know none. */
+function withoutBasePath(request) {
+    const url = new URL(request.url);
+    if (basePath && (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`))) {
+        url.pathname = url.pathname.slice(basePath.length) || "/";
+        return app.fetch(new Request(url, request));
+    }
+    return app.fetch(request);
+}
+const server = serve({ fetch: withoutBasePath, port: env.port, hostname: env.host }, (info) => {
+    console.log(`engenty wizards on :${info.port} — ${env.appUrl}`);
+    const entry = localEntryUrl();
+    if (entry && !env.local.accessKey && env.serves.studio) {
+        console.log(`Open the studio: ${entry}`);
+    }
+    if (!managed) {
+        writeRunning(env.dataDir, {
+            pid: process.pid,
+            port: info.port,
+            url: env.appUrl,
+            startedAt: new Date().toISOString(),
+            restarts: process.env.ENGENTY_WIZARDS_RESTARTS === "1",
+        });
+    }
+});
+// A runner takes the runs in line, those a stopped process left behind first (RUNTIME_ROLE).
+if (env.serves.runner) {
+    await registerRunner();
+    setInterval(() => void registerRunner().catch(() => undefined), 10_000).unref();
+    startRunner();
+}
+// End-user results are kept RESULT_TTL_DAYS; expired runs and their files go once an hour.
+// What a wizard keeps for a person goes once nobody used it for STORE_TTL_DAYS.
+async function purge() {
+    await purgeSessions();
+    for (const id of await knownTenants()) {
+        await withTenant(id, () => Promise.all([purgeExpiredRuns(), purgeUnusedStores()])).catch((err) => console.error(`[retention ${id}]`, err));
+    }
+}
+void purge().catch((err) => console.error("[retention]", err));
+setInterval(() => void purge().catch((err) => console.error("[retention]", err)), 3600_000).unref();
+// A runtime that runs alone sends again what did not arrive in its account's cloud.
+if (!managed) {
+    const { retryFailedSends } = await import("./services/cloud.js");
+    const retry = () => withTenant(LOCAL_TENANT, () => retryFailedSends("local")).catch((err) => console.error("[cloud] retry failed:", err));
+    setInterval(() => void retry(), 60_000).unref();
+}
+async function shutdown(code = 0) {
+    clearRunning(env.dataDir);
+    server.close();
+    if (env.serves.runner) {
+        // The runs go back in line for another runner; their steps start afresh there.
+        await stopRunner();
+        await forgetRunner().catch(() => undefined);
+    }
+    await closeBrowser();
+    process.exit(code);
+}
+process.on("SIGINT", () => shutdown());
+process.on("SIGTERM", () => shutdown());
+onRestart((code) => void shutdown(code));
+// `wizards restart`: the command that started it starts it again, where it ran.
+if (process.env.ENGENTY_WIZARDS_RESTARTS === "1" && process.platform !== "win32") {
+    process.on("SIGUSR2", () => shutdown(RESTART_EXIT));
+}

package/apps/runtime/dist/limits.js

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { and, count, eq, gte } from "drizzle-orm";
+import { canSpend } from "./credits/credits.js";
+import { db, schema } from "./db/client.js";
+import { env } from "./env.js";
+export function hashIp(ip) {
+    if (!ip) {
+        return null;
+    }
+    return createHash("sha256").update(`${env.authSecret}:${ip}`).digest("hex").slice(0, 32);
+}
+function startOfDay() {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    return d;
+}
+/**
+ * Why a shared wizard cannot start a run right now, or null when it can: a note, to answer in the
+ * wizard's language (`noteText(reason, wizardLang(def))`).
+ */
+export async function wizardUnavailable(w) {
+    if (!w.shareEnabled || w.publishedVersion === null) {
+        return { code: "wizardUnavailable" };
+    }
+    const [{ n }] = await db
+        .select({ n: count() })
+        .from(schema.run)
+        .where(and(eq(schema.run.wizardId, w.id), eq(schema.run.mode, "live"), gte(schema.run.createdAt, startOfDay())));
+    if (n >= w.dailyRunLimit) {
+        return { code: "wizardLimit" };
+    }
+    if (!(await canSpend())) {
+        return { code: "wizardUnavailable" };
+    }
+    return null;
+}
+export async function verifyTurnstile(token, ip) {
+    if (!env.turnstile.secret) {
+        return true;
+    }
+    if (!token) {
+        return false;
+    }
+    const body = new URLSearchParams({ secret: env.turnstile.secret, response: token });
+    if (ip) {
+        body.set("remoteip", ip);
+    }
+    try {
+        const res = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+            method: "POST",
+            body,
+            signal: AbortSignal.timeout(8000),
+        });
+        const data = (await res.json());
+        return Boolean(data.success);
+    }
+    catch {
+        return false;
+    }
+}
+/** Times per key, kept in this process; old ones drop out as the key is asked. */
+const seen = new Map();
+/** Counts one more try for `key`; false once `max` tries fell within the last `windowMs`. */
+export function allowed(key, max, windowMs) {
+    const now = Date.now();
+    const recent = (seen.get(key) ?? []).filter((t) => now - t < windowMs);
+    if (recent.length >= max) {
+        seen.set(key, recent);
+        return false;
+    }
+    recent.push(now);
+    seen.set(key, recent);
+    if (seen.size > 50_000) {
+        for (const [k, times] of seen) {
+            if (!times.some((t) => now - t < windowMs)) {
+                seen.delete(k);
+            }
+        }
+    }
+    return true;
+}

package/apps/runtime/dist/link-preview.js

@@ -0,0 +1,60 @@
+import { and, eq } from "drizzle-orm";
+import { db, schema } from "./db/client.js";
+import { env } from "./env.js";
+import { escapeHtml } from "./render/convert.js";
+import { sharedRun, shareView } from "./services/shares.js";
+function tags(p) {
+    const t = [
+        `<meta property="og:title" content="${escapeHtml(p.title)}">`,
+        `<meta property="og:description" content="${escapeHtml(p.description)}">`,
+        `<meta property="og:url" content="${escapeHtml(p.url)}">`,
+        `<meta property="og:type" content="website">`,
+        `<meta name="twitter:card" content="${p.image ? "summary_large_image" : "summary"}">`,
+        `<meta name="twitter:title" content="${escapeHtml(p.title)}">`,
+        `<meta name="twitter:description" content="${escapeHtml(p.description)}">`,
+    ];
+    if (p.image) {
+        t.push(`<meta property="og:image" content="${escapeHtml(p.image)}">`);
+        t.push(`<meta name="twitter:image" content="${escapeHtml(p.image)}">`);
+    }
+    return `<title>${escapeHtml(p.title)}</title>\n${t.join("\n")}`;
+}
+/**
+ * Open Graph tags for shared links, so X, LinkedIn, WhatsApp and Slack show a card: a shared
+ * result (`/s/<token>`) with its picture, a public wizard (`/w/<token>`, as a chat
+ * `/w/<token>/chat`) with its title.
+ */
+export async function linkPreview(path) {
+    const share = path.match(/^\/s\/([A-Za-z0-9_-]+)\/?$/);
+    if (share) {
+        const run = await sharedRun(share[1]);
+        if (!run) {
+            return null;
+        }
+        const view = await shareView(run);
+        return tags({
+            title: view.title === view.wizard.title ? view.title : `${view.title} · ${view.wizard.title}`,
+            description: view.message ?? view.wizard.description,
+            url: `${env.publicUrl}/s/${share[1]}`,
+            image: `${env.publicUrl}/api/shares/${share[1]}/image`,
+        });
+    }
+    const wizard = path.match(/^\/w\/([A-Za-z0-9_-]+)(\/chat)?\/?$/);
+    if (wizard) {
+        const w = await db.query.wizard.findFirst({ where: eq(schema.wizard.shareToken, wizard[1]) });
+        if (!w || w.publishedVersion === null || !w.shareEnabled) {
+            return null;
+        }
+        const v = await db.query.wizardVersion.findFirst({
+            where: and(eq(schema.wizardVersion.wizardId, w.id), eq(schema.wizardVersion.version, w.publishedVersion)),
+        });
+        return v
+            ? tags({
+                title: v.definition.title,
+                description: v.definition.description,
+                url: `${env.publicUrl}/w/${wizard[1]}${wizard[2] ?? ""}`,
+            })
+            : null;
+    }
+    return null;
+}

package/apps/runtime/dist/log.js

@@ -0,0 +1,106 @@
+import { format } from "node:util";
+const RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+const KEEP = Number(process.env.LOG_KEEP) || 3000;
+const LINE_MAX = 4000;
+/** When this process started. */
+export const startedAt = Date.now();
+const lines = [];
+let next = 1;
+/** What never leaves a process in a log line: keys, tokens, one-time links, passwords. */
+const SECRETS = [
+    [/(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, "$1[redacted]"],
+    [/\bwz_[A-Za-z0-9_-]{6,}/g, "wz_[redacted]"],
+    [/\b(sk|rk|pk)-[A-Za-z0-9_-]{8,}/g, "$1-[redacted]"],
+    [/\bAIza[0-9A-Za-z_-]{20,}/g, "AIza[redacted]"],
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, "[jwt]"],
+    [/([?&](?:k|t|rt|token|key|secret|code|password|api_?key)=)[^&\s"'<>]+/gi, "$1[redacted]"],
+    [
+        /((?:secret|password|passwd|token|api[_-]?key|authorization|refresh_token|access_token)["']?\s*[:=]\s*["']?)[^\s,"'}]{6,}/gi,
+        "$1[redacted]",
+    ],
+];
+export function redact(text) {
+    let out = text;
+    for (const [pattern, replacement] of SECRETS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+function push(level, args) {
+    const text = redact(format(...args)).slice(0, LINE_MAX);
+    lines.push({ id: next++, at: Date.now(), level, text });
+    if (lines.length > KEEP) {
+        lines.splice(0, lines.length - KEEP);
+    }
+}
+/** Keeps a line without printing it. */
+export function note(level, text) {
+    push(level, [text]);
+}
+export function tail(query = {}) {
+    const limit = Math.min(Math.max(1, query.limit ?? 200), 2000);
+    const rank = RANK[query.level ?? "debug"] ?? 0;
+    const needle = query.q?.trim().toLowerCase();
+    const out = [];
+    for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+        const line = lines[i];
+        if (query.since !== undefined && line.id <= query.since) {
+            break;
+        }
+        if (query.after !== undefined && line.at < query.after) {
+            break;
+        }
+        if (RANK[line.level] < rank) {
+            continue;
+        }
+        if (needle && !line.text.toLowerCase().includes(needle)) {
+            continue;
+        }
+        out.push(line);
+    }
+    return out.reverse();
+}
+/** How many lines the ring holds and the id of the newest. */
+export function logState() {
+    return { lines: lines.length, newest: next - 1, keeps: KEEP };
+}
+/** Reads a query string's values as a tail query. */
+export function tailQuery(get) {
+    const int = (key) => {
+        const v = Number(get(key));
+        return Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+    };
+    const level = get("level");
+    return {
+        since: int("since"),
+        after: int("after"),
+        limit: int("limit"),
+        level: level && level in RANK ? level : undefined,
+        q: get("q")?.slice(0, 200) || undefined,
+    };
+}
+let hooked = false;
+/** Hooks the console once: each method still prints, and keeps a copy here. */
+export function hookConsole() {
+    if (hooked) {
+        return;
+    }
+    hooked = true;
+    const methods = [
+        ["debug", "debug"],
+        ["log", "info"],
+        ["info", "info"],
+        ["warn", "warn"],
+        ["error", "error"],
+    ];
+    for (const [method, level] of methods) {
+        const original = console[method].bind(console);
+        console[method] = (...args) => {
+            push(level, args);
+            original(...args);
+        };
+    }
+    process.on("warning", (warning) => {
+        push("warn", [`${warning.name}: ${warning.message}`]);
+    });
+}