| 1 | # state_snapshot.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `state_snapshot.py` helper module. |
| 6 | - This module builds and validates typed WebUI state snapshots. |
| 7 | - Keep this file-level DOX profile synchronized with `state_snapshot.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `state_snapshot.py` owns the runtime implementation. |
| 12 | - `state_snapshot.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Classes: |
| 14 | - `SnapshotV1` (`TypedDict`) |
| 15 | - `StateRequestV1` (no explicit base class) |
| 16 | - `StateRequestValidationError` (`ValueError`) |
| 17 | - Top-level functions: |
| 18 | - `_annotation_to_isinstance_types(annotation: Any) -> tuple[type, ...]`: Convert type annotation to tuple suitable for isinstance(). |
| 19 | - `_build_schema_from_typeddict(td: type) -> dict[str, tuple[type, ...]]`: Extract field names and isinstance-compatible types from TypedDict. |
| 20 | - `validate_snapshot_schema_v1(snapshot: Mapping[str, Any]) -> None` |
| 21 | - `_coerce_non_negative_int(value: Any, default: int=...) -> int` |
| 22 | - `_get_agent_profile_labels() -> dict[str, str]` |
| 23 | - `_apply_agent_profile_metadata(context_data: dict[str, Any], ctx: AgentContext, labels: dict[str, str]) -> None` |
| 24 | - `_prune_missing_saved_contexts() -> None` |
| 25 | - `parse_state_request_payload(payload: Mapping[str, Any]) -> StateRequestV1` |
| 26 | - `_coerce_state_request_inputs(context: Any, log_from: Any, notifications_from: Any, timezone: Any) -> StateRequestV1` |
| 27 | - `advance_state_request_after_snapshot(request: StateRequestV1, snapshot: Mapping[str, Any]) -> StateRequestV1` |
| 28 | - `async build_snapshot_from_request(request: StateRequestV1, include_collections: bool=...) -> SnapshotV1`: Build a poll-shaped snapshot for both /poll and state_push. |
| 29 | - `_notify_timezone_changed(previous_timezone: str, current_timezone: str) -> None` |
| 30 | - `async build_snapshot(context: str | None, log_from: int, notifications_from: int, timezone: str | None) -> SnapshotV1` |
| 31 | - Notable constants/configuration names: `_SNAPSHOT_V1_SCHEMA`, `SNAPSHOT_SCHEMA_V1_KEYS`. |
| 32 | |
| 33 | ## Runtime Contracts |
| 34 | |
| 35 | - Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. |
| 36 | - Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. |
| 37 | - Observed side-effect areas: filesystem reads, plugin state, settings/state persistence, secret handling, scheduler state, in-memory context removal. |
| 38 | - Imported dependency areas include: `__future__`, `agent`, `dataclasses`, `helpers.dotenv`, `helpers.localization`, `helpers.persist_chat`, `helpers.task_scheduler`, `pytz`, `types`, `typing`. |
| 39 | |
| 40 | ## Key Concepts |
| 41 | |
| 42 | - Important called helpers/classes observed in the source: `dataclass`, `_build_schema_from_typeddict`, `get_origin`, `timezone.strip`, `StateRequestV1`, `localization.get_timezone`, `localization.set_timezone`, `ctxid.strip`, `_coerce_non_negative_int`, `AgentContext.get_notification_manager`, `notification_manager.output`, `_get_agent_profile_labels`, `ctxs.sort`, `tasks.sort`, `validate_snapshot_schema_v1`, `_coerce_state_request_inputs`, `super.__init__`, `get_args`, `_annotation_to_isinstance_types`, `TypeError`. |
| 43 | - Snapshot building prunes non-running in-memory contexts that were previously saved but no longer have a `chat.json`, preventing stale sidebar rows after chat files are deleted outside `/chat_remove`. |
| 44 | - Notification payloads use the manager's matching GUID and cursor from the same atomic read, preventing a concurrent notification from being skipped by the WebUI. |
| 45 | - `StateRequestV1.collections_delta` is an optional, false-by-default capability. Negotiated state pushes may use `null` for both `contexts` and `tasks` when those collections are unchanged; HTTP polling and legacy WebSocket clients always receive full lists. |
| 46 | - Keep request/response, tool, or helper semantics documented here at the same time as source changes. |
| 47 | |
| 48 | ## Work Guidance |
| 49 | |
| 50 | - Preserve public helper APIs used by core code and plugins unless every caller is updated. |
| 51 | - Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. |
| 52 | - Prefer adding cohesive helper functions here only when behavior is reused across modules. |
| 53 | |
| 54 | ## Verification |
| 55 | |
| 56 | - Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. |
| 57 | - Related tests observed by source search: |
| 58 | - `tests/test_multi_tab_isolation.py` |
| 59 | - `tests/test_snapshot_parity.py` |
| 60 | - `tests/test_snapshot_schema_v1.py` |
| 61 | - `tests/test_state_monitor.py` |
| 62 | - `tests/test_state_sync_handler.py` |
| 63 | - `tests/test_state_sync_welcome_screen.py` |
| 64 | |
| 65 | ## Child DOX Index |
| 66 | |
| 67 | No child DOX files. |