super-agents 0.1.0__py3-none-any.whl

super_agents/__init__.py

@@ -0,0 +1,27 @@
+"""Python implementation of the Super Agents MCP server."""
+
+from .app_server_client import (
+    CodexAppServerClient,
+    LabelQueryInput,
+    PendingServerRequest,
+    PermissionRequestCallback,
+    TurnState,
+    shared_permission_requests,
+    write_shared_permission_decision,
+    is_permission_request,
+)
+from .state import SessionRecord, StateFile, TurnSummary
+
+__all__ = [
+    "CodexAppServerClient",
+    "LabelQueryInput",
+    "PendingServerRequest",
+    "PermissionRequestCallback",
+    "SessionRecord",
+    "StateFile",
+    "TurnState",
+    "TurnSummary",
+    "shared_permission_requests",
+    "write_shared_permission_decision",
+    "is_permission_request",
+]

super_agents/__main__.py

@@ -0,0 +1,4 @@
+from .mcp_server import main
+
+if __name__ == "__main__":
+    main()

super_agents/app_client_routines.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import logging
+
+from .app_formatting import without_none
+from .app_models import LabelQueryInput
+from .app_protocol import extract_thread_id
+from .app_routines import (
+    DEFAULT_ROUTINE_TIMEZONE,
+    routine_from_patch,
+    routine_is_due,
+    routine_local_date,
+    routine_next_run_sort_key,
+    routine_next_run_summary,
+    routine_turn_input,
+    routine_with_next_run,
+)
+from .app_time import iso_now
+from .state import JsonObject, RoutineRecord, StateFile, get_string, update_state_file
+
+logger = logging.getLogger(__name__)
+
+
+class RoutineClientMixin:
+    async def save_routine(self, input_data: JsonObject) -> JsonObject:
+        name = str(input_data["name"])
+        async with self._state_lock:
+            def update(state: StateFile) -> JsonObject:
+                now = iso_now()
+                current = state.routines.get(name)
+                raw = current.to_json() if current else {"name": name, "createdAt": now}
+                for key, value in input_data.items():
+                    if value is not None:
+                        raw[key] = value
+                raw["name"] = name
+                raw["updatedAt"] = now
+                raw.setdefault("createdAt", now)
+                raw.setdefault("enabled", True)
+                raw.setdefault("timezone", DEFAULT_ROUTINE_TIMEZONE)
+                state.routines[name] = routine_from_patch(raw)
+                return state.routines[name].to_json()
+
+            routine = update_state_file(self.state_file, update)
+        return {
+            "routine": routine,
+            "nativeSupport": False,
+            "scheduler": "super-agents-local-wrapper",
+        }
+
+    async def list_routines(self) -> JsonObject:
+        state = await self.read_state()
+        routines = sorted(state.routines.values(), key=lambda routine: routine.updated_at, reverse=True)
+        return {
+            "count": len(routines),
+            "routines": [routine_with_next_run(routine) for routine in routines],
+            "nativeSupport": False,
+            "scheduler": "super-agents-local-wrapper",
+        }
+
+    async def read_routine(self, name: str) -> JsonObject:
+        state = await self.read_state()
+        routine = state.routines.get(name)
+        if routine is None:
+            raise ValueError(f"No Super Agents routine found for name {name}.")
+        return {
+            "routine": routine_with_next_run(routine),
+            "nativeSupport": False,
+            "scheduler": "super-agents-local-wrapper",
+        }
+
+    async def delete_routine(self, name: str) -> JsonObject:
+        async with self._state_lock:
+            def update(state: StateFile) -> JsonObject:
+                if name not in state.routines:
+                    raise ValueError(f"No Super Agents routine found for name {name}.")
+                removed = state.routines.pop(name)
+                return removed.to_json()
+
+            removed = update_state_file(self.state_file, update)
+        return {"deleted": True, "routine": removed}
+
+    async def routine_status_summary(self) -> JsonObject:
+        state = await self.read_state()
+        enabled = [routine for routine in state.routines.values() if routine.enabled]
+        return {
+            "count": len(state.routines),
+            "enabledCount": len(enabled),
+            "nextRuns": [
+                routine_next_run_summary(routine) for routine in sorted(enabled, key=routine_next_run_sort_key)[:5]
+            ],
+            "nativeSupport": False,
+            "scheduler": "super-agents-local-wrapper",
+        }
+
+    async def run_due_routines(self, name: str | None = None, force: bool = False) -> JsonObject:
+        candidates = await self.reserve_due_routines(name=name, force=force)
+        results = []
+        for routine in sorted(candidates, key=lambda item: item.name):
+            results.append(await self.run_routine(routine, force=force))
+        return {
+            "count": len(results),
+            "results": results,
+            "nativeSupport": False,
+            "scheduler": "super-agents-local-wrapper",
+        }
+
+    async def reserve_due_routines(self, name: str | None = None, force: bool = False) -> list[RoutineRecord]:
+        async with self._state_lock:
+            def update(state: StateFile) -> list[RoutineRecord]:
+                candidates = [
+                    routine
+                    for routine in state.routines.values()
+                    if (not name or routine.name == name) and (force or routine_is_due(routine))
+                ]
+                if name and not candidates and name not in state.routines:
+                    raise ValueError(f"No Super Agents routine found for name {name}.")
+                reserved: list[RoutineRecord] = []
+                now = iso_now()
+                for routine in candidates:
+                    run_date = routine_local_date(routine)
+                    merged = {
+                        **routine.to_json(),
+                        "lastRunDate": run_date,
+                        "lastStartedAt": now,
+                        "lastStatus": "starting",
+                        "lastError": None,
+                        "updatedAt": now,
+                    }
+                    reserved_routine = routine_from_patch(merged)
+                    state.routines[routine.name] = reserved_routine
+                    reserved.append(reserved_routine)
+                return reserved
+
+            return update_state_file(self.state_file, update)
+
+    async def run_routine(self, routine: RoutineRecord, *, force: bool = False) -> JsonObject:
+        if not routine.enabled and not force:
+            return {"name": routine.name, "skipped": True, "reason": "disabled"}
+        run_date = routine_local_date(routine)
+        try:
+            if routine.thread_id:
+                target = await self.resolve_queue_target(LabelQueryInput(thread_id=routine.thread_id, cwd=routine.cwd))
+                result = await self.start_or_queue_turn(target, routine_turn_input(routine))
+            elif routine.target_name:
+                target = await self.resolve_queue_target(
+                    LabelQueryInput(label=routine.target_name, cwd=routine.cwd, prefer="latest_any")
+                )
+                result = await self.start_or_queue_turn(target, routine_turn_input(routine))
+            else:
+                thread_result = await self.start_thread(
+                    without_none(
+                        {
+                            "name": routine.name,
+                            "cwd": routine.cwd,
+                            "developerInstructions": routine.developer_instructions,
+                        }
+                    )
+                )
+                thread_id = extract_thread_id(thread_result)
+                if not thread_id:
+                    raise RuntimeError(f"Could not start thread for routine {routine.name}.")
+                result = await self.start_turn(
+                    {**routine_turn_input(routine), "threadId": thread_id, "label": routine.name}
+                )
+            await self.record_routine_run(
+                routine.name,
+                {
+                    "lastRunDate": run_date,
+                    "lastStartedAt": iso_now(),
+                    "lastThreadId": get_string(result, "threadId"),
+                    "lastTurnId": get_string(result, "turnId"),
+                    "lastStatus": "queued" if result.get("queued") else "started",
+                    "lastError": None,
+                },
+            )
+            return {"name": routine.name, "ran": True, **result}
+        except Exception as exc:
+            await self.record_routine_run(
+                routine.name,
+                {
+                    "lastRunDate": run_date,
+                    "lastStartedAt": iso_now(),
+                    "lastStatus": "failed",
+                    "lastError": str(exc),
+                },
+            )
+            logger.exception("Failed to run Super Agents routine name=%s", routine.name)
+            return {"name": routine.name, "ran": False, "error": str(exc)}
+
+    async def record_routine_run(self, name: str, patch: JsonObject) -> None:
+        async with self._state_lock:
+            def update(state: StateFile) -> None:
+                routine = state.routines.get(name)
+                if routine is None:
+                    return
+                merged = {**routine.to_json(), **patch, "updatedAt": iso_now()}
+                state.routines[name] = routine_from_patch(merged)
+
+            update_state_file(self.state_file, update)

