@getbourdon/participants 0.2.0 → 0.2.1

package/dist/readers/hermes.js

@@ -1,426 +0,0 @@
-/**
- * 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}.
- */
-import { readFileSync, statSync } from "node:fs";
-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 { CONTRACT_VERSION, ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
-import { epochToIsoDate, friendlyLabel, projectKeyFromCwd, tableColumns, tableExists, tryOpenReadonly, } from "../sqlite-base.js";
-const AGENT_ID = "hermes";
-const AGENT_TYPE = "code-assistant";
-const DISPLAY_NAME = "Hermes Agent";
-const ROLE_NARRATIVE = "General-purpose tool-calling assistant (Nous Research). Operates across CLI, " +
-    "TUI, and messaging gateways (Slack/Telegram/Discord/WhatsApp); runs terminal, " +
-    "file, web, and delegation toolsets. Carries durable cross-session memory and a " +
-    "curated skill library. Federates session + memory context, not vendor account.";
-const DEFAULT_SESSION_LIMIT = 100;
-/** Hermes memory stores live as Markdown under `~/.hermes/memories/`. */
-const MEMORY_FILENAMES = ["memory.md", "user.md"];
-const DEFAULT_POLICY = makeVisibilityPolicy({
-    default: Visibility.TEAM,
-    private_tags: ["personal", "financial", "credential", "secret", "health", "family", "legal"],
-    team_tags: ["hermes-memory", "hermes-session", "hermes-project"],
-});
-/** cwd basenames that carry no project identity. */
-const GENERIC_PROJECT_NAMES = new Set([
-    "",
-    "root",
-    "home",
-    "tmp",
-    "temp",
-    "desktop",
-    "documents",
-    "downloads",
-    "src",
-]);
-// -- Path resolution ----------------------------------------------------------
-/**
- * Conventional Hermes home used by the setup wizard's detection.
- * Precedence: explicit `home` > `$HERMES_HOME` > `~/.hermes`.
- */
-export function defaultNativePath(home) {
-    if (home)
-        return join(home, ".hermes");
-    const env = process.env.HERMES_HOME;
-    if (env)
-        return env;
-    return join(homedir(), ".hermes");
-}
-function isDir(p) {
-    try {
-        return statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-function isFile(p) {
-    try {
-        return statSync(p).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-/** Redact secrets, collapse whitespace, and clamp length. */
-function bounded(value, limit = 240) {
-    const cleaned = redactText((value || "").replace(/\s+/g, " ").trim(), limit);
-    return cleaned.trim();
-}
-function projectKey(cwd) {
-    return projectKeyFromCwd(cwd, GENERIC_PROJECT_NAMES);
-}
-// -- SQLite (read-only) -------------------------------------------------------
-/** Pull recent, non-archived sessions newest-first. Never raises. */
-function collectSessionRows(stateDb, limit = DEFAULT_SESSION_LIMIT) {
-    if (!isFile(stateDb))
-        return [];
-    const conn = tryOpenReadonly(stateDb);
-    if (!conn)
-        return [];
-    const out = [];
-    try {
-        if (!tableExists(conn, "sessions"))
-            return [];
-        // `archived` may be absent in older schemas — guard the column.
-        const cols = tableColumns(conn, "sessions");
-        const archivedClause = cols.has("archived") ? "WHERE COALESCE(archived, 0) = 0" : "";
-        const rows = conn
-            .prepare(`SELECT id, source, model, title, cwd, started_at, ended_at,
-                message_count, tool_call_count
-         FROM sessions
-         ${archivedClause}
-         ORDER BY started_at DESC
-         LIMIT ?`)
-            .all(limit);
-        for (const r of rows) {
-            const day = epochToIsoDate(r["started_at"]);
-            if (!day)
-                continue;
-            out.push({
-                id: String(r["id"]),
-                source: String(r["source"] ?? "").toLowerCase(),
-                model: r["model"],
-                title: r["title"] ?? null,
-                cwd: r["cwd"] ?? null,
-                date: day,
-                messageCount: Number(r["message_count"] ?? 0) || 0,
-                toolCallCount: Number(r["tool_call_count"] ?? 0) || 0,
-            });
-        }
-    }
-    catch {
-        /* degrade to whatever rows we gathered */
-    }
-    finally {
-        conn.close();
-    }
-    return out;
-}
-/** Distinct tool names used in a session, for key_actions evidence. */
-function toolNamesForSession(conn, sessionId) {
-    if (!tableExists(conn, "messages"))
-        return [];
-    try {
-        const rows = conn
-            .prepare(`SELECT DISTINCT tool_name FROM messages
-         WHERE session_id = ? AND tool_name IS NOT NULL AND tool_name != ''`)
-            .all(sessionId);
-        const names = new Set();
-        for (const r of rows) {
-            if (r.tool_name)
-                names.add(r.tool_name);
-        }
-        return [...names].sort();
-    }
-    catch {
-        return [];
-    }
-}
-// -- Memory parsing -----------------------------------------------------------
-const BULLET_RE = /^\s*[-*]\s+(.*)$/;
-/** Return memory entries (one per bullet / non-empty line). Never raises. */
-function parseMemoryFile(path) {
-    let text;
-    try {
-        text = readFileSync(path, "utf8");
-    }
-    catch {
-        return [];
-    }
-    const entries = [];
-    for (const line of text.split(/\r?\n/)) {
-        const m = BULLET_RE.exec(line);
-        const candidate = m ? (m[1] ?? "") : line.trim();
-        if (candidate && !candidate.startsWith("#"))
-            entries.push(candidate);
-    }
-    return entries;
-}
-/** Map memory store name → list of entry strings. */
-function collectMemoryEntries(home) {
-    const memDir = join(home, "memories");
-    const result = [];
-    if (!isDir(memDir))
-        return result;
-    for (const fname of MEMORY_FILENAMES) {
-        const path = join(memDir, fname);
-        if (isFile(path)) {
-            const entries = parseMemoryFile(path);
-            if (entries.length) {
-                const stem = fname.replace(/\.md$/, "");
-                result.push([stem, entries]);
-            }
-        }
-    }
-    return result;
-}
-// -- Entity / session builders ------------------------------------------------
-function buildSession(record, toolNames) {
-    const key = projectKey(record.cwd);
-    const focus = [];
-    if (key)
-        focus.push(key);
-    const keyActions = [];
-    if (record.title)
-        keyActions.push(bounded(record.title, 160));
-    if (toolNames.length) {
-        keyActions.push("Tools: " + toolNames.slice(0, 8).join(", "));
-    }
-    else if (record.toolCallCount) {
-        keyActions.push(`${record.toolCallCount} tool call(s)`);
-    }
-    return makeSession({
-        date: record.date,
-        cwd: record.cwd || undefined,
-        project_focus: focus,
-        key_actions: keyActions,
-        visibility: Visibility.TEAM,
-    });
-}
-/** Turn a single memory line into a team-visibility entity. */
-function memoryEntity(store, entry) {
-    const tag = store === "user" ? "hermes-user-memory" : "hermes-memory";
-    return makeEntity({
-        name: bounded(entry, 80),
-        type: store === "user" ? "preference" : "fact",
-        summary: bounded(entry, 240),
-        tags: [tag],
-        visibility: Visibility.TEAM,
-    });
-}
-function projectEntities(records) {
-    const counts = new Map();
-    for (const r of records) {
-        const key = projectKey(r.cwd);
-        if (key)
-            counts.set(key, (counts.get(key) ?? 0) + 1);
-    }
-    const entities = [];
-    for (const [key, count] of counts) {
-        let last;
-        for (const r of records) {
-            if (projectKey(r.cwd) === key) {
-                if (last === undefined || r.date > last)
-                    last = r.date;
-            }
-        }
-        entities.push(makeEntity({
-            name: friendlyLabel(key),
-            type: "project",
-            summary: `Workspace observed across ${count} Hermes session(s).`,
-            aliases: [key],
-            last_touched: last,
-            tags: ["hermes-project"],
-            visibility: Visibility.TEAM,
-        }));
-    }
-    return entities;
-}
-// -- Participant --------------------------------------------------------------
-/** External participant for local Hermes Agent memory + sessions. */
-export class HermesParticipant {
-    agentId = AGENT_ID;
-    agentType = AGENT_TYPE;
-    displayName = DISPLAY_NAME;
-    nativePath;
-    home;
-    static defaultNativePath(home) {
-        return defaultNativePath(home);
-    }
-    /** `hermesHome` is the `.hermes` directory itself (matching the Python ctor). */
-    constructor(hermesHome) {
-        if (hermesHome) {
-            this.home = hermesHome;
-        }
-        else {
-            const path = defaultNativePath();
-            this.home = isDir(path) ? path : null;
-        }
-        this.nativePath = this.home ?? join(homedir(), ".hermes");
-    }
-    sources() {
-        const home = this.home;
-        const stateDb = home ? join(home, "state.db") : null;
-        const memDir = home ? join(home, "memories") : null;
-        const skillsDir = home ? join(home, "skills") : null;
-        return {
-            hermes_home: home,
-            state_db: stateDb && isFile(stateDb) ? stateDb : null,
-            memories_dir: memDir && isDir(memDir) ? memDir : null,
-            skills_dir: skillsDir && isDir(skillsDir) ? skillsDir : null,
-        };
-    }
-    discover() {
-        const sources = this.sources();
-        if (!Object.values(sources).some((v) => v)) {
-            throw new ParticipantDiscoveryError("No Hermes memory sources found. Expected ~/.hermes/ (set $HERMES_HOME to override).");
-        }
-        if (!sources["state_db"] && !sources["memories_dir"]) {
-            throw new ParticipantDiscoveryError(`Hermes home '${this.nativePath}' exists but has no state.db or memories/ — ` +
-                "nothing to federate yet.");
-        }
-        return {
-            path: this.nativePath,
-            version: "hermes-home-v1",
-            metadata: { sources },
-        };
-    }
-    exportSessions(since, limit = DEFAULT_SESSION_LIMIT) {
-        if (this.home === null)
-            return [];
-        const stateDb = join(this.home, "state.db");
-        const cutoff = since ? since.toISOString().slice(0, 10) : null;
-        const records = collectSessionRows(stateDb, limit);
-        if (!records.length)
-            return [];
-        const conn = tryOpenReadonly(stateDb);
-        const out = [];
-        try {
-            for (const rec of records) {
-                if (cutoff && rec.date < cutoff)
-                    continue;
-                const tools = conn ? toolNamesForSession(conn, rec.id) : [];
-                out.push(buildSession(rec, tools));
-            }
-        }
-        finally {
-            if (conn)
-                conn.close();
-        }
-        return out;
-    }
-    exportL5(since) {
-        const store = this.discover();
-        const sources = (store.metadata["sources"] ?? {});
-        const capabilities = Object.entries(sources)
-            .filter(([k, v]) => v && k !== "hermes_home")
-            .map(([k]) => k)
-            .sort();
-        const home = this.home;
-        const records = home ? collectSessionRows(join(home, "state.db"), DEFAULT_SESSION_LIMIT) : [];
-        // Entities: project workspaces + memory-derived facts/preferences.
-        const entities = projectEntities(records);
-        const seen = new Set();
-        for (const e of entities) {
-            seen.add(`${e.type || "topic"}${e.name.toLowerCase()}`);
-        }
-        if (home) {
-            for (const [storeName, entries] of collectMemoryEntries(home)) {
-                for (const entry of entries) {
-                    const ent = memoryEntity(storeName, entry);
-                    const key = `${ent.type || "topic"}${ent.name.toLowerCase()}`;
-                    if (seen.has(key))
-                        continue;
-                    seen.add(key);
-                    entities.push(ent);
-                }
-            }
-        }
-        // Visibility enforced here, before emission (contract requirement).
-        const visible = filterForFederation(entities, DEFAULT_POLICY);
-        const sessions = this.exportSessions(since ?? new Date(0), DEFAULT_SESSION_LIMIT);
-        return makeManifest({
-            spec_version: SPEC_VERSION,
-            agent: makeAgentInfo({
-                id: this.agentId,
-                type: this.agentType,
-                role_narrative: ROLE_NARRATIVE,
-                spec_version_compat: CONTRACT_VERSION,
-            }),
-            last_updated: new Date().toISOString(),
-            capabilities,
-            recent_sessions: sessions,
-            known_entities: visible,
-            visibility_policy: DEFAULT_POLICY,
-        });
-    }
-    healthCheck() {
-        const details = {
-            hermes_home: this.nativePath,
-            state_db: "missing",
-            memories_dir: "missing",
-            skills_dir: "missing",
-        };
-        try {
-            if (this.home === null) {
-                return {
-                    status: "blocked",
-                    reason: "~/.hermes/ not found — Hermes Agent not installed here",
-                    details,
-                    proposedFix: "Install Hermes Agent and run a session once, then `bourdon export-all`.",
-                };
-            }
-            const sources = this.sources();
-            for (const key of ["state_db", "memories_dir", "skills_dir"]) {
-                if (sources[key])
-                    details[key] = sources[key];
-            }
-            if (sources["state_db"]) {
-                const records = collectSessionRows(join(this.home, "state.db"), 1);
-                if (records.length)
-                    return { status: "ok", details };
-                return {
-                    status: "degraded",
-                    reason: "state.db present but no readable sessions yet",
-                    details,
-                    proposedFix: "Run at least one Hermes session, then `bourdon export-all`.",
-                };
-            }
-            if (sources["memories_dir"]) {
-                return {
-                    status: "degraded",
-                    reason: "memories/ present but state.db missing — session history unavailable",
-                    details,
-                };
-            }
-            return {
-                status: "blocked",
-                reason: "Hermes home has neither state.db nor memories/",
-                details,
-                proposedFix: "Run a Hermes session to populate ~/.hermes/state.db.",
-            };
-        }
-        catch (err) {
-            // healthCheck must NEVER raise (contract).
-            return {
-                status: "degraded",
-                reason: `unexpected error: ${String(err)}`,
-                details,
-            };
-        }
-    }
-}

package/dist/readers/openclaw.d.ts

@@ -1,78 +0,0 @@
-/**
- * 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 { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
-import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
-/** First OpenClaw release that patches CVE-2026-25253 (one-click RCE). */
-export 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.
- */
-export 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}".
- */
-export 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). */
-export 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;
-}