@turri-dev/cli 0.1.8-next.bcca62a → 0.1.8-next.bfcb24e

package/dist/regenerate/ledger-view.js

@@ -0,0 +1,345 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { describeUsage } from "./activity.js";
+import { formatElapsed } from "./jobs.js";
+import { LEDGER_DIR, ledgerRun, readLedger } from "./ledger.js";
+/** The projects whose ledgers a folder's pulses may be in: its own, and those of the projects in folders under it. */
+export function ledgerProjects(cwd, depth = 3) {
+    const found = [];
+    const visit = (dir, left) => {
+        if (existsSync(join(dir, ".turri", LEDGER_DIR)))
+            found.push(dir);
+        if (left === 0)
+            return;
+        let names;
+        try {
+            names = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.startsWith(".") || name === "node_modules" || name === "plain_modules" || name === "dist")
+                continue;
+            visit(join(dir, name), left - 1);
+        }
+    };
+    visit(resolve(cwd), depth);
+    return found;
+}
+/** A pulse's events, gathered: undefined when the ledger has none of it. `entries` are its run's, oldest first. */
+export function pulseView(id, entries) {
+    const own = entries.filter((entry) => entry.job !== undefined && entry.job.startsWith(id));
+    if (own.length === 0)
+        return undefined;
+    const fullId = own[0].job;
+    const view = {
+        id: fullId,
+        run: own[0].run,
+        stages: [],
+        retried: [],
+        rounds: new Map(),
+        scripts: [],
+        judge: new Map(),
+        reviews: [],
+        healers: [],
+        provider: { retries: 0, stalls: 0, errors: [] },
+        refused: new Map(),
+        stopped: [],
+        history: [],
+    };
+    const started = entries.find((entry) => entry.kind === "run.started" && entry.run === view.run);
+    if (started !== undefined)
+        view.runMode = `${started.mode}, ${started.ts.slice(0, 16).replace("T", " ")}`;
+    for (const entry of own) {
+        if (entry.job !== fullId)
+            continue;
+        switch (entry.kind) {
+            case "job.queued":
+                view.queued = { ...entry, ...(entry.module !== undefined ? { module: entry.module } : {}) };
+                break;
+            case "job.started":
+                view.started = entry;
+                break;
+            case "job.finished":
+                view.finished = entry;
+                view.usage = entry.usage;
+                break;
+            case "job.stage":
+                view.stages.push(entry.label);
+                break;
+            case "job.retried":
+                view.retried.push(entry);
+                break;
+            case "gate.round":
+                view.rounds.set(entry.gate, { round: Math.max(entry.round, view.rounds.get(entry.gate)?.round ?? 0), of: entry.of });
+                break;
+            case "script.run":
+                view.scripts.push(entry);
+                break;
+            case "judge.verdict":
+                view.judge.set(entry.culprit, (view.judge.get(entry.culprit) ?? 0) + 1);
+                break;
+            case "review.verdict":
+                view.reviews.push(entry);
+                break;
+            case "healer.ended":
+            case "healer.failed":
+                view.healers.push(entry);
+                break;
+            case "provider.retry":
+                view.provider.retries += 1;
+                break;
+            case "provider.stall":
+                view.provider.stalls += 1;
+                break;
+            case "provider.error":
+                view.provider.errors.push(entry.error);
+                break;
+            case "guard.refused":
+                view.refused.set(entry.rule, (view.refused.get(entry.rule) ?? 0) + 1);
+                break;
+            case "command.refused":
+                view.refused.set("command check", (view.refused.get("command check") ?? 0) + 1);
+                break;
+            case "turn.stopped":
+                view.stopped.push(entry.reason);
+                break;
+            case "history.committed":
+            case "history.failed":
+            case "history.reset":
+            case "history.rolledBack":
+                view.history.push(entry);
+                break;
+            case "environment.error":
+                view.environment = entry;
+                break;
+        }
+    }
+    return view;
+}
+/** What a pulse is called: its module, kind and number - as pulseName says it for a live one. */
+function nameOf(view) {
+    const queued = view.queued;
+    if (queued === undefined)
+        return view.id;
+    if (queued.module === undefined)
+        return queued.summary;
+    return queued.pulse !== undefined ? `${queued.module} · ${queued.jobKind} pulse ${queued.pulse}` : `${queued.module} ${queued.jobKind}`;
+}
+function outcomeOf(view) {
+    const finished = view.finished;
+    if (finished === undefined)
+        return view.started !== undefined ? "never ended - its run stopped while it ran" : "never started";
+    const landed = finished.landed === true ? ", landed" : finished.landed === false ? ", did not land" : "";
+    const stopped = finished.stoppedBy !== undefined ? ` by ${finished.stoppedBy === "turri" ? "turri" : "the person"}` : "";
+    return `${finished.status}${stopped}${landed}, after ${formatElapsed(finished.ms)}`;
+}
+/** A pulse from the ledger, for the chat and `turri ledger <pulse>`: what happened in it, as facts. */
+export function describePulseView(view) {
+    const lines = [`${view.id} · ${nameOf(view)}${view.queued?.title !== undefined ? ` - ${view.queued.title}` : ""}`];
+    lines.push(`  run ${view.run}${view.runMode !== undefined ? ` (${view.runMode})` : ""}`);
+    lines.push(`  ${outcomeOf(view)}${view.usage !== undefined && describeUsage(view.usage) !== "" ? ` · ${describeUsage(view.usage)}` : ""}${view.queued?.model !== undefined ? ` · ${view.queued.model}` : ""}`);
+    if (view.finished?.error !== undefined)
+        lines.push(`  ended with: ${view.finished.error}`);
+    if (view.environment !== undefined)
+        lines.push(`  the environment lacks ${view.environment.missing} (found by ${view.environment.source === "harness" ? "turri" : "an agent"})`);
+    for (const retry of view.retried)
+        lines.push(`  tried again (${retry.attempt} of ${retry.of}) after: ${retry.failure}`);
+    if (view.rounds.size > 0)
+        lines.push(`  rounds: ${[...view.rounds].map(([gate, { round, of }]) => `${gate} ${round} of ${of}`).join("; ")}`);
+    // can_it_fail's runs, on code changed to break it, apart: one failing is a test that caught the bug.
+    const mutations = view.scripts.filter((run) => run.mutated === true);
+    const tests = view.scripts.filter((run) => run.mutated !== true);
+    if (tests.length > 0) {
+        const failing = tests.filter((run) => run.exit !== 0);
+        const signatures = new Map();
+        for (const run of failing)
+            if (run.signature !== undefined)
+                signatures.set(run.signature, (signatures.get(run.signature) ?? 0) + 1);
+        const most = Math.max(0, ...signatures.values());
+        const timedOut = tests.filter((run) => run.timedOut).length;
+        lines.push(`  test runs: ${tests.length}, ${failing.length} failing` +
+            (most > 1 ? ` - ${most} of them the same way` : "") +
+            (timedOut > 0 ? `, ${timedOut} stopped at the time limit` : ""));
+    }
+    if (mutations.length > 0) {
+        const caught = mutations.filter((run) => run.exit !== 0 && !run.timedOut).length;
+        lines.push(`  can_it_fail: ${mutations.length} run${mutations.length === 1 ? "" : "s"} on code broken on purpose, ${caught} caught by the tests`);
+    }
+    if (view.judge.size > 0)
+        lines.push(`  the judge blamed: ${[...view.judge].map(([culprit, times]) => `${culprit} ${times}x`).join(", ")}`);
+    if (view.reviews.length > 0)
+        lines.push(`  reviews: ${view.reviews.map((review) => (review.pass ? "passed" : `${review.problems} problem${review.problems === 1 ? "" : "s"}`)).join(", ")}`);
+    // The same outcome again is counted, not said again: a debugger failing for want of a key fails every time.
+    const healed = new Map();
+    for (const healer of view.healers) {
+        const line = healer.kind === "healer.failed" ? `the ${healer.healer} FAILED: ${healer.error}` : `the ${healer.healer}${healer.found !== undefined ? `: ${healer.found}` : " found nothing"}`;
+        healed.set(line, (healed.get(line) ?? 0) + 1);
+    }
+    for (const [line, times] of healed)
+        lines.push(`  ${times > 1 ? line.replace(/^(the \S+( FAILED)?)/, `$1 ${times}x`) : line}`);
+    const provider = view.provider;
+    if (provider.retries + provider.stalls + provider.errors.length > 0) {
+        lines.push(`  the model provider: ${provider.retries} retries, ${provider.stalls} stalls${provider.errors.length > 0 ? `, ${provider.errors.length} errors - last: ${provider.errors.at(-1)}` : ""}`);
+    }
+    if (view.refused.size > 0)
+        lines.push(`  turri refused calls: ${[...view.refused].map(([rule, times]) => `${rule} ${times}x`).join(", ")}`);
+    if (view.stopped.length > 0)
+        lines.push(`  turri stopped ${view.stopped.length} turn${view.stopped.length === 1 ? "" : "s"} - last: ${view.stopped.at(-1)}`);
+    for (const event of view.history) {
+        if (event.kind === "history.committed")
+            lines.push(`  committed: ${event.subject}`);
+        else if (event.kind === "history.failed")
+            lines.push(`  a commit FAILED${event.landing ? " (landing work)" : ""}: ${event.said}`);
+        else if (event.kind === "history.reset")
+            lines.push(`  put back to the last commit: ${event.undone} change${event.undone === 1 ? "" : "s"} undone`);
+        else
+            lines.push(`  rolled back: ${event.why}`);
+    }
+    if (view.stages.length > 0)
+        lines.push("  last stages:", ...view.stages.slice(-8).map((stage) => `    ${stage}`));
+    const log = view.finished?.logFile ?? view.started?.logFile;
+    if (log !== undefined)
+        lines.push(`  log: ${log}`);
+    return lines.join("\n");
+}
+/** A pulse the ledger of any of these projects knows, described - or undefined. */
+export function describePastPulse(projects, id) {
+    for (const project of projects) {
+        const entries = readLedger(project);
+        const view = pulseView(id, entries);
+        if (view !== undefined)
+            return describePulseView(view);
+    }
+    return undefined;
+}
+export function runViews(project) {
+    const entries = readLedger(project);
+    const runs = new Map();
+    for (const entry of entries)
+        runs.set(entry.run, [...(runs.get(entry.run) ?? []), entry]);
+    return [...runs]
+        .map(([run, own]) => {
+        const ids = [...new Set(own.filter((entry) => entry.kind === "job.queued").map((entry) => entry.job))];
+        const started = own.find((entry) => entry.kind === "run.started");
+        const ended = own.find((entry) => entry.kind === "run.ended");
+        return { run, ...(started !== undefined ? { started } : {}), ...(ended !== undefined ? { ended } : {}), pulses: ids.map((id) => pulseView(id, own)).filter(Boolean) };
+    })
+        .reverse();
+}
+/** The project's last runs, a line a pulse: what `turri ledger` prints. */
+export function describeRuns(runs) {
+    if (runs.length === 0)
+        return "The ledger is empty: nothing has run here since it began.";
+    return runs
+        .map((view) => {
+        const started = view.started;
+        const when = started?.ts !== undefined ? started.ts.slice(0, 19).replace("T", " ") : "";
+        const version = started?.version !== undefined && started.version !== null ? ` · turri ${started.version}${started.commit !== null && started.commit !== undefined ? ` (${started.commit.slice(0, 7)}${started.dirty === true ? ", changed" : ""})` : ""}` : "";
+        const head = `run ${view.run} · ${started?.mode ?? "?"} · ${when}${view.ended !== undefined ? ` · ${formatElapsed(view.ended.ms)}` : " · still running, or killed"}${version}`;
+        const pulses = view.pulses.map((pulse) => `  ${pulse.id} ${nameOf(pulse).padEnd(32)} ${outcomeOf(pulse)}${pulse.usage !== undefined && describeUsage(pulse.usage) !== "" ? ` · ${describeUsage(pulse.usage)}` : ""}`);
+        return [head, ...(pulses.length > 0 ? pulses : ["  no pulses"])].join("\n");
+    })
+        .join("\n\n");
+}
+/**
+ * The pulses of earlier sessions, for a list beside this session's: the last `runs` runs of these projects that are not
+ * this one, the most recent first, each pulse as a job of its own marked `earlier` - none `known` to this session's
+ * registry. `more`: how many runs the ledger has beyond them.
+ */
+export function earlierPulses(projects, known, runs = 3) {
+    const own = ledgerRun();
+    const all = projects
+        .flatMap((project) => runViews(project))
+        .filter((view) => view.run !== own && view.pulses.some((pulse) => !known.has(pulse.id)))
+        .sort((a, b) => (b.started?.ts ?? "").localeCompare(a.started?.ts ?? ""));
+    const shown = all.slice(0, runs);
+    return { jobs: shown.flatMap((view) => view.pulses.filter((pulse) => !known.has(pulse.id)).map(asJob)), runs: shown, more: all.length - shown.length };
+}
+/** A pulse of the ledger's, as the lists show a job: finished as it ended, its time and cost - and nothing to run. */
+export function asJob(view) {
+    const at = (entry) => (entry?.ts !== undefined ? Date.parse(entry.ts) : undefined);
+    const queuedAt = at(view.queued) ?? 0;
+    const startedAt = at(view.started) ?? queuedAt;
+    const finished = view.finished;
+    // A pulse whose run ended before it did never finished: it was stopped with its run.
+    const status = finished !== undefined && ["succeeded", "failed", "stopped"].includes(finished.status) ? finished.status : "stopped";
+    const logFile = finished?.logFile ?? view.started?.logFile;
+    return {
+        id: view.id,
+        kind: view.queued?.jobKind ?? "regenerate",
+        summary: view.queued?.summary ?? view.id,
+        ...(view.queued?.module !== undefined ? { module: view.queued.module } : {}),
+        ...(view.queued?.pulse !== undefined ? { pulse: view.queued.pulse } : {}),
+        ...(view.queued?.title !== undefined ? { title: view.queued.title } : {}),
+        ...(view.queued?.model !== undefined ? { model: view.queued.model } : {}),
+        status,
+        sequence: 0,
+        queuedAt,
+        startedAt,
+        finishedAt: finished !== undefined ? startedAt + finished.ms : startedAt,
+        waitingOn: [],
+        tail: "",
+        activity: [],
+        usage: view.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 },
+        agents: [],
+        transcript: [],
+        ...(logFile !== undefined ? { logFile } : {}),
+        ...(finished?.error !== undefined ? { error: finished.error } : {}),
+        details: { ...(finished?.landed !== undefined ? { landed: finished.landed } : {}), ...(finished?.passed !== undefined ? { passed: finished.passed } : {}) },
+        earlier: { run: view.run, ...(view.runMode !== undefined ? { runMode: view.runMode } : {}), lines: describePulseView(view).split("\n").slice(1).map((line) => line.replace(/^  /, "")) },
+    };
+}
+/** The envelope's fields, said apart from an event's own. */
+const ENVELOPE = new Set(["v", "ts", "seq", "run", "job", "module", "agent", "kind"]);
+/** One event in a line: when, its pulse and module, its kind, its own fields - the agent's role when it has one. */
+export function eventLine(entry) {
+    const fields = Object.entries(entry)
+        .filter(([key]) => !ENVELOPE.has(key))
+        .map(([key, value]) => {
+        const text = typeof value === "string" ? JSON.stringify(value.length > 160 ? `${value.slice(0, 159)}…` : value) : JSON.stringify(value);
+        return `${key}=${text}`;
+    });
+    const where = [entry.job, entry.module, entry.agent?.role ?? entry.agent?.label].filter((part) => part !== undefined);
+    return [entry.ts.slice(0, 19).replace("T", " "), ...where, entry.kind, ...fields].join(" · ");
+}
+/**
+ * The events of these projects' ledgers that `query` asks for: how many of each kind, and the most recent, a line each -
+ * or, when no kind asked for is in the ledger, the kinds it has.
+ */
+export function describeEvents(projects, query = {}) {
+    const all = projects.flatMap((project) => readLedger(project, query.since !== undefined ? { since: query.since } : {}));
+    const inModule = query.module !== undefined ? all.filter((entry) => entry.module === query.module) : all;
+    const wanted = query.kinds?.map((kind) => kind.trim()).filter((kind) => kind !== "");
+    const matches = (kind) => wanted === undefined || wanted.length === 0 || wanted.some((asked) => kind === asked || kind.startsWith(`${asked}.`));
+    const found = inModule.filter((entry) => matches(entry.kind));
+    const scope = [query.module !== undefined ? `in ${query.module}` : "", query.since !== undefined ? `since ${query.since.toISOString().slice(0, 16).replace("T", " ")}` : ""].filter(Boolean).join(", ");
+    if (found.length === 0) {
+        const kinds = [...new Set(inModule.map((entry) => entry.kind))].sort();
+        return `No ${wanted !== undefined && wanted.length > 0 ? wanted.join(", ") : ""} events${scope !== "" ? ` ${scope}` : ""} in the ledger.${kinds.length > 0 ? ` It has: ${kinds.join(", ")}.` : ""}`;
+    }
+    const counts = new Map();
+    for (const entry of found)
+        counts.set(entry.kind, (counts.get(entry.kind) ?? 0) + 1);
+    const pulses = new Set(found.map((entry) => entry.job).filter((job) => job !== undefined)).size;
+    const runs = new Set(found.map((entry) => entry.run)).size;
+    const limit = Math.max(1, query.limit ?? 20);
+    const recent = found.slice(-limit);
+    return [
+        `${found.length} event${found.length === 1 ? "" : "s"}${scope !== "" ? ` ${scope}` : ""}, in ${runs} run${runs === 1 ? "" : "s"} and ${pulses} pulse${pulses === 1 ? "" : "s"}: ${[...counts].sort((a, b) => b[1] - a[1]).map(([kind, times]) => `${kind} ${times}`).join(", ")}`,
+        "",
+        recent.length === found.length ? "Each, oldest first:" : `The last ${recent.length}, oldest first:`,
+        ...recent.map(eventLine),
+    ].join("\n");
+}
+/** `24h`, `7d`, `30m`, or a date and time: the moment it means, or undefined when it means none. */
+export function sinceOf(text, now = Date.now()) {
+    const relative = /^(\d+)\s*([mhd])$/i.exec(text.trim());
+    if (relative !== null) {
+        const unit = { m: 60_000, h: 3_600_000, d: 86_400_000 }[relative[2].toLowerCase()];
+        return new Date(now - Number(relative[1]) * unit);
+    }
+    const date = new Date(text.trim());
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}

