@getbourdon/participants 0.2.3 → 0.3.0

package/dist/readers/copilot-cli.js

@@ -0,0 +1,416 @@
+/**
+ * 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.
+ */
+import { statSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
+import { redactText } from "@getbourdon/redaction";
+import { ParticipantDiscoveryError, SPEC_VERSION, } from "../base.js";
+import { tryOpenReadonly } from "../sqlite-base.js";
+const AGENT_ID = "copilot-cli";
+const AGENT_TYPE = "code-assistant";
+const DISPLAY_NAME = "GitHub Copilot CLI";
+const ROLE_NARRATIVE = "Terminal-native Copilot agent with full filesystem + tool access. " +
+    "Runs multi-turn sessions with checkpoints, file edits, and git " +
+    "operations. The CLI surface has the deepest tool integration of " +
+    "all Copilot surfaces — shell, grep, edit, git — and persists " +
+    "rich session history locally in SQLite.";
+const DEFAULT_POLICY = makeVisibilityPolicy({
+    default: Visibility.TEAM,
+    private_tags: ["personal", "financial", "credential", "health", "family", "legal"],
+    team_tags: ["copilot-cli", "copilot", "terminal", "workspace"],
+});
+const DB_FILENAME = "session-store.db";
+const COPILOT_DIR_NAME = ".copilot";
+const MAX_SUMMARY_CHARS = 260;
+const MAX_KEY_ACTIONS = 6;
+const MAX_KEY_ACTION_CHARS = 280;
+// -- Path resolution ----------------------------------------------------------
+/**
+ * Conventional `~/.copilot/` directory. Respects the `COPILOT_CLI_HOME`
+ * environment-variable override (mirrors `default_copilot_cli_dir`).
+ */
+export function defaultCopilotCliDir() {
+    const env = process.env.COPILOT_CLI_HOME;
+    if (env)
+        return env;
+    return join(homedir(), COPILOT_DIR_NAME);
+}
+/** Path to `session-store.db` under the given (or conventional) copilot dir. */
+function defaultCopilotCliDbPath(copilotDir) {
+    return join(copilotDir ?? defaultCopilotCliDir(), DB_FILENAME);
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// -- Text helpers -------------------------------------------------------------
+/** Redact secrets + clamp to the native-memory limit (`_safe_native_memory_text`). */
+function safeNativeMemoryText(value, limit = 180) {
+    return redactText(value, limit);
+}
+/**
+ * Collapse whitespace and clamp with a single-char ellipsis (mirrors the
+ * oracle's `_bounded`). NOTE: distinct from {@link redactText}'s `...` clamp —
+ * this one uses `…` (U+2026) and does no redaction.
+ */
+function bounded(value, limit) {
+    const normalized = value.split(/\s+/).filter(Boolean).join(" ");
+    if (normalized.length <= limit)
+        return normalized;
+    return normalized.slice(0, limit - 1).replace(/\s+$/, "") + "…";
+}
+// -- SQLite (read-only) -------------------------------------------------------
+/** Run a query and return rows as plain objects. Never raises (a missing table
+ * or any SQLite error degrades to `[]`, matching the oracle's `_query_db`). */
+function queryDb(db, sql, params = []) {
+    try {
+        return db.prepare(sql).all(...params);
+    }
+    catch {
+        return [];
+    }
+}
+function extractSessions(db, since) {
+    let sql = "SELECT id, cwd, repository, branch, summary, created_at, updated_at FROM sessions";
+    const params = [];
+    if (since) {
+        sql += " WHERE created_at >= ?";
+        params.push(since);
+    }
+    sql += " ORDER BY created_at DESC LIMIT 200";
+    return queryDb(db, sql, params);
+}
+function extractSessionFiles(db, sessionId) {
+    const rows = queryDb(db, "SELECT file_path FROM session_files WHERE session_id = ? LIMIT 20", [sessionId]);
+    const out = [];
+    for (const r of rows) {
+        const fp = r["file_path"];
+        if (fp)
+            out.push(String(fp));
+    }
+    return out;
+}
+function extractSessionRefs(db, sessionId) {
+    const rows = queryDb(db, "SELECT ref_type, ref_value FROM session_refs WHERE session_id = ?", [sessionId]);
+    return rows.map((r) => ({
+        ref_type: String(r["ref_type"] ?? ""),
+        ref_value: String(r["ref_value"] ?? ""),
+    }));
+}
+function extractCheckpoints(db, sessionId) {
+    return queryDb(db, "SELECT checkpoint_number, title, overview FROM checkpoints " +
+        "WHERE session_id = ? ORDER BY checkpoint_number", [sessionId]);
+}
+function extractDynamicContext(db) {
+    return queryDb(db, "SELECT repository, branch, src, name, description, content, read_count, count " +
+        "FROM dynamic_context_items ORDER BY count DESC LIMIT 50");
+}
+function extractTurnCount(db, sessionId) {
+    const rows = queryDb(db, "SELECT COUNT(*) as cnt FROM turns WHERE session_id = ?", [sessionId]);
+    const first = rows[0];
+    return first ? Number(first["cnt"] ?? 0) || 0 : 0;
+}
+// -- Conversion to Bourdon types ----------------------------------------------
+function sessionToBourdon(raw, files, refs, checkpoints, turnCount) {
+    const created = raw["created_at"] ? String(raw["created_at"]) : "";
+    const dateStr = created ? created.slice(0, 10) : "";
+    const keyActions = [];
+    if (raw["summary"]) {
+        keyActions.push(bounded(safeNativeMemoryText(String(raw["summary"])), MAX_KEY_ACTION_CHARS));
+    }
+    for (const cp of checkpoints.slice(0, 3)) {
+        if (cp["title"]) {
+            keyActions.push(bounded(`checkpoint: ${safeNativeMemoryText(String(cp["title"]))}`, MAX_KEY_ACTION_CHARS));
+        }
+    }
+    if (turnCount) {
+        keyActions.push(`turns: ${turnCount}`);
+    }
+    for (const ref of refs.slice(0, 3)) {
+        const refLabel = `${ref.ref_type}: ${ref.ref_value}`;
+        keyActions.push(bounded(refLabel, MAX_KEY_ACTION_CHARS));
+    }
+    const projectFocus = [];
+    if (raw["repository"])
+        projectFocus.push(String(raw["repository"]));
+    return makeSession({
+        date: dateStr,
+        cwd: raw["cwd"] ? String(raw["cwd"]) : undefined,
+        project_focus: projectFocus,
+        key_actions: keyActions.slice(0, MAX_KEY_ACTIONS),
+        files_touched: files.slice(0, 20),
+        visibility: Visibility.TEAM,
+    });
+}
+function entitiesFromSessionsAndContext(sessions, dynamicContext) {
+    const entities = new Map();
+    // Repositories as project entities.
+    for (const raw of sessions) {
+        const repo = raw["repository"] ? String(raw["repository"]) : "";
+        if (repo && !entities.has(repo)) {
+            const created = raw["created_at"] ? String(raw["created_at"]) : "";
+            const lastTouched = created.slice(0, 10) || null;
+            entities.set(repo, makeEntity({
+                name: repo,
+                type: "project",
+                summary: "Repository worked on via Copilot CLI.",
+                last_touched: lastTouched ?? undefined,
+                tags: ["copilot-cli", "project"],
+                visibility: Visibility.TEAM,
+            }));
+        }
+    }
+    // Dynamic context items as knowledge entities.
+    for (const ctx of dynamicContext) {
+        const name = ctx["name"] ? String(ctx["name"]) : "";
+        if (!name || entities.has(name))
+            continue;
+        const desc = ctx["description"] ? String(ctx["description"]) : "";
+        const content = ctx["content"] ? String(ctx["content"]) : "";
+        let summaryText = desc || content;
+        if (summaryText) {
+            summaryText = bounded(safeNativeMemoryText(summaryText), MAX_SUMMARY_CHARS);
+        }
+        entities.set(name, makeEntity({
+            name,
+            type: "dynamic-context",
+            summary: summaryText || undefined,
+            last_touched: undefined,
+            tags: ["copilot-cli", "dynamic-context", ctx["src"] ? String(ctx["src"]) : "unknown"],
+            visibility: Visibility.TEAM,
+        }));
+    }
+    return [...entities.values()];
+}
+/** UTC ISO datetime with `+00:00` offset (matching Python `isoformat`). */
+function toUtcIso(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "+00:00").replace(/Z$/, "+00:00");
+}
+// -- Participant --------------------------------------------------------------
+/**
+ * External participant for GitHub Copilot CLI (`~/.copilot/session-store.db`).
+ * Reads the SQLite database read-only (never locks the live db).
+ */
+export class CopilotCliParticipant {
+    agentId = AGENT_ID;
+    agentType = AGENT_TYPE;
+    displayName = DISPLAY_NAME;
+    nativePath;
+    copilotDir;
+    /** Conventional `~/.copilot` dir used by the setup wizard's detection. */
+    static defaultNativePath(home) {
+        if (home)
+            return join(home, COPILOT_DIR_NAME);
+        return defaultCopilotCliDir();
+    }
+    constructor(copilotDir) {
+        this.copilotDir = copilotDir ?? null;
+        this.nativePath = this.copilotDir ?? defaultCopilotCliDir();
+    }
+    // -- Protocol surface -------------------------------------------------------
+    discover() {
+        const dbPath = defaultCopilotCliDbPath(this.copilotDir);
+        if (!isFile(dbPath)) {
+            throw new ParticipantDiscoveryError(`Copilot CLI session-store.db not found at ${dbPath}. ` +
+                "The Copilot CLI agent must be run at least once to create this database.");
+        }
+        let dbSize = 0;
+        try {
+            dbSize = statSync(dbPath).size;
+        }
+        catch {
+            dbSize = 0;
+        }
+        return {
+            path: dirname(dbPath),
+            version: "schema-v4",
+            metadata: { db_path: dbPath, db_size_bytes: dbSize },
+        };
+    }
+    exportSessions(since, limit = 100) {
+        const dbPath = defaultCopilotCliDbPath(this.copilotDir);
+        const db = tryOpenReadonly(dbPath);
+        if (!db)
+            return [];
+        try {
+            const sinceIso = since ? toUtcIso(since) : null;
+            const rawSessions = extractSessions(db, sinceIso);
+            const sessions = [];
+            for (const raw of rawSessions.slice(0, limit)) {
+                const sid = String(raw["id"]);
+                const files = extractSessionFiles(db, sid);
+                const refs = extractSessionRefs(db, sid);
+                const checkpoints = extractCheckpoints(db, sid);
+                const turnCount = extractTurnCount(db, sid);
+                sessions.push(sessionToBourdon(raw, files, refs, checkpoints, turnCount));
+            }
+            return sessions;
+        }
+        finally {
+            db.close();
+        }
+    }
+    exportL5(since) {
+        const dbPath = defaultCopilotCliDbPath(this.copilotDir);
+        const db = tryOpenReadonly(dbPath);
+        if (!db)
+            return this.emptyManifest();
+        try {
+            const sinceIso = since ? toUtcIso(since) : null;
+            const rawSessions = extractSessions(db, sinceIso);
+            const dynamicContext = extractDynamicContext(db);
+            const sessions = [];
+            for (const raw of rawSessions.slice(0, 100)) {
+                const sid = String(raw["id"]);
+                const files = extractSessionFiles(db, sid);
+                const refs = extractSessionRefs(db, sid);
+                const checkpoints = extractCheckpoints(db, sid);
+                const turnCount = extractTurnCount(db, sid);
+                sessions.push(sessionToBourdon(raw, files, refs, checkpoints, turnCount));
+            }
+            const entities = entitiesFromSessionsAndContext(rawSessions, dynamicContext);
+            const visibleEntities = filterForFederation(entities, DEFAULT_POLICY);
+            return makeManifest({
+                spec_version: SPEC_VERSION,
+                agent: makeAgentInfo({
+                    id: AGENT_ID,
+                    type: AGENT_TYPE,
+                    instance: hostname() || "unknown",
+                    spec_version_compat: `>=${SPEC_VERSION}`,
+                    role_narrative: ROLE_NARRATIVE,
+                }),
+                last_updated: new Date().toISOString(),
+                capabilities: [
+                    "terminal-agent",
+                    "file-edit",
+                    "shell-execution",
+                    "git-operations",
+                    "multi-turn-sessions",
+                    "checkpoints",
+                    "dynamic-context",
+                ],
+                recent_sessions: sessions,
+                known_entities: visibleEntities,
+                visibility_policy: DEFAULT_POLICY,
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    healthCheck() {
+        try {
+            const copilotDir = this.copilotDir ?? defaultCopilotCliDir();
+            if (!isDir(copilotDir)) {
+                return {
+                    status: "blocked",
+                    reason: `Copilot CLI directory not found at ${copilotDir}.`,
+                    details: { expected_path: copilotDir },
+                    proposedFix: "Run the Copilot CLI agent (`copilot` or `gh copilot`) at least once " +
+                        "to create the session store.",
+                };
+            }
+            const dbPath = defaultCopilotCliDbPath(copilotDir);
+            if (!isFile(dbPath)) {
+                return {
+                    status: "blocked",
+                    reason: `session-store.db not found at ${dbPath}.`,
+                    details: { expected_db: dbPath },
+                    proposedFix: "Run the Copilot CLI agent at least once. The session-store.db is " +
+                        "created on first use.",
+                };
+            }
+            const db = tryOpenReadonly(dbPath);
+            if (!db) {
+                return {
+                    status: "degraded",
+                    reason: "Cannot copy session-store.db for reading.",
+                    details: { db_path: dbPath },
+                    proposedFix: "Check file permissions on the session-store.db.",
+                };
+            }
+            try {
+                const rawSessions = extractSessions(db);
+                const dynamicContext = extractDynamicContext(db);
+                const totalTurns = queryDb(db, "SELECT COUNT(*) as cnt FROM turns");
+                const first = totalTurns[0];
+                let dbSize = 0;
+                try {
+                    dbSize = statSync(dbPath).size;
+                }
+                catch {
+                    dbSize = 0;
+                }
+                return {
+                    status: "ok",
+                    details: {
+                        db_path: dbPath,
+                        db_size_bytes: dbSize,
+                        session_count: rawSessions.length,
+                        total_turns: first ? Number(first["cnt"] ?? 0) || 0 : 0,
+                        dynamic_context_items: dynamicContext.length,
+                    },
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            // healthCheck must NEVER raise (contract).
+            return {
+                status: "degraded",
+                reason: `unexpected error: ${String(err)}`,
+                details: {},
+            };
+        }
+    }
+    // -- Internal ---------------------------------------------------------------
+    emptyManifest() {
+        return makeManifest({
+            spec_version: SPEC_VERSION,
+            agent: makeAgentInfo({
+                id: AGENT_ID,
+                type: AGENT_TYPE,
+                instance: hostname() || "unknown",
+                spec_version_compat: `>=${SPEC_VERSION}`,
+                role_narrative: ROLE_NARRATIVE,
+            }),
+            last_updated: new Date().toISOString(),
+            capabilities: [],
+            recent_sessions: [],
+            known_entities: [],
+            visibility_policy: DEFAULT_POLICY,
+        });
+    }
+}

package/dist/readers/copilot-vscode.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GitHub Copilot · VS Code participant — reads the GUI Copilot Chat extension's
+ * per-workspace transcripts + repo-scoped memory. Port of
+ * `participants/copilot_vscode.py`.
+ *
+ * VS Code's Copilot Chat extension stores per-workspace data at
+ * `<workspaceStorage>/<hash>/GitHub.copilot-chat/`:
+ *   - `transcripts/<session-uuid>.jsonl` — event stream per chat session
+ *   - `memory-tool/memories/**\/*.md`    — per-repo memory (markdown bullets)
+ *
+ * This is a FILE/CONVENTION reader (not SQLite, not network): it walks the
+ * workspaceStorage tree read-only, parses JSONL transcripts + markdown memory
+ * files, aggregates across every workspace hash, redacts every native string,
+ * applies the visibility filter BEFORE emission, and is deterministic.
+ * `healthCheck` never throws.
+ *
+ * Distinct from:
+ *   - `copilot`        (convention-file at `~/.copilot-bourdon/memory.md`)
+ *   - `copilot-cli`    (terminal agent, `~/.copilot/session-store.db`, SQLite)
+ *   - `github-copilot` (network reader — GitHub-embedded Copilot)
+ */
+import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+/**
+ * Return the VS Code workspaceStorage path for this platform, or null when it
+ * cannot be resolved (Windows without `%APPDATA%`). Respects the
+ * `COPILOT_VSCODE_STORAGE` environment-variable override. Mirrors
+ * `default_vscode_workspace_storage_dir`.
+ */
+export declare function defaultVscodeWorkspaceStorageDir(): string | null;
+/**
+ * External participant for GitHub Copilot in VS Code. Reads transcripts and
+ * memory-tool files from VS Code's workspaceStorage read-only, aggregating
+ * across all workspace hashes.
+ */
+export declare class CopilotVscodeParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    private readonly workspaceStorage;
+    /** The workspaceStorage dir the setup wizard probes for presence. */
+    static defaultNativePath(home?: string): string;
+    constructor(workspaceStorage?: string);
+    get nativePath(): string;
+    private resolveWs;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    /** Collect and parse all transcripts across all workspaces. */
+    private allTranscripts;
+    /** Collect all memory-tool files across all workspaces. */
+    private allMemories;
+}