@scrylog/cli 0.2.0 → 0.3.1

package/src/daemon/collectors/codex/README.md

@@ -1,147 +0,0 @@
-# Codex Collector
-
-This module provides session discovery and real-time state tracking for OpenAI Codex CLI.
-
-## Architecture
-
-```
-  ~/.codex/sessions/YYYY/MM/DD/*.jsonl   ~/.codex/archived_sessions/*.jsonl
-         │                                        │
-         │                                        │
-         ▼                                        ▼
-  ┌──────────────┐                          ┌──────────────┐
-  │  discovery   │  discoverTranscripts()   │    hooks     │  readHookData()
-  │              │                        │              │
-  └──────┬───────┘                        └──────┬───────┘
-         │                                        │
-         │                                        │
-         ▼                                        │
-  ┌──────────────┐                                │
-  │     jsonl    │  parseJsonlFile()              │
-  └──────┬───────┘                                │
-         │                                        │
-         ▼                                        │
-  ┌──────────────┐                                │
-  │  transcript  │  extractMeta()                │
-  │              │  (no state inference)          │
-  └──────┬───────┘                                │
-         │                                        │
-         └────────────┬───────────────────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────────────┐
-         │           collector.ts            │
-         │                                 │
-         │  ┌──────────────┐  ┌──────────┐ │
-         │  │ 30s poll     │  │ fs.watch │ │
-         │  │ run()        │  │ hooksDir │ │
-         │  └──────┬───────┘  └────┬─────┘ │
-         │         │               │         │
-         │         └──────┬────────┘         │
-         │                │                  │
-         │                ▼                  │
-         │       processTranscript()         │
-         │                │                  │
-         │                │  ┌──────────────┴─────────────┐
-         │                └──│ mergeHookIntoModel()         │
-         │                   │ (if hook newer than transcript)│
-         │                   └──────────────────────────────┘
-         │                │                  │
-         │                ▼                  │
-         │       store.upsertSession()       │
-         │       store.syncChildSessionIds() │
-         └─────────────────────────────────┘
-                │
-                ▼
-        DaemonStore ──► /api/events SSE ──► TUI
-```
-
-## Modules
-
-| File | Responsibility | Key Exports |
-|------|-------------|-------------|
-| `discovery.ts` | Scan `~/.codex/sessions/YYYY/MM/DD/*.jsonl` and `~/.codex/archived_sessions/*.jsonl`; respect `$CODEX_HOME` | `discoverTranscripts()`, `getCodexDir()` |
-| `jsonl.ts` | Read JSONL tail with byte-size limits; parse lines into typed entries | `parseJsonlFile()`, `readTextTail()`, `CodexJsonlEntry` |
-| `transcript.ts` | Extract session metadata from JSONL (`session_meta`, `turn_context`, `token_count`). No state inference. | `extractMeta()`, `CodexTranscriptMeta` |
-| `hooks.ts` | Read/validate hook JSON files; merge hook data into a session model; merge codex metadata without overwriting existing fields | `readHookData()`, `mergeHookIntoModel()`, `mergeCodexMeta()`, `isHookNewer()`, `getHookTime()`, `isValidHookData()`, `CodexHookFileData` |
-| `collector.ts` | Orchestrate discovery, transcript watching, hook watching, deduplication, and store writes | `CodexCollector` (implements `Collector`) |
-| `index.ts` | Public re-exports | `CodexCollector`, `extractMeta` |
-
-## JSONL Format
-
-Codex JSONL files contain three processed line types:
-
-- `session_meta` — session identity and fork lineage
-- `turn_context` — active model slug
-- `event_msg` with `payload.type === "token_count"` — token usage
-
-No conversational content is parsed (format is unstable).
-
-## Hook Requirement
-
-Hooks are **required** for real-time state. Without hooks:
-
-- Sessions are discovered from JSONL files
-- State is always `idle`
-- `detectionSource` is `"codex-transcript"`
-
-With hooks (`codex.hooksEnabled: true`):
-
-- State is derived from Codex lifecycle events (`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, `Stop`)
-- `detectionSource` is `"codex-hook"`
-- `turn_id` is captured for turn-level tracking
-
-## Install Hooks
-
-```bash
-scrylog codex hooks install
-```
-
-This writes `~/.codex/hooks.json` with entries for all 6 Codex hook events pointing to `scrylog-codex-hook`.
-
-## Hook Merge Priority
-
-When both transcript and hook data exist, the collector uses this priority:
-
-1. **Hook newer** (`hookSeq` or `hookEventTime` >= existing): hook data wins for `state`, `hasAttention`, `summary`, `activeTool`
-2. **Hook older**: transcript data wins (except `codex` metadata merged via `mergeCodexMeta`)
-3. **Hook-managed session** (`detectionSource === "codex-hook"`): transcript can only fill missing metadata (e.g. `transcriptPath`), never override state
-
-## State Derivation Rules
-
-| Event | State | Reason |
-|-------|-------|--------|
-| `SessionStart` | `idle` | Session just started |
-| `UserPromptSubmit` | `working` | User submitted a prompt, Codex is working |
-| `PreToolUse` | `working` | Codex is about to use a tool |
-| `PermissionRequest` | `waiting-input` | Codex is waiting for user permission |
-| `PostToolUse` | `working` | Tool completed, Codex continues |
-| `Stop` with `stop_hook_active: true` | `working` | Codex will continue automatically |
-| `Stop` with `stop_hook_active: false` | `idle` | Session ended |
-
-## Configuration
-
-```json
-{
-  "codex": {
-    "codexDir": "/path/to/.codex",
-    "hooksEnabled": true,
-    "hooksDir": "/tmp/scrylog-codex-hooks"
-  }
-}
-```
-
-## Interactions
-
-| Component | How |
-|-----------|-----|
-| `GitCollector` | Resolves `currentPath` → `project` when hooks/transcript provide a directory |
-| `DaemonStore` | Upserts sessions; clears old bindings via `syncChildSessionIds()` |
-| `TmuxCollector` | Reads `@codex-session` pane option for authoritative pane→session linking |
-| `Scheduler` | Calls `start()` → sets up `30s` discovery interval + `5s` fallback re-read |
-| `TUI` | Receives updates via SSE from the store |
-
-## Detection Sources Produced
-
-- `"codex-transcript"` — session discovered from `.jsonl` file, state is `idle`
-- `"codex-hook"` — session discovered/enriched from hook JSON, state is authoritative from Codex CLI directly