package/dist/regenerate/ledger.d.ts

@@ -0,0 +1,275 @@
+import { type UsageReport } from "./activity.ts";
+/**
+ * The ledger: what turri does, as typed facts, one JSON line each, written as it happens - to
+ * `.turri/ledger/` in the project, one file a run (a conversation, a headless run, a host's session).
+ *
+ * The job and debug logs keep the bodies - every prompt, reply and tool result, whole - for reading one
+ * pulse closely. The ledger keeps the facts about them, across pulses, sessions and runs: that a pulse
+ * was queued, started, went through its stages and ended, and how; what each agent's model calls and
+ * turns cost; each tool call and test run, how long it took and how it ended; the gates' rounds and
+ * verdicts; what turri refused or stopped; what its healers did; the history's commits. What a pulse
+ * from an earlier session did is looked up here (`pulses`, `diagnose`, `turri ledger`). Never stored:
+ * prompts, replies, thinking, tool arguments and results, file contents - and what strings an event
+ * carries are masked as the logs are.
+ *
+ * A host hears each event as it is recorded (`onLedgerEvent`), with the project it is about, rather than reading the
+ * file again - written or not, so a project that keeps no ledger is heard all the same.
+ *
+ * Observation, never control: turri may react to events as they happen, but never reads the ledger on
+ * disk to decide what to build - the code and tests records are that (records.ts). Deleting
+ * `.turri/ledger/` loses only what can be looked up. A ledger that cannot be written stops, and never
+ * fails the work.
+ *
+ * Closed runs are gzipped, and the oldest pruned past `ledger-keep:` megabytes (100 unset; 0 keeps none),
+ * when a run first writes to the project. `.turri` ignores itself, so none of it is ever committed.
+ */
+export declare const LEDGER_DIR = "ledger";
+/** Megabytes of ledger a project keeps when `ledger-keep:` does not say. */
+export declare const DEFAULT_LEDGER_KEEP_MB = 100;
+/** Who did it: the agent an event is about. */
+export interface AgentRef {
+    role?: string;
+    label?: string;
+    model?: string;
+}
+/** Every event's own fields, by kind. */
+export type LedgerEvent = {
+    kind: "run.started";
+    mode: string;
+    version: string | null;
+    commit: string | null;
+    dirty: boolean | null;
+    pid: number;
+    platform: string;
+    node: string;
+} | {
+    kind: "run.ended";
+    ms: number;
+} | {
+    kind: "job.queued";
+    jobKind: string;
+    summary: string;
+    pulse?: number;
+    title?: string;
+    model?: string;
+    stack?: string;
+    waitingOn: string[];
+    follows?: string;
+} | {
+    kind: "job.started";
+    waitedMs: number;
+    logFile?: string;
+} | {
+    kind: "job.stage";
+    label: string;
+} | {
+    kind: "job.retried";
+    attempt: number;
+    of: number;
+    failure: string;
+} | {
+    kind: "job.finished";
+    status: string;
+    landed?: boolean;
+    passed?: boolean;
+    ms: number;
+    usage: UsageReport;
+    failedForGood?: boolean;
+    /** Who stopped it, for one stopped: the person, or turri itself, and why. */
+    stoppedBy?: "person" | "turri";
+    error?: string;
+    logFile?: string;
+} | {
+    kind: "loop.halted";
+    why: string;
+    track: "code" | "conformance";
+} | {
+    kind: "loop.stopped";
+    why: string;
+} | {
+    kind: "planner.failed";
+    step: "group" | "place";
+    error: string;
+} | {
+    kind: "planner.fellBack";
+    step: "group" | "place";
+    why: string;
+} | {
+    kind: "model.call";
+    ms?: number;
+    usage?: UsageReport;
+} | {
+    kind: "model.turn";
+} | {
+    kind: "model.compaction";
+} | {
+    kind: "provider.retry";
+    error: string;
+    attempt: number;
+    of: number;
+    waitMs: number;
+} | {
+    kind: "provider.stall";
+    waitMs: number;
+} | {
+    kind: "provider.error";
+    error: string;
+    transient: boolean;
+} | {
+    kind: "turn.stopped";
+    reason: string;
+} | {
+    kind: "tool.call";
+    tool: string;
+    ms: number;
+    ok: boolean;
+    resultChars: number;
+} | {
+    kind: "script.run";
+    script: string;
+    exit: number;
+    ms: number;
+    timedOut: boolean;
+    inPlace: boolean;
+    mutated?: boolean;
+    signature?: string;
+} | {
+    kind: "gate.round";
+    gate: "unit tests" | "conformance" | "regression";
+    round: number;
+    of: number;
+    signature?: string;
+} | {
+    kind: "review.verdict";
+    reviewer: "unit";
+    review: number;
+    pass: boolean;
+    problems: number;
+} | {
+    kind: "arbiter.ruling";
+    upheld: number;
+    dismissed: number;
+} | {
+    kind: "judge.verdict";
+    culprit: string;
+    round: number;
+    reason: string;
+} | {
+    kind: "guard.refused";
+    rule: "repeat" | "budget" | "restricted";
+    tool: string;
+    times: number;
+} | {
+    kind: "command.refused";
+    rule: string;
+} | {
+    kind: "audit.putBack";
+    putBack: number;
+    left: number;
+    lost: number;
+    conversation: number;
+} | {
+    kind: "healer.started";
+    healer: string;
+} | {
+    kind: "healer.ended";
+    healer: string;
+    ms: number;
+    found?: string;
+} | {
+    kind: "healer.failed";
+    healer: string;
+    ms: number;
+    error: string;
+} | {
+    kind: "history.committed";
+    subject: string;
+    commit?: string;
+} | {
+    kind: "history.failed";
+    subject: string;
+    said: string;
+    landing: boolean;
+} | {
+    kind: "history.reset";
+    undone: number;
+    paths: string[];
+} | {
+    kind: "history.rolledBack";
+    why: string;
+} | {
+    kind: "environment.error";
+    missing: string;
+    source: string;
+    sandbox: boolean;
+};
+export type LedgerKind = LedgerEvent["kind"];
+/** One line of the ledger: the event, and where and when it happened. */
+export type LedgerEntry = LedgerEvent & {
+    v: 1;
+    ts: string;
+    seq: number;
+    run: string;
+    job?: string;
+    module?: string;
+    agent?: AgentRef;
+};
+/** Where an event happened, when not where the code recording it runs: a job's own place is found by itself. */
+export interface LedgerPlace {
+    project?: string;
+    job?: string;
+    module?: string;
+    agent?: AgentRef;
+}
+/**
+ * Hear every event from now on, as it is recorded, with the project it is about - while the ledger is on. Returns
+ * what stops it. A listener that throws is left out of that event, never the work.
+ */
+export declare function onLedgerEvent(listener: (entry: LedgerEntry, project: string) => void): () => void;
+/** Whether turri turns the ledger on as it starts: always, unless TURRI_LEDGER=off. */
+export declare function ledgerWanted(): boolean;
+/** This run's id, while the ledger is on. */
+export declare function ledgerRun(): string | undefined;
+/**
+ * Start the ledger for this process: from now on, what is recorded is written. `project` is the one events about no
+ * project of their own go to. `warn` is told, once a project, when its ledger cannot be written. Returns what stops it.
+ */
+export declare function startLedger(options: {
+    mode: string;
+    project?: string;
+    warn?: (message: string) => void;
+}): () => void;
+/** Stop the ledger: each project this run wrote to is told it ended. */
+export declare function stopLedger(): void;
+/** Record an event: where it happened is the job this code runs for, unless `place` says. Nothing while the ledger is off. */
+export declare function record(event: LedgerEvent, place?: LedgerPlace): void;
+/**
+ * Run a healer - the debugger, the diagnosis of a failed pulse - and record it: started, ended with what it found, or
+ * failed and why. A healer that fails gives undefined, as it did before it was recorded, but is no longer silent.
+ */
+export declare function healing<T>(healer: string, work: () => Promise<T>, found?: (result: T) => string | undefined): Promise<T | undefined>;
+/** A failure's fingerprint, short: two runs failing the same way have the same one. */
+export declare function signatureHash(signature: string): string;
+/** The first line of a text, at most `max` characters: what an event keeps of an error or a reason. */
+export declare function firstLine(text: string, max?: number): string;
+/** The project's ledger folder. */
+export declare function ledgerDir(project: string): string;
+/**
+ * Keep the ledger folder within `keepBytes`: the files of runs that have ended gzipped, then the oldest pruned until
+ * the rest fit. A run still going - this one, or another turri's in the same project - is never touched.
+ */
+export declare function tidy(dir: string, keepBytes: number): void;
+/** What to read of the ledger. */
+export interface LedgerQuery {
+    /** A pulse, by its id or the start of it. */
+    job?: string;
+    run?: string;
+    kinds?: LedgerKind[];
+    /** Only events at or after this time. */
+    since?: Date;
+}
+/**
+ * The project's ledger, oldest first - every run's, the gzipped ones too, as `query` narrows it. A line that does not
+ * parse, or a kind this turri does not know, is skipped: the ledger is read as it is, whatever wrote it.
+ */
+export declare function readLedger(project: string, query?: LedgerQuery): LedgerEntry[];