from __future__ import annotations """Conversation rules and staged transcript values, without runtime I/O.""" import uuid from collections.abc import Mapping, Sequence from dataclasses import dataclass from types import MappingProxyType from typing import Literal, get_args from free_claude_code.core.json_types import JsonObject from .models import ( ACTIVE_RUN_STATUSES, CodeCatalog, CodeConflictError, CodeItem, CodeMode, CodeNotFoundError, CodePrompt, CodeRun, CodeSession, CodeUnavailableError, CodeValidationError, HarnessEvent, ItemUpdate, NativeThread, NativeTurn, PromptRequest, RunStatus, now_ms, ) @dataclass(frozen=True, slots=True) class SessionProgress: """Candidate records saved together by the existing progress transaction.""" session: CodeSession run: CodeRun | None = None items: tuple[CodeItem, ...] = () prompts: tuple[CodePrompt, ...] = () class SessionState: def __init__( self, session: CodeSession, run: CodeRun | None, items: Sequence[CodeItem], prompts: Sequence[CodePrompt], runs: Sequence[CodeRun], *, sequence: int = 0, ) -> None: self._session = session self._run = run self._items = {item.id: item for item in items} self._prompts = {prompt.id: prompt for prompt in prompts} self._runs = {run.id: run for run in runs} self._sequence = max( sequence, max((item.sequence for item in items), default=0) ) self._dirty: set[str] = set() self._dirty_characters = 0 self._review_generations: dict[str, str] = {} @property def session(self) -> CodeSession: return self._session @property def run(self) -> CodeRun | None: return self._run @property def items(self) -> Mapping[str, CodeItem]: return MappingProxyType(self._items) @property def prompts(self) -> Mapping[str, CodePrompt]: return MappingProxyType(self._prompts) @property def runs(self) -> Mapping[str, CodeRun]: return MappingProxyType(self._runs) @property def busy(self) -> bool: return self._run is not None and self._run.status in ACTIVE_RUN_STATUSES @property def pending(self) -> bool: return any( prompt.status in {"pending", "answering"} for prompt in self._prompts.values() ) @property def pending_items(self) -> tuple[CodeItem, ...]: return tuple(self._items[item_id] for item_id in self._dirty) @property def dirty_characters(self) -> int: return self._dirty_characters def active_review_ids(self, generation: str | None) -> tuple[str, ...]: return tuple( item_id for item_id, observed in self._review_generations.items() if observed == generation ) def clear_review_liveness(self) -> bool: changed = bool(self._review_generations) self._review_generations.clear() return changed def accept_session(self, session: CodeSession) -> None: self._session = session def accept_admission( self, session: CodeSession, run: CodeRun, item: CodeItem ) -> None: self._session, self._run = session, run self._runs[run.id] = run self._items[item.id] = item self._sequence = item.sequence def accept_prompt(self, prompt: CodePrompt) -> None: self._prompts[prompt.id] = prompt def apply_progress(self, progress: SessionProgress) -> None: """Install acknowledged records; pending transcript writes stay explicit.""" self._session = progress.session if (run := progress.run) is not None: self._runs[run.id] = run if self._run is not None and self._run.id == run.id: self._run = run for item in progress.items: self._items[item.id] = item self._sequence = max(self._sequence, item.sequence) self._prompts.update((prompt.id, prompt) for prompt in progress.prompts) def acknowledge_flush(self) -> None: """The caller holds serialization through saving the complete pending set.""" self._dirty.clear() self._dirty_characters = 0 def remember_items( self, items: Sequence[CodeItem], runs: Sequence[CodeRun] ) -> None: """Load durable identities needed by one serialized operation.""" for item in items: self._items.setdefault(item.id, item) for run in runs: self._runs.setdefault(run.id, run) def prune(self) -> None: """Release acknowledged history after its events have been published.""" self._prompts = { key: prompt for key, prompt in self._prompts.items() if prompt.status in {"pending", "answering"} } pinned = self._dirty | self._prompts.keys() | self._review_generations.keys() self._items = { key: item for key, item in self._items.items() if key in pinned or (self.busy and self._run and item.run_id == self._run.id) } run_ids = {item.run_id for item in self._items.values()} if self._run is not None: run_ids.add(self._run.id) self._runs = {key: run for key, run in self._runs.items() if key in run_ids} def discard_deleted_history(self) -> None: self._items.clear() self._prompts.clear() self._run = None self._runs.clear() def check_revision(self, revision: int) -> None: if self._session.revision != revision: raise CodeConflictError( "This session changed. Refresh its state and try again." ) def check_editable(self, revision: int) -> None: if self._session.status != "ready": raise CodeConflictError( "This session changed. Refresh its state and try again." ) self.check_revision(revision) @staticmethod def validate_settings_fields(changes: JsonObject) -> None: if not changes or changes.keys() - { "title", "model", "reasoning_effort", "mode", }: raise CodeValidationError( "Choose a title, model, effort or mode to update." ) def settings_updates(self, changes: JsonObject) -> dict[str, object]: """Validate local rules before the application obtains model inventory.""" updates: dict[str, object] = dict(changes) if "title" in changes: title = changes["title"] if not isinstance(title, str) or not title.strip() or len(title) > 200: raise CodeValidationError("Enter a title of at most 200 characters.") updates.update(title=title.strip(), auto_title=False) if changes.keys() & {"model", "reasoning_effort", "mode"} and ( self.busy or self.pending ): raise CodeConflictError( "Finish this turn and its prompts before changing settings." ) if "mode" in changes and changes["mode"] not in get_args(CodeMode.__value__): raise CodeValidationError("Choose an available permission mode.") return updates def prepare_settings( self, updates: dict[str, object], catalog: CodeCatalog | None ) -> CodeSession: updates = dict(updates) if updates.keys() & {"model", "reasoning_effort"}: assert catalog is not None model = updates.get("model", self._session.model) entry = next((entry for entry in catalog.models if entry.id == model), None) if entry is None: raise CodeValidationError( "This model is unavailable. Choose another model." ) effort = updates.get("reasoning_effort", self._session.reasoning_effort) if ( "reasoning_effort" not in updates and model != self._session.model and effort not in entry.reasoning_efforts ): effort = None if effort is not None and effort not in entry.reasoning_efforts: raise CodeValidationError( "This effort is unavailable. Choose another effort." ) updates.update(model=model, reasoning_effort=effort) return _revision(self._session, **updates) def check_receipt(self, previous: CodeRun, text: str) -> None: if previous.session_id != self._session.id or previous.text != text: raise CodeConflictError( "This Send ID was already used for a different message." ) def check_can_send(self) -> None: if self.busy or self.pending: raise CodeConflictError("This session is busy. Your draft has been kept.") def prepare_admission( self, operation_id: str, text: str, model: str, reasoning_effort: str | None, mode: CodeMode, ) -> tuple[CodeSession, CodeRun, CodeItem]: self.check_can_send() run = CodeRun( id=operation_id, session_id=self._session.id, text=text, model=model, reasoning_effort=reasoning_effort, mode=mode, ) title = ( " ".join(text.split())[:80] if self._session.auto_title else self._session.title ) session = _revision(self._session, title=title, auto_title=False, error=None) item = CodeItem( id=operation_id, session_id=self._session.id, sequence=self._sequence + 1, run_id=operation_id, kind="user", text=text, complete=True, ) return session, run, item def active_run(self, run_id: str) -> CodeRun | None: return self._run if self._run and self._run.id == run_id and self.busy else None def request_stop(self) -> SessionProgress | None: run = self._run if run is None or run.stop_requested: return None return SessionProgress( self._session, run=run.model_copy(update={"stop_requested": True, "status": "stopping"}), ) def attach_thread( self, thread_id: str, permission_defaults: JsonObject | None = None ) -> SessionProgress: return SessionProgress( self._session.model_copy( update={ "native_thread_id": thread_id, "native_permission_defaults": self._session.native_permission_defaults if self._session.native_permission_defaults is not None else permission_defaults, } ) ) def prepare_submission(self) -> SessionProgress: assert self._run is not None if self._session.native_permission_defaults is None: raise CodeUnavailableError( "The harness did not return its permission settings. Your input was not sent." ) return SessionProgress( self._session.model_copy(update={"native_may_have_input": True}), run=self._run.model_copy(update={"submission_started": True}), ) def bind_turn(self, turn_id: str) -> SessionProgress: run = self._run assert run is not None if run.native_turn_id not in {None, turn_id}: raise CodeUnavailableError("Codex returned a different turn identity.") return SessionProgress( self._session, run=run.model_copy( update={ "native_turn_id": turn_id, "status": "stopping" if run.stop_requested else "running", } ), ) def accepts_event(self, event: HarnessEvent) -> bool: return self._session.status == "ready" and event.thread_id in { None, self._session.native_thread_id, } def matches_turn(self, event: HarnessEvent, *, known_turn: bool) -> bool: run = self._run return bool( run is not None and self.busy and run.submission_started and event.turn_id is not None and ( run.native_turn_id == event.turn_id or ( run.native_turn_id is None and event.kind == "turn_started" and not known_turn ) ) ) def context_usage(self, used_tokens: int | None) -> SessionProgress | None: if used_tokens is None or used_tokens == self._session.context_used_tokens: return None return SessionProgress( self._session.model_copy(update={"context_used_tokens": used_tokens}) ) def match_history( self, native: NativeThread, runs: Sequence[CodeRun] ) -> tuple[tuple[NativeTurn, CodeRun], ...]: saved = {run.id: run for run in runs} mapped: dict[str, CodeRun] = {} for turn in native.turns: identities = { item.client_id for item in turn.items if item.kind == "user" and item.client_id } candidates = [ run for run in saved.values() if run.native_turn_id == turn.id or run.id in identities ] if len(candidates) > 1 or any( identity not in saved for identity in identities ): raise CodeUnavailableError( "Codex history contains conflicting turn identities. Saved history was retained." ) if candidates: run = candidates[0] if ( not run.submission_started or run.native_turn_id not in {None, turn.id} or run.id in {value.id for value in mapped.values()} ): raise CodeUnavailableError( "Codex history could not be matched to its saved turns." ) mapped[turn.id] = run unmatched = [turn for turn in native.turns if turn.id not in mapped] pending = [ run for run in saved.values() if run.submission_started and run.native_turn_id is None and run.id not in {value.id for value in mapped.values()} ] if unmatched: if len(unmatched) != 1 or len(pending) != 1: raise CodeUnavailableError( "Codex history could not be matched to its saved turns. No input was resent." ) mapped[unmatched[0].id] = pending[0] # Recovery fills content and diagnostics, preserving outcomes already settled # by restart or connection loss. return tuple( ( turn, mapped[turn.id].model_copy( update={ "native_turn_id": turn.id, "error": mapped[turn.id].error or turn.error, "error_details": mapped[turn.id].error_details or turn.error_details, } ), ) for turn in native.turns ) def native_item(self, update: ItemUpdate) -> CodeItem | None: return next( ( item for item in self._items.values() if item.native_turn_id == update.turn_id and item.native_item_id == update.item_id ), None, ) def stage_item( self, update: ItemUpdate, run: CodeRun, *, historical: bool = False ) -> tuple[CodeItem, bool]: existing = self.native_item(update) if existing is None and update.kind == "user": if update.client_id is not None and update.client_id != run.id: raise CodeUnavailableError( "Codex returned a different message identity." ) existing = self._items.get(run.id) if existing is not None and existing.run_id != run.id: raise CodeUnavailableError( "Codex returned output belonging to another turn." ) if existing is None: self._sequence += 1 preserve = bool(historical and existing and existing.complete) raw = _merge_source(existing.raw if existing else {}, update.raw, preserve) text, detail = update.text, update.detail if historical and existing: text = (existing.text or text) if preserve else (text or existing.text) detail = ( (existing.detail or detail) if preserve else (detail or existing.detail) ) item = CodeItem( id=existing.id if existing else str(uuid.uuid4()), session_id=self._session.id, sequence=existing.sequence if existing else self._sequence, run_id=run.id, native_turn_id=update.turn_id, native_item_id=update.item_id, kind=update.kind, title=update.title or (existing.title if existing else ""), text=text, detail=detail, raw=raw, complete=update.complete or bool(existing and existing.complete), ) if item == existing: return existing, False self._items[item.id] = item self._dirty.add(item.id) self._dirty_characters += abs( len(item.text) - (len(existing.text) if existing else 0) ) + abs(len(item.detail) - (len(existing.detail) if existing else 0)) return item, True def stage_review( self, update: ItemUpdate, generation: str ) -> tuple[CodeItem | None, bool]: if self._run is None: return None, False existing = self.native_item(update) if existing is not None and existing.complete and not update.complete: return None, False target = self._runs[existing.run_id] if existing else self._run item, changed = self.stage_item(update, target) previous = self._review_generations.get(item.id) if item.complete: self._review_generations.pop(item.id, None) else: self._review_generations[item.id] = generation if previous != self._review_generations.get(item.id): # The saved row is reannounced when its connection liveness changes. self._dirty.add(item.id) return item, changed def has_prompt(self, request: PromptRequest, generation: str) -> bool: return any( prompt.generation == generation and prompt.request_id == request.request_id for prompt in self._prompts.values() ) def prepare_prompt( self, request: PromptRequest, generation: str ) -> SessionProgress: if self._run is None: raise CodeUnavailableError("Codex returned a prompt without a saved turn.") prompt = CodePrompt( id=str(uuid.uuid4()), session_id=self._session.id, generation=generation, request_id=request.request_id, native_turn_id=request.turn_id, native_item_id=request.item_id, kind=request.kind, form=request.form, raw=request.raw, ) item = CodeItem( id=prompt.id, session_id=self._session.id, run_id=self._run.id, sequence=self._sequence + 1, kind="prompt", complete=True, ) return SessionProgress(self._session, items=(item,), prompts=(prompt,)) def answerable_prompt( self, prompt_id: str, response_id: str, generation: str | None ) -> CodePrompt: prompt = self._prompts.get(prompt_id) if prompt is None: raise CodeNotFoundError("This prompt no longer exists.") if prompt.response_id == response_id: return prompt if prompt.status != "pending" or prompt.generation != generation: raise CodeConflictError( "This prompt was already answered or is no longer active." ) return prompt def pending_answer( self, prompt_id: str, generation: str | None ) -> CodePrompt | None: current = self._prompts.get(prompt_id) return ( current if current is not None and current.status == "answering" and current.generation == generation else None ) def resolve_answer( self, prompt_id: str, generation: str | None ) -> CodePrompt | None: current = self.pending_answer(prompt_id, generation) return current.model_copy(update={"status": "resolved"}) if current else None def expire_answer(self, prompt_id: str) -> CodePrompt | None: current = self._prompts.get(prompt_id) return ( current.model_copy(update={"status": "expired"}) if current and current.status == "answering" else None ) def resolve_request( self, request_id: str | int | None, generation: str ) -> tuple[CodePrompt, ...]: return tuple( prompt.model_copy(update={"status": "resolved"}) for prompt in self._prompts.values() if prompt.generation == generation and prompt.request_id == request_id and prompt.status in {"pending", "answering"} ) def expire_prompts(self) -> tuple[CodePrompt, ...]: return tuple( prompt.model_copy(update={"status": "expired"}) for prompt in self._prompts.values() if prompt.status in {"pending", "answering"} ) def prepare_notice(self, event: HarnessEvent) -> CodeItem: assert self._run is not None message = event.message or "Codex reported an error." if event.kind == "error" and event.will_retry: message = f"Retrying… {message}" return CodeItem( id=str(uuid.uuid4()), session_id=self._session.id, sequence=self._sequence + 1, run_id=self._run.id, kind="notice", title="Notice", text=message, complete=True, raw=event.raw, ) def prepare_finish( self, status: RunStatus, message: str | None = None, error_details: JsonObject | None = None, ) -> SessionProgress | None: if self._run is None or not self.busy: return None run = self._run.model_copy( update={ "status": status, "error": message, "error_details": error_details or {}, "finished_at": now_ms(), } ) prompts = tuple( prompt.model_copy(update={"status": "expired"}) for prompt in self._prompts.values() if prompt.status in {"pending", "answering"} and prompt.native_turn_id is not None and prompt.native_turn_id == run.native_turn_id ) return SessionProgress( _revision(self._session, error=None), run=run, items=self.pending_items, prompts=prompts, ) def prepare_delete(self) -> SessionProgress: if self.busy or self.pending: raise CodeConflictError( "Stop the session and finish its prompts before deleting it." ) return SessionProgress(_revision(self._session, status="deleting", error=None)) def deletion_failed( self, status: Literal["ready", "delete_uncertain"], message: str ) -> SessionProgress: return SessionProgress(_revision(self._session, status=status, error=message)) def _merge_source( previous: JsonObject, current: JsonObject, preserve: bool ) -> JsonObject: merged = dict(previous) for key, value in current.items(): existing = merged.get(key) if isinstance(existing, dict) and isinstance(value, dict): merged[key] = _merge_source(existing, value, preserve) elif not preserve or existing in (None, "", [], {}): merged[key] = value return merged def _revision(session: CodeSession, **updates: object) -> CodeSession: return session.model_copy( update={"revision": session.revision + 1, "updated_at": now_ms(), **updates} )