langrove 0.1.0__tar.gz

langrove-0.1.0/.claude/agents/architect.md

@@ -0,0 +1,58 @@
+---
+name: architect
+description: Plans implementation approach for complex features
+model: claude-opus-4-6
+tools: ["Read", "Glob", "Grep", "WebSearch"]
+---
+You are the Langrove architect agent. Your job is to analyze
+requirements and create a detailed implementation plan. You do NOT
+write code — only plans. Follow CLAUDE.md principles strictly.
+
+## Before Planning
+1. Read `.claude/rules/` files relevant to the area you're planning for
+2. Read CLAUDE.md for project principles and structure
+3. Read the issue description and acceptance criteria carefully
+4. Identify ALL files that need to change — read them to understand current state
+
+## Plan Format
+Post the plan as a **GitHub issue comment** using this exact structure:
+
+```
+## Implementation Plan
+
+### Approach
+(1-3 sentences describing the strategy)
+
+### Files to Modify
+- `path/to/file.py` — what changes and why
+
+### Files to Create
+- `path/to/new.py` — purpose and responsibility
+
+### Test Plan
+- What scenarios to test
+- Which existing tests may need updates
+
+### Estimated Diff Size
+- Lines added/removed estimate
+- Complexity assessment
+
+### Risk Assessment
+- low / medium / high — and why
+- Any areas requiring extra caution
+```
+
+## Complexity Estimation
+- **small** (<100 lines diff, single file or module)
+- **medium** (100-300 lines, multiple files in same module)
+- **large** (>300 lines, cross-module changes)
+
+If estimated as large: add labels `complexity:large` + `blocked` instead of `planned`.
+Only proceed with `planned` label for small/medium issues.
+
+## After Planning
+- Remove `triage` label, add `planned` + appropriate `complexity:*` label
+- Append new learnings to the most relevant `.claude/rules/` file:
+  - Date prefix: `- YYYY-MM-DD: <concise learning>`
+  - Only add genuinely new insights, not duplicates of existing entries
+- **Do NOT commit or push** — you only read files and post issue comments

langrove-0.1.0/.claude/agents/implementer.md

@@ -0,0 +1,52 @@
+---
+name: implementer
+description: Implements features following the architect's plan
+model: claude-opus-4-6
+tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+You are the Langrove implementation agent. You receive a plan
+from the architect and implement it precisely. Follow CLAUDE.md strictly.
+
+## Before Implementing
+1. Read `.claude/rules/` files relevant to the files you'll touch
+2. Read CLAUDE.md for project principles and structure
+3. Read the **Implementation Plan** comment on the issue (posted by architect)
+4. Follow the plan exactly unless you find a technical reason not to
+
+## Implementation Process
+1. **Never commit or push directly to `main`.**
+2. Create a new branch from `main`: `git checkout main && git pull && git checkout -b claude/{issue-number}-{short-slug}`
+3. Implement changes following the architect's plan
+4. Write tests for all new/changed functionality
+5. Run the full quality check:
+   ```bash
+   uv run ruff check . && uv run ruff format . && uv run pytest
+   ```
+6. Fix any failures (up to 3 retry cycles)
+7. Commit all changes on the branch with a message referencing the issue
+
+## Diff Size Guard
+- If your changes exceed **500 lines**, STOP
+- Add labels `blocked` + `human-review-required` to the issue
+- Post a comment explaining why the diff is larger than expected
+- Do NOT open a PR
+
+## PR Convention
+- Branch: `claude/{issue-number}-{short-slug}` — always branched off `main`, never commit to `main` directly
+- Push the branch and open a PR targeting `main`
+- PR description must include: `Closes #{issue-number}`
+- If you deviated from the architect's plan, explain why in the PR description
+- Labels: remove `in-progress`, add `review`
+
+## Code Standards (from CLAUDE.md)
+- KISS, YAGNI, SOLID, OOP
+- Raw asyncpg SQL — no ORM
+- Services receive dependencies via constructor injection
+- API handlers are thin — delegate to services
+- No speculative abstractions
+
+## After Implementing
+- Append new learnings to the most relevant `.claude/rules/` file:
+  - Date prefix: `- YYYY-MM-DD: <concise learning>`
+  - Only genuinely new insights (implementation gotchas, patterns discovered)
+- Commit rules/ updates alongside implementation changes

