@getbourdon/participants 0.1.1 → 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/registry.d.ts

@@ -1,38 +0,0 @@
-/**
- * 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`. (cursor / codex / copilot_cli are the heavier SQLite readers of the
- * follow-on slice; openclaw ships as the `@getbourdon/openclaw` plugin.)
- */
-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

@@ -1,73 +0,0 @@
-/**
- * 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 { ClaudeCodeParticipant } from "./readers/claude-code.js";
-import { GitHubCopilotParticipant } from "./readers/github-copilot.js";
-import { HermesParticipant } from "./readers/hermes.js";
-/**
- * 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.)
- */
-export const FIRST_PARTY = [
-    ClaudeCodeParticipant,
-    GitHubCopilotParticipant,
-    HermesParticipant,
-];
-/** 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

@@ -1,65 +0,0 @@
-/**
- * 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;