@getbourdon/participants 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { L5ManifestModel, SessionModel } from '@getbourdon/l5';
+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';
 
@@ -67,6 +67,13 @@ interface BourdonParticipant {
     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;
@@ -356,6 +363,248 @@ declare class GitHubCopilotParticipant extends NetworkParticipant {
     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`).
@@ -377,8 +626,10 @@ declare class GitHubCopilotParticipant extends NetworkParticipant {
 type ParticipantCtor = new () => BourdonParticipant;
 /**
  * The first-party reader registry. Order here is irrelevant — discovery sorts by
- * `agentId`. (cursor / codex / copilot_cli are the heavier SQLite readers of the
- * follow-on slice; openclaw ships as the `@getbourdon/openclaw` plugin.)
+ * `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[];
 /**
@@ -395,4 +646,4 @@ declare function discoverParticipants(ctors?: ParticipantCtor[]): BourdonPartici
  */
 declare function resolvePluginParticipants(): ParticipantCtor[];
 
-export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, ClaudeCodeParticipant, DEFAULT_CACHE_TTL_SECONDS, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, 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 };
+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 };

package/dist/index.d.ts

@@ -2,10 +2,13 @@
  * @getbourdon/participants — the external-agent → L5 reader layer (BUSL-1.1).
  *
  * Each participant normalizes a foreign agent's native memory store into a
- * visibility-filtered, redacted L5 manifest. Three reader categories:
- *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant}
- *   - file / convention:                          {@link ClaudeCodeParticipant}
+ * visibility-filtered, redacted L5 manifest. Reader categories:
+ *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant},
+ *     {@link CursorParticipant}, {@link CopilotCliParticipant}
+ *   - file / convention:                          {@link ClaudeCodeParticipant},
+ *     {@link CopilotParticipant}, {@link CascadeParticipant}
  *   - network (TTL cache + lazy AuthProvider):     {@link GitHubCopilotParticipant}
+ *   - network + quarantined-class (handshake gate): {@link OpenClawParticipant}
  *
  * Four invariants enforced in code, not by trust: visibility-filter-before-
  * emission, deterministic exportL5, healthCheck never throws, redact every
@@ -13,8 +16,8 @@
  *
  * Python (`pip install bourdon`) is the oracle; this mirror asserts against the
  * @getbourdon/conformance `native_stores` fixtures (output shape only).
- * Follow-on slice: cursor + codex (heavier SQLite) + copilot_cli; openclaw ships
- * as the @getbourdon/openclaw plugin.
+ * Still deferred: codex (the ~2.6k-line turn-compiler reader) lands in a
+ * follow-on slice.
  */
 export { CONTRACT_VERSION, SPEC_VERSION, ParticipantError, ParticipantDiscoveryError, ParticipantExportError, ParticipantVersionMismatchError, isParticipant, type AgentStore, type BourdonParticipant, type HealthStatus, } from "./base.js";
 export { sqliteAvailable, openReadonly, tryOpenReadonly, tableExists, tableColumns, epochToIsoDate, epochToIsoDatetime, projectKeyFromCwd, friendlyLabel, type OpenReadonlyOptions, type SqliteDatabase, } from "./sqlite-base.js";
@@ -22,5 +25,10 @@ export { NETWORK_CONTRACT_VERSION, DEFAULT_CACHE_TTL_SECONDS, NetworkUnavailable
 export { HermesParticipant } from "./readers/hermes.js";
 export { ClaudeCodeParticipant } from "./readers/claude-code.js";
 export { GitHubCopilotParticipant, ghTokenProvider } from "./readers/github-copilot.js";
+export { CursorParticipant } from "./readers/cursor.js";
+export { CopilotParticipant } from "./readers/copilot.js";
+export { CopilotCliParticipant } from "./readers/copilot-cli.js";
+export { CascadeParticipant } from "./readers/cascade.js";
+export { OpenClawParticipant, OpenClawApiClient, verifyInstance, MIN_PATCHED_VERSION, } from "./readers/openclaw.js";
 export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, type ParticipantCtor, } from "./registry.js";
 export { Visibility, applyVisibility, filterForFederation, toDict, validateManifest, type EntityModel, type L5ManifestModel, type SessionModel, type VisibilityPolicyModel, } from "@getbourdon/l5";

package/dist/index.js

@@ -2,10 +2,13 @@
  * @getbourdon/participants — the external-agent → L5 reader layer (BUSL-1.1).
  *
  * Each participant normalizes a foreign agent's native memory store into a
- * visibility-filtered, redacted L5 manifest. Three reader categories:
- *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant}
- *   - file / convention:                          {@link ClaudeCodeParticipant}
+ * visibility-filtered, redacted L5 manifest. Reader categories:
+ *   - SQLite (read-only, better-sqlite3 mode=ro): {@link HermesParticipant},
+ *     {@link CursorParticipant}, {@link CopilotCliParticipant}
+ *   - file / convention:                          {@link ClaudeCodeParticipant},
+ *     {@link CopilotParticipant}, {@link CascadeParticipant}
  *   - network (TTL cache + lazy AuthProvider):     {@link GitHubCopilotParticipant}
+ *   - network + quarantined-class (handshake gate): {@link OpenClawParticipant}
  *
  * Four invariants enforced in code, not by trust: visibility-filter-before-
  * emission, deterministic exportL5, healthCheck never throws, redact every
@@ -13,8 +16,8 @@
  *
  * Python (`pip install bourdon`) is the oracle; this mirror asserts against the
  * @getbourdon/conformance `native_stores` fixtures (output shape only).
- * Follow-on slice: cursor + codex (heavier SQLite) + copilot_cli; openclaw ships
- * as the @getbourdon/openclaw plugin.
+ * Still deferred: codex (the ~2.6k-line turn-compiler reader) lands in a
+ * follow-on slice.
  */
 // Contract surface: Protocol interface, errors, AgentStore + HealthStatus.
 export { CONTRACT_VERSION, SPEC_VERSION, ParticipantError, ParticipantDiscoveryError, ParticipantExportError, ParticipantVersionMismatchError, isParticipant, } from "./base.js";
@@ -26,6 +29,11 @@ export { NETWORK_CONTRACT_VERSION, DEFAULT_CACHE_TTL_SECONDS, NetworkUnavailable
 export { HermesParticipant } from "./readers/hermes.js";
 export { ClaudeCodeParticipant } from "./readers/claude-code.js";
 export { GitHubCopilotParticipant, ghTokenProvider } from "./readers/github-copilot.js";
+export { CursorParticipant } from "./readers/cursor.js";
+export { CopilotParticipant } from "./readers/copilot.js";
+export { CopilotCliParticipant } from "./readers/copilot-cli.js";
+export { CascadeParticipant } from "./readers/cascade.js";
+export { OpenClawParticipant, OpenClawApiClient, verifyInstance, MIN_PATCHED_VERSION, } from "./readers/openclaw.js";
 // Discovery (static registry).
 export { FIRST_PARTY, discoverParticipants, resolvePluginParticipants, } from "./registry.js";
 // Re-exported from @getbourdon/l5 for convenience (the L5 model + serialization