langrove-0.1.0/.claude/agents/reviewer.md

@@ -0,0 +1,59 @@
+---
+name: reviewer
+description: Reviews code for quality, security, and correctness
+model: claude-opus-4-6
+tools: ["Read", "Glob", "Grep", "Bash"]
+---
+You are the Langrove code review agent. Review code changes thoroughly
+but concisely. Follow CLAUDE.md principles as the quality bar.
+
+## Before Reviewing
+1. Read `.claude/rules/` files relevant to the changed files
+2. Read CLAUDE.md for project principles
+
+## Review Checklist
+For every PR, check:
+
+### Security
+- [ ] All SQL queries use `$N` parameterized syntax — no f-strings or string interpolation
+- [ ] No hardcoded secrets or credentials
+- [ ] Auth bypass not possible via missing middleware checks
+- [ ] JSONB inputs properly cast with `::jsonb`
+
+### Async Correctness
+- [ ] All I/O operations properly awaited
+- [ ] No blocking calls in async context (no `time.sleep`, `requests.get`)
+- [ ] Connection pools properly acquired/released (context managers)
+- [ ] `asyncio.aclosing()` used for astream() generators
+
+### CLAUDE.md Adherence
+- [ ] KISS — no unnecessary complexity
+- [ ] YAGNI — no speculative features or abstractions
+- [ ] SOLID — single responsibility, dependency injection
+- [ ] Raw asyncpg — no ORM usage
+- [ ] Thin API handlers — logic in services, not routes
+
+### Test Coverage
+- [ ] New code paths have corresponding tests
+- [ ] Edge cases considered (None, empty, error states)
+- [ ] Tests actually assert meaningful behavior
+
+### SSE Format (if streaming changes)
+- [ ] Wire format compliance: `event: {name}\ndata: {json}\n\n`
+- [ ] Event sequence: metadata first, end last
+- [ ] Subgraph namespace uses pipe delimiter
+
+## Decision Tree
+- **APPROVE** if: tests pass, no security issues, follows CLAUDE.md, reasonable coverage
+- **REQUEST_CHANGES** if: security vulnerability, missing tests for critical paths, CLAUDE.md violations, broken async patterns
+
+## Review Cycle Limit
+- Track how many review cycles have occurred (check existing review comments)
+- After **2 review cycles** with unresolved issues: add `human-review-required` label and stop
+
+## After Reviewing
+- On approve: remove `review` label, add `done`
+- On request changes: remove `review` label, add `in-progress`
+- Append new learnings to the most relevant `.claude/rules/` file:
+  - Date prefix: `- YYYY-MM-DD: <concise learning>`
+  - Focus on recurring patterns (what keeps coming up in reviews)

langrove-0.1.0/.claude/journals/README.md

@@ -0,0 +1,30 @@
+# Agent Journals
+
+This directory previously contained per-role journal files (planner.md, implementer.md, reviewer.md).
+
+## Migration to `.claude/rules/`
+
+Agent learnings are now stored in **topic-based `.claude/rules/` files** instead of per-role journals.
+This follows the industry-standard pattern (Lore Protocol, Letta Context Repositories, Cline Memory Bank)
+and uses Claude Code's native path-scoped rules for automatic context loading.
+
+### How it works now
+
+- Knowledge organized by domain: `database.md`, `streaming.md`, `auth.md`, etc.
+- Files have `globs:` frontmatter — Claude auto-loads relevant rules when editing matching files
+- All agents share all knowledge (no role silos)
+- Agents append new learnings to the most relevant rules/ file after completing work
+- Weekly maintenance consolidates and deduplicates entries
+
+### Rules files
+
+| File | Scope |
+|------|-------|
+| `rules/database.md` | asyncpg, JSONB, pools, migrations |
+| `rules/streaming.md` | SSE format, pub/sub, event replay |
+| `rules/worker-tasks.md` | Redis Streams, consumer groups, recovery |
+| `rules/auth.md` | middleware, authorization, AuthUser |
+| `rules/api-design.md` | FastAPI patterns, services, error handling |
+| `rules/testing.md` | pytest conventions, fixtures, CI |
+| `rules/architecture.md` | system design, graph loading, lifecycle |
+| `rules/pipeline.md` | automation meta-learnings |

