@getbourdon/participants 0.2.3 → 0.3.0

package/dist/readers/codex-sessions.js

@@ -0,0 +1,194 @@
+/**
+ * Codex session-index title lookup — narrow port of the three
+ * `session_thread_titles` helpers in `participants/codex.py`.
+ *
+ * SCOPE (deliberately tiny): this is NOT the Codex participant/reader (the
+ * ~2.6k-line turn-compiler still lands in a follow-on slice). It ports ONLY the
+ * surface the tray/presence join needs — a `session_id -> human thread title`
+ * map read from `~/.codex/session_index.jsonl`.
+ *
+ * Why only the index: `session_thread_titles()` runs on EVERY tray refresh, so
+ * it must never touch rollout files. One small JSONL read, newest-first, done.
+ * It covers Codex CLI sessions AND ChatGPT-app threads — the app's Work and
+ * Codex modes share `~/.codex`, so `thread_name` is the human title for both.
+ *
+ * PRIVACY: titles are raw user text. Callers that EXPORT them MUST route them
+ * through the audited redaction pipeline (`redactField` in
+ * `mcp-server/src/agents-export.ts`, == Python's `_redact_field`), exactly like
+ * every other emitted string. This module deliberately does NOT redact — the
+ * redaction happens at the single audited egress point so it can't be
+ * double-applied or silently skipped.
+ *
+ * Best-effort by construction: a missing dir, an unreadable file, or a corrupt
+ * line degrades to fewer/no titles. Nothing here throws.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Default number of index records considered (newest-first). */
+export const DEFAULT_TITLE_LIMIT = 200;
+/** Default number of threads on the tray codex card (newest-first). */
+export const DEFAULT_RECENT_THREAD_LIMIT = 5;
+/** Collapse internal whitespace runs — mirrors Python `_normalize_text`. */
+function normalizeText(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate `~/.codex/` (the primary Codex store), or null.
+ *
+ * Resolution order, mirroring `_resolve_codex_home()` exactly:
+ *   1. `$CODEX_HOME` — **only if that directory already exists**
+ *   2. `~/.codex`    — only if it exists
+ *   3. `null`
+ *
+ * ⚠ FOOTGUN (preserved for parity, do not "fix" without changing Python too):
+ * step 1 is a silent fallback, not a pin. If `$CODEX_HOME` points at a path that
+ * does not exist yet, the env var is IGNORED and this returns the developer's
+ * REAL `~/.codex`. A sandbox/test that sets `CODEX_HOME` to a temp path without
+ * `mkdir`-ing it first looks isolated but reads live data. Always create the
+ * directory before setting the variable.
+ */
+export function resolveCodexHome(baseHome) {
+    const env = process.env.CODEX_HOME;
+    if (env) {
+        // Existence check FIRST — see the footgun note above.
+        if (isDir(env))
+            return env;
+    }
+    const home = baseHome ? baseHome : homedir();
+    const candidate = join(home, ".codex");
+    return isDir(candidate) ? candidate : null;
+}
+/**
+ * Read `session_index.jsonl`, newest-first by `updated_at`.
+ *
+ * Port of `_parse_session_index()`. Per-line JSON parse: a malformed line is
+ * WARNED and SKIPPED — it never aborts the scan (one bad append must not blind
+ * the tray to every other session). An unreadable file warns and yields `[]`.
+ * Only records that are objects with a string `id` are kept.
+ */
+export function parseSessionIndex(path, limit) {
+    let text;
+    try {
+        if (!statSync(path).isFile())
+            return [];
+        text = readFileSync(path, "utf8");
+    }
+    catch (exc) {
+        // Covers both "missing" (Python's `is_file()` guard) and OSError-on-read.
+        if (existsQuiet(path))
+            console.warn(`Failed to read ${path}: ${String(exc)}`);
+        return [];
+    }
+    const entries = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (exc) {
+            console.warn(`Skipping malformed JSONL in ${path}:${i + 1} -- ${String(exc)}`);
+            continue;
+        }
+        if (record !== null &&
+            typeof record === "object" &&
+            !Array.isArray(record) &&
+            typeof record.id === "string") {
+            entries.push(record);
+        }
+    }
+    // Descending by `updated_at` (missing key sorts as ""), stable on ties —
+    // mirrors Python's `sort(key=..., reverse=True)` on a stable sort.
+    entries.sort((a, b) => {
+        const ua = String(a.updated_at ?? "");
+        const ub = String(b.updated_at ?? "");
+        return ua < ub ? 1 : ua > ub ? -1 : 0;
+    });
+    return limit !== undefined && limit !== null ? entries.slice(0, limit) : entries;
+}
+/** True if the path exists at all (distinguishes "missing" from "unreadable"). */
+function existsQuiet(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Map full Codex session id → human thread title, newest-first.
+ *
+ * Port of `session_thread_titles()`. Reads ONLY `session_index.jsonl` — no
+ * rollout I/O, because this runs on every tray refresh. A missing/malformed
+ * index yields `{}`.
+ *
+ * NEWEST WINS: entries are already sorted newest-first and the insert is a
+ * `setdefault` equivalent, so the freshest `thread_name` for a repeated id is
+ * the one kept.
+ *
+ * Titles are RAW USER TEXT — see the module note; the exporter redacts.
+ */
+export function sessionThreadTitles(codexHome, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_TITLE_LIMIT;
+    const home = codexHome === undefined || codexHome === null ? resolveCodexHome() : codexHome;
+    if (home === null)
+        return {};
+    const titles = {};
+    for (const entry of parseSessionIndex(join(home, "session_index.jsonl"), limit)) {
+        const sid = entry.id;
+        const name = entry.thread_name;
+        if (typeof sid === "string" &&
+            sid &&
+            typeof name === "string" &&
+            name.trim() &&
+            !(sid in titles) // setdefault: first (== newest) wins
+        ) {
+            titles[sid] = normalizeText(name);
+        }
+    }
+    return titles;
+}
+/**
+ * Newest-first `[{instance, title, updated_at}]` for the tray codex card.
+ *
+ * Port of `recent_session_threads()`. Independent of PRESENCE: ChatGPT-app
+ * threads fire no presence hooks, so this is the only way they surface.
+ *
+ * Emits only the 8-char `instance` prefix — parity with `presence.summarize`:
+ * a full session id never leaves the local read path. Titles are RAW USER TEXT;
+ * the exporter redacts them (see `sessionThreadTitles`).
+ */
+export function recentSessionThreads(codexHome, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_RECENT_THREAD_LIMIT;
+    const home = codexHome === undefined || codexHome === null ? resolveCodexHome() : codexHome;
+    if (home === null)
+        return [];
+    const threads = [];
+    for (const entry of parseSessionIndex(join(home, "session_index.jsonl"), limit)) {
+        const sid = entry.id;
+        if (typeof sid !== "string" || !sid)
+            continue;
+        const name = entry.thread_name;
+        const title = typeof name === "string" && name.trim() ? normalizeText(name) : null;
+        const updated = String(entry.updated_at ?? "");
+        threads.push({
+            instance: sid.slice(0, 8),
+            title,
+            updated_at: updated || null,
+        });
+    }
+    return threads;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * GitHub Copilot · Automations participant — convention-file reader. Port of
+ * `participants/copilot_automations.py`.
+ *
+ * GitHub Copilot can be triggered by GitHub Actions workflows, scheduled tasks,
+ * and event-driven automations (issue triage, PR review, etc.). These run on a
+ * separate memory surface from both the CLI agent and the VS Code extension.
+ * Copilot automations have no standardized local state dump, so — mirroring the
+ * codex-automations reader — this participant uses a CONVENTION directory:
+ *
+ *   ~/.copilot-bourdon/automations/<automation-id>/
+ *       automation.toml   — id, name, status, trigger, kind, repos
+ *       memory.md         — dated bullet entries, one block per run
+ *
+ * Each `automation.toml` describes a recurring automation; each dated section of
+ * `memory.md` captures what happened in that run. Users or CI scripts maintain
+ * these files.
+ *
+ * Path resolution (matches the oracle):
+ *   1. `COPILOT_AUTOMATIONS_HOME` env-var override (verbatim, → /automations skipped:
+ *      the override IS the automations dir).
+ *   2. `~/.copilot-bourdon/automations/` (default convention path).
+ *
+ * Defensive throughout: a missing automations directory raises
+ * {@link ParticipantDiscoveryError} from `discover()`; a malformed
+ * `automation.toml` or unreadable `memory.md` is logged and skipped rather than
+ * raising; `healthCheck` never throws.
+ */
+import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+/**
+ * Return the conventional `~/.copilot-bourdon/automations/` directory. Respects
+ * the `COPILOT_AUTOMATIONS_HOME` env-var override (returned verbatim — the
+ * override IS the automations dir, no `/automations` suffix is appended).
+ */
+export declare function defaultCopilotAutomationsDir(copilotBourdonDir?: string | null): string;
+/**
+ * Convention-based Bourdon participant for Copilot automation memory artifacts.
+ * Users or CI scripts maintain `automation.toml` + `memory.md` files at
+ * `~/.copilot-bourdon/automations/<id>/`.
+ */
+export declare class CopilotAutomationsParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    displayName: string;
+    private readonly automationsDir;
+    private readonly policy;
+    /** Conventional automations dir (`~/.copilot-bourdon/automations`). Does NOT
+     * consult `COPILOT_AUTOMATIONS_HOME` (matches Python `default_native_path`). */
+    static defaultNativePath(home?: string): string;
+    constructor(automationsDir?: string | null);
+    get nativePath(): string;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    private runs;
+}
+/**
+ * Create an automation scaffold at `<automationsDir>/<id>/`. Returns the path
+ * of the created automation directory. Throws when `automation.toml` already
+ * exists unless `force` is true.
+ */
+export declare function initAutomation(automationsDir?: string | null, automationId?: string, name?: string, force?: boolean): string;