@getbourdon/participants 0.2.2 → 0.2.3

package/dist/index.d.cts

@@ -90,6 +90,27 @@ interface BourdonParticipant {
  * duck-type: a value is a participant iff it carries the four marker members.
  */
 declare function isParticipant(obj: unknown): obj is BourdonParticipant;
+/**
+ * Environment variable holding the deployment's own project-name recognition
+ * vocabulary, as a comma-separated list (e.g.
+ * `BOURDON_PROJECT_HINTS="Acme Portal,Widget API,internal-tools"`).
+ */
+declare const PROJECT_HINTS_ENV = "BOURDON_PROJECT_HINTS";
+/**
+ * Project-name hints used to tag sessions with a project focus.
+ *
+ * Bourdon ships **no** project roster of its own — the `defaults` a reader
+ * passes are limited to product-neutral names (this product, plus the agent
+ * surfaces it federates). A deployment that wants its own projects recognized
+ * sets {@link PROJECT_HINTS_ENV}; those entries are appended to `defaults`.
+ *
+ * Matching downstream is case-insensitive substring matching, so entries are
+ * de-duplicated case-insensitively here while preserving first-seen order and
+ * the original casing (which is what gets emitted as the project name).
+ *
+ * Mirrors Python `participants.base.load_project_hints`.
+ */
+declare function loadProjectHints(defaults?: readonly string[]): readonly string[];
 
 /**
  * Shared read-only SQLite + normalization helpers — port of
@@ -298,14 +319,17 @@ declare class HermesParticipant implements BourdonParticipant {
 }
 
 /**
- * Claude Code participant — reads claude-brain + auto-memory + MCP knowledge
+ * Claude Code participant — reads agent-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
+ *   1. agent-brain/                   — git-synced markdown records
  *   2. ~/.claude/projects/<ws>/memory/ — per-machine auto-memory frontmatter
  *   3. ~/claude-memory/memory.jsonl   — MCP knowledge-graph JSONL
  *
+ * For back-compat the pre-rename env var (`CLAUDE_BRAIN`) and the pre-rename
+ * directory name are still accepted — see BRAIN_DIR_NAMES / BRAIN_ENV_VARS.
+ *
  * 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
@@ -617,7 +641,7 @@ declare class OpenClawParticipant implements BourdonParticipant {
  * section of `memory.md` becomes a recent Session. Mirrors the Codex automation
  * publisher — it covers the federation gap that the interactive-only
  * `claude-code` participant leaves behind (automations whose work never touches
- * claude-brain / auto-memory / the MCP knowledge graph).
+ * agent-brain / auto-memory / the MCP knowledge graph).
  *
  * Privacy: every native string routes through the redaction SSOT
  * (`redactText`, == the oracle's `_safe_native_memory_text`); the visibility
@@ -928,6 +952,95 @@ declare class CopilotVscodeParticipant implements BourdonParticipant {
     private allMemories;
 }
 
+/**
+ * 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.
+ */
+/** Default number of index records considered (newest-first). */
+declare const DEFAULT_TITLE_LIMIT = 200;
+/** Default number of threads on the tray codex card (newest-first). */
+declare const DEFAULT_RECENT_THREAD_LIMIT = 5;
+/**
+ * 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.
+ */
+declare function resolveCodexHome(baseHome?: string | null): string | 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.
+ */
+declare function parseSessionIndex(path: string, limit?: number | null): Record<string, unknown>[];
+/**
+ * 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.
+ */
+declare function sessionThreadTitles(codexHome?: string | null, opts?: {
+    limit?: number;
+}): Record<string, string>;
+/** One row of the tray codex card. NOTE: `instance`, never a full session id. */
+interface RecentThread {
+    instance: string;
+    title: string | null;
+    updated_at: string | null;
+}
+/**
+ * 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`).
+ */
+declare function recentSessionThreads(codexHome?: string | null, opts?: {
+    limit?: number;
+}): RecentThread[];
+
 /**
  * Participant discovery — a STATIC TS registry replacing Python's `pkgutil`
  * package scan + entry-point duck-type (`participants/__init__.py`).
@@ -968,4 +1081,4 @@ declare function discoverParticipants(ctors?: ParticipantCtor[]): BourdonPartici
  */
 declare function resolvePluginParticipants(): ParticipantCtor[];
 
-export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, openReadonly, projectKeyFromCwd, resolvePluginParticipants, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };
+export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, DEFAULT_RECENT_THREAD_LIMIT, DEFAULT_TITLE_LIMIT, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, PROJECT_HINTS_ENV, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, type RecentThread, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, loadProjectHints, openReadonly, parseSessionIndex, projectKeyFromCwd, recentSessionThreads, resolveCodexHome, resolvePluginParticipants, sessionThreadTitles, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };

package/dist/index.d.ts

