@getbourdon/participants 0.2.3 → 0.2.4

package/dist/readers/openclaw.js

@@ -0,0 +1,386 @@
+/**
+ * OpenClaw participant — network-shaped, QUARANTINED-CLASS. Port of
+ * `participants/openclaw.py` (v0.9.0, spec R4/D9).
+ *
+ * OpenClaw is the highest-demand adapter target in the ecosystem and also its
+ * highest-risk agent class: CVE-2026-25253 (one-click RCE, CVSS 8.8, first
+ * patched in 2026.1.29), tens of thousands of internet-exposed instances (~93%
+ * without authentication), ClawHub's malicious-skill problem, and auth disabled
+ * by default on port 8080. Bourdon therefore treats OpenClaw differently from
+ * every on-disk participant:
+ *
+ *   1. **Network-shaped** — state is read from the OpenClaw instance's local
+ *      HTTP API, not on-disk artifacts. Because the {@link BourdonParticipant}
+ *      contract is SYNCHRONOUS (`discover`/`exportL5` return values, not
+ *      Promises) and `fetch` is async, the reads go through a tiny synchronous
+ *      `curl` shell-out (the same idiom as the github-copilot reader).
+ *   2. **Hard handshake gate** — {@link OpenClawParticipant.discover} refuses to
+ *      talk to an instance that is unpatched (< 2026.1.29) or has authentication
+ *      disabled. These are refusals with exact reasons AND fixes, not warnings,
+ *      and every read re-runs the gate.
+ *   3. **Quarantined-class** — `quarantinedClass = true`: registering the agent
+ *      trusted requires `--i-understand-the-risk`, and exports stage for
+ *      operator review (spec D6: quarantine follows the content, not the
+ *      invoker). Its content federates under TEAM, never PUBLIC.
+ *
+ * We gate on instance hygiene (version, auth) — NOT on auditing the user's
+ * installed skills; that's ClawSecure et al.'s job (spec non-goal 3).
+ */
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
+import { redactText } from "@getbourdon/redaction";
+import { ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
+// -- Constants -----------------------------------------------------------------
+const AGENT_ID = "openclaw";
+const AGENT_TYPE = "other";
+const DISPLAY_NAME = "OpenClaw (quarantined)";
+const ROLE_NARRATIVE = "OpenClaw personal AI assistant — federated as a QUARANTINED member: " +
+    "its reads are limited to granted namespaces and its writes are staged " +
+    "for operator review.";
+/** First OpenClaw release that patches CVE-2026-25253 (one-click RCE). */
+export const MIN_PATCHED_VERSION = "2026.1.29";
+const DEFAULT_OPENCLAW_URL = "http://127.0.0.1:8080";
+const SESSION_LIMIT = 50;
+const ENTITY_LIMIT = 100;
+// -- Helpers -------------------------------------------------------------------
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * `_safe_native_memory_text(v)` in Python == `redact_text(v, limit=180)`. The
+ * TS redaction SSOT exposes `redactText(value, limit = 180)` (positional), so
+ * we pass the cap explicitly to make the surface's 180-char limit load-bearing.
+ */
+function safeNativeMemoryText(value) {
+    return redactText(value, 180);
+}
+/**
+ * `"2026.1.29"` -> `[2026, 1, 29]`. Tolerates suffixes like `"2026.1.29-beta"`;
+ * returns null when nothing numeric parses. Faithful port of `_parse_version`.
+ */
+function parseVersion(value) {
+    const parts = [];
+    for (const chunk of String(value ?? "").trim().split(".")) {
+        const match = /^(\d+)/.exec(chunk);
+        if (!match)
+            break;
+        parts.push(Number(match[1]));
+    }
+    return parts.length > 0 ? parts : null;
+}
+/** Tuple comparison mirroring Python's `tuple < tuple` (lexicographic, shorter
+ * is smaller when it is a prefix). */
+function versionLessThan(a, b) {
+    const n = Math.max(a.length, b.length);
+    for (let i = 0; i < n; i += 1) {
+        const av = i < a.length ? a[i] : undefined;
+        const bv = i < b.length ? b[i] : undefined;
+        if (av === undefined)
+            return true; // a is a shorter prefix of b
+        if (bv === undefined)
+            return false; // b is a shorter prefix of a
+        if (av < bv)
+            return true;
+        if (av > bv)
+            return false;
+    }
+    return false;
+}
+/** `_status_version`: first non-empty of version / openclaw_version / app_version. */
+function statusVersion(status) {
+    for (const key of ["version", "openclaw_version", "app_version"]) {
+        const value = status[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return "";
+}
+/** `_status_auth_enabled`: auth_enabled / authEnabled / auth.enabled. */
+function statusAuthEnabled(status) {
+    for (const key of ["auth_enabled", "authEnabled"]) {
+        if (key in status)
+            return Boolean(status[key]);
+    }
+    const auth = status["auth"];
+    if (isRecord(auth))
+        return Boolean(auth["enabled"]);
+    return false;
+}
+/**
+ * Hard handshake preconditions (spec D9). Returns the version on success.
+ * Raises {@link ParticipantDiscoveryError} with the exact reason AND the fix —
+ * these are refusals, not warnings.
+ */
+export function verifyInstance(status, url) {
+    const version = statusVersion(status);
+    const parsed = parseVersion(version);
+    const minimum = parseVersion(MIN_PATCHED_VERSION);
+    if (parsed === null) {
+        throw new ParticipantDiscoveryError(`OpenClaw at ${url} did not report a parseable version ` +
+            `(got ${JSON.stringify(version)}). Refusing handshake: cannot verify the ` +
+            `CVE-2026-25253 patch level. Fix: upgrade OpenClaw to ` +
+            `>= ${MIN_PATCHED_VERSION} and ensure /api/status reports it.`);
+    }
+    if (versionLessThan(parsed, minimum)) {
+        throw new ParticipantDiscoveryError(`OpenClaw at ${url} runs ${version}, which predates the ` +
+            `CVE-2026-25253 patch (one-click RCE, CVSS 8.8). Refusing ` +
+            `handshake. Fix: upgrade OpenClaw to >= ${MIN_PATCHED_VERSION}.`);
+    }
+    if (!statusAuthEnabled(status)) {
+        throw new ParticipantDiscoveryError(`OpenClaw at ${url} has authentication DISABLED (the exposed-` +
+            "instance default). Refusing handshake. Fix: enable auth in " +
+            "your OpenClaw config (set auth.enabled=true / OPENCLAW_AUTH=1), " +
+            "restart the instance, and set OPENCLAW_TOKEN for Bourdon.");
+    }
+    return version;
+}
+/**
+ * Mirror `_before`: return true when `dateText` is strictly before `since`.
+ * Reproduces `datetime.fromisoformat(dateText.replace("Z","+00:00"))` with the
+ * naive→UTC coercion, and returns false on a parse (ValueError) miss so the
+ * caller keeps the session.
+ */
+function before(dateText, since) {
+    const parsed = fromIsoformatUtc(dateText.replace(/Z/g, "+00:00"));
+    if (parsed === null)
+        return false; // ValueError -> keep
+    return parsed.getTime() < since.getTime();
+}
+/**
+ * A best-effort `datetime.fromisoformat` for the two shapes OpenClaw emits
+ * (date-only and datetime, with or without an offset). A naive value (no
+ * offset) is interpreted as UTC — matching the Python `parsed.replace(
+ * tzinfo=timezone.utc)`. Returns null on an unparseable value.
+ */
+function fromIsoformatUtc(text) {
+    const value = text.trim();
+    if (!value)
+        return null;
+    const hasOffset = /[+-]\d{2}:?\d{2}$/.test(value);
+    // date-only ISO is already interpreted as UTC midnight by Date.parse;
+    // a naive datetime ("...T..") must be pinned to UTC with a trailing Z.
+    const normalized = hasOffset || !value.includes("T") ? value : `${value}Z`;
+    const ms = Date.parse(normalized);
+    return Number.isNaN(ms) ? null : new Date(ms);
+}
+/** Python `str(now_utc, "%Y-%m-%dT%H:%M:%SZ")` — second precision, Z suffix. */
+function nowIsoSeconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Synchronous GET via a tiny `curl` shell-out — the base contract is
+ * synchronous (matching the Python `urllib` reference), so `fetch` cannot be
+ * used. `-w` appends the HTTP status on a trailing sentinel line for parsing.
+ * Throws when curl itself fails (connection refused / timeout / DNS), which the
+ * caller maps to "instance unreachable".
+ */
+function curlGet(url, token, timeoutSec) {
+    const args = ["-sS", "-o", "-", "--max-time", String(timeoutSec)];
+    if (token) {
+        args.push("-H", `Authorization: Bearer ${token}`);
+    }
+    args.push("-w", "\n__BOURDON_STATUS__%{http_code}", url);
+    const raw = execFileSync("curl", args, {
+        encoding: "utf8",
+        timeout: (timeoutSec + 2) * 1000,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    const statusMatch = /\n__BOURDON_STATUS__(\d+)$/.exec(raw);
+    const status = statusMatch ? Number(statusMatch[1]) : 0;
+    const body = statusMatch ? raw.slice(0, statusMatch.index) : raw;
+    return { status, body };
+}
+/**
+ * Minimal HTTP client for a local OpenClaw instance. Read-only: status,
+ * sessions, memories. Failures raise {@link ParticipantDiscoveryError} with the
+ * reason — the participant decides how to surface them.
+ *
+ * Error mapping (faithful to the Python `urllib` client): an HTTP >= 400
+ * response -> "returned HTTP {code}"; a transport failure / timeout / non-JSON
+ * body -> "instance unreachable at {url}".
+ */
+export class OpenClawApiClient {
+    url;
+    token;
+    timeout;
+    constructor(url, token, timeout = 5.0) {
+        this.url = url.replace(/\/+$/, "");
+        this.token = token;
+        this.timeout = timeout;
+    }
+    get(path) {
+        let resp;
+        try {
+            resp = curlGet(this.url + path, this.token, this.timeout);
+        }
+        catch (err) {
+            throw new ParticipantDiscoveryError(`OpenClaw instance unreachable at ${this.url} (${String(err)})`);
+        }
+        if (resp.status >= 400) {
+            throw new ParticipantDiscoveryError(`OpenClaw API ${path} returned HTTP ${resp.status}`);
+        }
+        if (resp.status === 0) {
+            throw new ParticipantDiscoveryError(`OpenClaw instance unreachable at ${this.url} (no HTTP response)`);
+        }
+        try {
+            return JSON.parse(resp.body);
+        }
+        catch (err) {
+            throw new ParticipantDiscoveryError(`OpenClaw instance unreachable at ${this.url} (${String(err)})`);
+        }
+    }
+    status() {
+        const data = this.get("/api/status");
+        return isRecord(data) ? data : {};
+    }
+    sessions() {
+        return this.readCollection("/api/sessions", "sessions");
+    }
+    memories() {
+        return this.readCollection("/api/memories", "memories");
+    }
+    /** Shared `sessions()`/`memories()` body: try/except-returns-[], unwrap the
+     * `{ "<key>": [...] }` envelope, and keep only object rows. */
+    readCollection(path, key) {
+        let data;
+        try {
+            data = this.get(path);
+        }
+        catch (err) {
+            if (err instanceof ParticipantDiscoveryError)
+                return [];
+            throw err;
+        }
+        if (isRecord(data)) {
+            data = data[key] || [];
+        }
+        if (!Array.isArray(data))
+            return [];
+        return data.filter(isRecord);
+    }
+}
+// -- Participant ---------------------------------------------------------------
+/** Bourdon participant for OpenClaw (quarantined class). */
+export class OpenClawParticipant {
+    agentId = AGENT_ID;
+    agentType = AGENT_TYPE;
+    displayName = DISPLAY_NAME;
+    /** Trust marker consumed by `bourdon agent add/set-tier` + export-all:
+     * registering as trusted needs --i-understand-the-risk; exports stage. */
+    quarantinedClass = true;
+    url;
+    client;
+    static defaultNativePath(home) {
+        // Network-shaped: shown in the wizard for orientation only. The actual
+        // store is the instance API (OPENCLAW_URL).
+        return join(home ?? homedir(), ".openclaw");
+    }
+    constructor(url, token, client) {
+        this.url = (url || process.env.OPENCLAW_URL || DEFAULT_OPENCLAW_URL).replace(/\/+$/, "");
+        this.client = client ?? new OpenClawApiClient(this.url, token ?? process.env.OPENCLAW_TOKEN);
+    }
+    get nativePath() {
+        return this.url;
+    }
+    // -- protocol ----------------------------------------------------------------
+    discover() {
+        const status = this.client.status();
+        const version = verifyInstance(status, this.url);
+        return {
+            path: this.url,
+            version,
+            metadata: { auth_enabled: true, transport: "http" },
+        };
+    }
+    exportSessions(since, limit = SESSION_LIMIT) {
+        this.discover(); // handshake gate applies to every read
+        const sessions = [];
+        for (const row of this.client.sessions()) {
+            const date = String(row["updated_at"] || row["started_at"] || row["date"] || "").trim();
+            if (!date)
+                continue;
+            if (since !== undefined && before(date, since))
+                continue;
+            const title = safeNativeMemoryText(String(row["title"] || row["summary"] || ""));
+            const projects = Array.isArray(row["projects"]) ? row["projects"].slice(0, 5) : [];
+            sessions.push(makeSession({
+                date,
+                cwd: undefined,
+                project_focus: projects.map((p) => safeNativeMemoryText(String(p))),
+                key_actions: title ? [title] : [],
+            }));
+            if (sessions.length >= limit)
+                break;
+        }
+        return sessions;
+    }
+    exportL5(since) {
+        const store = this.discover();
+        const entities = [];
+        for (const row of this.client.memories().slice(0, ENTITY_LIMIT)) {
+            const name = safeNativeMemoryText(String(row["name"] || row["title"] || ""));
+            if (!name)
+                continue;
+            const tags = Array.isArray(row["tags"]) ? row["tags"].slice(0, 8) : [];
+            entities.push(makeEntity({
+                name,
+                type: String(row["type"] || "topic"),
+                summary: safeNativeMemoryText(String(row["summary"] || "")),
+                tags: tags.map((t) => safeNativeMemoryText(String(t))),
+            }));
+        }
+        // Quarantined-class content defaults to TEAM, never PUBLIC: it only
+        // federates beyond the local library after an explicit operator promotion
+        // AND a team-level read.
+        const policy = makeVisibilityPolicy({ default: Visibility.TEAM });
+        return makeManifest({
+            spec_version: SPEC_VERSION,
+            agent: makeAgentInfo({
+                id: AGENT_ID,
+                type: AGENT_TYPE,
+                instance: this.url,
+                role_narrative: ROLE_NARRATIVE,
+            }),
+            last_updated: nowIsoSeconds(),
+            capabilities: [`openclaw ${store.version}`],
+            recent_sessions: this.exportSessions(since),
+            known_entities: filterForFederation(entities, policy),
+            visibility_policy: policy,
+        });
+    }
+    healthCheck() {
+        let store;
+        try {
+            store = this.discover();
+        }
+        catch (exc) {
+            if (exc instanceof ParticipantDiscoveryError) {
+                const reason = exc.message;
+                let fix = "see the refusal reason above";
+                if (reason.includes("upgrade OpenClaw")) {
+                    fix = `upgrade the OpenClaw instance to >= ${MIN_PATCHED_VERSION}`;
+                }
+                else if (reason.includes("authentication DISABLED")) {
+                    fix = "enable auth on the OpenClaw instance, then set OPENCLAW_TOKEN";
+                }
+                else if (reason.includes("unreachable")) {
+                    fix =
+                        "start OpenClaw locally or set OPENCLAW_URL to the instance address";
+                }
+                return { status: "blocked", reason, proposedFix: fix, details: {} };
+            }
+            // health_check must never raise.
+            return {
+                status: "degraded",
+                reason: exc instanceof Error ? exc.message : String(exc),
+                details: {},
+            };
+        }
+        return {
+            status: "ok",
+            details: { url: this.url, version: store.version, quarantined: true },
+        };
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Participant discovery — a STATIC TS registry replacing Python's `pkgutil`
+ * package scan + entry-point duck-type (`participants/__init__.py`).
+ *
+ * Python scans the `participants/` package at runtime and duck-types each class
+ * by `_PARTICIPANT_MARKER_ATTRS`. A filesystem package scan does not survive
+ * bundling (`npx bourdon` is a single file), so the JS side declares an explicit
+ * {@link FIRST_PARTY} array. The three preserved invariants:
+ *   - output sorted by `agentId`
+ *   - first-wins dedupe on `agentId`
+ *   - log-and-skip a participant that throws on construction (one broken reader
+ *     must NOT abort discovery / crash the CLI)
+ *
+ * The marker-attr duck-typing collapses into the {@link BourdonParticipant}
+ * interface conformance (checked structurally via {@link isParticipant}).
+ */
+import { type BourdonParticipant } from "./base.js";
+/** A zero-arg-constructible participant class. */
+export type ParticipantCtor = new () => BourdonParticipant;
+/**
+ * The first-party reader registry. Order here is irrelevant — discovery sorts by
+ * `agentId`. Covers the base agents, their background-run "automations" variants,
+ * the Claude-desktop surfaces, and the quarantined-class openclaw network reader.
+ * codex — the ~2.6k-line turn-compiler reader — is the only one still deferred.
+ */
+export declare const FIRST_PARTY: ParticipantCtor[];
+/**
+ * Instantiate each registered participant, duck-type the contract, sort by
+ * `agentId`, and first-wins dedupe. A class that throws on construction is
+ * logged and skipped — never propagated.
+ */
+export declare function discoverParticipants(ctors?: ParticipantCtor[]): BourdonParticipant[];
+/**
+ * Optional Layer 2: third-party plugins declared via a `package.json`
+ * `"bourdon": { participants: { ... } }` field. Gated behind `BOURDON_PLUGINS=1`
+ * and a no-op today (no external participant exists yet) — the resolver ships so
+ * the seam is wired, defaulted off so `npx bourdon` stays predictable.
+ */
+export declare function resolvePluginParticipants(): ParticipantCtor[];

package/dist/registry.js

@@ -0,0 +1,98 @@
+/**
+ * Participant discovery — a STATIC TS registry replacing Python's `pkgutil`
+ * package scan + entry-point duck-type (`participants/__init__.py`).
+ *
+ * Python scans the `participants/` package at runtime and duck-types each class
+ * by `_PARTICIPANT_MARKER_ATTRS`. A filesystem package scan does not survive
+ * bundling (`npx bourdon` is a single file), so the JS side declares an explicit
+ * {@link FIRST_PARTY} array. The three preserved invariants:
+ *   - output sorted by `agentId`
+ *   - first-wins dedupe on `agentId`
+ *   - log-and-skip a participant that throws on construction (one broken reader
+ *     must NOT abort discovery / crash the CLI)
+ *
+ * The marker-attr duck-typing collapses into the {@link BourdonParticipant}
+ * interface conformance (checked structurally via {@link isParticipant}).
+ */
+import { isParticipant } from "./base.js";
+import { CascadeParticipant } from "./readers/cascade.js";
+import { ClaudeCodeParticipant } from "./readers/claude-code.js";
+import { ClaudeCodeAutomationsParticipant } from "./readers/claude-code-automations.js";
+import { ClaudeDesktopCodeParticipant } from "./readers/claude-desktop-code.js";
+import { ClaudeDesktopCoworkParticipant } from "./readers/claude-desktop-cowork.js";
+import { CodexAutomationsParticipant } from "./readers/codex-automations.js";
+import { CopilotParticipant } from "./readers/copilot.js";
+import { CopilotAutomationsParticipant } from "./readers/copilot-automations.js";
+import { CopilotCliParticipant } from "./readers/copilot-cli.js";
+import { CopilotVscodeParticipant } from "./readers/copilot-vscode.js";
+import { CursorParticipant } from "./readers/cursor.js";
+import { CursorAutomationsParticipant } from "./readers/cursor-automations.js";
+import { GitHubCopilotParticipant } from "./readers/github-copilot.js";
+import { HermesParticipant } from "./readers/hermes.js";
+import { OpenClawParticipant } from "./readers/openclaw.js";
+/**
+ * The first-party reader registry. Order here is irrelevant — discovery sorts by
+ * `agentId`. Covers the base agents, their background-run "automations" variants,
+ * the Claude-desktop surfaces, and the quarantined-class openclaw network reader.
+ * codex — the ~2.6k-line turn-compiler reader — is the only one still deferred.
+ */
+export const FIRST_PARTY = [
+    CascadeParticipant,
+    ClaudeCodeParticipant,
+    ClaudeCodeAutomationsParticipant,
+    ClaudeDesktopCodeParticipant,
+    ClaudeDesktopCoworkParticipant,
+    CodexAutomationsParticipant,
+    CopilotParticipant,
+    CopilotAutomationsParticipant,
+    CopilotCliParticipant,
+    CopilotVscodeParticipant,
+    CursorParticipant,
+    CursorAutomationsParticipant,
+    GitHubCopilotParticipant,
+    HermesParticipant,
+    OpenClawParticipant,
+];
+/** Minimal logger so a skipped participant is visible without a dep. */
+const logger = {
+    warn(msg) {
+        // eslint-disable-next-line no-console
+        console.warn(`[bourdon.participants] ${msg}`);
+    },
+};
+/**
+ * Instantiate each registered participant, duck-type the contract, sort by
+ * `agentId`, and first-wins dedupe. A class that throws on construction is
+ * logged and skipped — never propagated.
+ */
+export function discoverParticipants(ctors = FIRST_PARTY) {
+    const found = new Map();
+    for (const Ctor of [...ctors, ...resolvePluginParticipants()]) {
+        let instance;
+        try {
+            instance = new Ctor();
+        }
+        catch (err) {
+            logger.warn(`Skipping participant ${Ctor.name || "<anonymous>"}: construction failed: ${String(err)}`);
+            continue;
+        }
+        if (!isParticipant(instance))
+            continue;
+        if (!found.has(instance.agentId))
+            found.set(instance.agentId, instance);
+    }
+    return [...found.values()].sort((a, b) => a.agentId < b.agentId ? -1 : a.agentId > b.agentId ? 1 : 0);
+}
+/**
+ * Optional Layer 2: third-party plugins declared via a `package.json`
+ * `"bourdon": { participants: { ... } }` field. Gated behind `BOURDON_PLUGINS=1`
+ * and a no-op today (no external participant exists yet) — the resolver ships so
+ * the seam is wired, defaulted off so `npx bourdon` stays predictable.
+ */
+export function resolvePluginParticipants() {
+    if (process.env.BOURDON_PLUGINS !== "1")
+        return [];
+    // No external participant package exists yet; the resolver is intentionally a
+    // no-op stub. When one ships, resolve its declared ctors here.
+    return [];
+}

package/dist/sqlite-base.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared read-only SQLite + normalization helpers — port of
+ * `participants/_sqlite_base.py`.
+ *
+ * A SQLite-backed participant (hermes today; cursor/copilot_cli in the follow-on
+ * slice) reads a foreign agent's native DB read-only so a live writer's lock can
+ * never block the export, probes the schema defensively (native schemas drift
+ * across versions), and turns epoch timestamps + paths into the L5 shapes.
+ *
+ * `better-sqlite3` is a NATIVE addon. It is loaded lazily through `createRequire`
+ * inside a try/catch so this package — and the file/network readers — keep
+ * working even on a toolchain where the addon failed to build: in that case
+ * {@link sqliteAvailable} returns false and the sqlite readers degrade rather
+ * than crashing import. Nothing here applies visibility or builds manifests;
+ * that stays in the participant (per PARTICIPANT_CONTRACT.md).
+ */
+import type DatabaseT from "better-sqlite3";
+/** A better-sqlite3 connection (re-exported type alias for reader signatures). */
+export type SqliteDatabase = DatabaseT.Database;
+/** True when the better-sqlite3 native addon loaded successfully. Tests gate
+ * the SQLite-reader assertions on this so a missing addon skips, not fails. */
+export declare function sqliteAvailable(): boolean;
+export interface OpenReadonlyOptions {
+    /** `immutable=1`: skip locks + ignore the WAL. Only for genuinely static
+     * snapshots; against a live writer it risks stale reads / SQLITE_CORRUPT. */
+    immutable?: boolean;
+    /** SQLite busy-timeout in milliseconds (Python's `timeout=2.0` seconds). */
+    timeoutMs?: number;
+}
+/**
+ * Open a SQLite DB read-only so a live writer is never disturbed. The default
+ * (`immutable` omitted) is the safe `mode=ro`: it respects SQLite locking and
+ * reads the `-wal` sidecar of a live, actively-writing agent. Raises on a
+ * genuine open failure; callers wanting the never-raises contract use
+ * {@link tryOpenReadonly}.
+ */
+export declare function openReadonly(dbPath: string, opts?: OpenReadonlyOptions): SqliteDatabase;
+/**
+ * Like {@link openReadonly} but returns null instead of raising — for the
+ * export/health path where a missing or corrupt DB must degrade to "no rows".
+ */
+export declare function tryOpenReadonly(dbPath: string, opts?: OpenReadonlyOptions): SqliteDatabase | null;
+/** True if `name` is a table in the connected DB (swallows errors → false). */
+export declare function tableExists(db: SqliteDatabase, name: string): boolean;
+/** Column names for `table` (empty set if absent / on error). PRAGMA cannot be
+ * parameterized, matching the Python f-string. */
+export declare function tableColumns(db: SqliteDatabase, table: string): Set<string>;
+/**
+ * Convert epoch seconds (number/string) to an ISO `YYYY-MM-DD` UTC date, or
+ * null for missing/unparseable values. Mirrors `epoch_to_iso_date`.
+ */
+export declare function epochToIsoDate(value: unknown): string | null;
+/**
+ * Convert epoch seconds to a full ISO 8601 UTC datetime, or null. The offset is
+ * rendered `+00:00` (Python `datetime(...).isoformat()` style) rather than `Z`.
+ */
+export declare function epochToIsoDatetime(value: unknown): string | null;
+/**
+ * Derive a lowercase project key from a working-directory path: the basename
+ * lowercased, or null when the cwd is empty or its basename is "generic"
+ * (carries no project identity). Mirrors `project_key_from_cwd`.
+ */
+export declare function projectKeyFromCwd(cwd: string | null | undefined, genericNames?: ReadonlySet<string>): string | null;
+/** Turn a slug-ish key (`my-cool_project`) into a Title Case label. */
+export declare function friendlyLabel(key: string): string;