langrove-0.1.0/.claude/journals/implementer.md

@@ -0,0 +1,7 @@
+# Implementer Agent Journal
+
+> **Migrated to `.claude/rules/`** — Agent learnings are now stored by topic
+> (database.md, streaming.md, etc.) instead of by role. See `.claude/rules/` for all knowledge.
+>
+> This file is kept for backwards compatibility. New learnings go into the
+> most relevant `.claude/rules/` file.

langrove-0.1.0/.claude/journals/planner.md

@@ -0,0 +1,7 @@
+# Planner Agent Journal
+
+> **Migrated to `.claude/rules/`** — Agent learnings are now stored by topic
+> (database.md, streaming.md, etc.) instead of by role. See `.claude/rules/` for all knowledge.
+>
+> This file is kept for backwards compatibility. New learnings go into the
+> most relevant `.claude/rules/` file.

langrove-0.1.0/.claude/journals/reviewer.md

@@ -0,0 +1,7 @@
+# Reviewer Agent Journal
+
+> **Migrated to `.claude/rules/`** — Agent learnings are now stored by topic
+> (database.md, streaming.md, etc.) instead of by role. See `.claude/rules/` for all knowledge.
+>
+> This file is kept for backwards compatibility. New learnings go into the
+> most relevant `.claude/rules/` file.

langrove-0.1.0/.claude/rules/api-design.md

@@ -0,0 +1,64 @@
+---
+description: FastAPI route patterns, dependency injection, service layer, error handling, and request/response models
+globs:
+  - "src/langrove/api/**/*.py"
+  - "src/langrove/models/**/*.py"
+  - "src/langrove/services/**/*.py"
+  - "src/langrove/exceptions.py"
+---
+
+# API Design
+
+## Route Handler Pattern
+- **Thin handlers** — delegate ALL business logic to services
+- Handlers only: parse request, inject dependencies, call service, return response
+- One router per resource: agents, assistants, threads, runs, store, crons, health, dead_letter
+
+## Dependency Injection
+- FastAPI `Depends()` functions in `api/deps.py`
+- App-level resources: `request.app.state.{db_pool, redis, graph_registry, checkpointer, store}`
+- Request-scoped: `request.state.{user, auth}`
+- Service factory pattern:
+  ```python
+  def _get_service(db=Depends(get_db), registry=Depends(get_graph_registry)):
+      return ServiceClass(Repository(db), registry)
+  ```
+
+## Service Layer
+- Services instantiated fresh per-request (not cached)
+- Constructor injection: `__init__(self, repo, registry, ...)`
+- Repositories are lightweight, stateless data-access objects
+- One service per domain: AssistantService, RunService, ThreadService, StoreService, CronService
+
+## Error Hierarchy
+```
+LangroveError (base)
+├── NotFoundError(resource: str, resource_id: str) → 404
+├── ConflictError(message: str) → 409
+├── AuthError(message: str) → 401
+└── ForbiddenError(message: str) → 403
+```
+- Response format: `JSONResponse({"code": "error_type", "message": "..."})`
+- Exception handlers registered in `app.py`
+
+## Request/Response Models
+- Response models: Pydantic `BaseModel` with UUID + datetime fields
+- Create models: optional `if_exists` field ("raise" | "do_nothing")
+- Search models: optional filters + `limit`/`offset` pagination
+- Patch/Update: all fields optional, `model_dump(exclude_none=True)` for partial updates
+
+## Key Patterns
+- `if_exists="do_nothing"` returns existing record instead of ConflictError
+- Thread state is dual-sourced: record (metadata, status) from repo + state (values, next, tasks) from checkpointer
+- Ephemeral threads: auto-deleted after stream completes if `on_completion="delete"`
+- Run cancellation: DB status → "interrupted" + Redis cancel key + thread reset to "idle"
+
+## Three Run Execution Modes
+1. `stream_run()` — foreground SSE streaming (same process, asyncio.Queue)
+2. `wait_run()` — foreground blocking, returns final state
+3. `background_run()` — dispatches to Redis Streams queue, returns Run immediately
+
+## Gotchas
+- Services are NOT singletons — new instance per request
+- `metadata_` → `metadata` rename happens in repository layer, not service/API layer
+- Auth user injected into graph config as `langgraph_auth_user` key in configurable dict

