This commit is contained in:
Andrew Barnes 2026-10-25 21:41:31 +00:00 • committed by GitHub
commit c8abbf99a1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 385 additions and 4 deletions

View file

@ -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
)

View file

@ -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())

View file

@ -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

View file

@ -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

View file

@ -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`

View file

@ -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<import('../types').Commit> {
return requestV4<import('../types').Commit>('/chat/commit', {
method: 'POST',
@ -423,6 +425,11 @@ export async function getSessionCheckpoints(sessionId: string): Promise<import('
return requestV5<import('../types').Commit[]>(`/lineage/sessions/${sessionId}/checkpoints`);
}
/** Turns that produced a checkpoint (empty when no source range was recorded). */
export async function getCheckpointSourceTurns(checkpointId: string): Promise<import('../types').TurnEvent[]> {
return requestV5<import('../types').TurnEvent[]>(`/lineage/checkpoints/${checkpointId}/source-turns`);
}
export async function reviewCheckpoint(checkpointId: string): Promise<import('../types').CheckpointReviewResponse> {
return requestV5<import('../types').CheckpointReviewResponse>(`/checkpoint/${checkpointId}/review`, {
method: 'POST',

View file

@ -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) {

View file

@ -134,6 +134,7 @@ export interface Commit {
context_blob: Record<string, unknown>;
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 {