Add context generation for BlueBoxAgent session replay

[dimavrem22]

Summary

• Add BlueBoxAgentContext Pydantic model with JSON and Markdown round-trip serialization (to_markdown() / from_markdown())
• Add generate_context agent tool that saves both a canonical JSON and companion Markdown file to the workspace context/ directory
• Auto-discover and inject prior context into the system prompt on agent init (from workspace context/ dir or explicit --context-file CLI flag)
• Add /generate_context slash command in the TUI that prompts the agent to distill the current session into a reusable context file
• unit tests covering model serialization, markdown round-trip, context loading, prompt injection, truncation, and tool registration

[dimavrem22]

@claude review!

[claude]

Claude finished @dimavrem22's task in 2m 28s —— View job

---

Code Review

Tasks:

• Gather context and understand request
• Read all changed files
• Analyze code quality, correctness, and test coverage
• Post review feedback

---

Overall this is clean, well-structured work. The model design, round-trip serialization, auto-discovery logic, and context injection are all solid. The test coverage is thorough. A few issues worth fixing before merge:

---

Issues

1. Flaky test — time.sleep(0.05) may not be enough to differentiate mtimes

tests/unit/agents/test_bluebox_agent_context.py:233

time.sleep(0.05)  # ensure mtime differs

On some Linux filesystems (ext4 with relatime, tmpfs, CI NFS mounts), mtime granularity can be coarser than 50ms, making this test intermittently fail. Use os.utime to explicitly set the mtime instead:

old_file = context_dir / "old.json"
old_file.write_text(old.model_dump_json())
import os, time
os.utime(old_file, (time.time() - 1, time.time() - 1))  # force 1s in the past

Fix this →

---

2. import sys breaks import grouping

bluebox/scripts/run_bluebox_agent.py:28

import argparse
import shutil
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Any
import sys   # ← should be grouped with the other stdlib imports above

Per CLAUDE.md ("Group imports: stdlib, third-party, local (with blank lines between groups)"), import sys must be in the stdlib block at the top.

Fix this →

---

3. Auto-discovery only scans .json, not .md

bluebox/agents/bluebox_agent.py:340

json_files = sorted(context_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)

Explicit context_file= accepts both .json and .md, but auto-discovery silently ignores .md files. If a user manually provides only a Markdown context file (no companion JSON), auto-discovery misses it. Either add .md discovery with JSON taking priority, or document this limitation in the docstring.

---

4. Status None included in "completed" filter — misleading comment

bluebox/agents/bluebox_agent.py:382

# Only include completed executions
if rr.get("status") not in ("completed", None):
    continue

The comment says "Only include completed executions" but status=None (missing field) is also accepted. If a raw file is missing the status key entirely, it passes through. Either update the comment to reflect the intent ("include completed or unknown-status executions") or tighten the check to != "completed" if failed routines should truly be excluded.

---

5. Truncation can slightly exceed _CONTEXT_PROMPT_MAX_CHARS

bluebox/agents/bluebox_agent.py:359–363

if len(section) > self._CONTEXT_PROMPT_MAX_CHARS:
    section = section[:self._CONTEXT_PROMPT_MAX_CHARS] + (
        "\n\n... (context truncated — use `read_workspace_file` to read "
        "the full context files in `context/` for more detail)"
    )

After slicing to _CONTEXT_PROMPT_MAX_CHARS, the appended hint adds ~100 characters, pushing the result over the limit. This is unlikely to matter in practice (100 extra chars on a 20K limit), but worth noting if the limit is ever used for strict token budgeting.

---

6. _show_context_success type annotation is Any

bluebox/scripts/run_bluebox_agent.py:170

def _show_context_success(self, context: Any) -> None:

Since generate_context returns BlueBoxAgentContext, this should be typed context: BlueBoxAgentContext. Per CLAUDE.md every function must have type hints.

Fix this →

---

7. assert isinstance(...) in TUI gives a cryptic error on failure

bluebox/scripts/run_bluebox_agent.py:164

assert isinstance(self._agent, BlueBoxAgent)

A bare assert produces an unhelpful AssertionError. Prefer an explicit check:

if not isinstance(self._agent, BlueBoxAgent):
    raise TypeError(f"Expected BlueBoxAgent, got {type(self._agent).__name__}")

---

Nits

• TestContextLoading._make_agent return type (tests/unit/agents/test_bluebox_agent_context.py:185): annotated as Any but should be BlueBoxAgent. Same for TestContextPromptInjection._make_agent at line 291 and TestGenerateContext._make_agent at line 354.

• test_from_markdown_roundtrip missing generated_at assertion (tests/unit/agents/test_bluebox_agent_context.py:138): the sample context has a fixed generated_at; the round-trip test checks all other fields but skips the timestamp. Adding assert restored.generated_at == sample_context.generated_at would increase confidence in the ISO format parsing.

• AgentWorkspace.save_file docstring (bluebox/agents/workspace.py:51): the subdirectory description still says ("raw" or "outputs") — should include "context" now that context/ is a first-class directory.

---

Strengths