langrove-0.1.0/.claude/rules/architecture.md

@@ -0,0 +1,65 @@
+---
+description: System architecture, graph loading, app lifecycle, and cross-cutting patterns
+globs:
+  - "src/langrove/**/*.py"
+---
+
+# Architecture
+
+## Graph Instance Per Request
+- Base graphs loaded at startup into `GraphRegistry` — cached without checkpointer (immutable, shared)
+- Per-request: `graph.copy(update={...})` injects checkpointer + store
+- Config deep-copied per request via `deepcopy(config)` to prevent concurrent mutations
+- Fallback to shallow copy if deepcopy fails (e.g., non-serializable objects like LangfuseResourceManager)
+
+## Graph Loading (graph/loader.py)
+- Dynamic module loading: `importlib.util.spec_from_file_location()` from `"./path/to/module.py:attribute"` specs
+- Parent directory auto-added to `sys.path` for transitive imports
+- Relative paths resolve against config file directory, NOT cwd
+
+## App Factory (app.py)
+- `create_app()` with `@asynccontextmanager` for async lifespan
+- **Startup order:** load .env → asyncpg pool → Redis → load graphs → setup checkpointer (psycopg) → setup store (psycopg) → auto-create assistants
+- **Shutdown:** close all pools (checkpointer, store, db, redis)
+- State on `app.state`: `db_pool`, `redis`, `graph_registry`, `checkpointer`, `store`, `settings`, `config`
+
+## Middleware Stack
+1. CORS (configured from `config.http.cors`)
+2. Auth (if `config.auth.path` set) — see `.claude/rules/auth.md`
+
+## Two Database Pool Types
+- **asyncpg** (`db/pool.py`): app-level queries (threads, runs, assistants, store, crons)
+- **psycopg** (`db/langgraph_pools.py`): LangGraph checkpointer + store (separate pools, autocommit=True)
+
+## Streaming Architecture
+- **Foreground:** `asyncio.Queue` per run_id — publish/subscribe within same process
+- **Background:** Redis pub/sub (live events) + Redis Streams (replay/reconnection)
+- See `.claude/rules/streaming.md` for details
+
+## Thread State Lifecycle
+- Status: `idle` → `busy` → `success|error` → `idle`
+- Thread `values` and `interrupts` are NOT stored in threads table — derived from LangGraph checkpointer at read time
+
+## Ephemeral Threads
+- Created when no `thread_id` provided and `on_completion="delete"`
+- Auto-deleted in generator `finally` block after stream completes
+
+## Config File (langgraph.json)
+- Parsed by `config.py` with Pydantic models
+- Fallback loading: `langgraph.json` → `aegra.json` → defaults
+- `.env` path in config resolves relative to config file directory
+- Graphs: `{"graph_id": "./path/to/module.py:attribute"}`
+
+## CLI Commands (cli.py)
+- `langrove serve` — FastAPI via uvicorn (default port 8123)
+- `langrove worker` — Redis Streams consumer + recovery monitor
+- `langrove init` — scaffold langgraph.json + agent.py
+
+## Settings (settings.py)
+- Pydantic BaseSettings with `env_prefix="LANGROVE_"` and `.env` file support
+- Key defaults: DB pool 2-10, checkpointer pool 5, store pool 5, worker concurrency 5, task timeout 900s, event TTL 86400s (24h)
+
+## Gotchas
+- Multiple workers each spawn all pools — can exhaust PostgreSQL max_connections quickly
+- Auth user injected into graph configurable as `langgraph_auth_user` key
+- `asyncio.aclosing()` required for astream() generator cleanup (releases checkpoint locks)

langrove-0.1.0/.claude/rules/auth.md

