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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Native Git checkpoints for existing Show Page workspaces."""
from __future__ import annotations
import asyncio
import json
import logging
import os
import re
import shutil
import subprocess
import time
from concurrent.futures import Future
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from config import paths
from core.git_binary import ResolvedGit, resolve_git
from core.ordered_worker import OrderedWorker
from vibe.message_types import input_author_type_pairs
logger = logging.getLogger(__name__)
PRE_TURN = "pre-turn"
POST_TURN = "post-turn"
ADOPT = "adopt"
MAX_COMMITS = 500
MAX_GITDIR_BYTES = 200 * 1024 * 1024
STALE_INDEX_LOCK_SECONDS = 5 * 60
GIT_COMMAND_TIMEOUT_SECONDS = 60
GIT_MAINTENANCE_TIMEOUT_SECONDS = 5 * 60
# Queued checkpoints get this long at service stop before the rest are abandoned.
CHECKPOINT_DRAIN_SECONDS = 10.0
_PLATFORM_EXCLUDES = ("node_modules/", "dist/", ".vite/")
_CHECKPOINT_KINDS = {PRE_TURN, POST_TURN, ADOPT}
_MANAGED_POINTER_PARENT = "show-git"
_SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
_MAIN_ANCHOR_REF = "refs/avibe/checkpoint-main"
_TURN_STATE_KEY = "_avibe_show_git_checkpoint"
_CHECKPOINT_STATUS_VERSION = 1
TURN_CHECKPOINT_INPUT_AUTHOR_TYPES = (
*input_author_type_pairs(),
("user", "pending"),
("harness", "pending"),
)
TURN_CHECKPOINT_INPUT_TYPES = tuple(
dict.fromkeys(
message_type
for _author, message_type in TURN_CHECKPOINT_INPUT_AUTHOR_TYPES
)
)
_TURN_CHECKPOINT_INPUT_AUTHOR_TYPE_SET = frozenset(
TURN_CHECKPOINT_INPUT_AUTHOR_TYPES
)
_checkpoint_service_active: bool | None = None
_SCRUBBED_GIT_ENV = {
"GIT_DIR",
"GIT_WORK_TREE",
"GIT_INDEX_FILE",
"GIT_OBJECT_DIRECTORY",
"GIT_ALTERNATE_OBJECT_DIRECTORIES",
"GIT_COMMON_DIR",
"GIT_CONFIG_PARAMETERS",
"GIT_AUTHOR_NAME",
"GIT_AUTHOR_EMAIL",
"GIT_AUTHOR_DATE",
"GIT_COMMITTER_NAME",
"GIT_COMMITTER_EMAIL",
"GIT_COMMITTER_DATE",
"EMAIL",
}
_INPUT_TURN_MESSAGE_TYPES = tuple(
dict.fromkeys(message_type for _, message_type in input_author_type_pairs())
)
class ShowGitError(RuntimeError):
"""A platform Git operation failed."""
@dataclass(frozen=True)
class TurnCheckpointContext:
message: str = ""
run_id: str | None = None
message_id: str | None = None
turn_id: str | None = None
@dataclass(frozen=True)
class _ActiveTurnCheckpoint:
context: TurnCheckpointContext
started_at: str
turn_id: str | None = None
def _record_checkpoint_service_state(active: bool) -> None:
global _checkpoint_service_active
_checkpoint_service_active = active
status_path = paths.get_show_git_runtime_status_path()
temporary = status_path.with_name(f".{status_path.name}.{os.getpid()}.tmp")
payload = {
"version": _CHECKPOINT_STATUS_VERSION,
"active": active,
"service_pid": os.getpid(),
"updated_at": datetime.now(timezone.utc).isoformat(),
}
try:
status_path.parent.mkdir(parents=True, exist_ok=True)
temporary.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
os.replace(temporary, status_path)
except OSError:
logger.warning("failed to persist Show Page checkpoint service state", exc_info=True)
finally:
try:
temporary.unlink(missing_ok=True)
except OSError:
pass
def show_git_checkpointing_active() -> bool:
"""Return the running service's startup-latched checkpoint capability."""
if _checkpoint_service_active is not None:
return _checkpoint_service_active
try:
payload = json.loads(paths.get_show_git_runtime_status_path().read_text(encoding="utf-8"))
if payload.get("version") != _CHECKPOINT_STATUS_VERSION or payload.get("active") is not True:
return False
service_pid = int(payload.get("service_pid") or 0)
from vibe.runtime import resolve_service_owner_pid
return service_pid > 0 and resolve_service_owner_pid(include_starting=False) == service_pid
except (OSError, TypeError, ValueError, json.JSONDecodeError):
return False
def _read_git_pointer(pointer: Path) -> Path | None:
if pointer.is_symlink() or not pointer.is_file():
return None
try:
lines = pointer.read_text(encoding="utf-8").splitlines()
except OSError:
return None
if len(lines) != 1 or not lines[0].startswith("gitdir: "):
return None
raw = lines[0].removeprefix("gitdir: ").strip()
if not raw:
return None
target = Path(raw).expanduser()
if not target.is_absolute():
target = pointer.parent / target
return target.resolve(strict=False)
def _workspace_ownership(workspace: Path, gitdir: Path) -> tuple[bool, bool]:
pointer = workspace / ".git"
if not pointer.exists() and not pointer.is_symlink():
return True, False
target = _read_git_pointer(pointer)
if target is None:
return False, False
expected = gitdir.resolve(strict=False)
if target == expected:
return True, False
if not target.exists() and target.name == gitdir.name and target.parent.name == _MANAGED_POINTER_PARENT:
return True, True
return False, False
def _workspace_is_self_managed(session_id: str) -> bool:
if not _SESSION_ID_PATTERN.fullmatch(str(session_id or "")):
return True
managed, _rewrite_pointer = _workspace_ownership(
paths.get_show_page_dir(session_id),
paths.get_show_git_dir(session_id),
)
return not managed
def show_history_status(session_id: str) -> dict[str, Any]:
"""Describe this page's history on demand without creating or changing it."""
if not _SESSION_ID_PATTERN.fullmatch(str(session_id or "")):
raise ValueError("Invalid Show Page session id")
return {
"mode": "self-managed" if _workspace_is_self_managed(session_id) else "managed",
"checkpointing_active": show_git_checkpointing_active(),
"git_dir": str(paths.get_show_git_dir(session_id)),
}
def _single_line(value: Any) -> str:
without_controls = "".join(" " if ord(char) < 32 or ord(char) == 127 else char for char in str(value or ""))
return " ".join(without_controls.split())
def sanitize_checkpoint_subject(message: str | None) -> str:
return _single_line(message)[:72].rstrip() or "checkpoint"
def _checkpoint_message(subject: str, *, session_id: str, run_id: str | None, checkpoint: str) -> str:
safe_run_id = _single_line(run_id) or "-"
return (
f"{subject}\n\n"
f"Avibe-Session: {session_id}\n"
f"Avibe-Run: {safe_run_id}\n"
f"Avibe-Checkpoint: {checkpoint}"
)
def _git_environment() -> dict[str, str]:
env = dict(os.environ)
for key in list(env):
if key in _SCRUBBED_GIT_ENV or key.startswith("GIT_CONFIG_KEY_") or key.startswith("GIT_CONFIG_VALUE_"):
env.pop(key, None)
env.pop("GIT_CONFIG_COUNT", None)
env["GIT_CONFIG_GLOBAL"] = os.devnull
env["GIT_CONFIG_SYSTEM"] = os.devnull
return env
def _read_message_text(content_text: Any, content_json: Any) -> str:
text = str(content_text or "").strip()
if text:
return text
try:
content = json.loads(content_json or "{}")
except (TypeError, ValueError):
return ""
return str(content.get("text") or "").strip() if isinstance(content, dict) else ""
def _run_id_from_native_message_id(value: Any) -> str | None:
native_id = str(value or "").strip()
if not native_id.startswith("agent_run:"):
return None
run_id = native_id.removeprefix("agent_run:").strip()
return run_id or None
def _delivery_snapshot_text(value: Any) -> str:
try:
snapshot = json.loads(value or "{}")
except (TypeError, ValueError):
return ""
if not isinstance(snapshot, dict):
return ""
return _read_message_text(
snapshot.get("content_text"),
snapshot.get("content_json"),
)
def load_turn_checkpoint_context(
session_id: str,
*,
turn_id: str | None = None,
after: str | None = None,
) -> TurnCheckpointContext:
"""Read the driving message/run without changing the turn event payload."""
try:
from sqlalchemy import func, select, tuple_
from storage.db import get_cached_sqlite_engine
from storage.messages_service import transcript_order_value
from storage.models import (
agent_runs,
message_deliveries,
messages,
session_turns,
)
with get_cached_sqlite_engine().connect() as conn:
turn_query = select(
session_turns.c.id,
session_turns.c.initial_delivery_id,
session_turns.c.created_at,
session_turns.c.started_at,
).where(session_turns.c.session_id == session_id)
if turn_id:
turn_query = turn_query.where(session_turns.c.id == turn_id).limit(1)
elif after is None:
turn_query = (
turn_query.where(session_turns.c.state.in_(("starting", "active")))
.order_by(
func.coalesce(
session_turns.c.started_at,
session_turns.c.created_at,
).desc(),
session_turns.c.id.desc(),
)
.limit(1)
)
else:
turn_query = (
turn_query.where(
func.coalesce(
session_turns.c.started_at,
session_turns.c.created_at,
)
>= after
)
.order_by(
func.coalesce(
session_turns.c.started_at,
session_turns.c.created_at,
).asc(),
session_turns.c.id.asc(),
)
.limit(1)
)
turn = conn.execute(turn_query).first()
if turn is not None:
delivery = conn.execute(
select(
message_deliveries.c.id,
message_deliveries.c.message_id,
message_deliveries.c.snapshot_json,
)
.where(
message_deliveries.c.id == turn.initial_delivery_id
)
.limit(1)
).first()
if delivery is not None:
run_id = conn.execute(
select(agent_runs.c.id)
.where(agent_runs.c.delivery_id == delivery.id)
.where(agent_runs.c.run_type != "watch_runtime")
.order_by(agent_runs.c.created_at, agent_runs.c.id)
.limit(1)
).scalar_one_or_none()
if delivery.message_id:
message_row = conn.execute(
select(
messages.c.id,
messages.c.author,
messages.c.type,
messages.c.content_text,
messages.c.content_json,
messages.c.native_message_id,
)
.where(messages.c.id == delivery.message_id)
.limit(1)
).first()
if message_row is not None:
return TurnCheckpointContext(
message=_read_message_text(
message_row.content_text,
message_row.content_json,
),
run_id=(
str(run_id)
if run_id is not None
else _run_id_from_native_message_id(
message_row.native_message_id
)
),
message_id=str(message_row.id),
turn_id=str(turn.id),
)
return TurnCheckpointContext(
message=_delivery_snapshot_text(delivery.snapshot_json),
run_id=str(run_id) if run_id is not None else None,
message_id=str(delivery.id),
turn_id=str(turn.id),
)
active_run = conn.execute(
select(agent_runs.c.id, agent_runs.c.message, agent_runs.c.prompt)
.where(agent_runs.c.session_id == session_id)
.where(agent_runs.c.status.in_(("running", "processing")))
.where(agent_runs.c.run_type != "watch_runtime")
.order_by(agent_runs.c.started_at.desc(), agent_runs.c.created_at.desc(), agent_runs.c.id.desc())
.limit(1)
).first()
if active_run is not None:
text = str(active_run.message or active_run.prompt or "").strip()
run_id = str(active_run.id)
return TurnCheckpointContext(message=text, run_id=run_id, message_id=f"agent_run:{run_id}")
message_query = select(
messages.c.id,
messages.c.author,
messages.c.type,
messages.c.content_text,
messages.c.content_json,
messages.c.native_message_id,
).where(messages.c.session_id == session_id)
message_order = transcript_order_value(messages)
if after is None:
message_query = message_query.order_by(
message_order.desc(), messages.c.id.desc()
).limit(1)
else:
message_query = (
message_query.where(
tuple_(messages.c.author, messages.c.type).in_(
TURN_CHECKPOINT_INPUT_AUTHOR_TYPES
)
)
.where(message_order >= after)
.order_by(message_order.asc(), messages.c.id.asc())
.limit(1)
)
message_row = conn.execute(message_query).first()
if (
message_row is None
or (message_row.author, message_row.type)
not in _TURN_CHECKPOINT_INPUT_AUTHOR_TYPE_SET
):
return TurnCheckpointContext()
return TurnCheckpointContext(
message=_read_message_text(message_row.content_text, message_row.content_json),
run_id=_run_id_from_native_message_id(message_row.native_message_id),
message_id=str(message_row.id),
)
except Exception:
logger.debug("show checkpoint metadata lookup failed for session=%s", session_id, exc_info=True)
return TurnCheckpointContext()
class ShowGitRepository:
def __init__(
self,
session_id: str,
git: ResolvedGit,
*,
workspace: Path | None = None,
gitdir: Path | None = None,
) -> None:
if not _SESSION_ID_PATTERN.fullmatch(str(session_id or "")):
raise ValueError("invalid Show Page session id")
self.session_id = session_id
self.git = git
self.workspace = workspace or paths.get_show_page_dir(session_id)
self.gitdir = gitdir or paths.get_show_git_dir(session_id)
self.hooks_dir = self.gitdir / "avibe-empty-hooks"
def checkpoint(self, checkpoint: str, *, message: str = "", run_id: str | None = None) -> bool:
if checkpoint not in {PRE_TURN, POST_TURN}:
raise ValueError(f"unsupported checkpoint kind: {checkpoint}")
if not self.workspace.is_dir():
return False
managed, rewrite_pointer = self._workspace_ownership()
initialized = self._ensure_repository()
self._remove_stale_index_lock()
self._ensure_platform_config()
self._ensure_empty_hooks_dir()
self._ensure_platform_excludes()
if managed:
self._ensure_pointer(rewrite=rewrite_pointer)
self._reattach_main()
self._restore_forward_main()
if initialized or not self._has_commits():
created = self._commit_all(
"adopt existing workspace",
run_id=run_id,
checkpoint=ADOPT,
allow_empty=True,
)
else:
subject = "out-of-band changes" if checkpoint == PRE_TURN else sanitize_checkpoint_subject(message)
created = self._commit_if_dirty(subject, run_id=run_id, checkpoint=checkpoint)
self._prune_if_needed()
self._record_main_anchor()
return created
def _workspace_ownership(self) -> tuple[bool, bool]:
return _workspace_ownership(self.workspace, self.gitdir)
def _ensure_repository(self) -> bool:
valid = (self.gitdir / "HEAD").is_file() and (self.gitdir / "objects").is_dir()
if valid:
return False
self.gitdir.parent.mkdir(parents=True, exist_ok=True)
result = self._run_raw(
["init", "--bare", str(self.gitdir)],
timeout=GIT_COMMAND_TIMEOUT_SECONDS,
)
if result.returncode != 0:
raise ShowGitError(result.stderr.strip() or "failed to initialize Show Page checkpoint repository")
self._run_checked(["symbolic-ref", "HEAD", "refs/heads/main"])
return True
def _ensure_platform_config(self) -> None:
self._run_checked(["config", "core.bare", "false"])
def _ensure_empty_hooks_dir(self) -> None:
if self.hooks_dir.is_symlink() or (self.hooks_dir.exists() and not self.hooks_dir.is_dir()):
self.hooks_dir.unlink()
self.hooks_dir.mkdir(parents=True, exist_ok=True)
for child in self.hooks_dir.iterdir():
if child.is_dir() and not child.is_symlink():
shutil.rmtree(child)
else:
child.unlink()
def _ensure_platform_excludes(self) -> None:
exclude = self.gitdir / "info" / "exclude"
exclude.parent.mkdir(parents=True, exist_ok=True)
try:
existing = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
except OSError as exc:
raise ShowGitError(f"failed to read checkpoint excludes: {exc}") from exc
existing_lines = set(existing.splitlines())
missing = [pattern for pattern in _PLATFORM_EXCLUDES if pattern not in existing_lines]
if not missing:
return
prefix = existing
if prefix and not prefix.endswith("\n"):
prefix += "\n"
exclude.write_text(prefix + "\n".join(missing) + "\n", encoding="utf-8")
def _ensure_pointer(self, *, rewrite: bool) -> None:
pointer = self.workspace / ".git"
if pointer.exists() or pointer.is_symlink():
if not rewrite:
return
if pointer.is_symlink() or not pointer.is_file():
return
temporary = self.gitdir / f"avibe-git-pointer-{os.getpid()}.tmp"
try:
temporary.write_text(f"gitdir: {self.gitdir.resolve(strict=False)}\n", encoding="utf-8")
os.replace(temporary, pointer)
finally:
temporary.unlink(missing_ok=True)
def _remove_stale_index_lock(self) -> None:
lock = self.gitdir / "index.lock"
try:
age = time.time() - lock.stat().st_mtime
except OSError:
return
if age <= STALE_INDEX_LOCK_SECONDS:
return
try:
lock.unlink()
except OSError:
logger.warning("failed to remove stale Show Page checkpoint index lock: %s", lock, exc_info=True)
def _reattach_main(self) -> None:
current = self._run(["symbolic-ref", "-q", "HEAD"], check=False)
if current.returncode == 0 and current.stdout.strip() == "refs/heads/main":
return
self._run_checked(["symbolic-ref", "HEAD", "refs/heads/main"])
def _restore_forward_main(self) -> None:
anchor = self._run(["rev-parse", "--verify", _MAIN_ANCHOR_REF], check=False)
if anchor.returncode != 0:
return
anchor_oid = anchor.stdout.strip()
current = self._run(["rev-parse", "--verify", "refs/heads/main"], check=False)
if current.returncode != 0:
self._run_checked(["update-ref", "refs/heads/main", anchor_oid])
return
current_oid = current.stdout.strip()
ancestry = self._run(["merge-base", "--is-ancestor", anchor_oid, current_oid], check=False)
if ancestry.returncode == 0:
return
if ancestry.returncode != 1:
raise ShowGitError(ancestry.stderr.strip() or "failed to verify Show Page checkpoint ancestry")
self._run_checked(["update-ref", "refs/heads/main", anchor_oid, current_oid])
def _record_main_anchor(self) -> None:
head = self._run_checked(["rev-parse", "refs/heads/main"]).stdout.strip()
self._run_checked(["update-ref", _MAIN_ANCHOR_REF, head])
def _has_commits(self) -> bool:
return self._run(["rev-parse", "--verify", "HEAD"], check=False).returncode == 0
def _commit_if_dirty(self, subject: str, *, run_id: str | None, checkpoint: str) -> bool:
status = self._run_checked(["status", "--porcelain=v1", "--untracked-files=all"])
if not status.stdout:
return False
return self._commit_all(subject, run_id=run_id, checkpoint=checkpoint, allow_empty=False)
def _commit_all(self, subject: str, *, run_id: str | None, checkpoint: str, allow_empty: bool) -> bool:
if checkpoint not in _CHECKPOINT_KINDS:
raise ValueError(f"unsupported commit checkpoint kind: {checkpoint}")
self._run_checked(["add", "-A"])
command = ["commit"]
if allow_empty:
command.append("--allow-empty")
command.extend(
[
"-m",
_checkpoint_message(
subject,
session_id=self.session_id,
run_id=run_id,
checkpoint=checkpoint,
),
]
)
result = self._run(command, check=False)
if result.returncode == 0:
return True
if not allow_empty and "nothing to commit" in result.stdout.lower():
return False
raise ShowGitError(result.stderr.strip() or result.stdout.strip() or "failed to commit Show Page checkpoint")
def _prune_if_needed(self) -> None:
if not self._has_commits():
return
count_result = self._run_checked(["rev-list", "--count", "refs/heads/main"])
try:
commit_count = int(count_result.stdout.strip())
except ValueError:
commit_count = 0
if commit_count <= MAX_COMMITS and self._gitdir_size_at_most(MAX_GITDIR_BYTES):
return
remotes = self._run_checked(["remote"])
if remotes.stdout.strip():
self._run_checked(["gc"], timeout=GIT_MAINTENANCE_TIMEOUT_SECONDS)
return
old_head = self._run_checked(["rev-parse", "refs/heads/main"]).stdout.strip()
tree = self._run_checked(["rev-parse", "refs/heads/main^{tree}"]).stdout.strip()
message = self._run_checked(["log", "-1", "--format=%B", "refs/heads/main"]).stdout.rstrip()
baseline = self._run_checked(["commit-tree", tree], input_text=message + "\n").stdout.strip()
self._run_checked(["update-ref", "refs/heads/main", baseline, old_head])
refs = self._run_checked(["for-each-ref", "--format=%(refname)"]).stdout.splitlines()
for ref in refs:
if ref and ref != "refs/heads/main":
self._run_checked(["update-ref", "-d", ref])
self._run_checked(["reflog", "expire", "--expire=now", "--all"])
self._run_checked(["gc", "--prune=now"], timeout=GIT_MAINTENANCE_TIMEOUT_SECONDS)
def _gitdir_size_at_most(self, limit: int) -> bool:
total = 0
try:
for root, _dirs, files in os.walk(self.gitdir):
for filename in files:
try:
total += (Path(root) / filename).stat().st_size
except OSError:
continue
if total > limit:
return False
except OSError:
return True
return True
def _base_command(self) -> list[str]:
return [
str(self.git.path),
"-c",
"user.name=avibe-checkpoint",
"-c",
"[email protected]",
"-c",
"commit.gpgsign=false",
"-c",
f"core.hooksPath={self.hooks_dir}",
"-c",
"gc.auto=0",
]
def _run_raw(
self,
args: list[str],
*,
timeout: int,
input_text: str | None = None,
) -> subprocess.CompletedProcess[str]:
try:
return subprocess.run(
[*self._base_command(), *args],
check=False,
capture_output=True,
text=True,
input=input_text,
env=_git_environment(),
timeout=timeout,
)
except (OSError, subprocess.SubprocessError) as exc:
raise ShowGitError(f"failed to execute Git checkpoint command: {exc}") from exc
def _run(
self,
args: list[str],
*,
check: bool,
timeout: int = GIT_COMMAND_TIMEOUT_SECONDS,
input_text: str | None = None,
) -> subprocess.CompletedProcess[str]:
result = self._run_raw(
[f"--git-dir={self.gitdir}", f"--work-tree={self.workspace}", *args],
timeout=timeout,
input_text=input_text,
)
if check and result.returncode != 0:
detail = result.stderr.strip() or result.stdout.strip() or f"git {' '.join(args)} failed"
raise ShowGitError(detail)
return result
def _run_checked(
self,
args: list[str],
*,
timeout: int = GIT_COMMAND_TIMEOUT_SECONDS,
input_text: str | None = None,
) -> subprocess.CompletedProcess[str]:
return self._run(args, check=True, timeout=timeout, input_text=input_text)
_UNSET = object()
def _bot_directory_for_session(session_id: str) -> Path | None:
"""A Bot Session's directory (``ses_<handle>`` and ``~/.avibe/bots/<handle>/``), when it exists."""
from core.bots import bot_directory, bot_handle_for_session_id
handle = bot_handle_for_session_id(session_id)
if handle is None:
return None
directory = bot_directory(handle)
return directory if directory.is_dir() else None
class ShowGitCheckpointService:
"""Turn-boundary subscriber owned by the Controller process.
The same boundaries give a Bot's directory its automatic history (``core.bot_git``): a Bot Session's Turn is
committed before it starts and after it ends, in the same ordered worker.
The bus delivers turn events on the controller loop. The subscriber records
them there and runs the checkpoint work, storage reads and ``git``, on one
ordered worker thread (#2734), so a slow or hung ``git`` stalls no Session.
Order is kept per event: a Turn's PRE_TURN snapshot runs before its POST_TURN
one, and before the next Turn's. A Turn's dispatch waits for its own PRE_TURN
snapshot (``wait_for_turn_start``) before the prompt reaches the backend, so
the snapshot still precedes the agent's first edit.
"""
def __init__(self, git: ResolvedGit | None | object = _UNSET) -> None:
self.git = resolve_git() if git is _UNSET else git
self._bus: Any = None
self._subscription_id: int | None = None
# Read and written only by the worker.
self._active_turns: dict[str, _ActiveTurnCheckpoint] = {}
self._open_bus_turns: set[str] = set()
self._worker = OrderedWorker("show-git-checkpoints")
# Each Session's latest PRE_TURN job, until its dispatch has waited for it.
self._pre_turn_jobs: dict[str, Future[None]] = {}
@property
def enabled(self) -> bool:
return isinstance(self.git, ResolvedGit)
def start(self, event_bus: Any = None) -> None:
if self._subscription_id is not None:
return
_record_checkpoint_service_state(False)
if not self.enabled:
return
if event_bus is None:
from core.inbox_events import bus as event_bus
self._bus = event_bus
self._subscription_id = event_bus.subscribe_callback(self._handle_event)
_record_checkpoint_service_state(True)
def stop(self) -> None:
global _checkpoint_service_active
if self._bus is not None and self._subscription_id is not None:
self._bus.unsubscribe(self._subscription_id)
self._bus = None
self._subscription_id = None
# A Turn that ended just before shutdown still gets its POST_TURN snapshot.
self._worker.drain(CHECKPOINT_DRAIN_SECONDS)
self._active_turns.clear()
self._open_bus_turns.clear()
self._pre_turn_jobs.clear()
_record_checkpoint_service_state(False)
_checkpoint_service_active = None
@staticmethod
def _turn_state(context: Any) -> dict[str, Any] | None:
state = (getattr(context, "platform_specific", None) or {}).get(_TURN_STATE_KEY)
return state if isinstance(state, dict) else None
@staticmethod
def _existing_session_id(controller: Any, context: Any) -> str | None:
session_id = controller._session_id_from_context(context)
if session_id:
return session_id
payload = getattr(context, "platform_specific", None) or {}
base_session_id = str(payload.get("turn_base_session_id") or "").strip()
finder = getattr(getattr(controller, "sessions", None), "find_session_for_anchor", None)
if not base_session_id or not callable(finder):
return None
try:
row = finder(controller._get_session_key(context), base_session_id)
except Exception:
logger.debug("Show checkpoint session lookup failed", exc_info=True)
return None
session_id = str(row.get("id") or "").strip() if row else ""
if not session_id:
return None
updated = dict(payload)
updated["agent_session_id"] = session_id
context.platform_specific = updated
return session_id
@staticmethod
def _link_message(context: Any, session_id: str) -> bool:
platform = str(getattr(context, "platform", None) or "").strip()
message_id = str(getattr(context, "message_id", None) or "").strip()
if not platform or platform == "avibe" or not message_id:
return False
try:
from core.message_mirror import link_inbound_message_session
link_inbound_message_session(
platform=platform,
native_message_id=message_id,
session_id=session_id,
)
return True
except Exception:
logger.debug("Show checkpoint message link failed", exc_info=True)
return False
def begin_turn(self, controller: Any, context: Any) -> None:
"""Publish checkpoint start from the shared backend execution boundary."""
if self._bus is None:
return
state = self._turn_state(context)
if state is None or state.get("ended"):
state = {"start_observed": False, "ended": False}
if state.get("start_observed"):
return
payload = dict(getattr(context, "platform_specific", None) or {})
payload[_TURN_STATE_KEY] = state
context.platform_specific = payload
session_id = self._existing_session_id(controller, context)
if not session_id:
# A first-ever turn can bind its session only after backend dispatch.
# Keep the state on the context so terminal delivery can lazily adopt
# a workspace created during that turn.
return
owns_bus_lifecycle = session_id not in self._open_bus_turns
state = {
**state,
"start_observed": True,
"start_session_id": session_id,
"owns_bus_lifecycle": owns_bus_lifecycle,
"message_linked": self._link_message(context, session_id),
}
payload = dict(context.platform_specific or {})
payload[_TURN_STATE_KEY] = state
context.platform_specific = payload
# Workbench and /internal/dispatch may already have published their UI
# lifecycle before backend execution reached this shared boundary.
if owns_bus_lifecycle:
turn_id = str(payload.get("turn_token") or "").strip()
event = {"session_id": session_id}
if turn_id:
event["turn_id"] = turn_id
self._bus.publish("turn.start", event)
def end_turn(self, context: Any) -> None:
"""Publish checkpoint end from the shared terminal-result boundary."""
state = self._turn_state(context)
if self._bus is None or state is None or state.get("ended"):
return
payload = dict(getattr(context, "platform_specific", None) or {})
session_id = str(payload.get("agent_session_id") or state.get("start_session_id") or "").strip()
message_linked = bool(state.get("message_linked"))
if session_id and not message_linked:
message_linked = self._link_message(context, session_id)
payload[_TURN_STATE_KEY] = {**state, "ended": True, "message_linked": message_linked}
context.platform_specific = payload
if session_id and (not state.get("start_observed") or state.get("owns_bus_lifecycle")):
turn_id = str(payload.get("turn_token") or "").strip()
event = {"session_id": session_id}
if turn_id:
event["turn_id"] = turn_id
self._bus.publish("turn.end", event)
async def wait_for_turn_start(self, session_id: str) -> None:
"""Wait, without holding the loop, for this Session's PRE_TURN snapshot."""
job = self._pre_turn_jobs.get(session_id)
if job is None:
return
try:
# Shielded: a Stop that cancels the dispatch must not cancel the
# snapshot the Turn's POST_TURN checkpoint is compared against.
await asyncio.shield(asyncio.wrap_future(job))
finally:
if self._pre_turn_jobs.get(session_id) is job:
del self._pre_turn_jobs[session_id]
def _handle_event(self, event_type: str, data: Any) -> None:
if event_type not in {"turn.start", "turn.end"} or not isinstance(data, dict):
return
session_id = str(data.get("session_id") or "").strip()
if not _SESSION_ID_PATTERN.fullmatch(session_id):
return
if event_type == "turn.start":
self._open_bus_turns.add(session_id)
else:
self._open_bus_turns.discard(session_id)
if not paths.get_show_page_dir(session_id).is_dir() and _bot_directory_for_session(session_id) is None:
if event_type == "turn.end":
self._worker.submit(self._active_turns.pop, session_id, None)
return
turn_id = str(data.get("turn_id") or "").strip() or None
if event_type == "turn.start":
started_at = datetime.now(timezone.utc).isoformat()
self._pre_turn_jobs[session_id] = self._worker.submit(
self._checkpoint_turn_start, session_id, turn_id, started_at
)
else:
self._worker.submit(self._checkpoint_turn_end, session_id, turn_id)
def _checkpoint_turn_start(self, session_id: str, turn_id: str | None, started_at: str) -> None:
try:
context = (
load_turn_checkpoint_context(session_id, turn_id=turn_id)
if turn_id
else load_turn_checkpoint_context(session_id)
)
self._active_turns[session_id] = _ActiveTurnCheckpoint(
context=context,
started_at=started_at,
turn_id=turn_id or context.turn_id,
)
self._checkpoint_bot_directory(session_id, PRE_TURN, run_id=context.run_id)
if paths.get_show_page_dir(session_id).is_dir():
self._repository(session_id).checkpoint(PRE_TURN, run_id=context.run_id)
except Exception:
logger.exception("Show Page checkpoint failed at turn.start for session=%s", session_id)
def _checkpoint_turn_end(self, session_id: str, turn_id: str | None) -> None:
try:
active = self._active_turns.pop(session_id, None)
if active is None:
context = (
load_turn_checkpoint_context(session_id, turn_id=turn_id)
if turn_id
else load_turn_checkpoint_context(session_id)
)
start_context = TurnCheckpointContext()
else:
start_context = active.context
context = (
TurnCheckpointContext()
if start_context.message_id is not None
else load_turn_checkpoint_context(
session_id,
turn_id=active.turn_id,
)
if active.turn_id
else load_turn_checkpoint_context(
session_id,
after=active.started_at,
)
)
run_id = start_context.run_id or context.run_id
message = start_context.message if start_context.message_id is not None else context.message
self._checkpoint_bot_directory(session_id, POST_TURN, message=message, run_id=run_id)
if paths.get_show_page_dir(session_id).is_dir():
self._repository(session_id).checkpoint(POST_TURN, message=message, run_id=run_id)
except Exception:
logger.exception("Show Page checkpoint failed at turn.end for session=%s", session_id)
def _checkpoint_bot_directory(
self, session_id: str, checkpoint: str, *, message: str = "", run_id: str | None = None
) -> None:
"""Commit a Bot Session's directory; a failure here never blocks the Show Page checkpoint."""
from core.bot_git import BotGitRepository
from core.bots import bot_handle_for_session_id
directory = _bot_directory_for_session(session_id)
handle = bot_handle_for_session_id(session_id)
if directory is None or handle is None or not isinstance(self.git, ResolvedGit):
return
try:
BotGitRepository(handle, directory, self.git).checkpoint(
checkpoint, session_id=session_id, message=message, run_id=run_id
)
except Exception:
logger.exception("Bot directory checkpoint failed at %s for session=%s", checkpoint, session_id)
def _repository(self, session_id: str) -> ShowGitRepository:
if not isinstance(self.git, ResolvedGit):
raise ShowGitError("Git is unavailable")
return ShowGitRepository(session_id, self.git)