@getbourdon/participants 0.1.0

package/dist/network-base.js

@@ -0,0 +1,248 @@
+/**
+ * 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).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ParticipantError, } from "./base.js";
+export const NETWORK_CONTRACT_VERSION = "0.3";
+/** Default cache TTL — adapters override via `cacheTtlSeconds`. */
+export const DEFAULT_CACHE_TTL_SECONDS = 15 * 60; // 15 minutes
+// -- Network-specific errors --------------------------------------------------
+/** Transport failure / timeout / 5xx / rate-limit — recoverable via cache fallback. */
+export 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). */
+export class ParticipantAuthError extends ParticipantError {
+}
+/** Auth provider that reads a token from an environment variable. */
+export function envAuthProvider(varName) {
+    return () => process.env[varName] || null;
+}
+// -- Cache --------------------------------------------------------------------
+/** `$XDG_CACHE_HOME/bourdon` or `~/.cache/bourdon`. */
+export function defaultCacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg ? xdg : join(homedir(), ".cache");
+    return join(base, "bourdon");
+}
+/** A cached payload + the wall-clock time it was fetched (epoch seconds). */
+export class CacheEntry {
+    fetchedAt;
+    payload;
+    constructor(fetchedAt, payload) {
+        this.fetchedAt = fetchedAt;
+        this.payload = payload;
+    }
+    get ageSeconds() {
+        return Math.max(0, Date.now() / 1000 - this.fetchedAt);
+    }
+    isFresh(ttlSeconds) {
+        return this.ageSeconds < ttlSeconds;
+    }
+}
+/**
+ * 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.
+ */
+export class PayloadCache {
+    slug;
+    root;
+    path;
+    constructor(slug, rootDir) {
+        this.slug = slug;
+        this.root = join(rootDir ?? defaultCacheRoot(), slug);
+        this.path = join(this.root, "payload.json");
+    }
+    read() {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            return null;
+        }
+        if (typeof raw !== "object" || raw === null || !("payload" in raw))
+            return null;
+        const obj = raw;
+        let fetchedAt = Number(obj["fetched_at"] ?? 0);
+        if (!Number.isFinite(fetchedAt))
+            fetchedAt = 0;
+        const payload = obj["payload"];
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+            return null;
+        return new CacheEntry(fetchedAt, payload);
+    }
+    write(payload) {
+        try {
+            mkdirSync(this.root, { recursive: true });
+            const tmp = `${this.path}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ fetched_at: Date.now() / 1000, payload }), "utf8");
+            renameSync(tmp, this.path); // atomic
+        }
+        catch {
+            /* best-effort; a write failure degrades to "no cache" */
+        }
+    }
+}
+// -- Base participant ---------------------------------------------------------
+/**
+ * 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`.
+ */
+export class NetworkParticipant {
+    participantSlug = "network";
+    agentId = "network";
+    agentType = "other";
+    cacheTtlSeconds = DEFAULT_CACHE_TTL_SECONDS;
+    nativePath = "network://";
+    authProvider;
+    cacheRoot;
+    cacheInstance;
+    constructor(opts = {}) {
+        this.authProvider = opts.authProvider ?? null;
+        this.cacheRoot = opts.cacheRoot;
+    }
+    /** 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. */
+    get cache() {
+        if (!this.cacheInstance) {
+            this.cacheInstance = new PayloadCache(this.participantSlug, this.cacheRoot);
+        }
+        return this.cacheInstance;
+    }
+    // -- Core fetch-with-cache-and-degrade -------------------------------------
+    /**
+     * 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.
+     */
+    getPayload() {
+        const cached = this.cache.read();
+        if (cached !== null && cached.isFresh(this.cacheTtlSeconds)) {
+            return { payload: cached.payload, source: "cache" };
+        }
+        const token = this.authProvider ? this.authProvider() : null;
+        if (!token) {
+            // No credential: if we have any cache, serve it stale; else blocked.
+            if (cached !== null)
+                return { payload: cached.payload, source: "stale-cache" };
+            throw new ParticipantAuthError(`${this.participantSlug}: no auth token available and no cache`);
+        }
+        let payload;
+        try {
+            payload = this.fetchPayload(token);
+        }
+        catch (err) {
+            if (err instanceof ParticipantAuthError)
+                throw err; // never mask a bad token
+            if (err instanceof NetworkUnavailable) {
+                if (cached !== null)
+                    return { payload: cached.payload, source: "stale-cache" };
+                throw err;
+            }
+            throw err;
+        }
+        this.cache.write(payload);
+        return { payload, source: "network" };
+    }
+    // -- Participant protocol ---------------------------------------------------
+    discover() {
+        const { source } = this.getPayload();
+        return {
+            path: this.nativePath,
+            version: `${this.participantSlug}-network-v1`,
+            metadata: { source, contract_version: NETWORK_CONTRACT_VERSION },
+        };
+    }
+    exportL5(_since) {
+        const { payload } = this.getPayload();
+        return this.payloadToL5(payload);
+    }
+    exportSessions(since, limit = 100) {
+        const manifest = this.exportL5(since);
+        let sessions = manifest.recent_sessions ?? [];
+        if (since) {
+            const cutoff = since.toISOString().slice(0, 10);
+            sessions = sessions.filter((s) => (s.date || "") >= cutoff);
+        }
+        return sessions.slice(0, limit);
+    }
+    healthCheck() {
+        let source;
+        try {
+            source = this.getPayload().source;
+        }
+        catch (err) {
+            if (err instanceof ParticipantAuthError) {
+                return {
+                    status: "blocked",
+                    reason: String(err.message),
+                    details: { participant: this.participantSlug },
+                    proposedFix: `Provide a valid credential for ${this.participantSlug} ` +
+                        "(see the adapter docs for the auth path) and re-run `bourdon export-all`.",
+                };
+            }
+            if (err instanceof NetworkUnavailable) {
+                return {
+                    status: "degraded",
+                    reason: `network unavailable and no cache: ${err.message}`,
+                    details: { participant: this.participantSlug },
+                    proposedFix: "Check connectivity, then re-run `bourdon export-all`.",
+                };
+            }
+            // Defense in depth: health_check must NEVER raise. An adapter's
+            // fetchPayload should only raise the two contract errors; anything else is
+            // reported as blocked rather than propagated.
+            return {
+                status: "blocked",
+                reason: `unexpected error resolving payload: ${String(err)}`,
+                details: { participant: this.participantSlug },
+                proposedFix: `${this.participantSlug} raised an unexpected error during healthCheck; ` +
+                    "its fetchPayload should only raise ParticipantAuthError / NetworkUnavailable.",
+            };
+        }
+        const cached = this.cache.read();
+        const details = { participant: this.participantSlug, source };
+        if (cached !== null) {
+            details["cache_age_seconds"] = Math.round(cached.ageSeconds * 10) / 10;
+            details["cache_fetched_at"] = new Date(cached.fetchedAt * 1000)
+                .toISOString()
+                .replace(/\.\d{3}Z$/, "+00:00");
+        }
+        if (source === "stale-cache") {
+            return {
+                status: "degraded",
+                reason: "serving stale cache (network unavailable or no token)",
+                details,
+                proposedFix: "Restore connectivity / refresh the token to update.",
+            };
+        }
+        return { status: "ok", details };
+    }
+}

package/dist/readers/claude-code.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+/** External participant for Anthropic's Claude Code CLI. */
+export 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;
+}