@@ -0,0 +1,63 @@
+---
+description: Authentication middleware, authorization handlers, AuthUser protocol, and custom auth loading
+globs:
+  - "src/langrove/auth/**/*.py"
+---
+
+# Authentication & Authorization
+
+## Two-Stage Auth
+1. **Authenticate** (request-level via middleware): validates credentials → returns AuthUser
+2. **Authorize** (per-operation via deps.py): checks if user can perform action on resource
+
+## Auth Handler Resolution (Priority Order)
+1. Exact match: `(resource, action)` — e.g., `("assistants", "create")`
+2. Resource-level: `(resource, *)` — e.g., `("assistants", "*")`
+3. Global: catches all
+
+## AuthUser Protocol
+- Implements `langgraph_sdk.auth.types.BaseUser`
+- Properties: `identity`, `display_name`, `permissions`, `is_authenticated`
+- Dict-like access: `user[key]`, `key in user`, `iter(user)`
+- `to_dict()` serializes for graph configurable injection as `langgraph_auth_user`
+- Uses `__slots__` for memory efficiency
+
+## CustomAuthHandler (auth/custom.py)
+- Loads from `module.py:handler` spec in `langgraph.json` auth config
+- Supports two modes:
+  - Plain async function: `async def handler(headers) -> dict`
+  - `langgraph_sdk.Auth` instance with `@auth.authenticate` decorator
+
+### Parameter Injection (signature-based)
+Handler parameters are inspected and injected:
+- `headers` → full headers dict
+- `authorization` → extracted from `headers["authorization"]`
+- `method` → HTTP method string
+- `path` → request path string
+- Unknown params → falls back to headers as first positional arg
+
+### Return Type Handling
+- `None` → 401 (reject)
+- `str` → `AuthUser(identity=string)`
+- `dict` → must have `identity` key, optional `display_name`, `permissions`
+- Object with `.identity` → extracted as MinimalUser protocol
+
+## AuthMiddleware (auth/middleware.py)
+- Extends `BaseHTTPMiddleware`
+- Skip paths: `/ok`, `/health`, `/info`, `/docs`, `/openapi.json`, `/redoc`
+- Skips OPTIONS (CORS preflight)
+- Stores result: `request.state.user` (AuthUser) + `request.state.auth` (langgraph_sdk.Auth or None)
+
+## Authorization in API Endpoints (deps.py)
+- `authorize(request, resource, action, value_dict)` — for write operations
+  - Handler can return `False` (reject → 403), `True/None` (accept), or modified dict (rewrite values)
+- `authorize_read(request, resource, metadata)` — for read operations
+  - Validates fetched resource against filter operators: `$eq`, `$contains`
+
+## NoopAuthHandler (auth/noop.py)
+- Development mode: always returns `AuthUser(identity="anonymous", permissions=("authenticated",))`
+
+## Gotchas
+- Auth is null-safe: no `request.state.auth` = no-op passthrough
+- `request.state.auth` is the `langgraph_sdk.Auth` instance (for authorization rules), not the AuthUser
+- Store namespace can be rewritten by auth handler via authorization result

langrove-0.1.0/.claude/rules/database.md

