@baimingtao/lbs-agent 1.0.0

package/runtime/memory/session/session_store.py

@@ -0,0 +1,1118 @@
+"""lbs 运行时执行的持久化会话/工作器存储。
+
+每次 run 完成时把结果写成 <project_root>/sessions 下的一个 JSON 文件。
+CLI 可以读取真实执行结果，而不是占位输出。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+import json
+import os
+import re
+import threading
+
+from runtime.memory.task_contracts import TaskRecord, TaskStatus
+from runtime.memory.session.identity import ConversationIdentity
+from runtime.orchestration.loop.run_trace import run_trace_to_dicts
+from runtime.orchestration.runtime.events import runtime_events_to_dicts
+
+
+@dataclass
+class SessionRecord:
+    session_id: str
+    path: str
+    created_at: str
+    agent_name: str
+    task: str
+    status: str
+    success: bool
+    iterations: int
+    total_tool_calls: int
+    duration_seconds: float
+    summary: str
+    updated_at: str = ""
+
+
+class SessionStore:
+    def __init__(self, project_root: str, *, session_dir: str | Path | None = None):
+        self.project_root = Path(project_root)
+        self.session_dir = Path(session_dir) if session_dir is not None else self.project_root / "sessions"
+        self.session_dir.mkdir(parents=True, exist_ok=True)
+        self._write_lock = threading.RLock()
+
+    def _slug(self, text: str, max_len: int = 40) -> str:
+        text = re.sub(r'[\/:*?"<>|]+', '-', text.strip())
+        text = re.sub(r'\s+', '-', text)
+        text = re.sub(r'-+', '-', text)
+        return (text or 'task')[:max_len].strip('-') or 'task'
+
+    def _session_id(self, agent_name: str, task_id: str = '') -> str:
+        ts = datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')
+        suffix = f'-{self._slug(task_id, max_len=32)}' if task_id else ''
+        return f'{ts}-{self._slug(agent_name)}{suffix}'
+    def _now(self) -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+    def _atomic_write(self, path: Path, payload: dict[str, Any]) -> None:
+        """原子写入：先写 .tmp + os.replace + RLock 保护。"""
+        with self._write_lock:
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+            os.replace(tmp, path)
+
+    def _session_path(self, session_id: str) -> Path | None:
+        """Resolve a session file without allowing path traversal."""
+        if not session_id or Path(session_id).name != session_id or any(sep in session_id for sep in ("/", "\\")):
+            return None
+        path = self.session_dir / f"{session_id}.json"
+        return path if path.is_file() else None
+
+    def _find_path_by_session_id(self, session_id: str) -> Path | None:
+        return self._session_path(session_id)
+
+    def _find_path_by_task_id(self, task_id: str) -> Path | None:
+        if not task_id or not self.session_dir.exists():
+            return None
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if payload and payload.get('task_id') == task_id:
+                return path
+        return None
+
+    def create_task_record(
+        self,
+        *,
+        agent_name: str,
+        task: str,
+        task_id: str = '',
+        parent_task_id: str = '',
+        status: str = 'pending',
+        context: str = '',
+        depends_on: list[str] | None = None,
+        config: dict[str, Any] | None = None,
+        rerun_of: str = '',
+        session_id: str = '',
+        conversation_id: str = '',
+        run_id: str = '',
+    ) -> Path:
+        """在执行开始前创建一个可恢复的任务记录。
+
+        即使 worker 在产出 AgentResult 之前崩溃，也能给 orchestration
+        一个可恢复的 DAG 节点。
+
+        session_id: 外部传入的会话 ID（如 UI 创建的会话）。
+        如果提供，所有持久化数据（messages/steps/trace）都落到同一个文件，
+        下次 load_session_messages 可以读到完整历史。
+        """
+        if not task_id:
+            task_id = f'task-{datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")}'
+        existing = self._find_path_by_task_id(task_id)
+        if existing:
+            return existing
+        identity = ConversationIdentity.create(
+            conversation_id=conversation_id or task_id,
+            session_id=session_id,
+            run_id=run_id,
+            task_id=task_id,
+        )
+        resolved_session_id = identity.session_id
+        now = self._now()
+        existing_payload = self._load_path(self.session_dir / f'{resolved_session_id}.json')
+        if existing_payload is not None and session_id:
+            payload = {
+                **existing_payload,
+                'updated_at': now,
+                'agent_name': agent_name,
+                'task': task,
+                'context': context,
+                'task_id': task_id,
+                'parent_task_id': parent_task_id,
+                'depends_on': list(depends_on or []),
+                'rerun_of': rerun_of,
+                'conversation_id': identity.conversation_id,
+                'run_id': identity.run_id,
+                'status': status,
+                'success': status == 'done',
+                'config': config or {},
+                'started_at': now if status == 'running' else existing_payload.get('started_at', ''),
+                'finished_at': now if status in {'done', 'error', 'timeout', 'cancelled'} else '',
+                'lifecycle': list(existing_payload.get('lifecycle') or []) + [{'at': now, 'status': status, 'event': 'created'}],
+            }
+        else:
+            payload = {
+            'session_id': resolved_session_id,
+            'created_at': now,
+            'updated_at': now,
+            'agent_name': agent_name,
+            'task': task,
+            'context': context,
+            'task_id': task_id,
+            'parent_task_id': parent_task_id,
+            'depends_on': list(depends_on or []),
+            'rerun_of': rerun_of,
+            # 四层 identity：conversation 不再被 task 覆盖
+            'conversation_id': identity.conversation_id,
+            'run_id': identity.run_id,
+            'status': status,
+            'success': status == 'done',
+            'iterations': 0,
+            'total_tool_calls': 0,
+            'duration_seconds': 0.0,
+            'error': '',
+            'content': '',
+            'steps': [],
+            'model_attempts': [],
+            'messages': [],
+            'conversation_messages': [],
+            'config': config or {},
+            'started_at': now if status == 'running' else '',
+            'finished_at': now if status in {'done', 'error', 'timeout', 'cancelled'} else '',
+            'lifecycle': [{'at': now, 'status': status, 'event': 'created'}],
+            'run_trace': [],
+            }
+        path = self.session_dir / f'{resolved_session_id}.json'
+        self._atomic_write(path, payload)
+        return path
+
+    def append_run_trace_event(self, *, task_id: str, event) -> Path | None:
+        """Append one phase-level RunTrace event to an existing task record.
+
+        P1-5: 使用 update_task 原子操作，避免并发覆盖。
+        """
+        event_payload = event.to_dict() if hasattr(event, 'to_dict') else dict(event)
+        def _mutate(payload):
+            run_trace = payload.setdefault('run_trace', [])
+            run_trace.append(event_payload)
+            return payload
+        result = self.atomic_update_task(task_id, _mutate)
+        if result is None:
+            return None
+        path = self._find_path_by_task_id(task_id)
+        return path
+
+    def atomic_update_task(self, task_id: str, mutator=None) -> dict[str, Any] | None:
+        """原子 read-modify-write：在整个操作期间持有 _write_lock。
+
+        P1-5: 所有需要 read → mutate → write 的操作都应通过此方法，
+        避免两个线程同时读到旧版本然后互相覆盖。
+
+        Args:
+            task_id: 任务 ID
+            mutator: 接受 payload dict，返回修改后的 dict（或 None 表示不修改）
+        Returns:
+            修改后的 payload，或 None 如果任务不存在
+        """
+        path = self._find_path_by_task_id(task_id)
+        if path is None:
+            return None
+        with self._write_lock:
+            payload = self._load_path(path) or {}
+            if mutator is not None:
+                try:
+                    mutated = mutator(payload)
+                    if mutated is not None:
+                        payload = mutated
+                except Exception:
+                    return payload
+            payload['updated_at'] = self._now()
+            try:
+                self._atomic_write(path, payload)
+            except Exception:
+                return None
+            return payload
+
+
+    def find_conversation_runs(self, conversation_id: str) -> list[dict[str, Any]]:
+        """查找属于同一对话的所有运行记录（P2-2）。
+
+        conversation_id 跨多次 run 保持不变，
+        每次 run 对应一个独立的 session_id / task_id。
+        """
+        if not conversation_id or not self.session_dir.exists():
+            return []
+        runs = []
+        for path in sorted(self.session_dir.glob('*.json'), reverse=True):
+            payload = self._load_path(path)
+            if not payload:
+                continue
+            if payload.get('conversation_id', '') == conversation_id:
+                runs.append({
+                    'session_id': payload.get('session_id', path.stem),
+                    'task_id': payload.get('task_id', ''),
+                    'status': payload.get('status', ''),
+                    'created_at': payload.get('created_at', ''),
+                    'success': payload.get('success', False),
+                })
+        return runs
+
+    def load_task(self, task_id: str) -> dict[str, Any] | None:
+        path = self._find_path_by_task_id(task_id)
+        return self._load_path(path) if path else None
+
+    def update_task_status(self, task_id: str, status: str, *, error: str = '', event: str = 'status') -> Path | None:
+        path = self._find_path_by_task_id(task_id)
+        if not path:
+            return None
+        payload = self._load_path(path) or {}
+        now = self._now()
+        payload['status'] = status
+        payload['updated_at'] = now
+        if error:
+            payload['error'] = error
+        if status == 'running' and not payload.get('started_at'):
+            payload['started_at'] = now
+        if status in {'done', 'error', 'timeout', 'cancelled'}:
+            payload['finished_at'] = now
+            payload['success'] = status == 'done' and not bool(payload.get('error'))
+        lifecycle = payload.setdefault('lifecycle', [])
+        lifecycle.append({'at': now, 'status': status, 'event': event})
+        self._atomic_write(path, payload)
+        return path
+
+    def heartbeat(self, task_id: str) -> Path | None:
+        path = self._find_path_by_task_id(task_id)
+        if not path:
+            return None
+        payload = self._load_path(path) or {}
+        payload['heartbeat_at'] = self._now()
+        payload['updated_at'] = payload['heartbeat_at']
+        self._atomic_write(path, payload)
+        return path
+
+    def prepare_rerun(self, task_id: str) -> Path:
+        payload = self.load_task(task_id)
+        if not payload:
+            raise ValueError(f'task not found: {task_id}')
+        suffix = datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')
+        return self.create_task_record(
+            agent_name=payload.get('agent_name', ''),
+            task=payload.get('task', ''),
+            task_id=f'{task_id}-rerun-{suffix}',
+            parent_task_id=payload.get('parent_task_id', ''),
+            status='pending',
+            context=payload.get('context', ''),
+            depends_on=payload.get('depends_on', []) or [],
+            config=payload.get('config', {}) or {},
+            rerun_of=task_id,
+        )
+
+    def child_tasks(self, parent_task_id: str) -> list[dict[str, Any]]:
+        children: list[dict[str, Any]] = []
+        if not parent_task_id or not self.session_dir.exists():
+            return children
+        for path in sorted(self.session_dir.glob('*.json')):
+            payload = self._load_path(path)
+            if payload and payload.get('parent_task_id') == parent_task_id:
+                children.append(payload)
+        return children
+
+    def all_task_records(self) -> list[dict[str, Any]]:
+        records: list[dict[str, Any]] = []
+        if not self.session_dir.exists():
+            return records
+        for path in sorted(self.session_dir.glob('*.json')):
+            payload = self._load_path(path)
+            if payload and payload.get('task_id'):
+                records.append(payload)
+        return records
+
+    def ready_task_records(self) -> list[dict[str, Any]]:
+        """Return pending tasks whose dependencies have all completed successfully."""
+        records = self.all_task_records()
+        by_task_id = {record.get('task_id'): record for record in records if record.get('task_id')}
+        ready: list[dict[str, Any]] = []
+        for record in records:
+            if record.get('status') != 'pending':
+                continue
+            depends_on = record.get('depends_on', []) or []
+            if all((by_task_id.get(dep) or {}).get('status') == 'done' for dep in depends_on):
+                ready.append(record)
+        return ready
+
+    def blocked_task_records(self) -> list[dict[str, Any]]:
+        records = self.all_task_records()
+        by_task_id = {record.get('task_id'): record for record in records if record.get('task_id')}
+        blocked: list[dict[str, Any]] = []
+        for record in records:
+            if record.get('status') != 'pending':
+                continue
+            depends_on = record.get('depends_on', []) or []
+            if any((by_task_id.get(dep) or {}).get('status') != 'done' for dep in depends_on):
+                blocked.append(record)
+        return blocked
+
+    def mark_stale_running_tasks(self, max_age_seconds: float) -> list[dict[str, Any]]:
+        """Mark running tasks whose heartbeat is older than max_age_seconds as timeout."""
+        now = datetime.now(timezone.utc)
+        stale: list[dict[str, Any]] = []
+        for record in self.all_task_records():
+            if record.get('status') != 'running':
+                continue
+            heartbeat = record.get('heartbeat_at') or record.get('updated_at') or record.get('started_at') or record.get('created_at')
+            try:
+                heartbeat_dt = datetime.fromisoformat(str(heartbeat).replace('Z', '+00:00'))
+                if heartbeat_dt.tzinfo is None:
+                    heartbeat_dt = heartbeat_dt.replace(tzinfo=timezone.utc)
+            except Exception:
+                heartbeat_dt = datetime.fromtimestamp(0, tz=timezone.utc)
+            age = (now - heartbeat_dt).total_seconds()
+            if age > max_age_seconds:
+                task_id = record.get('task_id', '')
+                self.update_task_status(
+                    task_id,
+                    'timeout',
+                    error=f'stale heartbeat: age_seconds={int(age)} > max_age_seconds={int(max_age_seconds)}',
+                    event='recovery_timeout',
+                )
+                updated = self.load_task(task_id) or record
+                stale.append(updated)
+        return stale
+
+
+
+    def _merge_compression_history(self, existing: dict | None, new_results: list | None) -> list[dict]:
+        """合并历史压缩记录。"""
+        history = list((existing or {}).get('compression_history', []))
+        if new_results:
+            for r in new_results:
+                history.append({
+                    'before_tokens': getattr(r, 'before_tokens', 0),
+                    'after_tokens': getattr(r, 'after_tokens', 0),
+                    'method': getattr(r, 'method', 'unknown'),
+                    'pruned': getattr(r, 'pruned_tool_results', 0),
+                    'deduped': getattr(r, 'deduplicated_files', 0),
+                    'at': self._now(),
+                })
+        return history[-20:]  # 最多保留 20 条
+
+    # ── P2-1: 分层存储辅助 ──────────────────────
+
+    def _messages_path(self, session_path: Path) -> Path:
+        return session_path.with_suffix('.messages.jsonl')
+
+    def _steps_path(self, session_path: Path) -> Path:
+        return session_path.with_suffix('.steps.jsonl')
+
+    def _trace_path(self, session_path: Path) -> Path:
+        return session_path.with_suffix('.trace.jsonl')
+
+    def _write_jsonl(self, path: Path, items: list[dict[str, Any]]) -> None:
+        """原子写入 JSONL 文件。"""
+        with self._write_lock:
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            with open(tmp, 'w', encoding='utf-8') as f:
+                for item in items:
+                    f.write(json.dumps(item, ensure_ascii=False) + '\n')
+            os.replace(tmp, path)
+
+    def _read_jsonl(self, path: Path) -> list[dict[str, Any]]:
+        """读取 JSONL 文件。"""
+        if not path.exists():
+            return []
+        items = []
+        with open(path, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        items.append(json.loads(line))
+                    except Exception:
+                        pass
+        return items
+
+    def _save_layered(self, session_path: Path, messages: list, steps: list, run_trace: list, runtime_events: list) -> dict[str, str]:
+        """将大字段拆分到 sidecar 文件。返回存储位置摘要。"""
+        storage_info = {}
+        if messages:
+            self._write_jsonl(self._messages_path(session_path), messages)
+            storage_info['messages'] = 'sidecar'
+        if steps:
+            self._write_jsonl(self._steps_path(session_path), steps)
+            storage_info['steps'] = 'sidecar'
+        trace_combined = list(run_trace or []) + [
+            {**e, '_kind': 'runtime_event'} for e in (runtime_events or [])
+        ]
+        if trace_combined:
+            self._write_jsonl(self._trace_path(session_path), trace_combined)
+            storage_info['trace'] = 'sidecar'
+        return storage_info
+
+    def _load_layered_messages(self, session_path: Path, fallback_payload: dict) -> list[dict[str, Any]]:
+        """向后兼容：优先读 sidecar，不存在则从主 JSON 读。"""
+        sidecar = self._messages_path(session_path)
+        if sidecar.exists():
+            return self._read_jsonl(sidecar)
+        return fallback_payload.get('messages', []) or []
+
+    def _load_layered_steps(self, session_path: Path, fallback_payload: dict) -> list[dict[str, Any]]:
+        sidecar = self._steps_path(session_path)
+        if sidecar.exists():
+            return self._read_jsonl(sidecar)
+        return fallback_payload.get('steps', []) or []
+
+    def _load_layered_trace(self, session_path: Path, fallback_payload: dict) -> tuple[list, list]:
+        """返回 (run_trace, runtime_events)。"""
+        sidecar = self._trace_path(session_path)
+        if sidecar.exists():
+            items = self._read_jsonl(sidecar)
+            trace = [i for i in items if i.get('_kind') != 'runtime_event']
+            events = [{k: v for k, v in i.items() if k != '_kind'} for i in items if i.get('_kind') == 'runtime_event']
+            return trace, events
+        return (fallback_payload.get('run_trace', []) or [],
+                fallback_payload.get('runtime_events', []) or [])
+
+    def save_run(
+        self,
+        *,
+        agent_name: str,
+        task: str,
+        result,
+        messages: list[dict[str, Any]] | None = None,
+        task_id: str = '',
+        status: str = 'done',
+        config: dict[str, Any] | None = None,
+        parent_task_id: str = '',
+        session_id: str = '',
+        conversation_id: str = '',
+        run_id: str = '',
+    ) -> Path:
+        existing_path = self._find_path_by_task_id(task_id) if task_id else None
+        existing_payload = self._load_path(existing_path) if existing_path else None
+        # 优先使用外部传入的 session_id（对齐 UI 会话），
+        # 其次用已有记录的 session_id（追加写入），
+        # 最后才自动生成。
+        if session_id:
+            resolved_sid = session_id
+        elif existing_payload:
+            resolved_sid = existing_payload.get('session_id', '')
+        else:
+            resolved_sid = self._session_id(agent_name, task_id)
+        path = existing_path or (self.session_dir / f'{resolved_sid}.json')
+        now = self._now()
+        lifecycle = list((existing_payload or {}).get('lifecycle', []) or [])
+        lifecycle.append({'at': now, 'status': status, 'event': 'completed'})
+        # P2-1: 大字段序列化
+        steps_data = [s.to_dict() for s in getattr(result, 'steps', [])]
+        run_trace_data = run_trace_to_dicts(getattr(result, 'run_trace', None)) or (existing_payload or {}).get('run_trace', []) or []
+        runtime_events_data = runtime_events_to_dicts(getattr(result, 'runtime_events', None)) or (existing_payload or {}).get('runtime_events', []) or []
+        messages_data = messages or []
+
+        # P2-1: 拆分到 sidecar 文件
+        storage_info = self._save_layered(path, messages_data, steps_data, run_trace_data, runtime_events_data)
+
+        payload = {
+            **(existing_payload or {}),
+            'session_id': resolved_sid,
+            'created_at': (existing_payload or {}).get('created_at', now),
+            'updated_at': now,
+            'agent_name': agent_name,
+            'task': task,
+            'task_id': task_id,
+            'run_id': run_id or (existing_payload or {}).get('run_id', ''),
+            'parent_task_id': parent_task_id or (existing_payload or {}).get('parent_task_id', ''),
+            'conversation_id': conversation_id or (existing_payload or {}).get('conversation_id', '') or session_id or task_id,
+            'status': status,
+            'success': bool(getattr(result, 'success', False)),
+            'iterations': int(getattr(result, 'iterations', 0) or 0),
+            'total_tool_calls': int(getattr(result, 'total_tool_calls', 0) or 0),
+            'duration_seconds': float(getattr(result, 'duration_seconds', 0.0) or 0.0),
+            'error': getattr(result, 'error', '') or '',
+            'content': getattr(result, 'content', '') or '',
+            # P2-1: 大字段改为存摘要计数（完整数据在 sidecar）
+            'step_count': len(steps_data),
+            'message_count': len(messages_data),
+            'trace_count': len(run_trace_data),
+            'run_trace': run_trace_data,
+            'runtime_events': runtime_events_data,
+            'model_attempts': [a.to_dict() for a in getattr(result, 'model_attempts', [])],
+            'usage_summary': result.summary_dict().get('usage_summary', {}) if hasattr(result, 'summary_dict') else {},
+            'config': config or (existing_payload or {}).get('config', {}) or {},
+            'heartbeat_at': (existing_payload or {}).get('heartbeat_at', ''),
+            'started_at': (existing_payload or {}).get('started_at', ''),
+            'finished_at': now if status in {'done', 'error', 'timeout', 'cancelled', 'stalled', 'budget_exceeded'} else (existing_payload or {}).get('finished_at', ''),
+            'lifecycle': lifecycle,
+            'searchable_text': f"{task} {agent_name} {getattr(result, 'error', '') or ''} {(getattr(result, 'content', '') or '')[:500]}",
+            'compression_history': self._merge_compression_history(existing_payload, getattr(result, 'compression_results', None)),
+            # P2-1: 标记存储方式
+            '_storage': storage_info,
+        }
+        self._atomic_write(path, payload)
+        return path
+
+
+    def list_sessions_by_time(
+        self,
+        days: int = 7,
+        agent_name: str = "",
+        status: str = "",
+        limit: int = 50,
+    ) -> list[SessionRecord]:
+        """按时间范围查询会话。
+
+        Args:
+            days: 最近 N 天（默认 7 天）
+            agent_name: 按 agent 名过滤（空=所有）
+            status: 按状态过滤（空=所有）
+            limit: 最大返回数
+        """
+        from datetime import datetime, timedelta
+        cutoff = (datetime.now() - timedelta(days=days)).strftime('%Y-%m-%d')
+        items: list[SessionRecord] = []
+        if not self.session_dir.exists():
+            return items
+        loaded: list[tuple[Path, dict[str, Any]]] = []
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if not payload:
+                continue
+            created = payload.get('created_at', '')[:10]
+            if created < cutoff:
+                continue
+            if agent_name and payload.get('agent_name', '') != agent_name:
+                continue
+            if status and payload.get('status', '') != status:
+                continue
+            loaded.append((path, payload))
+        loaded.sort(key=lambda pair: self._session_sort_key(pair[1], pair[0]), reverse=True)
+        for path, payload in loaded[:max(0, limit)]:
+            items.append(
+                SessionRecord(
+                    session_id=payload.get('session_id', path.stem),
+                    path=str(path),
+                    created_at=payload.get('created_at', ''),
+                    agent_name=payload.get('agent_name', ''),
+                    task=payload.get('task', ''),
+                    status=payload.get('status', ''),
+                    success=bool(payload.get('success', False)),
+                    iterations=int(payload.get('iterations', 0) or 0),
+                    total_tool_calls=int(payload.get('total_tool_calls', 0) or 0),
+                    duration_seconds=float(payload.get('duration_seconds', 0.0) or 0.0),
+                    summary=(payload.get('content', '') or payload.get('error', '') or '')[:160],
+                    updated_at=payload.get('updated_at', '') or payload.get('created_at', ''),
+                )
+            )
+        return items
+
+    def load_session_messages(self, session_id: str) -> list[dict[str, Any]]:
+        """加载会话的 messages 列表，用于上下文恢复。
+
+        P2-1: 优先从 sidecar 读取，向后兼容旧格式。
+        """
+        payload = self.load_session(session_id)
+        if not payload:
+            return []
+        # P2-1: 如果有 sidecar 文件，从 sidecar 读
+        path = self._find_path_by_session_id(session_id)
+        if path is not None:
+            return self._load_layered_messages(path, payload)
+        return payload.get('messages', [])
+
+    def search_sessions(self, query: str, limit: int = 10) -> list[dict[str, Any]]:
+        """全文搜索历史会话。
+
+        搜索范围：task + agent_name + error + content 前500字
+        """
+        query_lower = query.lower()
+        results: list[dict[str, Any]] = []
+        if limit <= 0 or not query_lower:
+            return results
+        if not self.session_dir.exists():
+            return results
+
+        loaded: list[tuple[Path, dict[str, Any]]] = []
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if payload:
+                loaded.append((path, payload))
+        loaded.sort(key=lambda pair: self._session_sort_key(pair[1], pair[0]), reverse=True)
+        for path, payload in loaded:
+            searchable = (payload.get('searchable_text', '') or '').lower()
+            if query_lower in searchable:
+                results.append({
+                    'session_id': payload.get('session_id', path.stem),
+                    'agent_name': payload.get('agent_name', ''),
+                    'task': payload.get('task', ''),
+                    'created_at': payload.get('created_at', ''),
+                    'success': payload.get('success', False),
+                    'content_preview': (payload.get('content', '') or '')[:200],
+                    'path': str(path),
+                })
+            if len(results) >= limit:
+                break
+        return results
+
+    def get_compression_history(self, session_id: str) -> list[dict[str, Any]]:
+        """获取会话的压缩历史记录。"""
+        payload = self.load_session(session_id)
+        if not payload:
+            return []
+        return payload.get('compression_history', [])
+
+    def delete_session_files(self, session_path: str | Path) -> bool:
+        """删除会话主文件及其分层 sidecar 文件。"""
+        path = Path(session_path)
+        deleted = False
+        for candidate in (
+            path,
+            self._messages_path(path),
+            self._steps_path(path),
+            self._trace_path(path),
+        ):
+            try:
+                candidate.unlink()
+                deleted = True
+            except FileNotFoundError:
+                pass
+        return deleted
+
+    def cleanup_old_sessions(self, retention_days: int = 30) -> int:
+        """清理超过指定天数的旧会话。
+
+        Returns: 删除的主会话文件数
+        """
+        from datetime import datetime, timedelta
+        cutoff = (datetime.now() - timedelta(days=retention_days)).strftime('%Y-%m-%d')
+        deleted = 0
+        if not self.session_dir.exists():
+            return 0
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if not payload:
+                continue
+            created = payload.get('created_at', '')[:10]
+            if created < cutoff:
+                try:
+                    if self.delete_session_files(path):
+                        deleted += 1
+                except Exception:
+                    pass
+        return deleted
+
+    def session_stats(self) -> dict[str, Any]:
+        """会话统计信息。"""
+        if not self.session_dir.exists():
+            return {"total": 0}
+        all_sessions = []
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if payload:
+                all_sessions.append(payload)
+
+        by_agent: dict[str, int] = {}
+        by_status: dict[str, int] = {}
+        total_duration = 0.0
+        total_iterations = 0
+        total_tool_calls = 0
+        total_compressions = 0
+
+        for s in all_sessions:
+            agent = s.get('agent_name', 'unknown')
+            by_agent[agent] = by_agent.get(agent, 0) + 1
+            status = s.get('status', 'unknown')
+            by_status[status] = by_status.get(status, 0) + 1
+            total_duration += float(s.get('duration_seconds', 0) or 0)
+            total_iterations += int(s.get('iterations', 0) or 0)
+            total_tool_calls += int(s.get('total_tool_calls', 0) or 0)
+            total_compressions += len(s.get('compression_history', []))
+
+        return {
+            "total": len(all_sessions),
+            "by_agent": by_agent,
+            "by_status": by_status,
+            "total_duration_seconds": total_duration,
+            "total_iterations": total_iterations,
+            "total_tool_calls": total_tool_calls,
+            "total_compressions": total_compressions,
+        }
+
+    def _load_path(self, path: Path) -> dict[str, Any] | None:
+        try:
+            return json.loads(path.read_text(encoding='utf-8'))
+        except Exception:
+            return None
+
+
+    def _session_sort_key(self, payload: dict[str, Any] | None, path: Path) -> tuple[str, str, str]:
+        """按业务时间排序：最近写入 updated_at，其次创建时间，最后 session_id。
+
+        不使用文件 mtime：原子 replace、复制/恢复文件都会改变 mtime，导致列表看起来乱序。
+        """
+        payload = payload or {}
+        updated = str(payload.get('updated_at', '') or '')
+        created = str(payload.get('created_at', '') or '')
+        session_id = str(payload.get('session_id', path.stem) or path.stem)
+        return (updated, created, session_id)
+
+    def list_sessions(self, limit: int = 20) -> list[SessionRecord]:
+        items: list[SessionRecord] = []
+        if not self.session_dir.exists():
+            return items
+        loaded: list[tuple[Path, dict[str, Any]]] = []
+        for path in self.session_dir.glob('*.json'):
+            payload = self._load_path(path)
+            if not payload:
+                continue
+            loaded.append((path, payload))
+        loaded.sort(key=lambda pair: self._session_sort_key(pair[1], pair[0]), reverse=True)
+        # 新建 UI session 必须立即可见；更新后的会话也由 mtime 排序靠前。
+        if limit <= 0:
+            return items
+        for path, payload in loaded[:limit]:
+            items.append(
+                SessionRecord(
+                    session_id=payload.get('session_id', path.stem),
+                    path=str(path),
+                    created_at=payload.get('created_at', ''),
+                    agent_name=payload.get('agent_name', ''),
+                    task=payload.get('task', ''),
+                    status=payload.get('status', ''),
+                    success=bool(payload.get('success', False)),
+                    iterations=int(payload.get('iterations', 0) or 0),
+                    total_tool_calls=int(payload.get('total_tool_calls', 0) or 0),
+                    duration_seconds=float(payload.get('duration_seconds', 0.0) or 0.0),
+                    summary=(payload.get('content', '') or payload.get('error', '') or '')[:160],
+                    updated_at=payload.get('updated_at', '') or payload.get('created_at', ''),
+                )
+            )
+        return items
+
+    def latest_session(self) -> dict[str, Any] | None:
+        sessions = self.list_sessions(limit=1)
+        if not sessions:
+            return None
+        return self.load_session(sessions[0].session_id)
+
+    def load_session(self, session_id: str) -> dict[str, Any] | None:
+        path = self._find_path_by_session_id(session_id)
+        if path is None:
+            return None
+        payload = self._load_path(path)
+        if payload and not payload.get("messages") and payload.get("conversation_messages"):
+            # UI 会话历史使用 conversation_messages；对外 load_session 保持统一 messages 契约。
+            payload["messages"] = list(payload["conversation_messages"])
+        # P2-1: 如果是分层存储，合并 sidecar 数据回 payload（向后兼容调用方）
+        if payload and payload.get('_storage'):
+            messages = self._load_layered_messages(path, payload)
+            steps = self._load_layered_steps(path, payload)
+            run_trace, runtime_events = self._load_layered_trace(path, payload)
+            payload['messages'] = messages
+            payload['steps'] = steps
+            payload['run_trace'] = run_trace
+            payload['runtime_events'] = runtime_events
+        return payload
+
+    def worker_records(self, limit: int = 20) -> list[dict[str, Any]]:
+        records: list[dict[str, Any]] = []
+        for session in self.list_sessions(limit=limit):
+            payload = self.load_session(session.session_id) or {}
+            records.append(
+                {
+                    'session_id': session.session_id,
+                    'agent_name': session.agent_name,
+                    'task': session.task,
+                    'status': session.status,
+                    'success': session.success,
+                    'iterations': session.iterations,
+                    'tool_calls': session.total_tool_calls,
+                    'duration_seconds': session.duration_seconds,
+                    'summary': session.summary,
+                    'messages': len(payload.get('messages', []) or []),
+                }
+            )
+        return records
+
+    def load_messages(self, session_id: str | None = None) -> list[dict[str, Any]]:
+        payload = self.latest_session() if not session_id else self.load_session(session_id)
+        if not payload:
+            return []
+        # P2-1: 优先从 sidecar 读
+        path = self._find_path_by_session_id(session_id)
+        if path is not None:
+            return self._load_layered_messages(path, payload)
+        messages = payload.get('messages', []) or []
+        return messages if isinstance(messages, list) else []
+
+    def build_live_run_report(self, session_id: str | None = None) -> dict[str, Any]:
+        """Build a LBS-aligned, machine-readable run report from persisted state."""
+        payload = self.latest_session() if not session_id else self.load_session(session_id)
+        if not payload:
+            return {
+                'scope': 'runtime-session',
+                'status': 'missing',
+                'session_id': session_id or '',
+                'error': 'session not found',
+            }
+        model_attempts = payload.get('model_attempts', []) or []
+        failed_attempts = [a for a in model_attempts if a.get('status') != 'success']
+        successful_attempts = [a for a in model_attempts if a.get('status') == 'success']
+        steps = payload.get('steps', []) or []
+        run_trace = payload.get('run_trace', []) or []
+        runtime_events = payload.get('runtime_events', []) or []
+        run_trace_phases = []
+        for event in run_trace:
+            phase = event.get('phase', '') if isinstance(event, dict) else ''
+            if phase and phase not in run_trace_phases:
+                run_trace_phases.append(phase)
+        context_preflight_events = [
+            event for event in run_trace
+            if isinstance(event, dict) and event.get('phase') == 'context_preflight'
+        ]
+        compression_events = [
+            event for event in context_preflight_events
+            if bool((event.get('metadata') or {}).get('compressed'))
+        ]
+        latest_preflight = (context_preflight_events[-1].get('metadata') or {}) if context_preflight_events else {}
+        return {
+            'scope': 'runtime-session',
+            'session_id': payload.get('session_id', ''),
+            'created_at': payload.get('created_at', ''),
+            'agent_name': payload.get('agent_name', ''),
+            'task': payload.get('task', ''),
+            'status': payload.get('status', ''),
+            'success': bool(payload.get('success', False)),
+            'iterations': int(payload.get('iterations', 0) or 0),
+            'total_tool_calls': int(payload.get('total_tool_calls', 0) or 0),
+            'duration_seconds': float(payload.get('duration_seconds', 0.0) or 0.0),
+            'error': payload.get('error', '') or '',
+            'config': payload.get('config', {}) or {},
+            'step_count': len(steps),
+            'steps': steps,
+            'model_attempt_count': len(model_attempts),
+            'model_failure_count': len(failed_attempts),
+            'model_success_count': len(successful_attempts),
+            'model_attempts': model_attempts,
+            'failure_propagated': (not bool(payload.get('success', False))) and bool(payload.get('error', '')),
+            'run_trace_count': len(run_trace),
+            'run_trace_phases': run_trace_phases,
+            'run_trace_last_event': run_trace[-1] if run_trace else {},
+            'run_trace': run_trace,
+            'runtime_event_count': len(runtime_events),
+            'runtime_event_types': [event.get('type', '') for event in runtime_events if isinstance(event, dict)],
+            'runtime_event_last': runtime_events[-1] if runtime_events else {},
+            'runtime_events': runtime_events,
+            'usage_summary': payload.get('usage_summary', {}),
+            'context_preflight': {
+                'count': len(context_preflight_events),
+                'compression_count': len(compression_events),
+                'latest': dict(latest_preflight),
+            },
+            'task_id': payload.get('task_id', ''),
+            'parent_task_id': payload.get('parent_task_id', ''),
+            'depends_on': payload.get('depends_on', []) or [],
+            'rerun_of': payload.get('rerun_of', ''),
+            'heartbeat_at': payload.get('heartbeat_at', ''),
+            'started_at': payload.get('started_at', ''),
+            'finished_at': payload.get('finished_at', ''),
+            'lifecycle': payload.get('lifecycle', []) or [],
+            'child_count': len(self.child_tasks(payload.get('task_id', ''))),
+            'children': [
+                {
+                    'session_id': child.get('session_id', ''),
+                    'task_id': child.get('task_id', ''),
+                    'parent_task_id': child.get('parent_task_id', ''),
+                    'agent_name': child.get('agent_name', ''),
+                    'task': child.get('task', ''),
+                    'status': child.get('status', ''),
+                    'success': bool(child.get('success', False)),
+                    'rerun_of': child.get('rerun_of', ''),
+                }
+                for child in self.child_tasks(payload.get('task_id', ''))
+            ],
+        }
+
+    def create_task(self, *, agent_name: str, task: str, task_id: str = "", parent_task_id: str = "", context: str = "", depends_on: list[str] | None = None, config: dict[str, Any] | None = None, rerun_of: str = "") -> Any:
+        if not task_id:
+            task_id = f"task-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}"
+        now = self._now()
+        rec = TaskRecord(
+            task_id=task_id,
+            session_id=self._session_id(agent_name, task_id),
+            agent_name=agent_name,
+            task=task,
+            context=context,
+            parent_task_id=parent_task_id,
+            depends_on=list(depends_on or []),
+            rerun_of=rerun_of,
+            status=TaskStatus.PENDING,
+            created_at=now,
+            updated_at=now,
+            config=config or {},
+            lifecycle=[{"at": now, "status": "pending", "event": "created"}],
+        )
+        path = self.session_dir / f"{rec.session_id}.json"
+        self._atomic_write(path, rec.to_dict())
+        return rec
+
+    def update_task(self, task_id: str, status: Any, *, error: str = "", content: str = "", iterations: int = 0, total_tool_calls: int = 0, duration_seconds: float = 0.0) -> Any:
+        path = self._find_path_by_task_id(task_id)
+        if not path:
+            return None
+        payload = self._load_path(path) or {}
+        rec = TaskRecord.from_dict(payload)
+        now = self._now()
+        rec.status = status
+        rec.updated_at = now
+        if error:
+            rec.error = error
+        if content:
+            rec.content = content
+        if iterations:
+            rec.iterations = iterations
+        if total_tool_calls:
+            rec.total_tool_calls = total_tool_calls
+        if duration_seconds:
+            rec.duration_seconds = duration_seconds
+
+        if status == TaskStatus.RUNNING and not rec.started_at:
+            rec.started_at = now
+        if status in (TaskStatus.DONE, TaskStatus.ERROR, TaskStatus.TIMEOUT, TaskStatus.CANCELLED):
+            rec.finished_at = now
+            rec.success = status == TaskStatus.DONE and not bool(rec.error)
+
+        rec.lifecycle.append({"at": now, "status": status.value, "event": "status_update"})
+        self._atomic_write(path, rec.to_dict())
+        return rec
+
+    def get_task(self, task_id: str) -> Any:
+        path = self._find_path_by_task_id(task_id)
+        if not path:
+            return None
+        payload = self._load_path(path)
+        return TaskRecord.from_dict(payload) if payload else None
+
+    def create_ui_session(
+        self,
+        title: str = "新会话",
+        *,
+        session_id: str = "",
+        agent_name: str = "",
+        conversation_id: str = "",
+    ) -> dict[str, str]:
+        import time
+        stamp = time.strftime("%Y%m%dT%H%M%S")
+        session_id = session_id or f"ui-{stamp}-{__import__('uuid').uuid4().hex[:6]}"
+        path = self.session_dir / f"{session_id}.json"
+        now = self._now()
+        clean_title = title.strip() or "新会话"
+        if path.exists():
+            payload = self._load_path(path) or {}
+            return {"session_id": session_id, "title": payload.get("task", clean_title)}
+        payload = {
+            "session_id": session_id,
+            "conversation_id": conversation_id or session_id,
+            "created_at": now,
+            "updated_at": now,
+            "agent_name": agent_name,
+            "task": clean_title,
+            "status": "idle",
+            "run_status": "idle",
+            "active": True,
+            "success": False,
+            "iterations": 0,
+            "total_tool_calls": 0,
+            "duration_seconds": 0,
+            "messages": [],
+            "conversation_messages": [],
+            "model_override": {},
+            "events": [],
+        }
+        self._atomic_write(path, payload)
+        return {"session_id": session_id, "title": clean_title}
+
+    def append_interaction(self, session_id: str, *, agent_name: str, task: str, output: str, success: bool, model: str = "", usage: dict | None = None, context_info: dict | None = None, **extra: Any) -> None:
+        """追加 UI 对话消息；Agent provider history 由 save_run 单独持久化。
+
+        每轮交互（user + assistant）都标注 turn_number，从 1 开始递增。
+        向后兼容：旧消息没有 turn_number 时不影响新消息的编号。
+        """
+        path = self.session_dir / f"{session_id}.json"
+        if not path.exists():
+            return
+        with self._write_lock:
+            payload = self._load_path(path) or {}
+            now = self._now()
+            msgs = payload.setdefault("conversation_messages", [])
+            existing_turns = [m.get("turn_number", 0) for m in msgs if isinstance(m, dict) and m.get("turn_number")]
+            if existing_turns:
+                turn = max(existing_turns) + 1
+            else:
+                user_count = sum(1 for m in msgs if isinstance(m, dict) and m.get("role") == "user")
+                turn = user_count + 1
+            msgs.append({"role": "user", "content": task, "timestamp": now, "turn_number": turn})
+            assistant_msg: dict[str, Any] = {"role": "assistant", "content": output, "timestamp": now, "agent": agent_name, "success": success, "turn_number": turn}
+            if model:
+                assistant_msg["model"] = model
+            if usage:
+                assistant_msg["usage"] = usage
+            if context_info:
+                assistant_msg["context_info"] = context_info
+            msgs.append(assistant_msg)
+            payload["conversation_messages"] = msgs
+            payload["messages"] = list(msgs)
+            payload["updated_at"] = now
+            payload["agent_name"] = agent_name
+            payload["status"] = "completed" if success else "error"
+            payload["success"] = success
+            # 更新 usage_summary 累计
+            if usage:
+                u = payload.setdefault("usage_summary", {})
+                u["total_input_tokens"] = u.get("total_input_tokens", 0) + int(usage.get("input", 0))
+                u["total_output_tokens"] = u.get("total_output_tokens", 0) + int(usage.get("output", 0))
+                u["total_cost_usd"] = u.get("total_cost_usd", 0.0) + float(usage.get("cost", 0))
+                u["total_calls"] = u.get("total_calls", 0) + 1
+            if model:
+                payload["last_model"] = model
+            for key, value in extra.items():
+                if value is not None:
+                    payload[key] = value
+            payload["updated_at"] = now
+            self._atomic_write(path, payload)
+
+    def update_session(self, session_id: str, *, mutate=None, **fields) -> dict | None:
+        """原子读 + mutate/merge + 原子写。供 server 适配层使用。"""
+        path = self._find_path_by_session_id(session_id)
+        if path is None:
+            return None
+        with self._write_lock:
+            try:
+                payload = self._load_path(path) or {}
+            except Exception:
+                return None
+            if mutate is not None:
+                try:
+                    mutated = mutate(payload) or payload
+                except Exception:
+                    mutated = payload
+                payload = mutated
+            for k, v in (fields or {}).items():
+                if v is None:
+                    continue
+                payload[k] = v
+            try:
+                self._atomic_write(path, payload)
+            except Exception:
+                return None
+            return payload
+
+    def add_attachment(self, session_id: str, attachment: dict) -> bool:
+        """向 session 的 attachments 列表追加一条（原子写）。"""
+        result = self.update_session(
+            session_id,
+            mutate=lambda d: d.setdefault("attachments", []).append(attachment) or d,
+        )
+        return result is not None
+
+    def remove_attachment(self, session_id: str, name: str) -> bool:
+        """从 session 的 attachments 列表按 name 移除一条（原子写）。"""
+        result = self.update_session(
+            session_id,
+            mutate=lambda d: d.update({
+                "attachments": [a for a in d.get("attachments", []) if a.get("name") != name]
+            }) or d,
+        )
+        return result is not None
+