From 443d611821edc76ddb48e3f99ca1fa7bc3204beb Mon Sep 17 00:00:00 2001 From: Bortlesboat <169967362+Bortlesboat@users.noreply.github.com> Date: Sun, 25 Oct 2026 17:41:23 -0400 Subject: [PATCH] Add source turn range tracking to checkpoints Record which session turns produced each checkpoint under metadata.source_turn_range at commit time. The range covers only turns since the session's previous checkpoint, within the same isolation boundary send_message and the draft endpoint use: fork-local turns (sequence_number > 0) for forked sessions, and post-mount turns (sequence_number > history_base_seq) when the commit request carries mounted_checkpoint_id and history_base_seq. - SourceTurnRange schema and a defensive parser live in app.schemas - source_turn_range is exposed on the commit response, the space state commit, and lineage checkpoint nodes - GET /api/v5/lineage/checkpoints/{id}/source-turns returns the turns - The chat UI passes its mount state when committing Addresses the open question in DECISIONS.md about tracking which turn range produced a checkpoint. --- backend/app/api/routes/chat.py | 78 ++++++- backend/app/api/routes/lineage.py | 34 +++ backend/app/schemas/__init__.py | 26 +++ .../integration/test_source_turn_range.py | 211 ++++++++++++++++++ docs/API.md | 22 ++ frontend/src/api/client.ts | 7 + frontend/src/pages/ChatWorkspacePage.tsx | 2 + frontend/src/types/index.ts | 9 + 8 files changed, 385 insertions(+), 4 deletions(-) create mode 100644 backend/tests/integration/test_source_turn_range.py diff --git a/backend/app/api/routes/chat.py b/backend/app/api/routes/chat.py index 771f423..911e1fc 100644 --- a/backend/app/api/routes/chat.py +++ b/backend/app/api/routes/chat.py @@ -30,7 +30,7 @@ logger = logging.getLogger(__name__) from fastapi import APIRouter, Depends, HTTPException, Query, Response from pydantic import BaseModel, Field -from sqlalchemy import select +from sqlalchemy import func, select from sqlalchemy.orm import Session from app.db.database import get_db @@ -43,6 +43,7 @@ from app.db.models import ( WorkTree, ) from app.config_loader import get_config, providers_status, ProviderNotConfiguredError +from app.schemas import SourceTurnRange, parse_source_turn_range from app.providers.registry import get_adapter, get_mock_adapter from app.services.worktree_probe import _probe_worktree @@ -298,6 +299,10 @@ class ManualCommitRequest(BaseModel): # against where it was when this checkpoint was recorded. Empty for # clients that cannot inspect a repo (e.g. the MCP server). repo_state: dict = Field(default_factory=dict) + # Mount isolation, same semantics as SendMessageRequest. Used to scope the + # checkpoint's source turn range to post-mount turns. + mounted_checkpoint_id: Optional[str] = None + history_base_seq: Optional[int] = None class CommitResponse(BaseModel): @@ -318,10 +323,17 @@ class CommitResponse(BaseModel): entities: list artifacts: list context_blob: dict = Field(default_factory=dict) + source_turn_range: Optional[SourceTurnRange] = None created_at: datetime model_config = {"from_attributes": True} + @classmethod + def from_commit(cls, commit: CommitModel) -> CommitResponse: + resp = cls.model_validate(commit) + resp.source_turn_range = parse_source_turn_range(commit.metadata_) + return resp + class HeadResponse(BaseModel): repo_id: uuid.UUID @@ -821,6 +833,57 @@ def send_message(payload: SendMessageRequest, db: Session = Depends(get_db)): # ── Manual commit endpoint ──────────────────────────────────────────────────── +def _compute_source_turn_range( + session: ChatSession, + mounted_checkpoint_id: Optional[str], + history_base_seq: Optional[int], + db: Session, +) -> Optional[dict]: + """ + Find the turns that produced a checkpoint about to be created from `session`. + + Applies the same isolation boundary as send_message / _fetch_turns_for_draft: + - explicit mount: sequence_number > history_base_seq (post-mount turns only) + - forked session: sequence_number > 0 (fork-local turns only) + - main session: no sequence boundary + + and then keeps only turns created after the session's previous checkpoint, + so a second checkpoint does not re-claim turns the first one already covered. + """ + stmt = select( + func.min(TurnEvent.sequence_number), + func.max(TurnEvent.sequence_number), + func.count(TurnEvent.id), + ).where(TurnEvent.session_id == session.id, TurnEvent.role != "system") + + if mounted_checkpoint_id is not None and history_base_seq is not None: + stmt = stmt.where(TurnEvent.sequence_number > history_base_seq) + elif session.forked_from_checkpoint_id is not None: + stmt = stmt.where(TurnEvent.sequence_number > 0) + + previous = db.scalars( + select(CommitModel) + .where( + CommitModel.repo_id == session.repo_id, + CommitModel.metadata_["session_id"].as_string() == str(session.id), + ) + .order_by(CommitModel.created_at.desc()) + .limit(1) + ).first() + if previous is not None: + stmt = stmt.where(TurnEvent.created_at > previous.created_at) + + first_seq, last_seq, turn_count = db.execute(stmt).one() + if not turn_count: + return None + return { + "session_id": str(session.id), + "first_sequence_number": first_seq, + "last_sequence_number": last_seq, + "turn_count": turn_count, + } + + @router.post("/commit", response_model=CommitResponse, status_code=201) def manual_commit(payload: ManualCommitRequest, db: Session = Depends(get_db)): """ @@ -857,6 +920,13 @@ def manual_commit(payload: ManualCommitRequest, db: Session = Depends(get_db)): # "repo_state" so context_blob stays open for other uses. context_blob = {"repo_state": payload.repo_state} if payload.repo_state else {} + metadata: dict = {"session_id": str(session_id)} + source_turn_range = _compute_source_turn_range( + session, payload.mounted_checkpoint_id, payload.history_base_seq, db + ) + if source_turn_range: + metadata["source_turn_range"] = source_turn_range + commit = CommitModel( repo_id=repo_id, commit_hash=commit_hash, @@ -879,14 +949,14 @@ def manual_commit(payload: ManualCommitRequest, db: Session = Depends(get_db)): open_questions=payload.open_questions, entities=payload.entities, artifacts=payload.artifacts, - metadata_={"session_id": str(session_id)}, + metadata_=metadata, context_blob=context_blob, ) db.add(commit) repo.updated_at = _utcnow() db.commit() db.refresh(commit) - return commit + return CommitResponse.from_commit(commit) # ── Head endpoint ───────────────────────────────────────────────────────────── @@ -1121,7 +1191,7 @@ def get_space_state( ) commit_resp = ( - CommitResponse.model_validate(main_head_commit) + CommitResponse.from_commit(main_head_commit) if main_head_commit else None ) diff --git a/backend/app/api/routes/lineage.py b/backend/app/api/routes/lineage.py index 95a4d3c..d06afe3 100644 --- a/backend/app/api/routes/lineage.py +++ b/backend/app/api/routes/lineage.py @@ -9,6 +9,9 @@ Branch/lineage view: Checkpoint comparison: GET /api/v5/lineage/checkpoints/{a_id}/compare/{b_id} – structured diff of two checkpoints + +Checkpoint provenance: + GET /api/v5/lineage/checkpoints/{id}/source-turns – turns that produced a checkpoint """ from __future__ import annotations @@ -26,6 +29,8 @@ from sqlalchemy.orm import Session from app.db.database import get_db from app.db.models import ChatSession, CommitModel, RepoModel, TurnEvent from app.config_loader import get_config +from app.api.routes.chat import TurnResponse +from app.schemas import SourceTurnRange, parse_source_turn_range router = APIRouter(prefix="/lineage", tags=["lineage-v5"]) @@ -83,6 +88,7 @@ class CheckpointNode(BaseModel): author_agent: Optional[str] = None note_count: int = 0 note_kinds: list[str] = Field(default_factory=list) + source_turn_range: Optional[SourceTurnRange] = None model_config = {"from_attributes": True} @@ -462,6 +468,7 @@ def get_lineage(space_id: uuid.UUID, db: Session = Depends(get_db)): author_agent=c.author_agent, note_count=nc, note_kinds=nk, + source_turn_range=parse_source_turn_range(c.metadata_), )) session_nodes = [ @@ -619,3 +626,30 @@ def get_session_reachable_checkpoints(session_id: uuid.UUID, db: Session = Depen # ancestor walk may interleave with them if branches share commit timestamps) result.sort(key=lambda c: c.created_at, reverse=True) return result + + +# ── Source turns endpoint ───────────────────────────────────────────────────── + +@router.get("/checkpoints/{checkpoint_id}/source-turns", response_model=list[TurnResponse]) +def get_checkpoint_source_turns(checkpoint_id: uuid.UUID, db: Session = Depends(get_db)): + """ + Return the turns that produced a checkpoint, oldest first. + + Driven by metadata.source_turn_range recorded at commit time. Checkpoints + without a (valid) range return an empty list. + """ + commit = _get_commit(checkpoint_id, db) + turn_range = parse_source_turn_range(commit.metadata_) + if turn_range is None: + return [] + + return list(db.scalars( + select(TurnEvent) + .where( + TurnEvent.session_id == turn_range.session_id, + TurnEvent.sequence_number >= turn_range.first_sequence_number, + TurnEvent.sequence_number <= turn_range.last_sequence_number, + TurnEvent.role != "system", + ) + .order_by(TurnEvent.sequence_number.asc()) + ).all()) diff --git a/backend/app/schemas/__init__.py b/backend/app/schemas/__init__.py index a89a277..3618f88 100644 --- a/backend/app/schemas/__init__.py +++ b/backend/app/schemas/__init__.py @@ -164,3 +164,29 @@ class CheckpointExtractResponse(BaseModel): # persist mock content into a real project. provider: str = Field("", description="Provider that produced this extraction (e.g. 'openai', 'anthropic', 'mock').") model: str = Field("", description="Model identifier that produced this extraction (or 'mock').") + + +class SourceTurnRange(BaseModel): + """The span of session turns that produced a checkpoint. + + Stored under ``metadata.source_turn_range`` on the commit at checkpoint time. + """ + session_id: uuid.UUID + first_sequence_number: int + last_sequence_number: int + turn_count: int + + +def parse_source_turn_range(metadata: dict | None) -> SourceTurnRange | None: + """Read ``source_turn_range`` from commit metadata. + + Returns None when the key is absent or malformed, so a bad row never + turns a read endpoint into a 500. + """ + data = (metadata or {}).get("source_turn_range") if isinstance(metadata, dict) else None + if not isinstance(data, dict): + return None + try: + return SourceTurnRange.model_validate(data) + except ValueError: + return None diff --git a/backend/tests/integration/test_source_turn_range.py b/backend/tests/integration/test_source_turn_range.py new file mode 100644 index 0000000..61d5e69 --- /dev/null +++ b/backend/tests/integration/test_source_turn_range.py @@ -0,0 +1,211 @@ +""" +Integration tests for checkpoint source turn ranges. + +A checkpoint records only the turns that produced it: turns since the session's +previous checkpoint, within the same isolation boundary send_message uses +(fork-local turns for forks, post-mount turns for mounts). +""" +import uuid + +from app.db.models import CommitModel + +# ── Helpers ─────────────────────────────────────────────────────────────────── + +def _create_repo(client, name="Turn Range Test Repo"): + r = client.post("/api/v2/repos", json={"name": name}) + assert r.status_code == 201, r.text + return r.json()["id"] + + +def _create_session(client, repo_id, title="test session"): + r = client.post(f"/api/v4/chat/spaces/{repo_id}/sessions", json={ + "title": title, "provider": "openrouter", "model": "mock", + }) + assert r.status_code == 201, r.text + return r.json()["id"] + + +def _send(client, session_id, message="hello", **kwargs): + r = client.post("/api/v4/chat/send", json={ + "session_id": session_id, + "provider": "openrouter", + "model": "mock", + "message": message, + "use_mock": True, + **kwargs, + }) + assert r.status_code == 200, r.text + return r.json() + + +def _commit(client, repo_id, session_id, message="checkpoint", **kwargs): + r = client.post("/api/v4/chat/commit", json={ + "repo_id": repo_id, + "session_id": session_id, + "message": message, + **kwargs, + }) + assert r.status_code == 201, r.text + return r.json() + + +def _fork(client, repo_id, checkpoint_id): + r = client.post("/api/v5/lineage/sessions/fork", json={ + "space_id": repo_id, "checkpoint_id": checkpoint_id, + }) + assert r.status_code == 201, r.text + return r.json()["session_id"] + + +def _source_turns(client, checkpoint_id): + r = client.get(f"/api/v5/lineage/checkpoints/{checkpoint_id}/source-turns") + assert r.status_code == 200, r.text + return r.json() + + +def _range(commit): + tr = commit["source_turn_range"] + return (tr["first_sequence_number"], tr["last_sequence_number"], tr["turn_count"]) + + +# ── Range scoping ───────────────────────────────────────────────────────────── + +def test_first_checkpoint_covers_all_turns(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "first message") + _send(client, session_id, "second message") + + commit = _commit(client, repo_id, session_id) + + assert commit["source_turn_range"]["session_id"] == session_id + assert _range(commit) == (0, 3, 4) + + +def test_second_checkpoint_covers_only_new_turns(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "a") + _send(client, session_id, "b") + first = _commit(client, repo_id, session_id, "first") + + _send(client, session_id, "c") + _send(client, session_id, "d") + second = _commit(client, repo_id, session_id, "second") + + assert _range(first) == (0, 3, 4) + assert _range(second) == (4, 7, 4) + turns = _source_turns(client, second["id"]) + assert [t["content"] for t in turns if t["role"] == "user"] == ["c", "d"] + + +def test_checkpoint_with_no_new_turns_has_no_range(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "a") + _commit(client, repo_id, session_id, "first") + + second = _commit(client, repo_id, session_id, "second, nothing new") + + assert second["source_turn_range"] is None + + +def test_fork_checkpoint_covers_only_fork_local_turns(client): + repo_id = _create_repo(client) + main_session = _create_session(client, repo_id) + _send(client, main_session, "main work") + base = _commit(client, repo_id, main_session, "base") + + fork_session = _fork(client, repo_id, base["id"]) + _send(client, fork_session, "fork a") + _send(client, fork_session, "fork b") + fork_ckpt = _commit(client, repo_id, fork_session, "fork checkpoint") + + # Same boundary send_message applies to forks: sequence_number > 0. + assert fork_ckpt["source_turn_range"]["session_id"] == fork_session + assert _range(fork_ckpt) == (1, 3, 3) + + _send(client, fork_session, "fork c") + fork_ckpt2 = _commit(client, repo_id, fork_session, "fork checkpoint 2") + assert _range(fork_ckpt2) == (4, 5, 2) + + +def test_mounted_checkpoint_covers_only_post_mount_turns(client): + repo_id = _create_repo(client) + other_session = _create_session(client, repo_id, "other") + _send(client, other_session, "other work") + mounted = _commit(client, repo_id, other_session, "to mount") + + session_id = _create_session(client, repo_id) + _send(client, session_id, "before mount 1") + _send(client, session_id, "before mount 2") # seq 0..3 + mount = {"mounted_checkpoint_id": mounted["id"], "history_base_seq": 3} + _send(client, session_id, "after mount", **mount) # seq 4..5 + + commit = _commit(client, repo_id, session_id, "mounted checkpoint", **mount) + + assert _range(commit) == (4, 5, 2) + turns = _source_turns(client, commit["id"]) + assert [t["content"] for t in turns if t["role"] == "user"] == ["after mount"] + + +# ── Read paths ──────────────────────────────────────────────────────────────── + +def test_source_turns_endpoint_returns_turns(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "design the API") + _send(client, session_id, "add error handling") + commit = _commit(client, repo_id, session_id) + + turns = _source_turns(client, commit["id"]) + + assert [t["role"] for t in turns] == ["user", "assistant", "user", "assistant"] + assert turns[0]["content"] == "design the API" + assert turns[2]["content"] == "add error handling" + assert all(t["role"] != "system" for t in turns) + seqs = [t["sequence_number"] for t in turns] + assert seqs == sorted(seqs) + + +def test_source_turns_empty_without_range(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + commit = _commit(client, repo_id, session_id, "no turns") + + assert commit["source_turn_range"] is None + assert _source_turns(client, commit["id"]) == [] + + +def test_source_turns_not_found_checkpoint(client): + r = client.get(f"/api/v5/lineage/checkpoints/{uuid.uuid4()}/source-turns") + assert r.status_code == 404 + + +def test_malformed_range_metadata_is_ignored(client, db_session): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "hello") + commit = _commit(client, repo_id, session_id) + + row = db_session.get(CommitModel, uuid.UUID(commit["id"])) + row.metadata_ = {"session_id": session_id, "source_turn_range": {"session_id": session_id}} + db_session.commit() + + assert _source_turns(client, commit["id"]) == [] + r = client.get(f"/api/v5/lineage/spaces/{repo_id}") + assert r.status_code == 200 + assert r.json()["checkpoints"][0]["source_turn_range"] is None + + +def test_lineage_and_state_include_source_turn_range(client): + repo_id = _create_repo(client) + session_id = _create_session(client, repo_id) + _send(client, session_id, "hello") + _commit(client, repo_id, session_id) + + lineage = client.get(f"/api/v5/lineage/spaces/{repo_id}").json() + assert lineage["checkpoints"][0]["source_turn_range"]["turn_count"] == 2 + + state = client.get(f"/api/v4/chat/spaces/{repo_id}/state").json() + assert state["commit"]["source_turn_range"]["turn_count"] == 2 diff --git a/docs/API.md b/docs/API.md index 9aa02bb..da47091 100644 --- a/docs/API.md +++ b/docs/API.md @@ -626,6 +626,16 @@ section. The field is optional: clients that cannot inspect a repo (e.g. the MCP server, which runs in the host's arbitrary working directory) may omit it, and the backend stores an empty `context_blob`. +**Source turn range.** Each checkpoint records which session turns produced it +under `metadata.source_turn_range` (`session_id`, `first_sequence_number`, +`last_sequence_number`, `turn_count`), also returned as `source_turn_range` on +the commit response, the state response's `commit`, and lineage checkpoint +nodes. The range covers only turns since the session's previous checkpoint, +within the same isolation boundary as `send`: fork-local turns for forked +sessions, and turns after `history_base_seq` when `mounted_checkpoint_id` and +`history_base_seq` are passed on the commit request. It is `null` when no new +turns exist. + --- ### Checkpoint history @@ -827,6 +837,18 @@ Reachability rules: --- +### Get source turns for a checkpoint + +``` +GET /api/v5/lineage/checkpoints/{checkpoint_id}/source-turns +``` + +Returns the turns covered by the checkpoint's `source_turn_range`, oldest first. +Empty array when the checkpoint has no recorded range. `404` if the checkpoint +does not exist. + +--- + ## V5 — Work Claims API Prefix: `/api/v5/claims` diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 3a71857..92f94c7 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -301,6 +301,8 @@ export async function createChatCommit(payload: { open_questions?: string[]; entities?: string[]; artifacts?: { id: string; type: string; label: string; content: string }[]; + mounted_checkpoint_id?: string | null; + history_base_seq?: number | null; }): Promise { return requestV4('/chat/commit', { method: 'POST', @@ -423,6 +425,11 @@ export async function getSessionCheckpoints(sessionId: string): Promise(`/lineage/sessions/${sessionId}/checkpoints`); } +/** Turns that produced a checkpoint (empty when no source range was recorded). */ +export async function getCheckpointSourceTurns(checkpointId: string): Promise { + return requestV5(`/lineage/checkpoints/${checkpointId}/source-turns`); +} + export async function reviewCheckpoint(checkpointId: string): Promise { return requestV5(`/checkpoint/${checkpointId}/review`, { method: 'POST', diff --git a/frontend/src/pages/ChatWorkspacePage.tsx b/frontend/src/pages/ChatWorkspacePage.tsx index d31d730..9ee5432 100644 --- a/frontend/src/pages/ChatWorkspacePage.tsx +++ b/frontend/src/pages/ChatWorkspacePage.tsx @@ -349,6 +349,8 @@ function CommitModal({ repoId, sessionId, onClose, onCommitted, providerStatus, open_questions: parseLines(openQuestions), entities: parseLines(entities), artifacts: artifacts.filter(a => a.content.trim()), + mounted_checkpoint_id: mountedCheckpointId ?? null, + history_base_seq: mountedCheckpointId !== null ? (mountedAtSeq ?? null) : null, }); onCommitted(commit); } catch (e: any) { diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts index 059fceb..1813f53 100644 --- a/frontend/src/types/index.ts +++ b/frontend/src/types/index.ts @@ -134,6 +134,7 @@ export interface Commit { context_blob: Record; raw_source_text: string | null; metadata: CommitMetadata; + source_turn_range?: SourceTurnRange | null; created_at: string; } /** Delta between a commit and its parent, used for the diff view on CommitDetailPage */ @@ -223,6 +224,13 @@ export interface ForkSessionResponse { history_base_seq: number; } +export interface SourceTurnRange { + session_id: string; + first_sequence_number: number; + last_sequence_number: number; + turn_count: number; +} + export interface CheckpointNode { id: string; commit_hash: string; @@ -235,6 +243,7 @@ export interface CheckpointNode { author_agent: string | null; note_count: number; note_kinds: string[]; + source_turn_range: SourceTurnRange | null; } export interface SessionNode {