@@ -0,0 +1,56 @@
+---
+description: asyncpg query patterns, JSONB handling, connection pools, and migration conventions
+globs:
+  - "src/langrove/db/**/*.py"
+  - "migrations/**/*.py"
+---
+
+# Database
+
+## asyncpg JSONB Handling
+- asyncpg returns JSONB as JSON-encoded strings. The custom codec in `db/pool.py` uses `orjson.loads()` which may need two passes (first unwraps outer quotes, second extracts the object)
+- Encoder: `orjson.dumps(v).decode()` — must decode bytes to string for PostgreSQL
+- Codec registration uses "text" format (not "binary") via `init` callback on pool creation
+
+## Query Patterns
+- ALL queries use `$N` positional parameters — never f-strings or string interpolation (SQL injection prevention)
+- JSONB inserts require explicit `::jsonb` cast: `VALUES ($1::jsonb)`
+- Dynamic WHERE building: track `idx` counter, append conditions + args in lockstep
+  ```python
+  conditions.append(f"{key} = ${idx}")
+  args.append(value)
+  idx += 1
+  ```
+- JSONB containment operator: `metadata_ @> $N::jsonb` with `orjson.dumps(dict).decode()`
+- Only interpolate known field names into SQL — parameters always use $N placeholders
+
+## Field Naming
+- DB column `metadata_` (reserved word escape) → normalized to `metadata` in Python dicts
+- All repositories call `_normalize()` to handle this rename
+- Config/JSON columns use `::jsonb` cast on INSERT/UPDATE
+
+## Store Namespace
+- PostgreSQL `ARRAY(TEXT)` type for hierarchical keys
+- Queried via array slice: `namespace[1:{len(prefix)}]` — positional, not semantic
+- Composite PK: `(namespace, key)`
+
+## Connection Pools
+- asyncpg: min=2, max=10 (app-level queries via `db/pool.py`)
+- psycopg: max=5 each (LangGraph checkpointer + store via `db/langgraph_pools.py`)
+- Total up to 20 connections per server instance — watch for PostgreSQL `max_connections` exhaustion with multiple workers
+- psycopg pools use `autocommit=True, prepare_threshold=0`
+
+## Transactions & Atomicity
+- No explicit transactions in repositories — each method is a single atomic query
+- Multi-step operations (create run + update status) are NOT transactional
+
+## Version Snapshots
+- `ON CONFLICT (assistant_id, version) DO NOTHING` for idempotent history writes
+- Version auto-incremented on UPDATE before INSERT into versions table
+
+## Gotchas
+- `orjson.dumps(None)` produces `"null"` string — correct for PostgreSQL NULL JSONB
+- Store items have no indices beyond PK — could bottleneck on large stores
+- Pool acquisition: `async with self.pool.acquire() as conn` — single connection per query
+- All `fetch_*` methods return dicts via `dict(row)` conversion from asyncpg.Record
+- 2026-04-07: Checkpointer pool is psycopg (not asyncpg) — uses `%s` placeholders, acquired via `async with checkpointer.conn.connection() as conn`. The `$N` asyncpg convention applies only to the app-level `DatabasePool`, not the checkpointer/store psycopg pools.

langrove-0.1.0/.claude/rules/pipeline.md

@@ -0,0 +1,23 @@
+---
+description: Automated pipeline meta-learnings and coordination knowledge
+---
+
+# Pipeline Automation
+
+## Label State Machine
+```
+New Issue → [triage] → [planned] → [in-progress] → [review] → [done]
+                                         ↑               |
+                                         +-- (REQUEST_CHANGES) --+
+
+blocked / human-review-required: applied on top of any state, pause automation
+```
+
+## Coordination Rules
+- Only ONE issue may be `in-progress` at a time
+- `complexity:large` issues skipped unless `force-auto` label present
+- Max 2 review cycles before `human-review-required`
+- 500-line diff limit on PRs
+
+## Learnings
+<!-- Pipeline agents append new learnings below this line -->

langrove-0.1.0/.claude/rules/streaming.md

@@ -0,0 +1,74 @@
+---
+description: SSE wire format, event types, stream modes, pub/sub broker, and event replay
+globs:
+  - "src/langrove/streaming/**/*.py"
+---
+
+# Streaming
+
+## SSE Wire Format (useStream / LangGraph SDK compatible)
+- Format: `event: {name}\ndata: {json}\n\n` — double newline terminates each event
+- Content-Type: `text/event-stream`
+- Optional reconnection: `id: {event_id}` line before data line
+
+## Event Sequence
+1. `metadata` — always first: `{"run_id": "..."}`
+2. `values` / `updates` / `messages` — graph execution events
+3. `end` — always last: `data: null` (literal null, not omitted)
+4. `error` — terminal on exception: `{"error": "...", "message": "ExceptionType"}`
+
+## Stream Modes
+- Input can be string or list: `stream_mode: str | list[str]`
+- Langrove internally adds "updates" (always) for interrupt detection
+- "messages" mode also adds "messages-tuple" internally (SDK convenience)
+- SDK-internal modes ("events", "messages-tuple") stripped before processing chunks
+
+## Chunk Processing (executor.py)
+LangGraph `astream()` output varies by configuration:
+- Single mode, no subgraphs: bare `chunk`
+- Multi-mode, no subgraphs: `(mode, chunk)` tuple
+- Single mode, subgraphs=True: `(namespace_tuple, chunk)`
+- Multi-mode, subgraphs=True: `(namespace_tuple, mode, chunk)`
+
+## Subgraph Namespace
+- Pipe-delimited event names: `updates|parent|child`
+- SDK parses pipes to route subagent messages to correct handler
+- Supports arbitrary nesting depth
+
+## Messages Mode
+- Chunks are `(BaseMessageChunk, metadata_dict)` tuples
+- Serialized via `model_dump()` (Pydantic v2) or `dict()` (Pydantic v1)
+- If message is already a dict (not Pydantic), use as-is
+
+## Updates Mode
+- Contains interrupts as `__interrupt__` key: `{"__interrupt__": [...]}`
+- Only forwarded as SSE if explicitly requested OR contains interrupt data
+- Prevents duplicate state broadcasts
+
+## JSON Serialization
+- `_default(obj)` fallback: tries `obj.model_dump()` → `obj.dict()` → TypeError
+- Handles LangChain message objects, UUIDs, datetimes (orjson native)
+
+## Event IDs
+- Format: `{run_id}_event_{counter}` — monotonically increasing
+- Must be sortable for Redis XRANGE replay
+- Client sends `Last-Event-ID` header on reconnect
+
+## Event Broker Architecture
+- **Foreground runs (same process):** `asyncio.Queue` per run_id in `_local_queues` dict
+- **Background runs (cross-process):** Redis pub/sub channel `langrove:runs:{run_id}:stream`
+- **Event storage:** Redis Streams `langrove:runs:{run_id}:events` (TTL configurable, default 24h)
+
+## Event Replay (subscribe-first pattern)
+1. Subscribe to pub/sub FIRST (captures events during replay gap)
+2. Replay stored events via XRANGE from "-" to "+"
+3. Skip events until `last_event_id` found
+4. Yield stored events, tracking seen IDs in `seen_ids` set
+5. Drain live pub/sub, deduplicating by ID
+6. Stop on "end" or "error" event
+
+## Gotchas
+- Redis pub/sub doesn't persist — messages lost if no subscribers present
+- `end` event data is `null`, not omitted: `data: null\n`
+- `asyncio.aclosing()` required for astream() generator cleanup (releases checkpoint locks)
+- Implicitly added `values` mode is suppressed if not in user's original request

langrove-0.1.0/.claude/rules/testing.md

@@ -0,0 +1,37 @@
+---
+description: pytest conventions, fixtures, test patterns, and CI commands
+globs:
+  - "tests/**/*.py"
+---
+
+# Testing
+
+## Framework
+- `pytest` + `pytest-asyncio` for all async tests
+- Dev dependencies: `httpx` (test client), `testcontainers[postgres,redis]`
+
+## Fixtures (conftest.py)
+- `fixtures_dir` → `Path(__file__).parent / "fixtures"` — test data directory
+- `test_config_path` → path to test `langgraph.json`
+- Path objects from fixtures — convert with `str()` when passing to functions expecting strings
+
+## Test Patterns
+- **Auth tests:** create temp handler files with `tmp_path.write_text()`, test module loading
+- **SSE formatter tests:** verify exact wire format (event names, JSON encoding, blank line separators, null data)
+- **Config tests:** valid/invalid JSON, missing files (returns defaults), type validation, CORS parsing
+- **Graph registry tests:** loading from config, NotFoundError for missing graphs, schema extraction
+
+## Conventions
+- No mocking of database when possible — use real postgres via testcontainers
+- Full stream sequence tests: metadata → events → end
+- Test both success and error paths for every endpoint
+
+## Commands
+```bash
+uv run pytest --tb=short -q          # Quick feedback
+uv run pytest tests/test_runs.py     # Specific file
+uv run pytest -x -v                  # Stop on first failure, verbose
+uv run ruff check .                  # Lint
+uv run ruff format .                 # Format
+uv run ruff check . && uv run ruff format . && uv run pytest  # Full pre-commit check
+```