context-intelligence-session-navigation

# Context Intelligence Session Navigation This skill covers navigation of flat JSONL session files written by the `LoggingHandler`. These files are the universal baseline — always present regardless of whether graph stores are configured. Use shell tools (`jq`, `grep`, `wc`, `head`) to extract data safely. For the complete event-by-event field reference, see `context/event-schema.md`. For ready-to-use jq/grep recipes, see `context/safe-extraction-patterns.md`. --- ## Disk Layout Resolve the root once before any discovery: ```bash CONTEXT_INTELLIGENCE_ROOT="${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}" ``` ``` $CONTEXT_INTELLIGENCE_ROOT/{project-slug}/sessions/{session_id}/context-intelligence/ ├── events.jsonl # one JSON object per line, append-only └── metadata.json # session metadata, written on start, updated on end ``` - `$CONTEXT_INTELLIGENCE_ROOT` — resolved from the idiom `"${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}"` (unset → legacy default). **Relocation is reader-visible ONLY via this env var.** The hook's `config.base_path` moves where the *writer* stores captures, but readers (this skill, `discover.py`, the recipe) resolve the root solely from the env var — so always relocate via `AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH`, not `config.base_path` alone, or readers will look in the wrong place. - `{project-slug}` — derived from the full working directory path (see Project Slug Algorithm below) - `{session_id}` — unique session identifier (UUID or UUID with agent suffix for child sessions) - `context-intelligence/` — subdirectory containing the session data files - `events.jsonl` — append-only log of every event the kernel emits during the session - `metadata.json` — compact session metadata for quick lookup without parsing the full event log Example paths (with root resolved): ``` $CONTEXT_INTELLIGENCE_ROOT/-home-user-myapp/sessions/55c8841a-1234-5678-9abc-def012345678/context-intelligence/events.jsonl $CONTEXT_INTELLIGENCE_ROOT/-home-user-myapp/sessions/55c8841a-1234-5678-9abc-def012345678/context-intelligence/metadata.json ``` > **⚠ MARKER RULE — the defect this prevents:** Every discovery glob MUST include the > `context-intelligence/` path segment and MUST NOT stop at `sessions/<id>/`: > > ``` > CORRECT: "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl > WRONG: "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/metadata.json # catches Amplifier core's files > ``` > > **Why:** Amplifier core writes `sessions/<id>/metadata.json` with NO `context-intelligence/` > segment. Globbing one level too shallow latches onto core's files and produces a confident > wrong count. > > **Canonical marker = `events.jsonl`.** The Python readers (`discover.py`, the workflow > recipe) treat `context-intelligence/events.jsonl` as the single discriminator of a real > capture. `metadata.json` is used here only to read fields (`workspace`, `status`, …); both > files are written together, so either glob includes the `context-intelligence/` segment and > avoids the false-positive. When you need a strict capture count that matches the code, > glob `events.jsonl`, not `metadata.json`. > **⚠ FAIL-LOUD RULE:** When zero captures are found, say exactly `"looked in <root>, found 0"` — > never report a confident count from a shallower glob, never silently fall back to a different path. --- ## Record Format Each line in `events.jsonl` is a single JSON object with exactly **four** fields, always in this order: ```json {"event":"tool:pre","workspace":"my-project","timestamp":"2026-03-10T11:13:09.792+00:00","data":{...}} ``` | Field | Type | Description | |-------|------|-------------| | `event` | string | Event name in `{namespace}:{action}` format | | `workspace` | string | Workspace scope — always present, empty string `""` when not configured | | `timestamp` | string | ISO 8601 timestamp of when the event was recorded | | `data` | object | Raw event payload, exactly as the kernel emitted it | **Key principle:** No field promotion, no level classification, no payload mutation. What the kernel emits is exactly what gets stored in `data`. The `workspace` field is the only addition the hook makes — it is injected at write time from `ConfigResolver.workspace`. --- ## metadata.json Written on `session:start` or `session:fork`, updated on `session:end`. ### Required Fields (always present) | Field | Type | Description | |-------|------|-------------| | `format` | string | Schema family identifier, always `"context-intelligence"` | | `version` | string | Schema version, always `"1.0.0"` | | `session_id` | string | Unique session identifier | | `workspace` | string | Workspace scope — same value as in `events.jsonl`, empty string if not configured | | `parent_id` | string | Parent session identifier (empty string for root sessions) | | `started_at` | string | ISO 8601 timestamp | | `status` | string | `"running"` / `"completed"` / `"failed"` / `"cancelled"` | | `working_dir` | string | Working directory path | ### Optional Fields (omitted when absent — no nulls) | Field | Type | Description | |-------|------|-------------| | `agent_name` | string | Agent name (e.g., `"foundation:explorer"`) | | `parallel_group_id` | string | Parallel execution group identifier | | `recipe_name` | string | Recipe name if in recipe context | | `recipe_step` | string | Recipe step if in recipe context | | `ended_at` | string | ISO 8601 timestamp (added on `session:end`) | Optional fields are omitted entirely when absent — no null values, compact JSON. Example (minimal root session): ```json {"format":"context-intelligence","version":"1.0.0","session_id":"55c8841a-...","workspace":"my-project","parent_id":"","started_at":"2026-03-10T11:13:09.000+00:00","status":"running","working_dir":"/home/user/myapp"} ``` Example (child session with optional fields): ```json {"format":"context-intelligence","version":"1.0.0","session_id":"55c8841a-...-foundation:explorer","workspace":"my-project","parent_id":"1cb9e5f5-...","started_at":"2026-03-10T11:13:09.000+00:00","status":"completed","ended_at":"2026-03-10T11:15:42.000+00:00","working_dir":"/home/user/myapp","agent_name":"foundation:explorer","recipe_name":"code-review","recipe_step":"analyze"} ``` --- ## Workspace and Project Slug **Workspace** scopes all event data. It is written into every `events.jsonl` line and `metadata.json`. Two concepts work together: | Concept | Purpose | Where used | |---------|---------|------------| | `project_slug` | Directory name under `$CONTEXT_INTELLIGENCE_ROOT/` | On-disk path | | `workspace` | Field in every record | Querying and filtering | By **default** workspace equals `project_slug` (both derived from the working directory). They can differ when workspace is set explicitly via `settings.yaml` or env var — for example, workspace `"my-api"` while project_slug is `"-home-user-myapp"`. **Consequence for navigation:** - **Directory-first lookup** — when workspace matches the project_slug, all sessions for that workspace live under `$CONTEXT_INTELLIGENCE_ROOT/{workspace}/sessions/`. This is fast and the common case. - **Field-based filtering** — when workspace was set explicitly (overriding the slug default), scan across all project directories and filter records by `jq 'select(.workspace == "TARGET")'`. Always check both: attempt directory lookup first, then fall back to cross-project field scan. --- ## Project Slug Algorithm The project slug is derived from the **full absolute path** of the working directory: 1. Take the resolved absolute path of `working_dir` 2. Replace every `/` with `-` and every `\` with `-` 3. Remove `:` (Windows drive letters) 4. If the result does not start with `-`, prepend `-` 5. Use `"default"` if the result is empty Examples: | Working Directory | Slug | |-------------------|------| | `/workspace` | `-workspace` | | `/home/user/my-api` | `-home-user-my-api` | | `/home/user/repos/amplifier-core` | `-home-user-repos-amplifier-core` | > Note: the slug encodes the **full path**, not just the basename. `/home/alice/myapp` and `/home/bob/myapp` get different slugs: `-home-alice-myapp` and `-home-bob-myapp`. --- ## Safe Extraction Discipline Session event files can contain lines with 100k+ tokens (e.g., `llm:response` with full model output). Four golden rules protect against context overflow: 1. **Never `cat` an events.jsonl file.** A single line can be larger than your entire context window. Always use targeted extraction. 2. **Use `jq -c` for structured queries.** The `-c` flag keeps output compact (one line per result). Always filter to specific fields rather than dumping entire records. 3. **Use `grep -n | cut` for line-targeted extraction.** First find matching line numbers with `grep -n`, then extract specific lines with `sed` or `head`/`tail`. Never pipe raw grep output of event data into your context. 4. **Preview with `wc -l` and `head` before extracting.** Always check file size and peek at the first few lines before running any extraction. This prevents accidentally pulling in massive files. --- ## Common Navigation Patterns Resolve the root once before all discovery snippets in this section: ```bash CONTEXT_INTELLIGENCE_ROOT="${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}" ``` ### Resolve workspace to a project directory ```bash # If workspace == project_slug (common default), sessions are here: ls "$CONTEXT_INTELLIGENCE_ROOT"/{workspace}/sessions/ # If workspace was set explicitly and differs from project_slug, # find all directories containing sessions tagged with this workspace: grep -rl '"workspace":"{workspace}"' "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/metadata.json \ | sed 's|/context-intelligence/metadata.json||' ``` ### List all sessions for a workspace ```bash # Fast path: workspace matches directory name (default case) for ev in "$CONTEXT_INTELLIGENCE_ROOT"/my-project/sessions/*/context-intelligence/events.jsonl; do f="${ev%/events.jsonl}/metadata.json" # canonical marker = events.jsonl; fields from sibling jq -r '[.session_id, .status, .started_at, .agent_name // "(root)"] | join("\t")' "$f" 2>/dev/null done | sort -t$'\t' -k3 # Scoped path: workspace set explicitly — scan all projects, filter by field for ev in "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl; do f="${ev%/events.jsonl}/metadata.json" # canonical marker = events.jsonl; fields from sibling jq -r 'select(.workspace == "my-project") | [.session_id, .status, .started_at, .agent_name // "(root)"] | join("\t")' "$f" 2>/dev/null done | sort -t$'\t' -k3 ``` ### Check what workspace a session belongs to ```bash jq -r '.workspace' metadata.json # or from events.jsonl (first line only — safe): head -1 events.jsonl | jq -r '.workspace' ``` ### Filter events by workspace across a project ```bash # Count events per workspace across all sessions in a project directory: jq -r '.workspace' "$CONTEXT_INTELLIGENCE_ROOT"/-home-user-myapp/sessions/*/context-intelligence/events.jsonl \ | sort | uniq -c | sort -rn ``` ### Find sessions by status within a workspace ```bash # Within a single project directory: for ev in "$CONTEXT_INTELLIGENCE_ROOT"/my-project/sessions/*/context-intelligence/events.jsonl; do f="${ev%/events.jsonl}/metadata.json" # canonical marker = events.jsonl; fields from sibling jq -r 'select(.status == "running") | .session_id' "$f" 2>/dev/null done # Cross-project, scoped to workspace: for ev in "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl; do