@getbourdon/participants 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,649 @@
+import { L5ManifestModel, SessionModel, VisibilityPolicyModel } from '@getbourdon/l5';
+export { EntityModel, L5ManifestModel, SessionModel, Visibility, VisibilityPolicyModel, applyVisibility, filterForFederation, toDict, validateManifest } from '@getbourdon/l5';
+import DatabaseT from 'better-sqlite3';
+
+/**
+ * Bourdon participant base — the Protocol → TS interface, errors, and the
+ * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.
+ *
+ * The L5 dataclass model (AgentInfo/Entity/Session/VisibilityPolicy/L5Manifest),
+ * the `toDict` omission rules, and the visibility helpers all live in
+ * `@getbourdon/l5` and are reused verbatim — only THAT output shape is the parity
+ * contract. This module owns the participant CONTRACT surface around them.
+ *
+ * Contract semantics (enforced by every reader, asserted by the conformance
+ * fixtures, never by trust):
+ *   1. visibility filter BEFORE emission (`filterForFederation`) — private wins.
+ *   2. deterministic / idempotent `exportL5` — same store → identical `toDict`.
+ *   3. `healthCheck` NEVER throws — catch-all → degraded/blocked.
+ *   4. every native string through `@getbourdon/redaction` before it enters L5.
+ */
+
+/** Tied to Bourdon spec v0.1 — same literals as the Python oracle. */
+declare const CONTRACT_VERSION = "0.1";
+declare const SPEC_VERSION = "0.1";
+/** Base class for participant errors. */
+declare class ParticipantError extends Error {
+    constructor(message?: string);
+}
+/** Raised by `discover()` when the native store cannot be found or read.
+ * Non-fatal: L6 skips this agent rather than aborting the whole export. */
+declare class ParticipantDiscoveryError extends ParticipantError {
+}
+/** Raised by `exportL5()` / `exportSessions()` when an export fails mid-op
+ * (the store WAS present — distinct from a discovery miss). */
+declare class ParticipantExportError extends ParticipantError {
+}
+/** Raised when the native store's version is outside the supported range.
+ * Subtype of discovery error (a version mismatch is a discovery-time miss). */
+declare class ParticipantVersionMismatchError extends ParticipantDiscoveryError {
+}
+/** Metadata describing the native agent store. Returned by `discover()`. */
+interface AgentStore {
+    path: string;
+    version: string;
+    metadata: Record<string, unknown>;
+}
+/** Returned by `healthCheck()`. Consumed by the `bourdon doctor` CLI. */
+interface HealthStatus {
+    status: "ok" | "degraded" | "blocked";
+    reason?: string;
+    details: Record<string, unknown>;
+    /** A human-runnable command to remedy a non-ok status. */
+    proposedFix?: string;
+}
+/**
+ * Structural interface every participant must satisfy (the Python
+ * `@runtime_checkable Protocol`). Duck-typed at registration: a class is a
+ * participant iff it has `agentId` + `agentType` + `exportL5` + `healthCheck`.
+ *
+ * Optional members (`displayName`, a `defaultNativePath` static) are documented
+ * here as in the Python Protocol; discovery + the setup wizard fall back to
+ * sensible defaults when absent.
+ */
+interface BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    nativePath: string;
+    /** Human-friendly label (e.g. "GitHub Copilot"). Optional. */
+    displayName?: string;
+    /** Quarantined-class marker (Python `QUARANTINED_CLASS`). When true, the CLI
+     * requires `--i-understand-the-risk` to register the agent trusted, and its
+     * exports are staged for operator review rather than written to the live
+     * store (spec D6: quarantine follows the content, not the invoker). Absent =
+     * a normal, non-quarantined participant. Read by `bourdon agent add/set-tier`
+     * (cli/src/commands/federation.ts). */
+    quarantinedClass?: boolean;
+    /** Confirm the native store exists; return metadata. Throws
+     * {@link ParticipantDiscoveryError} when missing/unreadable. */
+    discover(): AgentStore;
+    /** Build the L5 manifest from native memory, applying the visibility filter
+     * BEFORE return. Deterministic — same store yields the same manifest. */
+    exportL5(since?: Date): L5ManifestModel;
+    /** Export recent sessions in normalized schema. */
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    /** Return ok / degraded / blocked with a reason. MUST NOT throw. */
+    healthCheck(): HealthStatus;
+}
+/**
+ * Tiny structural guard mirroring Python's `_PARTICIPANT_MARKER_ATTRS`
+ * duck-type: a value is a participant iff it carries the four marker members.
+ */
+declare function isParticipant(obj: unknown): obj is BourdonParticipant;
+
+/**
+ * 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).
+ */
+
+/** A better-sqlite3 connection (re-exported type alias for reader signatures). */
+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. */
+declare function sqliteAvailable(): boolean;
+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}.
+ */
+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".
+ */
+declare function tryOpenReadonly(dbPath: string, opts?: OpenReadonlyOptions): SqliteDatabase | null;
+/** True if `name` is a table in the connected DB (swallows errors → false). */
+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. */
+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`.
+ */
+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`.
+ */
+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`.
+ */
+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. */
+declare function friendlyLabel(key: string): string;
+
+/**
+ * Network-shaped participant base — port of `participants/_network_base.py`
+ * (v0.3 adapter contract). Same `exportL5` / `exportSessions` half as a file
+ * participant; only the discovery half differs (fetch from an authenticated
+ * API). The base provides the three guarantees so adapters don't reimplement:
+ *
+ *   1. Local TTL cache under `~/.cache/bourdon/<slug>/payload.json` storing ONLY
+ *      `{fetched_at, payload}` — NEVER the token. A cache hit = zero network.
+ *   2. Graceful degradation: network down → serve the most recent cached payload
+ *      (even expired) and report `degraded` (not silence).
+ *   3. Auth boundary: an injected lazy {@link AuthProvider} (env / keychain).
+ *      An invalid token (401/403 non-ratelimit) ALWAYS propagates as `blocked`
+ *      and is NEVER masked by stale cache; a missing token serves stale when a
+ *      cache exists, else blocks; rate-limit degrades.
+ *
+ * A subclass sets `participantSlug` / `agentId` / `agentType` (+ `nativePath`)
+ * and implements `fetchPayload(token)` + `payloadToL5(payload)` (pure, no I/O).
+ */
+
+declare const NETWORK_CONTRACT_VERSION = "0.3";
+/** Default cache TTL — adapters override via `cacheTtlSeconds`. */
+declare const DEFAULT_CACHE_TTL_SECONDS: number;
+/** Transport failure / timeout / 5xx / rate-limit — recoverable via cache fallback. */
+declare class NetworkUnavailable extends ParticipantError {
+}
+/** 401/403 / missing credential — NOT recoverable via cache. The user must fix
+ * auth; surfaced as `blocked`, never silently served from stale cache (stale
+ * data would mask a broken token indefinitely). */
+declare class ParticipantAuthError extends ParticipantError {
+}
+/** A zero-arg callable returning the token string, or null if no credential is
+ * available. Kept a callable (not a bare string) so the token is fetched lazily
+ * at call time and never sits in the participant's fields or the cache. */
+type AuthProvider = () => string | null;
+/** Auth provider that reads a token from an environment variable. */
+declare function envAuthProvider(varName: string): AuthProvider;
+/** `$XDG_CACHE_HOME/bourdon` or `~/.cache/bourdon`. */
+declare function defaultCacheRoot(): string;
+/** A cached payload + the wall-clock time it was fetched (epoch seconds). */
+declare class CacheEntry {
+    readonly fetchedAt: number;
+    readonly payload: Record<string, unknown>;
+    constructor(fetchedAt: number, payload: Record<string, unknown>);
+    get ageSeconds(): number;
+    isFresh(ttlSeconds: number): boolean;
+}
+/**
+ * A tiny JSON file cache, one file per participant slug. Stores only
+ * `{fetched_at, payload}` — never the auth token. Read/write are best-effort: a
+ * corrupt or unwritable cache degrades to "no cache", never raises.
+ */
+declare class PayloadCache {
+    readonly slug: string;
+    readonly root: string;
+    readonly path: string;
+    constructor(slug: string, rootDir?: string);
+    read(): CacheEntry | null;
+    write(payload: Record<string, unknown>): void;
+}
+interface NetworkParticipantOptions {
+    authProvider?: AuthProvider | null;
+    cacheRoot?: string;
+}
+/**
+ * Base for participants whose native state lives behind an authenticated API.
+ * Caching, degradation, the auth boundary, and the
+ * `discover`/`exportL5`/`exportSessions`/`healthCheck` plumbing live here;
+ * subclasses provide only `fetchPayload` + `payloadToL5`.
+ */
+declare abstract class NetworkParticipant implements BourdonParticipant {
+    participantSlug: string;
+    agentId: string;
+    agentType: string;
+    cacheTtlSeconds: number;
+    nativePath: string;
+    protected readonly authProvider: AuthProvider | null;
+    private readonly cacheRoot?;
+    private cacheInstance?;
+    constructor(opts?: NetworkParticipantOptions);
+    /** Lazily built so it reads the SUBCLASS's `participantSlug` — subclass field
+     * initializers run after `super()`, so building the cache in the constructor
+     * would capture the base "network" slug instead. */
+    protected get cache(): PayloadCache;
+    /** Do the authenticated API call; return a JSON-serializable dict. Raise
+     * {@link NetworkUnavailable} on transport/5xx/rate-limit (→ cache fallback) or
+     * {@link ParticipantAuthError} on 401/403 (→ blocked, no fallback). */
+    abstract fetchPayload(token: string): Record<string, unknown>;
+    /** Normalize a (fresh or cached) payload into an L5 manifest. Pure, no I/O. */
+    abstract payloadToL5(payload: Record<string, unknown>): L5ManifestModel;
+    /**
+     * Resolve (payload, source) where source is 'cache' | 'network' | 'stale-cache'.
+     *   1. Fresh cache hit           → 'cache'        (no network)
+     *   2. Miss/expired + token      → 'network'      (fetch + refresh cache)
+     *   3. Net fails + any cache     → 'stale-cache'  (serve last good payload)
+     *   4. Net fails + no cache      → raise
+     * Auth errors are never swallowed — they propagate so health surfaces
+     * 'blocked' rather than serving stale data behind a dead token.
+     */
+    protected getPayload(): {
+        payload: Record<string, unknown>;
+        source: string;
+    };
+    discover(): AgentStore;
+    exportL5(_since?: Date): L5ManifestModel;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    healthCheck(): HealthStatus;
+}
+
+/**
+ * Hermes participant — normalize Hermes Agent (Nous Research) memory + sessions
+ * into L5. Port of `participants/hermes.py`.
+ *
+ * Reads two surfaces under `~/.hermes/` (override `$HERMES_HOME`):
+ *   * `state.db` — a SQLite store (`sessions` + `messages` tables). Recent
+ *     non-archived sessions + project entities (from cwd basename) come from it.
+ *   * `memories/{memory.md,user.md}` — durable cross-session facts (one
+ *     Markdown bullet/line per memory). The highest-signal entities.
+ *
+ * Read-only (`mode=ro`), deterministic, visibility-enforced-before-emission,
+ * and redaction on every native string. `healthCheck` never throws; `discover`
+ * raises only {@link ParticipantDiscoveryError}.
+ */
+
+/** External participant for local Hermes Agent memory + sessions. */
+declare class HermesParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    nativePath: string;
+    private readonly home;
+    static defaultNativePath(home?: string): string;
+    /** `hermesHome` is the `.hermes` directory itself (matching the Python ctor). */
+    constructor(hermesHome?: string);
+    private sources;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+}
+
+/**
+ * Claude Code participant — reads claude-brain + auto-memory + MCP knowledge
+ * graph. Port of `participants/claude_code.py`.
+ *
+ * Three optional sources (the participant degrades gracefully):
+ *   1. claude-brain/                  — git-synced markdown records
+ *   2. ~/.claude/projects/<ws>/memory/ — per-machine auto-memory frontmatter
+ *   3. ~/claude-memory/memory.jsonl   — MCP knowledge-graph JSONL
+ *
+ * Privacy: entities typed `person` (+ family/contact variants) and observations
+ * containing credential-like strings default to PRIVATE and are filtered before
+ * federation. Entities are deduped by case-insensitive name and sorted
+ * alphabetically.
+ */
+
+/** External participant for Anthropic's Claude Code CLI. */
+declare class ClaudeCodeParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    nativePath: string;
+    /** Public so a hermetic test can seed the discovered sources directly (path
+     * RESOLUTION is not the parity contract — only the export output shape is). */
+    brainPath: string | null;
+    autoMemoryPath: string | null;
+    knowledgeGraphPath: string | null;
+    static defaultNativePath(home?: string): string;
+    constructor();
+    discover(): AgentStore;
+    exportL5(since?: Date): L5ManifestModel;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    healthCheck(): HealthStatus;
+}
+
+/**
+ * GitHub-embedded Copilot participant — the v0.3 network-adapter reference.
+ * Port of `participants/github_copilot.py`.
+ *
+ * Cloud-side Copilot (PR review, `@copilot` comments) persists nothing on the
+ * user's machine — its state lives on github.com. This adapter federates it by
+ * reading the user's GitHub activity over the REST API. The
+ * {@link NetworkParticipant} base provides the cache, degradation, and auth
+ * boundary; this class provides only the GitHub-specific fetch + payload→L5.
+ *
+ * Auth: a token with `repo` + `read:user` scope, sourced from `$GITHUB_TOKEN` /
+ * `$GH_TOKEN`, else `gh auth token`. Fetched lazily; never stored in the cache
+ * or the manifest.
+ */
+
+/** Resolve a GitHub token: env var first, then the `gh` CLI keychain. */
+declare function ghTokenProvider(): string | null;
+/** Federates cloud-side GitHub Copilot activity via the GitHub REST API. */
+declare class GitHubCopilotParticipant extends NetworkParticipant {
+    participantSlug: string;
+    agentId: string;
+    agentType: string;
+    nativePath: string;
+    displayName: string;
+    private readonly maxResults;
+    constructor(opts?: NetworkParticipantOptions & {
+        maxResults?: number;
+    });
+    static defaultNativePath(): string;
+    fetchPayload(token: string): Record<string, unknown>;
+    payloadToL5(payload: Record<string, unknown>): L5ManifestModel;
+}
+
+/**
+ * Cursor participant — reads Cursor's (the AI-first IDE) SQLite-backed
+ * workspace/composer state and normalizes it into L5. Port of
+ * `participants/cursor.py` + the extraction helper `participants/_cursor_sqlite.py`.
+ *
+ * Cursor stores workspace state in `state.vscdb` SQLite DBs at platform-specific
+ * paths (`~/.config/Cursor/`, `~/Library/Application Support/Cursor/`,
+ * `%APPDATA%/Cursor/`). This reader discovers those stores, reads the `ItemTable`
+ * key/value rows read-only, parses the composer/chat records into sessions +
+ * project/topic entities, and merges curated `.cursor/memory/short-index.json`
+ * entities alongside them.
+ *
+ * SQLite access: the Python oracle copies each DB (+ its `-wal`/`-shm`
+ * companions) to a tmp file and opens it read-write so SQLite folds the WAL into
+ * a consistent snapshot. The TS mirror instead leans on {@link tryOpenReadonly}
+ * (`mode=ro`), which respects SQLite locking and reads the `-wal` sidecar of a
+ * live writer — the same consistent view without the copy. Read-only,
+ * deterministic, visibility-enforced-before-emission, redaction on every native
+ * string; `healthCheck` never throws.
+ */
+
+/** External participant for Cursor's SQLite workspace state. */
+declare class CursorParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    private readonly cursorDir;
+    private readonly workspaceRoot;
+    private readonly policy;
+    /**
+     * Conventional Cursor config dir (`~/.cursor`) used by the setup wizard. The
+     * wizard probes `~/.cursor` for presence; the SQLite workspace state that
+     * `exportL5` actually reads lives at {@link defaultCursorDir}. Detection and
+     * extraction intentionally use different anchors.
+     */
+    static defaultNativePath(home?: string): string;
+    constructor(cursorDir?: string | null, workspaceRoot?: string | null);
+    get nativePath(): string;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    private extract;
+}
+
+/**
+ * GitHub Copilot (local convention) participant — reads the convention-based
+ * memory file at `~/.copilot-bourdon/memory.md`. Port of `participants/copilot.py`.
+ *
+ * Copilot has no accessible local session index (its reasoning is cloud-side and
+ * its native memory is not exposed on disk), so — like the Codex pre-distillation
+ * fallback — this reader normalizes a user-maintained convention file into a
+ * Bourdon L5 manifest. The file is YAML front-matter (structured `entities:` /
+ * `sessions:`) followed by an optional freeform markdown body that Copilot Chat
+ * reads as plain context but this reader ignores.
+ *
+ * NOT the cloud GitHub-Copilot network adapter ({@link GitHubCopilotParticipant})
+ * and NOT the Copilot CLI SQLite reader.
+ *
+ * Paths checked (in order):
+ *   1. `COPILOT_BOURDON_HOME` env-var override
+ *   2. `~/.copilot-bourdon/`  (default convention path)
+ *
+ * Defensive throughout: a missing convention directory raises
+ * {@link ParticipantDiscoveryError} from `discover()`; malformed YAML degrades to
+ * an empty manifest rather than raising; `healthCheck` never throws.
+ */
+
+/**
+ * External participant for GitHub Copilot via `~/.copilot-bourdon/memory.md`.
+ * Implements {@link BourdonParticipant} structurally.
+ */
+declare class CopilotParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    nativePath: string;
+    /** Conventional `~/.copilot-bourdon` dir used by the setup wizard's detection. */
+    static defaultNativePath(home?: string): string;
+    private readonly copilotDir;
+    constructor(copilotDir?: string | null);
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    private read;
+}
+
+/**
+ * GitHub Copilot CLI participant — normalize the `copilot` terminal agent's
+ * SQLite session store into L5. Port of `participants/copilot_cli.py`.
+ *
+ * Copilot CLI stores session history in a SQLite database at
+ * `~/.copilot/session-store.db` (override `$COPILOT_CLI_HOME`). This is distinct
+ * from:
+ *   - the VS Code Copilot Chat extension (`github-copilot` network reader)
+ *   - the `~/.copilot-bourdon/memory.md` convention-file participant (`copilot`)
+ *   - GitHub-embedded Copilot (no local state)
+ *
+ * The schema (schema_version 4) carries `sessions` / `turns` / `checkpoints`
+ * plus `session_files` / `session_refs` / `dynamic_context_items`. The reader
+ * opens the DB read-only (`mode=ro` via {@link tryOpenReadonly}) so a live
+ * writer's lock can never block the export, probes each table defensively (a
+ * missing table degrades to "no rows" rather than raising), redacts every native
+ * string, applies the visibility filter BEFORE emission, and is deterministic.
+ * `healthCheck` never throws.
+ */
+
+/**
+ * External participant for GitHub Copilot CLI (`~/.copilot/session-store.db`).
+ * Reads the SQLite database read-only (never locks the live db).
+ */
+declare class CopilotCliParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    nativePath: string;
+    private readonly copilotDir;
+    /** Conventional `~/.copilot` dir used by the setup wizard's detection. */
+    static defaultNativePath(home?: string): string;
+    constructor(copilotDir?: string);
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    private emptyManifest;
+}
+
+/**
+ * Cascade (Windsurf) participant — convention-file reader. Port of
+ * `participants/cascade.py`.
+ *
+ * Cascade's internal state is not exposed on the filesystem in a standardized
+ * format (like cloud Copilot). Instead this participant uses a CONVENTION FILE:
+ * Cascade maintains a structured memory file at `~/.cascade-bourdon/memory.md`
+ * with YAML front-matter carrying `entities` + `sessions`. Cascade owns that
+ * projection explicitly (it writes what it knows at session end); the
+ * participant normalizes the front-matter into an L5 manifest for federation.
+ *
+ * Privacy: entity/session summaries pass through the redaction SSOT; the
+ * visibility policy (private_tags) filters PRIVATE entities before emission.
+ */
+
+/**
+ * Convention-based Bourdon participant for Cascade (Windsurf). Reads structured
+ * memory from `~/.cascade-bourdon/memory.md` and normalizes it into L5.
+ */
+declare class CascadeParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    private readonly dir;
+    private readonly policy;
+    static defaultNativePath(home?: string): string;
+    constructor(cascadeDir?: string, policy?: VisibilityPolicyModel);
+    /** Path to the Cascade-Bourdon convention directory. */
+    get nativePath(): string;
+    private memoryPath;
+    private readFrontmatter;
+    discover(): AgentStore;
+    exportL5(since?: Date): L5ManifestModel;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    healthCheck(): HealthStatus;
+}
+
+/**
+ * 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).
+ */
+
+/** First OpenClaw release that patches CVE-2026-25253 (one-click RCE). */
+declare const MIN_PATCHED_VERSION = "2026.1.29";
+/**
+ * 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.
+ */
+declare function verifyInstance(status: Record<string, unknown>, url: string): string;
+/**
+ * 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}".
+ */
+declare class OpenClawApiClient {
+    readonly url: string;
+    private readonly token;
+    readonly timeout: number;
+    constructor(url: string, token?: string, timeout?: number);
+    private get;
+    status(): Record<string, unknown>;
+    sessions(): Record<string, unknown>[];
+    memories(): Record<string, unknown>[];
+    /** Shared `sessions()`/`memories()` body: try/except-returns-[], unwrap the
+     * `{ "<key>": [...] }` envelope, and keep only object rows. */
+    private readCollection;
+}
+/** Bourdon participant for OpenClaw (quarantined class). */
+declare class OpenClawParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    /** Trust marker consumed by `bourdon agent add/set-tier` + export-all:
+     * registering as trusted needs --i-understand-the-risk; exports stage. */
+    quarantinedClass: boolean;
+    readonly url: string;
+    private readonly client;
+    static defaultNativePath(home?: string): string;
+    constructor(url?: string, token?: string, client?: OpenClawApiClient);
+    get nativePath(): string;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+}
+
+/**
+ * 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}).
+ */
+
+/** A zero-arg-constructible participant class. */
+type ParticipantCtor = new () => BourdonParticipant;
+/**
+ * The first-party reader registry. Order here is irrelevant — discovery sorts by
+ * `agentId`. (cursor / copilot-cli are the heavier SQLite readers; copilot is the
+ * convention-file reader; cascade reads Windsurf; openclaw is the quarantined-
+ * class network reader. codex — the ~2.6k-line turn-compiler reader — is still
+ * deferred.)
+ */
+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.
+ */
+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.
+ */
+declare function resolvePluginParticipants(): ParticipantCtor[];
+
+export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeParticipant, CopilotCliParticipant, CopilotParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, openReadonly, projectKeyFromCwd, resolvePluginParticipants, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };