Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(storage): Avibe Agent transcript store over messages and agent_events (#2338)

Call Whitecf67caa63cbd
diff --git a/storage/agent_events_service.py b/storage/agent_events_service.py
index 54841e27e..63d37aad6 100644
--- a/storage/agent_events_service.py
+++ b/storage/agent_events_service.py
@@ -1,9 +1,12 @@
"""Append-only trace events emitted by agent runtimes.
``agent_events`` is intentionally separate from ``messages``: rows here are
-debug/trace material, not transcript content. The first writer is tool-call
+debug/trace material, not chat/inbox messages. The first writer is tool-call
output from backend SDK streams, which should be retained for diagnosis without
-ever becoming a chat/inbox message.
+ever becoming a chat/inbox message. The Avibe Agent's tool results and context
+checkpoints also live here with ``visibility='context'`` and a ``context_seq``;
+``storage/agent_transcript.py`` is their only writer, and trace retention never
+removes them.
"""
from __future__ import annotations
@@ -51,6 +54,7 @@ def _row_to_payload(row: dict[str, Any]) -> dict[str, Any]:
"event_type": row.get("event_type"),
"visibility": row.get("visibility"),
"sequence": row.get("sequence"),
+ "context_seq": row.get("context_seq"),
"text": row.get("content_text") or content.get("text") or "",
"content": content,
"metadata": metadata,
@@ -77,6 +81,7 @@ def append(
visibility: str = "trace",
source: Optional[str] = "agent",
sequence: Optional[int] = None,
+ context_seq: Optional[int] = None,
) -> dict[str, Any]:
body: dict[str, Any] = {}
if content:
@@ -98,6 +103,7 @@ def append(
"event_type": event_type,
"visibility": visibility,
"sequence": sequence,
+ "context_seq": context_seq,
"content_text": plain,
"content_json": json.dumps(body),
"metadata_json": json.dumps(metadata or {}),
diff --git a/storage/agent_transcript.py b/storage/agent_transcript.py
new file mode 100644
index 000000000..24ed16cc6
--- /dev/null
+++ b/storage/agent_transcript.py
@@ -0,0 +1,627 @@
+"""C-5 transcript store over the ``messages`` and ``agent_events`` tables.
+
+The Avibe Agent's model context is Avibe's own rows, with no second copy
+(``docs/plans/agent-core-contracts/transcript.md``). A row is in a Session's
+context exactly when its ``context_seq`` is non-null:
+
+* inputs are existing ``messages`` rows (``user``, ``harness``,
+ ``agent_initiated``, ``annotation``); consuming one sets its ``context_seq``
+ and ``content_json.model`` once;
+* responses are new ``assistant`` / ``result`` rows with ``content_json.model``,
+ a rendered ``content_text``, and the output outbox state
+ ``metadata_json.delivery``;
+* tool results, checkpoints, context edits, and hook state are new
+ ``agent_events`` rows with ``visibility='context'``.
+
+Allocation. Every write takes SQLite's writer lock before its first read
+(``reserve_write_lock``) and runs under a per-Session lock, so
+``max(context_seq over both tables) + 1`` cannot be allocated twice, across
+tasks or processes; the partial unique indexes back the rule.
+
+Attribution. Inserted rows take ``platform`` and ``scope_id`` from the Turn's
+initial input: the latest consumed input names its Turn through its accepted
+Delivery, and that Turn's initial Delivery names the input row. That is the
+channel the Turn answers, where ``persist_agent_message`` attributes the same
+output, and a steer from another surface does not re-home the reply. An input
+without a Delivery link stands for itself. ``agent_events.turn_id`` is that
+Turn.
+
+Fork. A child inherits its source's context rows up to ``anchor_seq``, read
+from the top-level Session metadata ``fork_source_session_id`` and
+``fork_source_context_seq`` and followed through the source's own fork. The
+anchor is resolved once, when the fork is reserved
+(``resolve_fork_anchor_seq``), so rows that receive a ``context_seq`` later can
+never move into or out of the prefix. A fork without that key (a released fork,
+or one from another backend) inherits nothing. The child's own rows continue
+from ``anchor_seq + 1``.
+
+Outbox. A response row commits with ``delivery = {"state": "pending",
+"parts": []}``. The adapter records a receipt for each part a surface splits it
+into; the row becomes ``delivered`` only when every part has one
+(``recovery.md`` D1). A response whose display text is blank (only thinking or
+tool calls) has no part on any surface and commits ``delivered``.
+
+Cancellation. A worker thread cannot be interrupted, so a cancelled write keeps
+the Session's lock until its transaction settles and only then raises: when a
+write call returns or raises, the rows already show whether it committed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Literal, Mapping, Optional, Sequence, TypeVar
+
+from sqlalchemy import and_, func, or_, select
+from sqlalchemy.engine import Connection, Engine
+
+from core.agent_core.harness.store import ContextEntry, EntryKind
+from core.agent_core.messages import (
+ AssistantMessage,
+ TextBlock,
+ ToolResultMessage,
+ UserMessage,
+ message_from_dict,
+ message_to_dict,
+)
+from storage import agent_events_service, messages_service
+from storage.agent_session_rows import reserve_write_lock
+from storage.models import agent_events, agent_sessions, message_deliveries, messages, session_turns
+
+INPUT_TYPES = ("user", "harness", "agent_initiated", "annotation")
+RESPONSE_TYPES = ("assistant", "result")
+CONTEXT_VISIBILITY = "context"
+PAYLOAD_VERSION = 1
+
+PayloadKind = Literal["compaction", "context_edit", "agent_state"]
+_EVENT_TYPE_BY_KIND: dict[str, str] = {
+ "tool_result": "tool_result",
+ "compaction": "context_compaction",
+ "context_edit": "context_edit",
+ "agent_state": "agent_state",
+}
+_KIND_BY_EVENT_TYPE = {event_type: kind for kind, event_type in _EVENT_TYPE_BY_KIND.items()}
+
+DisplayRenderer = Callable[[AssistantMessage], str]
+_T = TypeVar("_T")
+
+
+def render_text(message: AssistantMessage) -> str:
+ """Default display copy of a response: its text blocks, verbatim, in order."""
+ return "\n\n".join(block.text for block in message.content if isinstance(block, TextBlock) and block.text)
+
+
+class TranscriptError(RuntimeError):
+ """A write the context rules refuse, or rows that cannot form a context."""
+
+
+@dataclass(frozen=True)
+class PendingDelivery:
+ """A committed response whose surface delivery has not been recorded."""
+
+ session_id: str
+ context_seq: int
+ row_id: str
+ final: bool
+ text: str
+ message: AssistantMessage
+ parts: tuple[Optional[Mapping[str, Any]], ...] = ()
+ """Receipts by part index from an earlier attempt; ``None`` marks a part still to send."""
+
+
+@dataclass(frozen=True)
+class _TurnOrigin:
+ platform: str
+ scope_id: Optional[str]
+ turn_id: Optional[str]
+ agent_name: Optional[str]
+ backend: Optional[str]
+
+
+class SQLiteTranscriptStore:
+ """``TranscriptStore`` over Avibe's tables, plus the output outbox helpers.
+
+ ``render`` produces a response row's ``content_text``; the adapter supplies
+ its display rendering, the default keeps the text blocks.
+ """
+
+ def __init__(self, engine: Engine, *, render: DisplayRenderer = render_text) -> None:
+ self._engine = engine
+ self._render = render
+ self._locks: dict[str, asyncio.Lock] = {}
+
+ # --- TranscriptStore ----------------------------------------------------
+
+ async def load(self, session_id: str) -> Sequence[ContextEntry]:
+ return await asyncio.to_thread(self._load, session_id)
+
+ async def consume_input(self, session_id: str, message_id: str, message: UserMessage) -> ContextEntry:
+ if not isinstance(message, UserMessage):
+ raise TypeError("consume_input takes a UserMessage")
+ model = _canonical({"version": PAYLOAD_VERSION, "message": message_to_dict(message)})
+
+ def work(conn: Connection) -> ContextEntry:
+ row = conn.execute(
+ select(messages.c.session_id, messages.c.type, messages.c.context_seq, messages.c.content_json).where(
+ messages.c.id == message_id
+ )
+ ).mappings().first()
+ if row is None or row["session_id"] != session_id:
+ raise TranscriptError(f"input {message_id} is not a message of Session {session_id}")
+ if row["type"] not in INPUT_TYPES:
+ raise TranscriptError(f"message {message_id} of type {row['type']!r} is not an input")
+ content = _json_object(row["content_json"], message_id)
+ seq = row["context_seq"]
+ if seq is not None:
+ # A retried commit of the same input is the committed entry; anything
+ # else would rewrite a context row after commit.
+ if content.get("model") != model:
+ raise TranscriptError(f"input {message_id} is already in the context")
+ else:
+ seq = _next_context_seq(conn, session_id)
+ conn.execute(
+ messages.update()
+ .where(messages.c.id == message_id, messages.c.context_seq.is_(None))
+ .values(context_seq=seq, content_json=json.dumps({**content, "model": model}), updated_at=_utc_now())
+ )
+ return ContextEntry(session_id, seq, "input", message_id, message=message, payload=model)
+
+ return await self._write(session_id, work)
+
+ async def append_response(self, session_id: str, message: AssistantMessage, *, final: bool) -> ContextEntry:
+ if not isinstance(message, AssistantMessage):
+ raise TypeError("append_response takes an AssistantMessage")
+ model = _canonical({"version": PAYLOAD_VERSION, "message": message_to_dict(message)})
+ display_text = self._render(message)
+
+ def work(conn: Connection) -> ContextEntry:
+ origin = _turn_origin(conn, session_id)
+ seq = _next_context_seq(conn, session_id)
+ row = messages_service.append(
+ conn,
+ scope_id=origin.scope_id,
+ session_id=session_id,
+ platform=origin.platform,
+ author="agent",
+ source="agent",
+ author_name=origin.agent_name,
+ message_type="result" if final else "assistant",
+ text=display_text,
+ content={"model": model},
+ metadata={"delivery": {"state": "pending" if display_text.strip() else "delivered", "parts": []}},
+ )
+ conn.execute(messages.update().where(messages.c.id == row["id"]).values(context_seq=seq))
+ return ContextEntry(session_id, seq, "response", row["id"], message=message, payload=model)
+
+ return await self._write(session_id, work)
+
+ async def append_tool_result(
+ self, session_id: str, message: ToolResultMessage, *, details: Mapping[str, Any]
+ ) -> ContextEntry:
+ if not isinstance(message, ToolResultMessage):
+ raise TypeError("append_tool_result takes a ToolResultMessage")
+ payload: dict[str, Any] = {"version": PAYLOAD_VERSION, "message": message_to_dict(message)}
+ if details:
+ payload["details"] = dict(details)
+ payload = _canonical(payload)
+ return await self._write(
+ session_id, lambda conn: self._append_event(conn, session_id, "tool_result", payload, message)
+ )
+
+ async def append_payload(self, session_id: str, kind: PayloadKind, payload: Mapping[str, Any]) -> ContextEntry:
+ if kind not in ("compaction", "context_edit", "agent_state"):
+ raise ValueError(f"not a payload entry kind: {kind!r}")
+ data = _canonical(dict(payload))
+ if not _is_current_version(data):
+ raise ValueError(f"a {kind} payload needs version {PAYLOAD_VERSION}")
+ return await self._write(session_id, lambda conn: self._append_event(conn, session_id, kind, data, None))
+
+ # --- output outbox --------------------------------------------------------
+
+ async def pending_deliveries(self, session_id: str) -> list[PendingDelivery]:
+ """The Session's committed responses not yet delivered, in ``context_seq`` order."""
+ return await asyncio.to_thread(self._pending_deliveries, session_id)
+
+ async def record_delivery_part(
+ self,
+ session_id: str,
+ row_id: str,
+ *,
+ index: int,
+ count: int,
+ native_message_id: Optional[str] = None,
+ ) -> bool:
+ """Record the receipt of part ``index`` of ``count``; True once every part has one.
+
+ A part that already has a receipt keeps its first one, so a retried send is
+ recorded once.
+ """
+ if not 0 <= index < count:
+ raise ValueError(f"part {index} is outside a delivery of {count} part(s)")
+ return await asyncio.to_thread(self._record_delivery_part, session_id, row_id, index, count, native_message_id)
+
+ # --- implementation -------------------------------------------------------
+
+ async def _write(self, session_id: str, work: Callable[[Connection], _T]) -> _T:
+ lock = self._locks.setdefault(session_id, asyncio.Lock())
+ async with lock:
+ commit = asyncio.ensure_future(asyncio.to_thread(self._commit, work))
+ try:
+ return await asyncio.shield(commit)
+ except asyncio.CancelledError:
+ await _settle(commit)
+ raise
+
+ def _commit(self, work: Callable[[Connection], _T]) -> _T:
+ with self._engine.begin() as conn:
+ reserve_write_lock(conn)
+ return work(conn)
+
+ def _append_event(
+ self,
+ conn: Connection,
+ session_id: str,
+ kind: EntryKind,
+ payload: dict[str, Any],
+ message: Optional[ToolResultMessage],
+ ) -> ContextEntry:
+ origin = _turn_origin(conn, session_id)
+ seq = _next_context_seq(conn, session_id)
+ row = agent_events_service.append(
+ conn,
+ scope_id=origin.scope_id,
+ session_id=session_id,
+ platform=origin.platform,
+ event_type=_EVENT_TYPE_BY_KIND[kind],
+ content=payload,
+ agent_name=origin.agent_name,
+ backend=origin.backend,
+ turn_id=origin.turn_id,
+ visibility=CONTEXT_VISIBILITY,
+ source="agent",
+ context_seq=seq,
+ )
+ return ContextEntry(session_id, seq, kind, row["id"], message=message, payload=payload)
+
+ def _load(self, session_id: str) -> list[ContextEntry]:
+ with self._engine.begin() as conn:
+ # One read snapshot across both tables and every ancestor.
+ if not conn.connection.dbapi_connection.in_transaction:
+ conn.exec_driver_sql("BEGIN")
+ entries = [
+ entry for member, bound in _ancestry(conn, session_id) for entry in _context_rows(conn, member, bound)
+ ]
+ entries.sort(key=lambda entry: entry.context_seq)
+ for previous, current in zip(entries, entries[1:]):
+ if previous.context_seq == current.context_seq:
+ raise TranscriptError(
+ f"rows {previous.row_id} and {current.row_id} share context_seq {current.context_seq}"
+ )
+ return entries
+
+ def _pending_deliveries(self, session_id: str) -> list[PendingDelivery]:
+ with self._engine.connect() as conn:
+ rows = conn.execute(
+ select(
+ messages.c.id,
+ messages.c.type,
+ messages.c.context_seq,
+ messages.c.content_text,
+ messages.c.content_json,
+ messages.c.metadata_json,
+ )
+ .where(
+ messages.c.session_id == session_id,
+ messages.c.context_seq.is_not(None),
+ messages.c.type.in_(RESPONSE_TYPES),
+ func.json_extract(messages.c.metadata_json, "$.delivery.state") == "pending",
+ )
+ .order_by(messages.c.context_seq)
+ ).mappings().all()
+ deliveries = []
+ for row in rows:
+ entry = _message_entry(session_id, row)
+ assert isinstance(entry.message, AssistantMessage)
+ deliveries.append(
+ PendingDelivery(
+ session_id=session_id,
+ context_seq=entry.context_seq,
+ row_id=entry.row_id,
+ final=row["type"] == "result",
+ text=row["content_text"] or "",
+ message=entry.message,
+ parts=tuple(_delivery(row["metadata_json"], entry.row_id)["parts"]),
+ )
+ )
+ return deliveries
+
+ def _record_delivery_part(
+ self, session_id: str, row_id: str, index: int, count: int, native_message_id: Optional[str]
+ ) -> bool:
+ with self._engine.begin() as conn:
+ reserve_write_lock(conn)
+ raw = conn.execute(
+ select(messages.c.metadata_json).where(
+ messages.c.id == row_id,
+ messages.c.session_id == session_id,
+ messages.c.context_seq.is_not(None),
+ messages.c.type.in_(RESPONSE_TYPES),
+ )
+ ).scalar_one_or_none()
+ if raw is None:
+ raise TranscriptError(f"{row_id} is not a response of Session {session_id}")
+ metadata = _json_object(raw, row_id)
+ delivery = _delivery(raw, row_id)
+ if delivery["state"] == "delivered":
+ return True
+ parts = delivery["parts"] or [None] * count
+ if len(parts) != count:
+ raise TranscriptError(f"{row_id} was split into {len(parts)} part(s), not {count}")
+ if parts[index] is None:
+ now = _utc_now()
+ receipt: dict[str, Any] = {"delivered_at": now}
+ if native_message_id:
+ receipt["native_message_id"] = native_message_id
+ parts[index] = receipt
+ state = "delivered" if all(part is not None for part in parts) else "pending"
+ conn.execute(
+ messages.update()
+ .where(messages.c.id == row_id)
+ .values(
+ metadata_json=json.dumps({**metadata, "delivery": {"state": state, "parts": parts}}),
+ updated_at=now,
+ )
+ )
+ return all(part is not None for part in parts)
+
+
+async def _settle(task: asyncio.Future[Any]) -> None:
+ """Wait for ``task`` to finish, whatever cancellations arrive meanwhile."""
+ while not task.done():
+ try:
+ await asyncio.wait({task})
+ except asyncio.CancelledError:
+ pass
+ if not task.cancelled():
+ # The cancelled caller does not see this outcome; retrieve it so a failed
+ # commit is not reported as an unhandled task exception.
+ task.exception()
+
+
+# --- allocation and attribution ----------------------------------------------
+
+
+def _own_bound(conn: Connection, session_id: str) -> Optional[int]:
+ values = [
+ conn.execute(
+ select(func.max(table.c.context_seq)).where(
+ table.c.session_id == session_id, table.c.context_seq.is_not(None)
+ )
+ ).scalar()
+ for table in (messages, agent_events)
+ ]
+ return max((value for value in values if value is not None), default=None)
+
+
+def _next_context_seq(conn: Connection, session_id: str) -> int:
+ top = _own_bound(conn, session_id)
+ if top is None:
+ link = _fork_link(conn, session_id)
+ top = link[1] if link is not None else 0
+ return top + 1
+
+
+def _turn_origin(conn: Connection, session_id: str) -> _TurnOrigin:
+ session = conn.execute(
+ select(agent_sessions.c.agent_name, agent_sessions.c.agent_backend).where(agent_sessions.c.id == session_id)
+ ).first()
+ if session is None:
+ raise TranscriptError(f"Session {session_id} does not exist")
+ latest = conn.execute(
+ select(messages.c.id, messages.c.platform, messages.c.scope_id)
+ .where(
+ messages.c.session_id == session_id,
+ messages.c.context_seq.is_not(None),
+ messages.c.type.in_(INPUT_TYPES),
+ )
+ .order_by(messages.c.context_seq.desc())
+ .limit(1)
+ ).first()
+ if latest is None:
+ raise TranscriptError(f"Session {session_id} has consumed no input; a context row answers a Turn")
+ platform, scope_id = latest.platform, latest.scope_id
+ turn_id = conn.execute(
+ select(message_deliveries.c.turn_id)
+ .where(
+ message_deliveries.c.session_id == session_id,
+ message_deliveries.c.state == "accepted",
+ message_deliveries.c.message_id == latest.id,
+ )
+ .limit(1)
+ ).scalar()
+ if turn_id is not None:
+ initial = conn.execute(
+ select(messages.c.platform, messages.c.scope_id)
+ .select_from(
+ session_turns.join(
+ message_deliveries, message_deliveries.c.id == session_turns.c.initial_delivery_id
+ ).join(messages, messages.c.id == message_deliveries.c.message_id)
+ )
+ .where(session_turns.c.id == turn_id)
+ ).first()
+ if initial is not None:
+ platform, scope_id = initial.platform, initial.scope_id
+ return _TurnOrigin(platform, scope_id, turn_id, session.agent_name, session.agent_backend)
+
+
+# --- fork ancestry -------------------------------------------------------------
+
+
+def resolve_fork_anchor_seq(conn: Connection, source_session_id: str, anchor_message_id: Optional[str]) -> int:
+ """``anchor_seq`` for a fork of ``source_session_id`` at ``anchor_message_id`` (C-5 §4).
+
+ The largest ``context_seq`` of the source's context among rows at or before
+ the anchor in transcript order, including the prefix the source itself
+ inherited; the anchor may be a display-only row. The fork reservation calls
+ this in its own transaction and persists the result as the child's
+ ``fork_source_context_seq``.
+ """
+ link = _fork_link(conn, source_session_id)
+ inherited = link[1] if link is not None else 0
+ if anchor_message_id is None:
+ return inherited
+ order = messages_service.transcript_order_value()
+ anchor = conn.execute(
+ select(messages.c.session_id, order.label("order_at")).where(messages.c.id == anchor_message_id)
+ ).first()
+ if anchor is None or anchor.session_id != source_session_id:
+ raise TranscriptError(f"fork anchor {anchor_message_id} is not a message of Session {source_session_id}")
+ own_messages = conn.execute(
+ select(func.max(messages.c.context_seq)).where(
+ messages.c.session_id == source_session_id,
+ messages.c.context_seq.is_not(None),
+ or_(order < anchor.order_at, and_(order == anchor.order_at, messages.c.id <= anchor_message_id)),
+ )
+ ).scalar()
+ own_events = conn.execute(
+ select(func.max(agent_events.c.context_seq)).where(
+ agent_events.c.session_id == source_session_id,
+ agent_events.c.context_seq.is_not(None),
+ agent_events.c.created_at <= anchor.order_at,
+ )
+ ).scalar()
+ return max(value for value in (inherited, own_messages, own_events) if value is not None)
+
+
+def _fork_link(conn: Connection, session_id: str) -> Optional[tuple[str, int]]:
+ """``(source_session_id, anchor_seq)`` when the Session inherits a context."""
+ raw = conn.execute(
+ select(agent_sessions.c.metadata_json).where(agent_sessions.c.id == session_id)
+ ).scalar_one_or_none()
+ try:
+ metadata = json.loads(raw or "{}")
+ except (TypeError, ValueError):
+ return None
+ if not isinstance(metadata, dict):
+ return None
+ source = str(metadata.get("fork_source_session_id") or "").strip()
+ anchor = metadata.get("fork_source_context_seq")
+ if not source or anchor is None:
+ return None
+ if not isinstance(anchor, int) or isinstance(anchor, bool) or anchor < 0:
+ raise TranscriptError(f"Session {session_id} has an invalid fork_source_context_seq: {anchor!r}")
+ return source, anchor
+
+
+def _ancestry(conn: Connection, session_id: str) -> list[tuple[str, Optional[int]]]:
+ """The Session and its fork sources, each with its ``context_seq`` upper bound."""
+ chain: list[tuple[str, Optional[int]]] = [(session_id, None)]
+ seen = {session_id}
+ member, bound = session_id, None
+ while (link := _fork_link(conn, member)) is not None:
+ source_id, anchor_seq = link
+ if source_id in seen:
+ raise TranscriptError(f"fork ancestry of Session {session_id} loops back to {source_id}")
+ bound = anchor_seq if bound is None else min(bound, anchor_seq)
+ chain.append((source_id, bound))
+ seen.add(source_id)
+ member = source_id
+ return chain
+
+
+# --- reading rows --------------------------------------------------------------
+
+
+def _context_rows(conn: Connection, session_id: str, bound: Optional[int]) -> list[ContextEntry]:
+ entries: list[ContextEntry] = []
+ for table, columns, to_entry in (
+ (messages, (messages.c.type,), _message_entry),
+ (agent_events, (agent_events.c.event_type, agent_events.c.visibility), _event_entry),
+ ):
+ conditions = [table.c.session_id == session_id, table.c.context_seq.is_not(None)]
+ if bound is not None:
+ conditions.append(table.c.context_seq <= bound)
+ rows = conn.execute(
+ select(table.c.id, table.c.context_seq, table.c.content_json, *columns).where(*conditions)
+ ).mappings()
+ entries.extend(to_entry(session_id, row) for row in rows)
+ return entries
+
+
+def _message_entry(session_id: str, row: Mapping[str, Any]) -> ContextEntry:
+ row_id = row["id"]
+ if row["type"] in INPUT_TYPES:
+ kind: EntryKind = "input"
+ expected: type = UserMessage
+ elif row["type"] in RESPONSE_TYPES:
+ kind, expected = "response", AssistantMessage
+ else:
+ raise TranscriptError(f"context row {row_id} has message type {row['type']!r}")
+ payload = _versioned(_json_object(row["content_json"], row_id).get("model"), row_id)
+ message = _message(payload.get("message"), expected, row_id)
+ return ContextEntry(session_id, row["context_seq"], kind, row_id, message=message, payload=payload)
+
+
+def _event_entry(session_id: str, row: Mapping[str, Any]) -> ContextEntry:
+ row_id = row["id"]
+ kind = _KIND_BY_EVENT_TYPE.get(row["event_type"])
+ if kind is None or row["visibility"] != CONTEXT_VISIBILITY:
+ raise TranscriptError(f"context row {row_id} is a {row['visibility']} {row['event_type']!r} event")
+ payload = _versioned(_json_object(row["content_json"], row_id), row_id)
+ message = _message(payload.get("message"), ToolResultMessage, row_id) if kind == "tool_result" else None
+ return ContextEntry(session_id, row["context_seq"], kind, row_id, message=message, payload=payload)
+
+
+def _message(value: Any, expected: type, row_id: str) -> Any:
+ try:
+ message = message_from_dict(value)
+ except (TypeError, ValueError) as exc:
+ raise TranscriptError(f"context row {row_id}: {exc}") from exc
+ if not isinstance(message, expected):
+ raise TranscriptError(f"context row {row_id} holds a {message.role} message")
+ return message
+
+
+def _versioned(value: Any, row_id: str) -> dict[str, Any]:
+ if not isinstance(value, dict) or not _is_current_version(value):
+ raise TranscriptError(f"context row {row_id} has no version {PAYLOAD_VERSION} payload")
+ return value
+
+
+def _is_current_version(payload: Mapping[str, Any]) -> bool:
+ version = payload.get("version")
+ return isinstance(version, int) and not isinstance(version, bool) and version == PAYLOAD_VERSION
+
+
+def _delivery(raw_metadata: Any, row_id: str) -> dict[str, Any]:
+ delivery = _json_object(raw_metadata, row_id).get("delivery")
+ parts = delivery.get("parts") if isinstance(delivery, dict) else None
+ if (
+ not isinstance(delivery, dict)
+ or delivery.get("state") not in ("pending", "delivered")
+ or not isinstance(parts, list)
+ or any(part is not None and not isinstance(part, dict) for part in parts)
+ ):
+ raise TranscriptError(f"response {row_id} has no readable delivery state")
+ return {"state": delivery["state"], "parts": list(parts)}
+
+
+def _json_object(raw: Any, row_id: str) -> dict[str, Any]:
+ try:
+ value = json.loads(raw or "{}")
+ except (TypeError, ValueError) as exc:
+ raise TranscriptError(f"row {row_id} holds invalid JSON") from exc
+ if not isinstance(value, dict):
+ raise TranscriptError(f"row {row_id} holds a JSON {type(value).__name__}, not an object")
+ return value
+
+
+def _canonical(value: dict[str, Any]) -> dict[str, Any]:
+ """The value exactly as it reads back from a row."""
+ return json.loads(json.dumps(value))
+
+
+def _utc_now() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
diff --git a/storage/alembic/versions/20261002_0063_agent_context_seq.py b/storage/alembic/versions/20261002_0063_agent_context_seq.py
new file mode 100644
index 000000000..5ab97f719
--- /dev/null
+++ b/storage/alembic/versions/20261002_0063_agent_context_seq.py
@@ -0,0 +1,53 @@
+"""Order the Avibe Agent's model context across messages and agent_events.
+
+C-5 (``docs/plans/agent-core-contracts/transcript.md``): a row belongs to a
+Session's model context exactly when its ``context_seq`` is non-null, and the
+value is unique per Session across both tables. ``agent_events.sequence`` keeps
+its released, turn-local meaning and is not touched. Every existing row keeps a
+null ``context_seq`` and stays outside any model context; there is no backfill.
+
+Replay-safe against head shape: a database born from ``metadata.create_all``
+already has both columns and indexes and is left as it is.
+
+Revision ID: 20261002_0063
+Revises: 20260923_0062
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "20261002_0063"
+down_revision = "20260923_0062"
+branch_labels = None
+depends_on = None
+MIGRATION_SAFETY = "additive"
+
+_CONTEXT_INDEXES = {
+ "messages": "uq_messages_session_context_seq",
+ "agent_events": "uq_agent_events_session_context_seq",
+}
+
+
+def _columns(table: str) -> set[str]:
+ return {row[1] for row in op.get_bind().exec_driver_sql(f'pragma table_info("{table}")')}
+
+
+def upgrade() -> None:
+ bind = op.get_bind()
+ for table, index in _CONTEXT_INDEXES.items():
+ if "context_seq" not in _columns(table):
+ op.add_column(table, sa.Column("context_seq", sa.Integer(), nullable=True))
+ bind.exec_driver_sql(
+ f"create unique index if not exists {index} on {table} (session_id, context_seq) "
+ "where context_seq is not null"
+ )
+
+
+def downgrade() -> None:
+ # Older SQLite cannot drop a column without rebuilding the table. The
+ # nullable columns are harmless to older code, and keeping their values lets
+ # a later upgrade restore the same context.
+ for index in _CONTEXT_INDEXES.values():
+ op.get_bind().exec_driver_sql(f"drop index if exists {index}")
diff --git a/storage/migrations.py b/storage/migrations.py
index b9f09234c..cbbe2a60d 100644
--- a/storage/migrations.py
+++ b/storage/migrations.py
@@ -145,6 +145,8 @@ HEAD_REQUIRED_COLUMNS = PRE_SHOW_SESSION_EVENTS_REQUIRED_COLUMNS | {
"delivery_history_json",
"version",
},
+ "messages": PRE_SHOW_SESSION_EVENTS_REQUIRED_COLUMNS["messages"] | {"context_seq"},
+ "agent_events": {"context_seq"},
"session_turns": {
"initial_delivery_id",
"state",
@@ -703,6 +705,11 @@ def _repair_head_required_columns(conn: sqlite3.Connection, tables: set[str]) ->
if "web_push_subscriptions" in tables and "provider_invalidated_at" not in _column_names(conn, "web_push_subscriptions"):
conn.execute('alter table "web_push_subscriptions" add column "provider_invalidated_at" VARCHAR')
changed = True
+ # context_seq (20261002_0063): the Avibe Agent's model-context order key.
+ for table in ("messages", "agent_events"):
+ if table in tables and "context_seq" not in _column_names(conn, table):
+ conn.execute(f'alter table "{table}" add column "context_seq" INTEGER')
+ changed = True
_ensure_head_indexes(conn, tables)
return changed
@@ -957,6 +964,12 @@ def _ensure_agent_events_indexes(conn: sqlite3.Connection, tables: set[str]) ->
"create index if not exists ix_agent_events_turn_sequence_id "
"on agent_events (turn_id, sequence, id)"
)
+ # The model-context order key of both tables (20261002_0063).
+ for table in ("messages", "agent_events"):
+ conn.execute(
+ f"create unique index if not exists uq_{table}_session_context_seq "
+ f"on {table} (session_id, context_seq) where context_seq is not null"
+ )
def _ensure_vault_authz_indexes(conn: sqlite3.Connection, tables: set[str]) -> None:
diff --git a/storage/models.py b/storage/models.py
index 7150d1106..bad52652f 100644
--- a/storage/models.py
+++ b/storage/models.py
@@ -490,6 +490,10 @@ agent_events = Table(
Column("event_type", String, nullable=False),
Column("visibility", String, nullable=False, server_default="trace"),
Column("sequence", Integer, nullable=True),
+ # C-5 model-context order (agent-core-contracts/transcript.md), shared with
+ # ``messages.context_seq``: non-null exactly for rows in a Session's context.
+ # Unrelated to the turn-local ``sequence``.
+ Column("context_seq", Integer, nullable=True),
Column("content_text", Text, nullable=True),
Column("content_json", Text, nullable=False),
Column("metadata_json", Text, nullable=False),
@@ -500,6 +504,13 @@ agent_events = Table(
Index("ix_agent_events_session_type_created_id", "session_id", "event_type", "created_at", "id"),
Index("ix_agent_events_scope_created_id", "scope_id", "created_at", "id"),
Index("ix_agent_events_turn_sequence_id", "turn_id", "sequence", "id"),
+ Index(
+ "uq_agent_events_session_context_seq",
+ "session_id",
+ "context_seq",
+ unique=True,
+ sqlite_where=text("context_seq is not null"),
+ ),
Index(
"ix_agent_events_skill_created_id",
"created_at",
@@ -658,6 +669,10 @@ messages = Table(
Column("updated_at", String, nullable=False),
Column("delivered_at", String, nullable=True),
Column("read_at", String, nullable=True),
+ # C-5 model-context order, unique per Session across this table and
+ # ``agent_events``. Null for display-only rows and for inputs the Avibe Agent
+ # loop has not consumed.
+ Column("context_seq", Integer, nullable=True),
Index(
"uq_messages_platform_scope_native",
"platform",
@@ -673,6 +688,13 @@ messages = Table(
unique=True,
sqlite_where=text("scope_id is null and native_message_id is not null"),
),
+ Index(
+ "uq_messages_session_context_seq",
+ "session_id",
+ "context_seq",
+ unique=True,
+ sqlite_where=text("context_seq is not null"),
+ ),
Index("ix_messages_session_created", "session_id", "created_at"),
Index("ix_messages_session_created_id", "session_id", "created_at", "id"),
Index("ix_messages_session_type_created_id", "session_id", "type", "created_at", "id"),
diff --git a/tests/test_agent_context_seq_migration.py b/tests/test_agent_context_seq_migration.py
new file mode 100644
index 000000000..0087a7133
--- /dev/null
+++ b/tests/test_agent_context_seq_migration.py
@@ -0,0 +1,83 @@
+"""20261002_0063: ``context_seq`` on ``messages`` and ``agent_events`` (agent-core-contracts/transcript.md).
+
+Exercises the real migration chain on a database holding released rows: they keep
+every column and stay outside any model context, ``agent_events.sequence`` keeps
+its released value and index, and ``context_seq`` is unique per Session in each
+table.
+"""
+
+import sqlite3
+
+import pytest
+from alembic import command
+
+from storage import migrations
+
+pytestmark = pytest.mark.no_sqlite_template
+
+_INDEXES = {"messages": "uq_messages_session_context_seq", "agent_events": "uq_agent_events_session_context_seq"}
+# Two rows of one Session and one of another, per table.
+_IDS = {"messages": ("msg_a1", "msg_a2", "msg_b1"), "agent_events": ("evt_a1", "evt_a2", "evt_b1")}
+
+
+def _index_sql(conn, name):
+ row = conn.execute("SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?", (name,)).fetchone()
+ return row[0] if row else None
+
+
+def test_context_seq_upgrade_and_downgrade_keep_released_rows(tmp_path):
+ path = tmp_path / "state.sqlite"
+ migrations.run_migrations(path, revision="20260923_0062")
+ stamp = "2026-09-30T00:00:00.000000Z"
+ with sqlite3.connect(path) as conn:
+ conn.executemany(
+ "INSERT INTO messages (id, session_id, platform, author, type, content_text, content_json, "
+ "metadata_json, created_at, updated_at) VALUES (?, ?, 'slack', ?, ?, ?, '{}', '{}', ?, ?)",
+ [
+ ("msg_a1", "ses_a", "user", "user", "看一下目录", stamp, stamp),
+ ("msg_a2", "ses_a", "agent", "result", "done", stamp, stamp),
+ ("msg_b1", "ses_b", "user", "user", "hi", stamp, stamp),
+ ],
+ )
+ conn.executemany(
+ "INSERT INTO agent_events (id, session_id, turn_id, platform, event_type, visibility, sequence, "
+ "content_json, metadata_json, created_at, updated_at) "
+ "VALUES (?, ?, 'turn_1', 'slack', 'tool_call', 'trace', ?, '{}', '{}', ?, ?)",
+ [("evt_a1", "ses_a", 7, stamp, stamp), ("evt_a2", "ses_a", 8, stamp, stamp), ("evt_b1", "ses_b", None, stamp, stamp)],
+ )
+ released = {}
+ for table in _INDEXES:
+ cursor = conn.execute(f"SELECT * FROM {table} ORDER BY id")
+ released[table] = (", ".join(column[0] for column in cursor.description), cursor.fetchall())
+
+ def assert_released_rows_unchanged(conn):
+ for table, (columns, rows) in released.items():
+ assert conn.execute(f"SELECT {columns} FROM {table} ORDER BY id").fetchall() == rows
+
+ migrations.run_migrations(path)
+ with sqlite3.connect(path) as conn:
+ assert conn.execute("SELECT version_num FROM alembic_version").fetchone() == ("20261002_0063",)
+ assert_released_rows_unchanged(conn)
+ assert _index_sql(conn, "ix_agent_events_turn_sequence_id") is not None
+ for table, (first, same_session, other_session) in _IDS.items():
+ assert conn.execute(f"SELECT count(*) FROM {table} WHERE context_seq IS NOT NULL").fetchone() == (0,)
+ assert _index_sql(conn, _INDEXES[table]).lower().endswith("where context_seq is not null")
+ conn.execute(f"UPDATE {table} SET context_seq = 1 WHERE id IN (?, ?)", (first, other_session))
+ with pytest.raises(sqlite3.IntegrityError):
+ conn.execute(f"UPDATE {table} SET context_seq = 1 WHERE id = ?", (same_session,))
+ conn.commit()
+
+ command.downgrade(migrations.alembic_config(path), "20260923_0062")
+ with sqlite3.connect(path) as conn:
+ assert_released_rows_unchanged(conn)
+ assert [_index_sql(conn, index) for index in _INDEXES.values()] == [None, None]
+
+ migrations.run_migrations(path)
+ with sqlite3.connect(path) as conn:
+ assert_released_rows_unchanged(conn)
+ assert all(_index_sql(conn, index) is not None for index in _INDEXES.values())
+ for table, (first, _same_session, other_session) in _IDS.items():
+ assert conn.execute(
+ f"SELECT id FROM {table} WHERE context_seq = 1 ORDER BY id"
+ ).fetchall() == [(first,), (other_session,)]
+ assert conn.execute("PRAGMA integrity_check").fetchone() == ("ok",)
diff --git a/tests/test_agent_events_retention.py b/tests/test_agent_events_retention.py
index 4d8df0862..644a2805c 100644
--- a/tests/test_agent_events_retention.py
+++ b/tests/test_agent_events_retention.py
@@ -92,6 +92,35 @@ def test_run_deletes_only_old_tool_call_traces(state) -> None:
assert remaining == {"boundary", "new-trace", "old-visible", "old-other-type"}
+def test_context_rows_are_never_selected_by_any_retention_pass(state) -> None:
+ """C-5: the Avibe Agent's context rows outlive every trace and Skill window.
+
+ Context membership is the visibility, so even event types that retention
+ owns under ``trace`` survive with ``visibility='context'``.
+ """
+ engine = state
+ old = datetime(2026, 1, 1, tzinfo=timezone.utc)
+ event_types = (
+ "tool_result",
+ "context_compaction",
+ "context_edit",
+ "agent_state",
+ "tool_call",
+ "skill.catalog_result",
+ "skill.load_result",
+ )
+ for event_type in event_types:
+ _seed_event(engine, event_id=f"ctx-{event_type}", event_type=event_type, visibility="context", created_at=old)
+
+ with engine.connect() as conn:
+ assert agent_events_retention.plan(conn, retention_days=30, now=_NOW)["eligible_count"] == 0
+ assert agent_events_retention.run_retention(engine, retention_days=30, now=_NOW)["deleted_rows"] == 0
+ assert agent_events_retention.run_skill_retention(engine, now=_NOW)["events"] == 0
+ with engine.connect() as conn:
+ remaining = {row[0] for row in conn.execute(select(agent_events.c.id))}
+ assert remaining == {f"ctx-{event_type}" for event_type in event_types}
+
+
def test_cutoff_rejects_oversized_window() -> None:
with pytest.raises(ValueError, match="between"):
agent_events_retention.cutoff_iso(1_000_000, now=_NOW)
diff --git a/tests/test_agent_transcript.py b/tests/test_agent_transcript.py
new file mode 100644
index 000000000..82e161149
--- /dev/null
+++ b/tests/test_agent_transcript.py
@@ -0,0 +1,432 @@
+"""C-5 transcript store over ``messages`` and ``agent_events`` (agent-core-contracts/transcript.md).
+
+Properties: a Session's context is exactly its rows with a ``context_seq``, plus
+its fork ancestry up to the anchor, in one total order across both tables; every
+payload kind reads back as written; ``context_seq`` is never allocated twice;
+the output outbox replays pending responses in order.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import threading
+
+import pytest
+from sqlalchemy import select
+
+from core.agent_core.messages import (
+ AssistantMessage,
+ ImageBlock,
+ Origin,
+ ThinkingBlock,
+ ToolCallBlock,
+ ToolResultMessage,
+ Usage,
+ UserMessage,
+ text,
+)
+from config.paths import get_sqlite_state_path
+from storage import message_deliveries, messages_service
+from storage.agent_transcript import SQLiteTranscriptStore, TranscriptError, resolve_fork_anchor_seq
+from storage.db import create_sqlite_engine
+from storage.importer import ensure_sqlite_state
+from storage.models import agent_events, messages
+from storage.models import message_deliveries as delivery_rows
+from storage.settings_service import upsert_scope
+
+NOW = "2026-10-02T00:00:00.000000Z"
+ORIGIN = Origin(provider="anthropic", api="anthropic", model="claude-opus-5-5")
+
+
+def engine():
+ ensure_sqlite_state()
+ engine = create_sqlite_engine()
+ yield engine
+ engine.dispose()
+
+
+def _scope(conn, native_id: str, platform: str = "slack") -> str:
+ return upsert_scope(conn, platform=platform, scope_type="channel", native_id=native_id, now=NOW)
+
+
+def _session(conn, session_id: str, scope_id: str, metadata: dict | None = None) -> None:
+ conn.exec_driver_sql(
+ "insert into agent_sessions (id, scope_id, agent_name, agent_backend, agent_variant, session_anchor, "
+ "workdir, native_session_id, status, visibility, pinned, agent_status, metadata_json, created_at, "
+ "updated_at, last_active_at) values (?, ?, 'avibe', 'avibe', 'avibe', ?, '/tmp', ?, 'active', "
+ "'foreground', 0, 'idle', ?, ?, ?, ?)",
+ (session_id, scope_id, session_id, session_id, json.dumps(metadata or {}), NOW, NOW, NOW),
+ )
+
+
+def _fork(conn, session_id: str, scope_id: str, source_id: str, anchor_id: str | None) -> None:
+ """A fork as reservation records it, with the anchor resolved by the transcript rule."""
+ metadata = {"created_via": "session_fork", "fork_source_session_id": source_id, "fork_source_message_id": anchor_id}
+ if anchor_id is not None:
+ metadata["fork_source_context_seq"] = resolve_fork_anchor_seq(conn, source_id, anchor_id)
+ _session(conn, session_id, scope_id, metadata)
+
+
+def _row(conn, session_id: str, scope_id: str, body: str, *, kind: str = "user", platform: str = "slack") -> str:
+ author = "user" if kind == "user" else "agent"
+ row = messages_service.append(
+ conn,
+ scope_id=scope_id,
+ session_id=session_id,
+ platform=platform,
+ author=author,
+ source=author,
+ message_type=kind,
+ text=body,
+ )
+ return row["id"]
+
+
+def _accepted_turn(conn, session_id: str, scope_id: str, body: str, turn_id: str) -> str:
+ """An input accepted through the real Delivery path; returns its message id."""
+ delivery = message_deliveries.insert_delivery(
+ conn,
+ delivery_id=f"dlv_{turn_id}",
+ session_id=session_id,
+ priority="p3",
+ state="reserved",
+ snapshot=message_deliveries.message_snapshot(
+ scope_id=scope_id,
+ session_id=session_id,
+ platform="slack",
+ author="user",
+ source="user",
+ message_type="user",
+ text=body,
+ ),
+ dispatch_text=body,
+ now=NOW,
+ )
+ claimed = message_deliveries.claim_start_batch(
+ conn, turn_id=turn_id, session_id=session_id, backend="avibe", deliveries=[delivery], dispatch_text=body
+ )
+ assert message_deliveries.bind_native_start(
+ conn,
+ turn_id,
+ expected_version=int(claimed["turn"]["version"]),
+ runtime_key="runtime",
+ runtime_turn_id=turn_id,
+ native_turn_id=turn_id,
+ )
+ assert message_deliveries.materialize_start_acceptance(conn, turn_id=turn_id, evidence={"kind": "test"})
+ return conn.execute(
+ select(delivery_rows.c.message_id).where(delivery_rows.c.id == f"dlv_{turn_id}")
+ ).scalar_one()
+
+
+def _accepted_steer(conn, session_id: str, scope_id: str, body: str, turn_id: str) -> str:
+ message_id = _row(conn, session_id, scope_id, body, platform="avibe")
+ conn.execute(
+ delivery_rows.insert().values(
+ id=f"dlv_{message_id}",
+ session_id=session_id,
+ message_id=message_id,
+ priority="p1",
+ state="accepted",
+ snapshot_sha256="steer",
+ dispatch_sha256="steer",
+ turn_id=turn_id,
+ turn_role="steer",
+ turn_position=1,
+ submitted_at=NOW,
+ updated_at=NOW,
+ materialized_at=NOW,
+ )
+ )
+ return message_id
+
+
+def _user(body: str) -> UserMessage:
+ return UserMessage(content=(text(body),))
+
+
+def _assistant(body: str, *, call_id: str | None = None) -> AssistantMessage:
+ content: tuple = (text(body),)
+ if call_id is not None:
+ content = (
+ ThinkingBlock(text="look first", signature="sig-1"),
+ text(body),
+ ToolCallBlock(id=call_id, name="bash", arguments={"command": "ls"}),
+ )
+ return AssistantMessage(
+ content=content,
+ origin=ORIGIN,
+ stop_reason="tool_use" if call_id else "stop",
+ usage=Usage(input_tokens=10, output_tokens=2),
+ )
+
+
+def _tool_result(call_id: str, body: str) -> ToolResultMessage:
+ return ToolResultMessage(tool_call_id=call_id, tool_name="bash", content=(text(body),))
+
+
+COMPACTION = {
+ "version": 1,
+ "summary": "## Objective\n修复路径测试",
+ "first_kept_seq": 3,
+ "summarized_from_seq": 1,
+ "summarized_to_seq": 2,
+ "previous_compaction_id": None,
+ "reason": "manual",
+ "focus": None,
+ "tokens_before": 100,
+ "tokens_after_estimate": 40,
+ "summarizer": {"origin": {"provider": "anthropic", "api": "anthropic", "model": "claude-opus-5-5"},
+ "prompt_version": "ckpt-v1", "chunks": 1},
+ "files_read": ["core/paths.py"],
+ "files_modified": [],
+ "current_request_message_id": None,
+}
+
+
+async def test_every_kind_round_trips_in_one_order_attributed_to_the_turn(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ elsewhere = _scope(conn, "C-elsewhere", platform="avibe")
+ _session(conn, "ses_main", home)
+ first = _accepted_turn(conn, "ses_main", home, "看一下目录", "turn_main")
+ steer = _accepted_steer(conn, "ses_main", elsewhere, "also check tests", "turn_main")
+ store = SQLiteTranscriptStore(engine)
+ input_message = UserMessage(content=(text("[10:00] 看一下目录"), ImageBlock("image/png", "tok_1", name="s.png")))
+
+ written = [
+ await store.consume_input("ses_main", first, input_message),
+ await store.append_response("ses_main", _assistant("Listing.", call_id="call_1"), final=False),
+ await store.append_tool_result(
+ "ses_main", _tool_result("call_1", "a.py\nb.py"), details={"exit_code": 0, "job_id": "job_1"}
+ ),
+ await store.consume_input("ses_main", steer, _user("also check tests")),
+ await store.append_payload("ses_main", "agent_state", {"version": 1, "state": {"mode": "plan"}}),
+ await store.append_payload(
+ "ses_main",
+ "context_edit",
+ {"version": 1, "target_event_id": "evt_x", "replacement": {"text": "[cleared]"},
+ "reason": "clear_old_tool_result"},
+ ),
+ await store.append_payload("ses_main", "compaction", COMPACTION),
+ await store.append_response("ses_main", _assistant("两个文件。"), final=True),
+ ]
+
+ assert [entry.context_seq for entry in written] == list(range(1, 9))
+ assert [entry.kind for entry in written] == [
+ "input", "response", "tool_result", "input", "agent_state", "context_edit", "compaction", "response",
+ ]
+ assert list(await SQLiteTranscriptStore(engine).load("ses_main")) == written
+ with engine.connect() as conn:
+ rows = {
+ row["id"]: row
+ for row in conn.execute(select(messages).where(messages.c.session_id == "ses_main")).mappings()
+ }
+ events = conn.execute(
+ select(agent_events).where(agent_events.c.session_id == "ses_main").order_by(agent_events.c.context_seq)
+ ).mappings().all()
+ assert rows[first]["content_text"] == "看一下目录"
+ assert json.loads(rows[first]["content_json"])["text"] == "看一下目录"
+ for entry, row_type, display in ((written[1], "assistant", "Listing."), (written[7], "result", "两个文件。")):
+ row = rows[entry.row_id]
+ assert (row["type"], row["content_text"], row["author"]) == (row_type, display, "agent")
+ assert json.loads(row["metadata_json"])["delivery"] == {"state": "pending", "parts": []}
+ # Every inserted row answers the Turn's initial input, not the steer's surface.
+ inserted = [rows[written[1].row_id], rows[written[7].row_id], *events]
+ assert {(row["platform"], row["scope_id"]) for row in inserted} == {("slack", home)}
+ assert {row["turn_id"] for row in events} == {"turn_main"}
+ assert [(row["event_type"], row["visibility"]) for row in events] == [
+ ("tool_result", "context"),
+ ("agent_state", "context"),
+ ("context_edit", "context"),
+ ("context_compaction", "context"),
+ ]
+
+
+async def test_rows_outside_the_context_never_load(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_main", home)
+ consumed = _row(conn, "ses_main", home, "go")
+ queued = _row(conn, "ses_main", home, "queued, never consumed")
+ _row(conn, "ses_main", home, "status", kind="notify")
+ store = SQLiteTranscriptStore(engine)
+ entry = await store.consume_input("ses_main", consumed, _user("go"))
+ with engine.begin() as conn:
+ conn.execute(
+ agent_events.insert().values(
+ id="evt_trace", session_id="ses_main", platform="slack", event_type="tool_call",
+ visibility="trace", content_json="{}", metadata_json="{}", created_at=NOW, updated_at=NOW,
+ )
+ )
+
+ assert list(await store.load("ses_main")) == [entry]
+ with engine.connect() as conn:
+ assert conn.execute(select(messages.c.context_seq).where(messages.c.id == queued)).scalar() is None
+
+
+async def test_an_input_enters_the_context_once(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_main", home)
+ _session(conn, "ses_other", home)
+ consumed = _row(conn, "ses_main", home, "go")
+ reply = _row(conn, "ses_main", home, "done", kind="result")
+ foreign = _row(conn, "ses_other", home, "elsewhere")
+ store = SQLiteTranscriptStore(engine)
+ entry = await store.consume_input("ses_main", consumed, _user("go"))
+
+ assert await store.consume_input("ses_main", consumed, _user("go")) == entry
+ for message_id, message in ((consumed, _user("edited")), (reply, _user("done")), (foreign, _user("x"))):
+ with pytest.raises(TranscriptError):
+ await store.consume_input("ses_main", message_id, message)
+ assert list(await store.load("ses_main")) == [entry]
+
+
+async def test_concurrent_writers_never_share_a_context_seq(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_main", home)
+ consumed = _row(conn, "ses_main", home, "go")
+ # Two stores on two engines stand in for two processes: only SQLite orders them.
+ other_engine = create_sqlite_engine()
+ stores = (SQLiteTranscriptStore(engine), SQLiteTranscriptStore(other_engine))
+ try:
+ await stores[0].consume_input("ses_main", consumed, _user("go"))
+ await asyncio.gather(
+ *(
+ stores[index % 2].append_tool_result("ses_main", _tool_result(f"call_{index}", "ok"), details={})
+ for index in range(40)
+ ),
+ *(stores[index % 2].append_response("ses_main", _assistant(f"r{index}"), final=False) for index in range(20)),
+ )
+ finally:
+ other_engine.dispose()
+
+ loaded = await stores[0].load("ses_main")
+ assert [entry.context_seq for entry in loaded] == list(range(1, 62))
+
+
+async def test_fork_chain_reads_the_ancestry_up_to_each_anchor(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_root", home)
+ ask = _row(conn, "ses_root", home, "ask")
+ store = SQLiteTranscriptStore(engine)
+ root = [
+ await store.consume_input("ses_root", ask, _user("ask")),
+ await store.append_response("ses_root", _assistant("run", call_id="call_1"), final=False),
+ await store.append_tool_result("ses_root", _tool_result("call_1", "ok"), details={}),
+ ]
+ with engine.begin() as conn:
+ # A steer accepted before the anchor but consumed after the fork, and a
+ # display-only anchor whose last preceding context row is a tool result.
+ steer = _row(conn, "ses_root", home, "steer")
+ anchor = _row(conn, "ses_root", home, "progress", kind="notify")
+ _fork(conn, "ses_child", home, "ses_root", anchor)
+ # Released forks and forks of other backends carry no anchor_seq.
+ _session(conn, "ses_released", home, {"fork_source_session_id": "ses_root", "fork_source_message_id": anchor})
+ await store.consume_input("ses_root", steer, _user("steer"))
+ await store.append_payload("ses_root", "compaction", {**COMPACTION, "first_kept_seq": 4})
+
+ with engine.begin() as conn:
+ child_ask = _row(conn, "ses_child", home, "child ask")
+ released_ask = _row(conn, "ses_released", home, "fresh")
+ child = [
+ await store.consume_input("ses_child", child_ask, _user("child ask")),
+ await store.append_response("ses_child", _assistant("child done"), final=True),
+ ]
+ with engine.begin() as conn:
+ _fork(conn, "ses_grandchild", home, "ses_child", child[1].row_id)
+ grandchild_ask = _row(conn, "ses_grandchild", home, "grandchild ask")
+ # A fork at an earlier message of a Session that has moved on.
+ _fork(conn, "ses_early", home, "ses_root", ask)
+ early_ask = _row(conn, "ses_early", home, "early ask")
+ grandchild = await store.consume_input("ses_grandchild", grandchild_ask, _user("grandchild ask"))
+ released = await store.consume_input("ses_released", released_ask, _user("fresh"))
+ early = await store.consume_input("ses_early", early_ask, _user("early ask"))
+
+ # The child continues after the anchor; the root's later steer and checkpoint
+ # (4, 5) are not in its context.
+ assert [entry.context_seq for entry in child] == [4, 5]
+ assert list(await store.load("ses_child")) == root + child
+ assert list(await store.load("ses_grandchild")) == [*root, *child, grandchild]
+ assert grandchild.context_seq == 6
+ assert [entry.kind for entry in await store.load("ses_root")][-2:] == ["input", "compaction"]
+ assert list(await store.load("ses_released")) == [released]
+ assert released.context_seq == 1
+ assert list(await store.load("ses_early")) == [root[0], early]
+ assert early.context_seq == 2
+
+
+async def test_outbox_replays_pending_responses_until_every_part_is_confirmed(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_main", home)
+ consumed = _row(conn, "ses_main", home, "go")
+ store = SQLiteTranscriptStore(engine)
+ await store.consume_input("ses_main", consumed, _user("go"))
+ narration = await store.append_response("ses_main", _assistant("step", call_id="call_1"), final=False)
+ await store.append_tool_result("ses_main", _tool_result("call_1", "ok"), details={})
+ # A response with nothing to display has no part on any surface.
+ silent = AssistantMessage(content=(ToolCallBlock(id="call_2", name="bash"),), origin=ORIGIN, stop_reason="tool_use")
+ await store.append_response("ses_main", silent, final=False)
+ await store.append_tool_result("ses_main", _tool_result("call_2", "ok"), details={})
+ reply = await store.append_response("ses_main", _assistant("answer"), final=True)
+
+ pending = await store.pending_deliveries("ses_main")
+ assert [(item.row_id, item.context_seq, item.final, item.text, item.parts) for item in pending] == [
+ (narration.row_id, 2, False, "step", ()),
+ (reply.row_id, 6, True, "answer", ()),
+ ]
+ assert pending[1].message == reply.message
+
+ assert await store.record_delivery_part("ses_main", narration.row_id, index=0, count=1) is True
+ # A reply split in two stays pending until both parts are confirmed, and a
+ # retried part keeps its first receipt.
+ assert await store.record_delivery_part("ses_main", reply.row_id, index=1, count=2, native_message_id="b") is False
+ assert await store.record_delivery_part("ses_main", reply.row_id, index=1, count=2, native_message_id="x") is False
+ [still_pending] = await store.pending_deliveries("ses_main")
+ assert still_pending.row_id == reply.row_id
+ assert [part and part["native_message_id"] for part in still_pending.parts] == [None, "b"]
+ with pytest.raises(TranscriptError):
+ await store.record_delivery_part("ses_main", reply.row_id, index=0, count=3)
+ assert await store.record_delivery_part("ses_main", reply.row_id, index=0, count=2, native_message_id="a") is True
+
+ assert await store.pending_deliveries("ses_main") == []
+ with engine.connect() as conn:
+ delivery = json.loads(
+ conn.execute(select(messages.c.metadata_json).where(messages.c.id == reply.row_id)).scalar_one()
+ )["delivery"]
+ assert delivery["state"] == "delivered"
+ assert [part["native_message_id"] for part in delivery["parts"]] == ["a", "b"]
+ with pytest.raises(TranscriptError):
+ await store.record_delivery_part("ses_main", consumed, index=0, count=1)
+
+
+async def test_a_cancelled_write_raises_only_after_its_commit_settled(engine) -> None:
+ with engine.begin() as conn:
+ home = _scope(conn, "C-home")
+ _session(conn, "ses_main", home)
+ consumed = _row(conn, "ses_main", home, "go")
+ store = SQLiteTranscriptStore(engine)
+ await store.consume_input("ses_main", consumed, _user("go"))
+ # Another writer holds SQLite's lock, so the append waits inside its thread.
+ holder = sqlite3.connect(get_sqlite_state_path(), isolation_level=None, check_same_thread=False)
+ holder.execute("BEGIN IMMEDIATE")
+ release = threading.Timer(0.5, holder.execute, ("COMMIT",))
+ append = asyncio.create_task(store.append_tool_result("ses_main", _tool_result("call_1", "ok"), details={}))
+ await asyncio.sleep(0.1)
+ release.start()
+ append.cancel()
+ try:
+ with pytest.raises(asyncio.CancelledError):
+ await append
+ # Recovery after the cancellation already sees the commit, so it cannot append it again.
+ assert [entry.kind for entry in await store.load("ses_main")] == ["input", "tool_result"]
+ finally:
+ release.join()
+ holder.close()
diff --git a/tests/test_skill_observability_migration.py b/tests/test_skill_observability_migration.py
index 555d93c0b..aece5af4f 100644
--- a/tests/test_skill_observability_migration.py
+++ b/tests/test_skill_observability_migration.py
@@ -28,11 +28,14 @@ def test_skill_schema_upgrade_downgrade_preserves_existing_events(tmp_path):
)
],
)
- original = conn.execute("SELECT * FROM agent_events ORDER BY id").fetchall()
+ cursor = conn.execute("SELECT * FROM agent_events ORDER BY id")
+ original = cursor.fetchall()
+ # Later revisions may add nullable columns; the released ones must not change.
+ columns = ", ".join(column[0] for column in cursor.description)
migrations.run_migrations(path)
with sqlite3.connect(path) as conn:
- assert conn.execute("SELECT * FROM agent_events ORDER BY id").fetchall() == original
- assert conn.execute("SELECT version_num FROM alembic_version").fetchone() == ("20260923_0062",)
+ assert conn.execute(f"SELECT {columns} FROM agent_events ORDER BY id").fetchall() == original
+ assert conn.execute("SELECT version_num FROM alembic_version").fetchone() == ("20261002_0063",)
assert conn.execute("SELECT count(*) FROM skill_usage_daily").fetchone() == (0,)
assert {row[2] for row in conn.execute("PRAGMA foreign_key_list(skill_usage_daily)")} == {
"scopes",
@@ -47,7 +50,7 @@ def test_skill_schema_upgrade_downgrade_preserves_existing_events(tmp_path):
)
command.downgrade(migrations.alembic_config(path), "20260821_0060")
with sqlite3.connect(path) as conn:
- assert conn.execute("SELECT * FROM agent_events ORDER BY id").fetchall() == original
+ assert conn.execute(f"SELECT {columns} FROM agent_events ORDER BY id").fetchall() == original
assert conn.execute("SELECT name FROM sqlite_master WHERE name='skill_usage_daily'").fetchone() is None
assert (
conn.execute("SELECT name FROM sqlite_master WHERE name='ix_agent_events_skill_created_id'").fetchone()
@@ -55,5 +58,5 @@ def test_skill_schema_upgrade_downgrade_preserves_existing_events(tmp_path):
)
migrations.run_migrations(path)
with sqlite3.connect(path) as conn:
- assert conn.execute("SELECT * FROM agent_events ORDER BY id").fetchall() == original
+ assert conn.execute(f"SELECT {columns} FROM agent_events ORDER BY id").fetchall() == original
assert conn.execute("PRAGMA integrity_check").fetchone() == ("ok",)
diff --git a/tests/test_sqlite_state_migration.py b/tests/test_sqlite_state_migration.py
index d73d13849..a305ea724 100644
--- a/tests/test_sqlite_state_migration.py
+++ b/tests/test_sqlite_state_migration.py
@@ -38,7 +38,7 @@ from vibe.message_types import build_partial_index_predicate
pytestmark = pytest.mark.no_sqlite_template
-HEAD_REVISION = "20260923_0062"
+HEAD_REVISION = "20261002_0063"
# ``storage.models`` builds a bare ``MetaData()``, so its foreign keys are unnamed and
# Alembic cannot re-emit them when batch mode recreates a table. Every migration that
# rebuilds one therefore passes this convention; the rebuild simulated below has to pass
@@ -1582,6 +1582,9 @@ def test_scoped_native_message_identity_upgrade_preserves_accepted_delivery(
engine = create_sqlite_engine(db_path)
now = "2026-08-02T00:00:00Z"
with engine.begin() as conn:
+ # The fixture is written by today's delivery code, which selects the
+ # current Message columns; 20261002_0063 accepts the column already present.
+ conn.exec_driver_sql("alter table messages add column context_seq integer")
scope_id = upsert_scope(
conn,
platform="telegram",
@@ -3197,9 +3200,10 @@ def test_show_annotation_migration_changes_only_the_user_send_index(
),
)
conn.commit()
- original_rows = conn.execute(
- "select * from messages order by id"
- ).fetchall()
+ cursor = conn.execute("select * from messages order by id")
+ original_rows = cursor.fetchall()
+ # Later revisions may add nullable columns; the released ones must not change.
+ original_columns = ", ".join(column[0] for column in cursor.description)
original_index = _index_sql(conn, "ix_messages_inbox_user_send")
migration = import_module(
@@ -3211,7 +3215,7 @@ def test_show_annotation_migration_changes_only_the_user_send_index(
with sqlite3.connect(db_path) as conn:
upgraded_rows = conn.execute(
- "select * from messages order by id"
+ f"select {original_columns} from messages order by id"
).fetchall()
user_send_index = _index_sql(conn, "ix_messages_inbox_user_send")
version = conn.execute("select version_num from alembic_version").fetchone()
@@ -3230,7 +3234,7 @@ def test_show_annotation_migration_changes_only_the_user_send_index(
with sqlite3.connect(db_path) as conn:
downgraded_rows = conn.execute(
- "select * from messages order by id"
+ f"select {original_columns} from messages order by id"
).fetchall()
user_send_index = _index_sql(conn, "ix_messages_inbox_user_send")
versions = {
diff --git a/tests/test_web_push_provider_invalidation_migration.py b/tests/test_web_push_provider_invalidation_migration.py
index 739a0eda7..9385ad512 100644
--- a/tests/test_web_push_provider_invalidation_migration.py
+++ b/tests/test_web_push_provider_invalidation_migration.py
@@ -69,7 +69,7 @@ def test_upgrade_keeps_legacy_disabled_failure_opted_out(tmp_path):
web_push_service.mark_send_failure(conn, endpoint=enabled["endpoint"], disable=True)
with sqlite3.connect(path) as conn:
assert conn.execute("select version_num from alembic_version").fetchone() == (
- "20260923_0062",
+ "20261002_0063",
)
command.downgrade(migrations.alembic_config(path), "20260907_0061")