@getbourdon/participants 0.2.3 → 0.3.0

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

@@ -0,0 +1,55 @@
+/**
+ * Codex automations participant — publishes read-only Codex background/automation
+ * run memory into Bourdon as L5 evidence. Port of
+ * `participants/codex_automations.py`.
+ *
+ * Store convention (NOT SQLite, NOT network): a CONVENTION-FILE directory tree at
+ * `~/.codex/automations/<id>/`, each holding an `automation.toml` config and an
+ * optional `memory.md` run log. The reader parses the TOML config and extracts
+ * dated "runs" from the markdown memory, normalizing them into L5 sessions +
+ * entities (the automation itself, plus inferred projects and signal classes).
+ *
+ * Source-resolution order for the automations dir:
+ *   1. explicit `automationsDir` constructor arg
+ *   2. `codexHome` constructor arg → `<codexHome>/automations`
+ *   3. `CODEX_HOME` env-var → `$CODEX_HOME/automations`
+ *   4. `~/.codex/automations`  (default convention path)
+ *
+ * Privacy: every native string routes through the redaction SSOT
+ * (`redactText(v, 180)` == the oracle's `_safe_native_memory_text`); the
+ * visibility policy filters PRIVATE entities before emission. Defensive
+ * throughout — a missing dir raises {@link ParticipantDiscoveryError} from
+ * `discover()`, malformed TOML/markdown degrades to empty rather than raising,
+ * and `healthCheck` never throws.
+ *
+ * NOTE: does NOT depend on the full codex reader — only the redaction helper it
+ * imports (`_safe_native_memory_text`, reproduced inline as {@link safeNativeMemoryText}).
+ */
+import { type L5ManifestModel, type SessionModel } from "@getbourdon/l5";
+import { type AgentStore, type BourdonParticipant, type HealthStatus } from "../base.js";
+/** Return the default Codex automations directory (source-resolution order). */
+export declare function defaultCodexAutomationsDir(codexHome?: string): string;
+/**
+ * External participant for Codex automation memory artifacts. Reads
+ * `~/.codex/automations/<id>/{automation.toml,memory.md}` and normalizes dated
+ * runs into an L5 manifest.
+ */
+export declare class CodexAutomationsParticipant implements BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    private readonly automationsDir;
+    private readonly policy;
+    /**
+     * Conventional Codex automations dir (`~/.codex/automations`). Provided for
+     * protocol uniformity — the setup wizard wires the parent `codex` participant
+     * and skips `-automations` sub-surfaces rather than detecting this one.
+     */
+    static defaultNativePath(home?: string): string;
+    constructor(automationsDir?: string, codexHome?: string);
+    get nativePath(): string;
+    discover(): AgentStore;
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    exportL5(since?: Date): L5ManifestModel;
+    healthCheck(): HealthStatus;
+    private runs;
+}

package/dist/readers/codex-automations.js