super_agents/app_client_sessions.py

@@ -0,0 +1,442 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import replace
+
+from .app_formatting import (
+    apply_field_selection,
+    preview_text,
+    text_preview,
+    without_none,
+)
+from .app_models import LabelQueryInput, PendingServerRequest, ResolvedSession, TurnState
+from .app_queue import (
+    complete_queued_turn,
+    queued_turn_summaries,
+    release_queued_turn,
+    reserve_next_queued_turn,
+)
+from .app_protocol import (
+    extract_thread_cwd,
+    extract_thread_id,
+    extract_thread_name,
+    extract_threads,
+    find_latest_turn,
+    is_active_status,
+    is_likely_stale,
+    normalize_thread_status,
+    to_tracked_turn_status,
+)
+from .app_sessions import merge_turns, required_label, session_from_patch, session_from_thread, session_recency
+from .app_time import age_ms, iso_from_thread_time, iso_now, parse_iso_ms, thread_recency, turn_key
+from .state import (
+    JsonObject,
+    SessionRecord,
+    StateFile,
+    StoredStatus,
+    get_string,
+    read_state_file_locked,
+    update_state_file,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SessionClientMixin:
+    async def filtered_sessions(self, input_data: LabelQueryInput) -> list[SessionRecord]:
+        state = await self.read_state()
+        sessions = list(state.sessions.values())
+        sessions = [session for session in sessions if not input_data.label or session.label == input_data.label]
+        sessions = [session for session in sessions if not input_data.cwd or session.cwd == input_data.cwd]
+        sessions = [session for session in sessions if not input_data.group or session.group == input_data.group]
+        sessions = [
+            session
+            for session in sessions
+            if not input_data.status or self.session_status(session) == input_data.status
+        ]
+        return sorted(sessions, key=session_recency, reverse=True)
+
+    async def resolve_session(self, label: str, input_data: LabelQueryInput) -> ResolvedSession:
+        prefer = input_data.prefer or "latest_active"
+        native_thread = await self.resolve_thread_name(label, input_data)
+        native_thread_id = extract_thread_id(native_thread)
+        if native_thread_id:
+            session = await self.get_session(native_thread_id) or session_from_thread(native_thread, label)
+            status = self.session_status(session)
+            if prefer == "latest_active" and not is_active_status(status):
+                raise ValueError(
+                    f"No active Super Agents session found for name {label}. Recent match: {json.dumps(self.session_view(session))}"
+                )
+            return ResolvedSession(
+                session=session,
+                turn_id=input_data.turn_id or session.active_turn_id or session.last_turn_id,
+                status=status,
+            )
+
+        candidates = await self.filtered_sessions(replace(input_data, label=label))
+        if not candidates:
+            raise ValueError(f"No Super Agents session found for name {label}.")
+        active_candidates = [session for session in candidates if is_active_status(self.session_status(session))]
+        scoped_candidates = candidates if prefer == "latest_any" else active_candidates
+        if not scoped_candidates:
+            recent = [self.session_view(session) for session in candidates[:5]]
+            raise ValueError(
+                f"No active Super Agents session found for name {label}. Recent inactive candidates: {json.dumps(recent)}"
+            )
+        first = scoped_candidates[0]
+        if len(scoped_candidates) > 1 and session_recency(first) == session_recency(scoped_candidates[1]):
+            candidates_json = json.dumps([self.session_view(session) for session in scoped_candidates[:5]])
+            raise ValueError(f"Ambiguous Super Agents name {label}. Candidates: {candidates_json}")
+        return ResolvedSession(
+            session=first,
+            turn_id=input_data.turn_id or first.active_turn_id or first.last_turn_id,
+            status=self.session_status(first),
+        )
+
+    async def resolve_queue_target(self, input_data: LabelQueryInput) -> ResolvedSession:
+        if input_data.thread_id:
+            session = await self.get_session(input_data.thread_id)
+            if session is None:
+                session = SessionRecord(
+                    label=input_data.label,
+                    thread_id=input_data.thread_id,
+                    cwd=input_data.cwd,
+                    updated_at=iso_now(),
+                )
+            return ResolvedSession(
+                session=session,
+                turn_id=session.active_turn_id or session.last_turn_id,
+                status=self.session_status(session),
+            )
+        return await self.resolve_session(
+            required_label(input_data),
+            replace(input_data, prefer=input_data.prefer or "latest_any"),
+        )
+
+    def queued_turn_summary(self) -> list[JsonObject]:
+        return queued_turn_summaries(self.queue_dir)
+
+    def schedule_queue_drain(self, thread_id: str) -> None:
+        existing = self._queue_tasks.get(thread_id)
+        if existing and not existing.done():
+            return
+        self._queue_tasks[thread_id] = asyncio.create_task(self._drain_queue(thread_id))
+
+    async def _drain_queue(self, thread_id: str) -> None:
+        await asyncio.sleep(0)
+        while True:
+            queued = reserve_next_queued_turn(
+                self.queue_dir,
+                thread_id,
+                lambda: self.thread_has_active_turn(thread_id),
+            )
+            if queued is None:
+                return
+            try:
+                await self.start_turn(
+                    {
+                        **queued.input_data,
+                        "threadId": thread_id,
+                        "label": queued.label,
+                        "agentName": queued.agent_name,
+                    }
+                )
+                complete_queued_turn(self.queue_dir, queued)
+            except Exception as exc:
+                release_queued_turn(self.queue_dir, queued, error=exc)
+                logger.exception("Failed to start queued Super Agents turn for thread_id=%s", thread_id)
+                return
+
+    def thread_has_active_turn(self, thread_id: str) -> bool:
+        for turn in self._turns.values():
+            if turn.thread_id == thread_id and self.tracked_turn_is_active(turn):
+                return True
+        session = self.session_from_memory(thread_id)
+        return bool(session and is_active_status(self.session_status(session)))
+
+    def tracked_turn_is_active(self, turn: TurnState) -> bool:
+        return is_active_status(turn.status) and not turn.finished_at
+
+    async def resolve_thread_name(self, name: str, input_data: LabelQueryInput) -> JsonObject:
+        try:
+            response = await self.list_threads(True, name, input_data.cwd, input_data.limit or 50)
+        except Exception:
+            return {}
+        threads = extract_threads(response)
+        matches = [thread for thread in threads if extract_thread_name(thread) == name]
+        if not matches:
+            return {}
+        matches.sort(key=thread_recency, reverse=True)
+        return matches[0]
+
+    async def recent_items(self, input_data: LabelQueryInput) -> list[JsonObject]:
+        if input_data.thread_id:
+            session = await self.get_session(input_data.thread_id)
+            if session:
+                return [self.session_view(session)]
+            return []
+        try:
+            response = await self.list_threads(
+                True,
+                input_data.label,
+                input_data.cwd,
+                input_data.limit or 50,
+            )
+        except Exception:
+            response = {}
+        threads = extract_threads(response)
+        if not threads:
+            sessions = await self.filtered_sessions(input_data)
+            return [self.session_view(session) for session in sessions]
+        items = [
+            self.thread_view(thread)
+            for thread in threads
+            if not input_data.label or extract_thread_name(thread) == input_data.label
+        ]
+        if input_data.status:
+            items = [item for item in items if item.get("status") == input_data.status]
+        return sorted(items, key=lambda item: parse_iso_ms(str(item.get("updatedAt") or "")), reverse=True)
+
+    def thread_view(self, thread: JsonObject) -> JsonObject:
+        thread_id = extract_thread_id(thread)
+        session = self.session_from_memory(thread_id) if thread_id else None
+        status = self.session_status(session) if session else normalize_thread_status(thread) or "unknown"
+        running_turn_id = (
+            session.active_turn_id or session.last_turn_id if session and is_active_status(status) else None
+        )
+        updated_at = iso_from_thread_time(thread)
+        last_event_at = session.last_event_at if session else None
+        return without_none(
+            {
+                "name": extract_thread_name(thread),
+                "agentName": session.agent_name if session else None,
+                "cwd": extract_thread_cwd(thread),
+                "threadId": thread_id,
+                "runningTurnId": running_turn_id,
+                "lastTurnId": session.last_turn_id if session else None,
+                "reasoningEffort": self.session_turn_reasoning_effort(
+                    session, running_turn_id or (session.last_turn_id if session else None)
+                ),
+                "status": status,
+                "ageMs": int(time.time() * 1000) - thread_recency(thread),
+                "updatedAt": updated_at,
+                "lastEventAt": last_event_at,
+                "lastEventAgeMs": age_ms(last_event_at),
+                "ageSinceUpdateMs": age_ms(updated_at),
+                "isLikelyStale": is_likely_stale(status, last_event_at or updated_at),
+                "preview": get_string(thread, "preview"),
+                "lastUsefulMessage": session.last_useful_message if session else None,
+                "pendingRequestCount": self.pending_request_count(thread_id, running_turn_id) if thread_id else None,
+            }
+        )
+
+    def session_view(self, session: SessionRecord) -> JsonObject:
+        status = self.session_status(session)
+        running_turn_id = session.active_turn_id or session.last_turn_id if is_active_status(status) else None
+        started_at = session.last_started_at or session.updated_at
+        return without_none(
+            {
+                "label": session.label,
+                "agentName": session.agent_name,
+                "group": session.group,
+                "cwd": session.cwd,
+                "threadId": session.thread_id,
+                "runningTurnId": running_turn_id,
+                "lastTurnId": session.last_turn_id,
+                "reasoningEffort": self.session_turn_reasoning_effort(session, running_turn_id or session.last_turn_id),
+                "status": status,
+                "ageMs": int(time.time() * 1000) - parse_iso_ms(started_at),
+                "updatedAt": session.updated_at,
+                "lastEventAt": session.last_event_at,
+                "lastEventAgeMs": age_ms(session.last_event_at),
+                "ageSinceUpdateMs": age_ms(session.updated_at),
+                "isLikelyStale": is_likely_stale(status, session.last_event_at or session.updated_at),
+                "lastUsefulMessage": session.last_useful_message,
+                "pendingRequestCount": self.pending_request_count(session.thread_id, running_turn_id),
+            }
+        )
+
+    def compact_agent_item(self, item: JsonObject, query: LabelQueryInput) -> JsonObject:
+        result = dict(item)
+        include_preview = query.include_preview if query.include_preview is not None else True
+        preview_length = query.preview_length or 160
+        if not include_preview:
+            result.pop("preview", None)
+            result.pop("lastUsefulMessage", None)
+        else:
+            if isinstance(result.get("preview"), str):
+                result["preview"] = preview_text(str(result["preview"]), preview_length)
+            if isinstance(result.get("lastUsefulMessage"), str):
+                result["lastUsefulMessage"] = preview_text(str(result["lastUsefulMessage"]), preview_length)
+        return apply_field_selection(result, query.fields)
+
+    def status_item(self, item: JsonObject) -> JsonObject:
+        return without_none(
+            {
+                "name": item.get("name") or item.get("label"),
+                "threadId": item.get("threadId"),
+                "turnId": item.get("runningTurnId") or item.get("lastTurnId"),
+                "reasoningEffort": item.get("reasoningEffort"),
+                "status": item.get("status"),
+                "lastEventAt": item.get("lastEventAt"),
+                "updatedAt": item.get("updatedAt"),
+                "lastEventAgeMs": item.get("lastEventAgeMs"),
+                "ageSinceUpdateMs": item.get("ageSinceUpdateMs"),
+                "isLikelyStale": item.get("isLikelyStale"),
+                "pendingRequestCount": item.get("pendingRequestCount"),
+                "cwd": item.get("cwd"),
+            }
+        )
+
+    def compact_tracked_turn(self, turn: TurnState | None) -> JsonObject:
+        if turn is None:
+            return {}
+        last_event_at = get_string(turn.events[-1], "receivedAt") if turn.events else turn.started_at
+        return without_none(
+            {
+                "threadId": turn.thread_id,
+                "turnId": turn.turn_id,
+                "status": turn.status,
+                "reasoningEffort": turn.reasoning_effort,
+                "startedAt": turn.started_at,
+                "finishedAt": turn.finished_at,
+                "lastEventAt": last_event_at,
+                "lastEventAgeMs": age_ms(last_event_at),
+                "isLikelyStale": is_likely_stale(turn.status, last_event_at),
+                "eventCount": len(turn.events),
+                "pendingRequestCount": len(turn.pending_requests),
+                "pendingRequestIds": [request.id for request in turn.pending_requests],
+            }
+        )
+
+    def session_turn_reasoning_effort(self, session: SessionRecord | None, turn_id: str | None) -> str | None:
+        if not session or not turn_id:
+            return None
+        runtime_turn = self._turns.get(turn_key(session.thread_id, turn_id))
+        if runtime_turn and runtime_turn.reasoning_effort:
+            return runtime_turn.reasoning_effort
+        turn_summary = (session.turns or {}).get(turn_id)
+        return turn_summary.reasoning_effort if turn_summary else None
+
+    def session_status(self, session: SessionRecord) -> StoredStatus:
+        turn_id = session.active_turn_id or session.last_turn_id
+        runtime_turn = self._turns.get(turn_key(session.thread_id, turn_id)) if turn_id else None
+        if runtime_turn:
+            if is_active_status(runtime_turn.status) and runtime_turn.finished_at:
+                if session.last_status and not is_active_status(session.last_status):
+                    return session.last_status
+                return "unknown"
+            return runtime_turn.status
+        return session.last_status or "unknown"
+
+    def session_from_memory(self, thread_id: str | None) -> SessionRecord | None:
+        if not thread_id:
+            return None
+        return read_state_file_locked(self.state_file).sessions.get(thread_id)
+
+    def pending_request_count(self, thread_id: str, turn_id: str | None = None) -> int:
+        return len(
+            [
+                request
+                for request in self._pending_server_requests.values()
+                if request.params.get("threadId") == thread_id
+                and (not turn_id or request.params.get("turnId") == turn_id)
+            ]
+        )
+
+    async def record_turn_progress(
+        self,
+        thread_id: str,
+        turn_id: str,
+        status: str,
+        persisted_turn: JsonObject | None,
+        pending_requests: list[PendingServerRequest],
+    ) -> None:
+        tracked_status: StoredStatus = "unknown" if status == "unknown" else to_tracked_turn_status(status)
+        tracked_turn = self._turns.get(turn_key(thread_id, turn_id))
+        state_session = await self.get_session(thread_id)
+        reasoning_effort = (
+            tracked_turn.reasoning_effort if tracked_turn else None
+        ) or self.session_turn_reasoning_effort(
+            state_session,
+            turn_id,
+        )
+        finished_at = (
+            (tracked_turn.finished_at if tracked_turn else None) or iso_now()
+            if tracked_status in {"completed", "failed", "cancelled"}
+            else None
+        )
+        await self.merge_session(
+            thread_id,
+            {
+                "threadId": thread_id,
+                "activeTurnId": turn_id if is_active_status(tracked_status) else None,
+                "lastTurnId": turn_id,
+                "lastStatus": tracked_status,
+                "lastFinishedAt": finished_at,
+                "lastUsefulMessage": text_preview(persisted_turn),
+                "turns": {
+                    turn_id: {
+                        "turnId": turn_id,
+                        "status": "running" if tracked_status == "unknown" else tracked_status,
+                        "reasoningEffort": reasoning_effort,
+                        "startedAt": tracked_turn.started_at if tracked_turn else iso_now(),
+                        "updatedAt": iso_now(),
+                        "finishedAt": finished_at,
+                        "lastUsefulMessage": text_preview(persisted_turn),
+                        "pendingRequestIds": [request.id for request in pending_requests],
+                        "eventCount": len(tracked_turn.events) if tracked_turn else 0,
+                    }
+                },
+            },
+            clear_fields=[] if is_active_status(tracked_status) else ["activeTurnId"],
+        )
+        if not is_active_status(tracked_status):
+            self.schedule_queue_drain(thread_id)
+
+    async def remember_session(self, thread_id: str, patch: JsonObject) -> None:
+        async with self._state_lock:
+            def update(state: StateFile) -> None:
+                now = iso_now()
+                state.sessions[thread_id] = session_from_patch(
+                    {"threadId": thread_id, "createdAt": now, **patch, "updatedAt": now}
+                )
+
+            update_state_file(self.state_file, update)
+
+    async def merge_session(
+        self,
+        thread_id: str,
+        patch: JsonObject,
+        clear_fields: list[str] | None = None,
+    ) -> None:
+        async with self._state_lock:
+            def update(state: StateFile) -> None:
+                now = iso_now()
+                current = state.sessions.get(thread_id) or SessionRecord(
+                    thread_id=thread_id, created_at=now, updated_at=now
+                )
+                merged_json = {**current.to_json(), **without_none(patch), "threadId": thread_id, "updatedAt": now}
+                merged_json["createdAt"] = current.created_at or now
+                merged_json["turns"] = merge_turns(current.turns, patch.get("turns"))
+                for field_name in clear_fields or []:
+                    merged_json.pop(field_name, None)
+                state.sessions[thread_id] = session_from_patch(merged_json)
+
+            update_state_file(self.state_file, update)
+
+    async def get_session(self, thread_id: str) -> SessionRecord | None:
+        state = await self.read_state()
+        return state.sessions.get(thread_id)
+
+    async def read_state(self) -> StateFile:
+        async with self._state_lock:
+            return read_state_file_locked(self.state_file)
+
+    async def latest_turn_id(self, thread_id: str) -> str | None:
+        thread = await self.read_thread(thread_id, True)
+        turn = find_latest_turn(thread, active_only=True) or find_latest_turn(thread, active_only=False)
+        return get_string(turn, "id") if turn else None