story-kit: create 266_story_matrix_bot_structured_conversation_history

.story_kit/work/1_upcoming/266_story_matrix_bot_structured_conversation_history.md

@@ -20,11 +20,28 @@ As a user chatting with the Matrix bot, I want it to remember and own its prior
 
 The current implementation attempts session resumption via `--resume <session_id>` but it's not working:
 
-1. **No session_id captured:** `matrix_history.json` contains conversation entries but no `session_id` field. The `RoomConversation.session_id` is always `None`.
+### Code path: how session resumption is supposed to work
-2. **Root cause:** `claude -p --output-format stream-json` may not emit a `session_id` in its JSON events, or the PTY stream parser (`process_json_event` in `claude_code.rs:348`) isn't finding it. The oneshot channel (`sid_rx`) never receives a value.
+
-3. **Effect:** Every message spawns a fresh Claude Code process with no `--resume` flag. Each turn is a blank slate — the bot has no memory of prior messages despite the history being persisted.
+1. `server/src/matrix/bot.rs:671-676` — `handle_message()` reads `conv.session_id` from the per-room `RoomConversation` to get the resume ID.
-4. **The history entries are persisted and loaded correctly** — the serialization round-trip works (confirmed by tests). The problem is purely that `--resume` is never invoked.
+2. `server/src/matrix/bot.rs:717` — passes `resume_session_id` to `provider.chat_stream()`.
-5. **To fix:** Verify what `claude -p --output-format stream-json` actually emits for `session_id`. If it doesn't emit one, an alternative approach may be needed (e.g. passing history as a system prompt prefix, or using the Claude API directly instead of the CLI).
+3. `server/src/llm/providers/claude_code.rs:57` — `chat_stream()` stores it as `resume_id`.
+4. `server/src/llm/providers/claude_code.rs:170-173` — if `resume_session_id` is `Some`, appends `--resume <id>` to the `claude -p` command.
+5. `server/src/llm/providers/claude_code.rs:348` — `process_json_event()` looks for `json["session_id"]` in each streamed NDJSON event and sends it via a oneshot channel (`sid_tx`).
+6. `server/src/llm/providers/claude_code.rs:122` — after the PTY exits, `sid_rx.await.ok()` captures the session ID (or `None` if never sent).
+7. `server/src/matrix/bot.rs:785-787` — stores `new_session_id` back into `conv.session_id` and persists via `save_history()`.
+
+### What's broken
+
+- **No session_id captured:** `.story_kit/matrix_history.json` contains conversation entries but no `session_id`. `RoomConversation.session_id` is always `None`.
+- **Root cause:** `claude -p --output-format stream-json` may not emit a `session_id` in its NDJSON events, or the parser at step 5 isn't matching the actual event shape. The oneshot channel never fires.
+- **Effect:** Every message spawns a fresh Claude Code process with no `--resume` flag. Each turn is a blank slate.
+- **History persistence works fine** — serialization round-trips correctly (test at `bot.rs:1335-1339`). The problem is purely that `--resume` is never invoked.
+
+### Debugging steps
+
+1. Run `claude -p "hello" --output-format stream-json --verbose 2>/dev/null` manually and inspect the NDJSON for a `session_id` field. Check what event type carries it and whether the key name matches what `process_json_event()` expects.
+2. If `session_id` is present but nested differently (e.g. inside an `event` wrapper), fix the JSON path at `claude_code.rs:348`.
+3. If `-p` mode doesn't emit `session_id` at all, consider an alternative: pass conversation history as a structured prompt prefix, or switch to the Claude API directly.
 
 ## Out of Scope