@@ -0,0 +1,519 @@
+/**
+ * Codex automations participant — publishes read-only Codex background/automation
+ * run memory into Bourdon as L5 evidence. Port of
+ * `participants/codex_automations.py`.
+ *
+ * Store convention (NOT SQLite, NOT network): a CONVENTION-FILE directory tree at
+ * `~/.codex/automations/<id>/`, each holding an `automation.toml` config and an
+ * optional `memory.md` run log. The reader parses the TOML config and extracts
+ * dated "runs" from the markdown memory, normalizing them into L5 sessions +
+ * entities (the automation itself, plus inferred projects and signal classes).
+ *
+ * Source-resolution order for the automations dir:
+ *   1. explicit `automationsDir` constructor arg
+ *   2. `codexHome` constructor arg → `<codexHome>/automations`
+ *   3. `CODEX_HOME` env-var → `$CODEX_HOME/automations`
+ *   4. `~/.codex/automations`  (default convention path)
+ *
+ * Privacy: every native string routes through the redaction SSOT
+ * (`redactText(v, 180)` == the oracle's `_safe_native_memory_text`); the
+ * visibility policy filters PRIVATE entities before emission. Defensive
+ * throughout — a missing dir raises {@link ParticipantDiscoveryError} from
+ * `discover()`, malformed TOML/markdown degrades to empty rather than raising,
+ * and `healthCheck` never throws.
+ *
+ * NOTE: does NOT depend on the full codex reader — only the redaction helper it
+ * imports (`_safe_native_memory_text`, reproduced inline as {@link safeNativeMemoryText}).
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { parse as tomlParse } from "smol-toml";
+import { Visibility, filterForFederation, makeAgentInfo, makeEntity, makeManifest, makeSession, makeVisibilityPolicy, } from "@getbourdon/l5";
+import { redactText } from "@getbourdon/redaction";
+import { ParticipantDiscoveryError, SPEC_VERSION, loadProjectHints, } from "../base.js";
+// -- Constants -----------------------------------------------------------------
+const AGENT_ID = "codex-automations";
+const AGENT_TYPE = "other";
+const ROLE_NARRATIVE = "Publishes read-only Codex automation run memory into Bourdon so background " +
+    "monitors, digests, and recurring checks are visible alongside interactive " +
+    "agent sessions.";
+const DEFAULT_POLICY = makeVisibilityPolicy({
+    default: Visibility.TEAM,
+    private_tags: ["personal", "financial", "credential", "health", "family", "legal"],
+    team_tags: ["codex-automation", "automation", "workspace"],
+});
+const AUTOMATIONS_DIR_NAME = "automations";
+const AUTOMATION_TOML = "automation.toml";
+const MEMORY_MD = "memory.md";
+const MAX_MEMORY_CHARS = 160_000;
+const MAX_KEY_ACTIONS_PER_RUN = 6;
+const MAX_KEY_ACTION_CHARS = 280;
+const RUN_HEADER_RE = /^(\d{4}-\d{2}-\d{2})(?:\b|$)(.*)$/;
+// Product-neutral defaults only: this product plus the agent surfaces Bourdon
+// federates. A deployment adds its own project roster via the
+// `BOURDON_PROJECT_HINTS` env var (comma-separated) — see `loadProjectHints`.
+const DEFAULT_PROJECT_HINTS = ["Bourdon", "Cursor", "Copilot"];
+const SIGNAL_PATTERNS = [
+    ["human-dashboard-action", /\b(human|dashboard|manual)\b/i],
+    ["release-gate", /\b(release|store|app review|play console|testflight)\b/i],
+    ["billing-drift", /\b(billing|stripe|revenuecat|iap|subscription)\b/i],
+    ["memory-coverage-gap", /\b(memory|l5|manifest|federated|bourdon)\b/i],
+    ["launch-decision", /\b(launch|go-live|pricing|prod|production)\b/i],
+];
+/** Minimal logger so a degraded parse is visible without pulling in a dep. */
+const logger = {
+    warn(msg) {
+        // eslint-disable-next-line no-console
+        console.warn(`[bourdon.participants] ${msg}`);
+    },
+};
+// -- fs helpers ----------------------------------------------------------------
+function homeDir() {
+    // os.homedir() can throw under some sandboxes; stay defensive so import +
+    // construction never crash even when HOME points at an unreadable path.
+    try {
+        return homedir();
+    }
+    catch {
+        return process.env.HOME || process.env.USERPROFILE || ".";
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// -- Path resolution -----------------------------------------------------------
+/** Return the default Codex automations directory (source-resolution order). */
+export function defaultCodexAutomationsDir(codexHome) {
+    if (codexHome !== undefined && codexHome !== null) {
+        return join(codexHome, AUTOMATIONS_DIR_NAME);
+    }
+    const env = process.env.CODEX_HOME;
+    if (env)
+        return join(env, AUTOMATIONS_DIR_NAME);
+    return join(homeDir(), ".codex", AUTOMATIONS_DIR_NAME);
+}
+// -- Redaction -----------------------------------------------------------------
+/**
+ * Thin wrapper over the redaction SSOT (the oracle's `_safe_native_memory_text`,
+ * `redact_text(value, limit=180)`).
+ */
+function safeNativeMemoryText(value) {
+    return redactText(value, 180);
+}
+// -- Coercion helpers (mirror Python str() / truthiness) -----------------------
+/** Mirror Python `str(a or b)`: use `a` when truthy, else `b`, then stringify. */
+function pyStrOr(a, b) {
+    return String(a ? a : b);
+}
+// -- TOML config ---------------------------------------------------------------
+/** Read + parse an automation.toml. Returns {} on any I/O or parse error. */
+function readAutomationToml(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (exc) {
+        logger.warn(`CodexAutomationsParticipant: cannot parse ${path}: ${String(exc)}`);
+        return {};
+    }
+    try {
+        const parsed = tomlParse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch (exc) {
+        logger.warn(`CodexAutomationsParticipant: cannot parse ${path}: ${String(exc)}`);
+        return {};
+    }
+}
+/** Build an AutomationConfig from a toml path. Returns null on an empty id. */
+function buildConfig(tomlPath) {
+    const raw = readAutomationToml(tomlPath);
+    const parentName = basename(dirname(tomlPath));
+    const automationId = pyStrOr(raw["id"], parentName).trim();
+    if (!automationId)
+        return null;
+    const name = pyStrOr(raw["name"], automationId).trim();
+    const status = pyStrOr(raw["status"], "UNKNOWN").trim().toUpperCase();
+    const rrule = pyStrOr(raw["rrule"], "").trim();
+    const kind = pyStrOr(raw["kind"], "").trim();
+    const cwdsRaw = raw["cwds"];
+    const cwds = Array.isArray(cwdsRaw)
+        ? cwdsRaw.filter((cwd) => typeof cwd === "string" && cwd.trim() !== "")
+        : [];
+    const memoryPath = join(dirname(tomlPath), MEMORY_MD);
+    return {
+        automationId,
+        name,
+        status,
+        rrule,
+        kind,
+        cwds,
+        path: tomlPath,
+        memoryPath: isFile(memoryPath) ? memoryPath : null,
+    };
+}
+/**
+ * Enumerate the `<id>/automation.toml` files, sorted (mirrors Python's sorted-glob).
+ * The varying path segment is the immediate sub-directory, so sorting the
+ * resulting toml paths reproduces the oracle's ordering.
+ */
+function iterConfigs(automationsDir) {
+    if (!isDir(automationsDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(automationsDir);
+    }
+    catch {
+        return [];
+    }
+    const tomlPaths = [];
+    for (const entry of entries) {
+        const tomlPath = join(automationsDir, entry, AUTOMATION_TOML);
+        if (isFile(tomlPath))
+            tomlPaths.push(tomlPath);
+    }
+    tomlPaths.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const configs = [];
+    for (const tomlPath of tomlPaths) {
+        const config = buildConfig(tomlPath);
+        if (config !== null)
+            configs.push(config);
+    }
+    return configs;
+}
+// -- Memory extraction ---------------------------------------------------------
+/** Read the memory file, returning at most the last MAX_MEMORY_CHARS characters. */
+function readMemoryText(path) {
+    if (path === null)
+        return "";
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (exc) {
+        logger.warn(`CodexAutomationsParticipant: cannot read ${path}: ${String(exc)}`);
+        return "";
+    }
+    return text.length > MAX_MEMORY_CHARS ? text.slice(-MAX_MEMORY_CHARS) : text;
+}
+/** Split into lines the way Python's str.splitlines() does (best-effort). */
+function splitLines(text) {
+    // Python splitlines includes ASCII record separators; this explicit set preserves parity.
+    // eslint-disable-next-line no-control-regex
+    return text.split(/\r\n|[\n\r\u000B\u000C\u001C\u001D\u001E\u0085\u2028\u2029]/u);
+}
+/** Python `str.rstrip()` — strip trailing whitespace only. */
+function rstrip(s) {
+    return s.replace(/\s+$/, "");
+}
+/** Python `" ".join(value.split())` — collapse all whitespace runs. */
+function collapseWhitespace(value) {
+    return value
+        .split(/\s+/)
+        .filter((p) => p.length > 0)
+        .join(" ");
+}
+/** Port of `_bounded`: collapse whitespace then cap with a `...` ellipsis. */
+function bounded(value, limit) {
+    const normalized = collapseWhitespace(value);
+    if (normalized.length <= limit)
+        return normalized;
+    return rstrip(normalized.slice(0, limit - 1)) + "...";
+}
+function actionsFromLines(lines) {
+    const actions = [];
+    for (const line of lines) {
+        let cleaned = line.trim();
+        if (!cleaned)
+            continue;
+        cleaned = (cleaned.startsWith("- ") ? cleaned.slice(2) : cleaned).trim();
+        const lowered = cleaned.toLowerCase();
+        if (!cleaned || lowered.startsWith("runtime"))
+            continue;
+        if (lowered === "first run" || lowered === "follow-up")
+            continue;
+        if (lowered.startsWith("run:"))
+            cleaned = cleaned.slice(4).trim();
+        const safe = bounded(safeNativeMemoryText(cleaned), MAX_KEY_ACTION_CHARS);
+        if (safe && !actions.includes(safe))
+            actions.push(safe);
+        if (actions.length >= MAX_KEY_ACTIONS_PER_RUN)
+            break;
+    }
+    return actions;
+}
+function titleFromActions(config, actions) {
+    if (actions.length === 0)
+        return config.name;
+    const first = actions[0];
+    const prefix = `${config.name}: `;
+    if (first.startsWith(prefix))
+        return bounded(first, 120);
+    return bounded(prefix + first, 120);
+}
+function inferProjects(text) {
+    const projects = [];
+    const lowered = text.toLowerCase();
+    const seen = new Set();
+    for (const project of loadProjectHints(DEFAULT_PROJECT_HINTS)) {
+        const key = project.toLowerCase();
+        if (lowered.includes(key) && !seen.has(key)) {
+            projects.push(project);
+            seen.add(key);
+        }
+    }
+    return projects;
+}
+function inferSignals(text) {
+    const signals = [];
+    for (const [name, pattern] of SIGNAL_PATTERNS) {
+        if (pattern.test(text))
+            signals.push(name);
+    }
+    return signals;
+}
+function extractMemoryRuns(config) {
+    const text = readMemoryText(config.memoryPath);
+    if (!text)
+        return [];
+    const chunks = [];
+    let currentDate = "";
+    let currentLines = [];
+    for (const rawLine of splitLines(text)) {
+        const line = rstrip(rawLine);
+        const match = RUN_HEADER_RE.exec(line.trim());
+        if (match) {
+            if (currentDate)
+                chunks.push([currentDate, currentLines]);
+            currentDate = match[1];
+            const suffix = stripChars(match[2].trim(), " -:—");
+            currentLines = suffix ? [suffix] : [];
+            continue;
+        }
+        if (currentDate)
+            currentLines.push(line);
+    }
+    if (currentDate)
+        chunks.push([currentDate, currentLines]);
+    const runs = [];
+    for (const [runDate, lines] of chunks) {
+        const actions = actionsFromLines(lines);
+        if (actions.length === 0)
+            continue;
+        const body = actions.join(" ");
+        const title = titleFromActions(config, actions);
+        runs.push({
+            automation: config,
+            date: runDate,
+            title,
+            keyActions: actions,
+            projects: inferProjects(body),
+            signals: inferSignals(body),
+        });
+    }
+    return runs;
+}
+/** Python `str.strip(chars)` — strip any of `chars` from both ends. */
+function stripChars(s, chars) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && chars.includes(s[start]))
+        start++;
+    while (end > start && chars.includes(s[end - 1]))
+        end--;
+    return s.slice(start, end);
+}
+// -- L5 assembly ---------------------------------------------------------------
+function sessionFromRun(run) {
+    const config = run.automation;
+    const keyActions = [
+        `automation_id: ${config.automationId}`,
+        `run: ${run.title}`,
+        ...run.keyActions,
+    ];
+    const filesTouched = [config.path];
+    if (config.memoryPath !== null)
+        filesTouched.push(config.memoryPath);
+    return makeSession({
+        date: run.date,
+        cwd: config.cwds.length > 0 ? config.cwds[0] : dirname(config.path),
+        project_focus: [...run.projects],
+        key_actions: keyActions.slice(0, MAX_KEY_ACTIONS_PER_RUN + 2),
+        files_touched: filesTouched,
+        visibility: Visibility.TEAM,
+    });
+}
+function entitiesFromConfigsAndRuns(configs, runs) {
+    const byName = new Map();
+    for (const config of configs) {
+        byName.set(config.automationId, makeEntity({
+            name: config.automationId,
+            type: "automation",
+            summary: bounded(`Codex automation '${config.name}' (${config.status}). ` +
+                `Schedule: ${config.rrule || "unspecified"}.`, 260),
+            last_touched: undefined,
+            tags: ["codex-automation", "automation", config.status.toLowerCase()],
+            visibility: Visibility.TEAM,
+        }));
+    }
+    for (const run of runs) {
+        for (const project of run.projects) {
+            if (!byName.has(project)) {
+                byName.set(project, makeEntity({
+                    name: project,
+                    type: "project",
+                    summary: "Project mentioned by Codex automation run memory.",
+                    last_touched: run.date,
+                    tags: ["codex-automation", "automation-evidence"],
+                    visibility: Visibility.TEAM,
+                }));
+            }
+        }
+        for (const signal of run.signals) {
+            if (!byName.has(signal)) {
+                byName.set(signal, makeEntity({
+                    name: signal,
+                    type: "automation-signal",
+                    summary: "Signal class inferred from Codex automation run memory.",
+                    last_touched: run.date,
+                    tags: ["codex-automation", "automation-signal"],
+                    visibility: Visibility.TEAM,
+                }));
+            }
+        }
+    }
+    return [...byName.values()];
+}
+// -- Participant ---------------------------------------------------------------
+/**
+ * External participant for Codex automation memory artifacts. Reads
+ * `~/.codex/automations/<id>/{automation.toml,memory.md}` and normalizes dated
+ * runs into an L5 manifest.
+ */
+export class CodexAutomationsParticipant {
+    agentId = AGENT_ID;
+    agentType = AGENT_TYPE;
+    automationsDir;
+    policy;
+    /**
+     * Conventional Codex automations dir (`~/.codex/automations`). Provided for
+     * protocol uniformity — the setup wizard wires the parent `codex` participant
+     * and skips `-automations` sub-surfaces rather than detecting this one.
+     */
+    static defaultNativePath(home) {
+        return defaultCodexAutomationsDir(home);
+    }
+    constructor(automationsDir, codexHome) {
+        this.automationsDir = automationsDir ?? defaultCodexAutomationsDir(codexHome);
+        this.policy = DEFAULT_POLICY;
+    }
+    get nativePath() {
+        return this.automationsDir;
+    }
+    discover() {
+        if (!isDir(this.automationsDir)) {
+            throw new ParticipantDiscoveryError(`Codex automations directory not found at ${this.automationsDir}.`);
+        }
+        const configs = iterConfigs(this.automationsDir);
+        return {
+            path: this.automationsDir,
+            version: "unknown",
+            metadata: {
+                automations: configs.length,
+                with_memory: configs.filter((c) => c.memoryPath !== null).length,
+            },
+        };
+    }
+    exportSessions(since, limit = 100) {
+        const sessions = this.runs(undefined, since).map(sessionFromRun);
+        sessions.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+        return sessions.slice(0, limit);
+    }
+    exportL5(since) {
+        const configs = iterConfigs(this.automationsDir);
+        const runs = this.runs(configs, since);
+        const sessions = runs.map(sessionFromRun);
+        sessions.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+        const entities = entitiesFromConfigsAndRuns(configs, runs);
+        const visibleEntities = filterForFederation(entities, this.policy);
+        return makeManifest({
+            spec_version: SPEC_VERSION,
+            agent: makeAgentInfo({
+                id: AGENT_ID,
+                type: AGENT_TYPE,
+                instance: hostname(),
+                spec_version_compat: SPEC_VERSION,
+                role_narrative: ROLE_NARRATIVE,
+            }),
+            last_updated: new Date().toISOString(),
+            capabilities: ["codex-automation-memory", "run-summary-publication"],
+            recent_sessions: sessions,
+            known_entities: visibleEntities,
+            visibility_policy: this.policy,
+        });
+    }
+    healthCheck() {
+        if (!isDir(this.automationsDir)) {
+            return {
+                status: "blocked",
+                reason: `Codex automations directory not found at ${this.automationsDir}.`,
+                details: { automations_dir: this.automationsDir },
+                proposedFix: "Create Codex automations or pass --automations-dir.",
+            };
+        }
+        const configs = iterConfigs(this.automationsDir);
+        const runs = this.runs(configs);
+        const hasConfigs = configs.length > 0;
+        return {
+            status: hasConfigs ? "ok" : "degraded",
+            reason: hasConfigs ? undefined : "No automation.toml files found.",
+            details: {
+                automations_dir: this.automationsDir,
+                automation_count: configs.length,
+                memory_files: configs.filter((c) => c.memoryPath !== null).length,
+                runs_extracted: runs.length,
+                active_automations: configs.filter((c) => c.status === "ACTIVE").length,
+            },
+            proposedFix: hasConfigs ? undefined : "Add Codex automation.toml files.",
+        };
+    }
+    // -- Internal ---------------------------------------------------------------
+    runs(configs, since) {
+        const runCutoff = since ? since.toISOString().slice(0, 10) : null;
+        const runs = [];
+        for (const config of configs ?? iterConfigs(this.automationsDir)) {
+            for (const run of extractMemoryRuns(config)) {
+                if (runCutoff && run.date < runCutoff)
+                    continue;
+                runs.push(run);
+            }
+        }
+        runs.sort((a, b) => {
+            if (a.date !== b.date)
+                return a.date < b.date ? 1 : -1;
+            const ai = a.automation.automationId;
+            const bi = b.automation.automationId;
+            if (ai !== bi)
+                return ai < bi ? 1 : -1;
+            return 0;
+        });
+        return runs;
+    }
+}

package/dist/readers/codex-sessions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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). */
+export declare const DEFAULT_TITLE_LIMIT = 200;
+/** Default number of threads on the tray codex card (newest-first). */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export 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`).
+ */
+export declare function recentSessionThreads(codexHome?: string | null, opts?: {
+    limit?: number;
+}): RecentThread[];