• Clean Pydantic model with well-described fields and sensible defaults
• The dual-format (JSON + Markdown) strategy is practical: JSON for machine parsing, Markdown for human readability and system-prompt injection
• Safety net at generate_context:823 auto-populating routines_used from raw/ when the LLM leaves it empty is a nice guard
• Truncation with a read_workspace_file hint is agent-friendly
• Test coverage is comprehensive — good range of happy-path, edge cases (empty fields, bad JSON, missing files), and integration-level tests
• Workspace test cleanup (removing redundant .mkdir() calls) is a clean side-effect fix
• The "one-shot structured output call that doesn't advance _previous_response_id" pattern is well-commented and correct

[dimavrem22]

@claude review again

[claude]

Claude finished @dimavrem22's task in 2m 39s —— View job

---

Code Review (re-review)

Tasks:

• Gather context and understand request
• Read all changed files
• Compare against previous review findings
• Post updated review feedback

---

Great work addressing the feedback — 6 of 7 issues from the previous review are fixed. One new issue spotted, and a few nits remain.

---

Fixed Since Last Review ✓

#	Issue	Status
1	Flaky time.sleep(0.05) test	✅ Fixed — now uses os.utime with 10s offset
2	import sys import grouping	✅ Fixed — moved to stdlib block at line 25
3	Auto-discovery only scanned .json	✅ Fixed — now falls back to .md with JSON priority
4	status=None accepted in "completed" filter	✅ Fixed — now strictly != "completed"
5	_show_context_success typed as Any	✅ Fixed — now BlueBoxAgentContext at line 172
6	assert isinstance(...) cryptic error	✅ Fixed — TypeError with message at line 165

---

New Issue

Lazy imports in test file violate CLAUDE.md

tests/unit/agents/test_bluebox_agent_context.py:189, 294, 336, 357, 374

# Repeated in _make_agent() of every test class, and in two standalone tests:
from bluebox.agents.bluebox_agent import BlueBoxAgent
from bluebox.agents.workspace import LocalWorkspace

CLAUDE.md is explicit: "NO lazy imports! All imports must be at the top of the file." BlueBoxAgent and LocalWorkspace are imported inside method bodies in 5 separate places. They should be top-level imports alongside the existing from bluebox.data_models.agents.context import ... at line 18.

Fix this →

---

Remaining from Previous Review

Truncation slightly exceeds _CONTEXT_PROMPT_MAX_CHARS (still minor)

bluebox/agents/bluebox_agent.py:365–369

The appended hint (~100 chars) pushes the result over the 20_000 limit. Still acceptable unless this limit is ever used for strict token budgeting.

---

Remaining Nits

• _make_agent return type Any — tests/unit/agents/test_bluebox_agent_context.py:183, 293, 356: all three should return BlueBoxAgent instead of Any

• Missing generated_at in test_from_markdown_roundtrip — test_bluebox_agent_context.py:140: the round-trip check skips the timestamp field; adding assert restored.generated_at == sample_context.generated_at would confirm ISO format parsing works

• AgentWorkspace.save_file docstring — bluebox/agents/workspace.py:52: still says ("raw" or "outputs"), should include "context" now that it's a first-class subdirectory

---

Strengths

All the core logic is clean and the new _auto_discover_context fallback to .md is a nice improvement over the original. The strict != "completed" filter is correct and the TypeError message in the TUI is much more helpful. Ready to merge once the lazy-import issue is addressed.

---

[dimavrem22]

@claude check again!

[claude]

Claude finished @dimavrem22's task in 1m 25s —— View job

---

Code Review (re-review #3)

Tasks:

• Gather context and understand request
• Read all changed files
• Compare against previous review findings
• Post updated review feedback

---

All previously flagged issues and nits from review #2 are now fixed. This PR is ready to merge.

---

All Issues Resolved ✓

#	Issue	Status
1	Flaky time.sleep(0.05) test	✅ Fixed — os.utime with 10s offset
2	import sys import grouping	✅ Fixed — stdlib block at line 25
3	Auto-discovery only scanned .json	✅ Fixed — falls back to .md
4	status=None accepted in "completed" filter	✅ Fixed — strictly != "completed"
5	_show_context_success typed as Any	✅ Fixed — BlueBoxAgentContext at line 172
6	assert isinstance(...) cryptic error	✅ Fixed — TypeError with message at line 166
7	Lazy imports in test file	✅ Fixed — top-level at lines 17–18

All Nits Resolved ✓

Nit	Status
_make_agent return type Any (×3)	✅ Fixed — all three return BlueBoxAgent
Missing generated_at in test_from_markdown_roundtrip	✅ Fixed — assertion at line 156
AgentWorkspace.save_file docstring	✅ Fixed — includes "context" at line 52

---

Still Minor (not blocking)

Truncation slightly exceeds _CONTEXT_PROMPT_MAX_CHARS — bluebox/agents/bluebox_agent.py:365–369

The appended hint (~100 chars) pushes the result over 20_000. Acceptable unless this limit is used for strict token budgeting.

---

No new issues found. The code is clean, all feedback has been addressed, and the test coverage is solid.

---