@@ -90,6 +90,27 @@ interface BourdonParticipant {
  * duck-type: a value is a participant iff it carries the four marker members.
  */
 declare function isParticipant(obj: unknown): obj is BourdonParticipant;
+/**
+ * Environment variable holding the deployment's own project-name recognition
+ * vocabulary, as a comma-separated list (e.g.
+ * `BOURDON_PROJECT_HINTS="Acme Portal,Widget API,internal-tools"`).
+ */
+declare const PROJECT_HINTS_ENV = "BOURDON_PROJECT_HINTS";
+/**
+ * Project-name hints used to tag sessions with a project focus.
+ *
+ * Bourdon ships **no** project roster of its own — the `defaults` a reader
+ * passes are limited to product-neutral names (this product, plus the agent
+ * surfaces it federates). A deployment that wants its own projects recognized
+ * sets {@link PROJECT_HINTS_ENV}; those entries are appended to `defaults`.
+ *
+ * Matching downstream is case-insensitive substring matching, so entries are
+ * de-duplicated case-insensitively here while preserving first-seen order and
+ * the original casing (which is what gets emitted as the project name).
+ *
+ * Mirrors Python `participants.base.load_project_hints`.
+ */
+declare function loadProjectHints(defaults?: readonly string[]): readonly string[];
 
 /**
  * Shared read-only SQLite + normalization helpers — port of
@@ -298,14 +319,17 @@ declare class HermesParticipant implements BourdonParticipant {
 }
 
 /**
- * Claude Code participant — reads claude-brain + auto-memory + MCP knowledge
+ * Claude Code participant — reads agent-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
+ *   1. agent-brain/                   — git-synced markdown records
  *   2. ~/.claude/projects/<ws>/memory/ — per-machine auto-memory frontmatter
  *   3. ~/claude-memory/memory.jsonl   — MCP knowledge-graph JSONL
  *
+ * For back-compat the pre-rename env var (`CLAUDE_BRAIN`) and the pre-rename
+ * directory name are still accepted — see BRAIN_DIR_NAMES / BRAIN_ENV_VARS.
+ *
  * 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
@@ -617,7 +641,7 @@ declare class OpenClawParticipant implements BourdonParticipant {
  * section of `memory.md` becomes a recent Session. Mirrors the Codex automation
  * publisher — it covers the federation gap that the interactive-only
  * `claude-code` participant leaves behind (automations whose work never touches
- * claude-brain / auto-memory / the MCP knowledge graph).
+ * agent-brain / auto-memory / the MCP knowledge graph).
  *
  * Privacy: every native string routes through the redaction SSOT
  * (`redactText`, == the oracle's `_safe_native_memory_text`); the visibility
@@ -928,6 +952,95 @@ declare class CopilotVscodeParticipant implements BourdonParticipant {
     private allMemories;
 }
 
+/**
+ * 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.
+ */
+/** Default number of index records considered (newest-first). */
+declare const DEFAULT_TITLE_LIMIT = 200;
+/** Default number of threads on the tray codex card (newest-first). */
+declare const DEFAULT_RECENT_THREAD_LIMIT = 5;
+/**
+ * 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.
+ */
+declare function resolveCodexHome(baseHome?: string | null): string | 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.
+ */
+declare function parseSessionIndex(path: string, limit?: number | null): Record<string, unknown>[];
+/**
+ * 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.
+ */
+declare function sessionThreadTitles(codexHome?: string | null, opts?: {
+    limit?: number;
+}): Record<string, string>;
+/** One row of the tray codex card. NOTE: `instance`, never a full session id. */
+interface RecentThread {
+    instance: string;
+    title: string | null;
+    updated_at: string | null;
+}
+/**
+ * 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`).
+ */
+declare function recentSessionThreads(codexHome?: string | null, opts?: {
+    limit?: number;
+}): RecentThread[];
+
 /**
  * Participant discovery — a STATIC TS registry replacing Python's `pkgutil`
  * package scan + entry-point duck-type (`participants/__init__.py`).
@@ -968,4 +1081,4 @@ declare function discoverParticipants(ctors?: ParticipantCtor[]): BourdonPartici
  */
 declare function resolvePluginParticipants(): ParticipantCtor[];
 
-export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, openReadonly, projectKeyFromCwd, resolvePluginParticipants, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };
+export { type AgentStore, type AuthProvider, type BourdonParticipant, CONTRACT_VERSION, CacheEntry, CascadeParticipant, ClaudeCodeAutomationsParticipant, ClaudeCodeParticipant, ClaudeDesktopCodeParticipant, ClaudeDesktopCoworkParticipant, CodexAutomationsParticipant, CopilotAutomationsParticipant, CopilotCliParticipant, CopilotParticipant, CopilotVscodeParticipant, CursorAutomationsParticipant, CursorParticipant, DEFAULT_CACHE_TTL_SECONDS, DEFAULT_RECENT_THREAD_LIMIT, DEFAULT_TITLE_LIMIT, FIRST_PARTY, GitHubCopilotParticipant, type HealthStatus, HermesParticipant, MIN_PATCHED_VERSION, NETWORK_CONTRACT_VERSION, NetworkParticipant, type NetworkParticipantOptions, NetworkUnavailable, OpenClawApiClient, OpenClawParticipant, type OpenReadonlyOptions, PROJECT_HINTS_ENV, ParticipantAuthError, type ParticipantCtor, ParticipantDiscoveryError, ParticipantError, ParticipantExportError, ParticipantVersionMismatchError, PayloadCache, type RecentThread, SPEC_VERSION, type SqliteDatabase, defaultCacheRoot, discoverParticipants, envAuthProvider, epochToIsoDate, epochToIsoDatetime, friendlyLabel, ghTokenProvider, isParticipant, loadProjectHints, openReadonly, parseSessionIndex, projectKeyFromCwd, recentSessionThreads, resolveCodexHome, resolvePluginParticipants, sessionThreadTitles, sqliteAvailable, tableColumns, tableExists, tryOpenReadonly, verifyInstance };