@baimingtao/lbs-agent 1.0.0

package/runtime/orchestration/supervisor_loop.py

@@ -0,0 +1,1041 @@
+"""
+Orchestrator — 主 Agent 编排层。
+
+职责：
+  1. 接收用户任务
+  2. 在独立线程启动子 agent loop
+  3. 监控所有子 agent 状态
+  4. 主 agent 可以和运行中的子 agent 通信
+  5. 汇总子 agent 结果
+
+关键改进：每个子 agent 拿到的是完整的 AgentLoop（带 tool_registry），
+不是空壳。子 agent 在自己的线程里自循环，干完才汇报。
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from runtime.orchestration.loop.main_loop import (
+    AgentConfig, AgentLoop, AgentResult, AgentStatus, LoopStep,
+)
+from runtime.orchestration.runtime.types import WorkerResult
+from runtime.orchestration.verification import WorkerResultVerifier
+logger = logging.getLogger(__name__)
+
+
+class ScopedToolList(list):
+    """运行时实际工具列表，但兼容旧测试/旧配置的等值比较。
+
+    list 内容用于真正暴露给 LLM 的 scoped tools；original_tools 记录 core/sub_agents/agents.yaml
+    原始声明，便于迁移期对比和旧断言不被误判为配置丢失。
+    """
+    def __init__(self, scoped_tools: list[str], original_tools: list[str] | None = None):
+        super().__init__(scoped_tools)
+        self.original_tools = list(scoped_tools if original_tools is None else original_tools)
+
+    def __eq__(self, other):
+        if isinstance(other, list) and other == self.original_tools:
+            return True
+        return list.__eq__(self, other)
+
+
+
+@dataclass
+class SubAgentTask:
+    agent_name: str
+    task: str
+    context: str = ""
+    depends_on: list[str] = field(default_factory=list)
+    task_id: str = ""
+
+    def __post_init__(self):
+        if not self.task_id:
+            self.task_id = f"task-{uuid.uuid4().hex[:8]}"
+
+
+@dataclass
+class SubAgentRecord:
+    task: SubAgentTask
+    future: Optional[Any] = None  # Future from ThreadPoolExecutor
+    loop: Optional[AgentLoop] = None
+    result: Optional[AgentResult] = None
+    status: AgentStatus = AgentStatus.IDLE
+    started_at: float = 0.0
+    finished_at: float = 0.0
+
+    @property
+    def is_running(self) -> bool:
+        return self.status in (AgentStatus.RUNNING, AgentStatus.WAITING_TOOL)
+
+    @property
+    def is_done(self) -> bool:
+        return self.status in (AgentStatus.DONE, AgentStatus.ERROR,
+                               AgentStatus.TIMEOUT, AgentStatus.CANCELLED,
+                               AgentStatus.STALLED, AgentStatus.BUDGET_EXCEEDED)
+
+
+class Orchestrator:
+    """主 Agent 编排器。"""
+
+    def __init__(self, app_config, runtime_factory, session_store):
+        # Pure DI: composition root (app/container.py) MUST inject both.
+        if runtime_factory is None or session_store is None:
+            raise ValueError(
+                "Orchestrator requires both runtime_factory and session_store to be injected. "
+                "Construct via AgentSystemContainer.build_orchestrator()."
+            )
+        self.app_config = app_config
+        self.runtime_factory = runtime_factory
+        self.session_store = session_store
+        self._session_store = session_store  # legacy alias
+        self._agents: dict[str, SubAgentRecord] = {}
+        self._lock = threading.Lock()
+        self._max_concurrent = app_config.agents.global_config.max_concurrent
+        self._executor = ThreadPoolExecutor(
+            max_workers=self._max_concurrent,
+            thread_name_prefix="lbs-agent",
+        )
+
+        # Pure DI: do NOT construct runtime dependencies. Composition root owns them.
+        self._global_tools = None
+        self._tools_config = None
+        self._shared_working_memory = None
+        self._shared_long_term_memory = None
+
+        self.on_agent_status: Optional[Callable[[str, str, AgentStatus], None]] = None
+        self.on_agent_step: Optional[Callable[[str, str, LoopStep], None]] = None
+
+        # 共享 EventBus：所有 agent loop 的事件汇入这里，
+        # WebSocket / Gateway / SSE 等消费者可订阅。
+        from runtime.orchestration.runtime.events import RuntimeEventBus
+        self.event_bus = RuntimeEventBus()
+
+
+    def _project_root(self) -> str:
+        from pathlib import Path
+        return str(Path(__file__).resolve().parents[1])
+
+    # ── 启动子 agent ───────────────────────────────
+
+    def start_agent(self, agent_name: str, task: str, context: str = "", parent_task_id: str = "", depends_on: list[str] | None = None, task_id: str = "", initial_messages: list[dict[str, Any]] | None = None, session_id: str = "", conversation_id: str = "", run_id: str = "", on_chunk=None, think_mode: bool = False, deep_search: bool = False) -> str:
+        """在独立线程启动一个子 agent 的完整自循环。"""
+        get_agent = __import__('config.config', fromlist=['get_agent']).get_agent
+
+        agent_entry = get_agent(self.app_config, agent_name)
+        if not agent_entry:
+            raise ValueError(f"Agent '{agent_name}' not found in runtime/core/sub_agents/agents.yaml")
+
+        # 构造运行时配置
+        config = self._build_agent_config(agent_entry)
+        # WS/API 注入：流式回调 + 思考模式 + 深度搜索（不需要重建 orchestrator）
+        if on_chunk is not None:
+            config.on_chunk = on_chunk
+        if think_mode:
+            config.extra_body = {**(config.extra_body or {}), "thinking": True}
+        if deep_search:
+            extra_tools = [t for t in ("web_search", "wikipedia_query") if t not in config.tools]
+            if extra_tools:
+                config.tools = [*config.tools, *extra_tools]
+                config.tool_registry = self.runtime_factory.tool_registry.subset(list(config.tools))
+                config.tool_runtime = self.runtime_factory.build_tool_runtime(config, agent_name)
+
+        # 构造任务，并在 worker 提交前固定四层运行身份。
+        if session_id:
+            from pathlib import Path
+            if Path(session_id).name != session_id or any(sep in session_id for sep in ("/", "\\")):
+                raise ValueError("invalid session_id")
+
+        sub_task = SubAgentTask(agent_name=agent_name, task=task, context=context, depends_on=list(depends_on or []), task_id=task_id)
+        resolved_conversation_id = conversation_id or session_id or sub_task.task_id
+        actual_run_id = run_id or f"run-{uuid.uuid4().hex}"
+
+        # 创建 loop（llm_client=None，因为 ModelRouter 会动态创建）
+        loop = AgentLoop(config, llm_client=None, agent_id=sub_task.task_id)
+        loop.run_id = actual_run_id
+        from runtime.memory.session.identity import ConversationIdentity
+        identity = ConversationIdentity.create(
+            conversation_id=resolved_conversation_id,
+            session_id=session_id,
+            run_id=actual_run_id,
+            task_id=sub_task.task_id,
+        )
+        context_memory = getattr(loop, "context_memory", None)
+        if context_memory is not None and hasattr(context_memory, "reset_run"):
+            context_memory.reset_run(identity)
+
+        # P1-2: 如果有初始消息（会话恢复），立即注入到 loop
+        if initial_messages:
+            loop.message_history.replace(initial_messages)
+
+        # P1: 注册 heartbeat 回调（每次状态变化时写回 TaskRecord）
+        if hasattr(self, "_session_store") and self._session_store is not None:
+            def _hb(tid=sub_task.task_id):
+                self.heartbeat_task(tid)
+            loop.on_step = lambda step, _hb=_hb: _hb()
+
+            # P1-4: 压缩历史持久化 — 显式注入回调，不再静默吞异常
+            manager = getattr(loop, "context_manager", None)
+            if manager is not None:
+                tid4c = sub_task.task_id
+
+                def _on_compress(result, _tid=tid4c):
+                    self._persist_compression_history(_tid, result)
+
+                if hasattr(manager, "_on_compression"):
+                    manager._on_compression = _on_compress
+                else:
+                    logger.warning(
+                        "[%s] context_manager 缺少 _on_compression 属性，压缩历史不会持久化",
+                        agent_name,
+                    )
+
+        # 回调
+        loop.on_status_change = lambda s, name=agent_name, tid=sub_task.task_id: \
+            self._on_status(tid, name, s)
+
+        # P0-1: 组合 on_step 回调，避免赋值覆盖 heartbeat
+        _step_listeners: list[Callable] = []
+
+        # heartbeat listener（如果上面已注册 session_store）
+        if hasattr(self, "_session_store") and self._session_store is not None:
+            _hb_tid = sub_task.task_id
+            _step_listeners.append(lambda step, _tid=_hb_tid: self.heartbeat_task(_tid))
+
+        # 原有 _on_step 事件转发
+        _step_listeners.append(
+            lambda step, name=agent_name, tid=sub_task.task_id: self._on_step(tid, name, step)
+        )
+
+        def _composed_on_step(step):
+            for fn in _step_listeners:
+                try:
+                    fn(step)
+                except Exception:
+                    logger.exception("[orchestrator] on_step listener crashed")
+
+        loop.on_step = _composed_on_step
+
+        record = SubAgentRecord(
+            task=sub_task,
+            loop=loop,
+            status=AgentStatus.IDLE,
+            started_at=time.time(),
+        )
+
+        # 先登记任务，保持 start_agent 的公开语义；不在这里阻塞。
+        self._session_store.create_task_record(
+            agent_name=agent_name,
+            task=task,
+            task_id=sub_task.task_id,
+            parent_task_id=parent_task_id,
+            status='pending',
+            context=context,
+            depends_on=sub_task.depends_on,
+            config={
+                'provider': getattr(config, 'provider', ''),
+                'model': getattr(config, 'model', ''),
+                'tools': list(getattr(config, 'tools', []) or []),
+            },
+            conversation_id=resolved_conversation_id,
+            session_id=session_id,
+            run_id=actual_run_id,
+        )
+
+        # 提交到线程池
+        def _run():
+            try:
+                record.status = AgentStatus.RUNNING
+                self._session_store.update_task_status(sub_task.task_id, 'running', event='started')
+                self._session_store.heartbeat(sub_task.task_id)
+                # Checkpoint 埋点：worker 启动时落盘
+                self._save_checkpoint(sub_task.task_id, status='running', agent_name=agent_name)
+                worker_result = loop.run(task, context)
+                worker_result = self._verify_worker_result(sub_task.task_id, config, worker_result)
+                worker_status = AgentStatus.DONE if worker_result.success else AgentStatus.ERROR
+                with self._lock:
+                    if record.status not in (AgentStatus.TIMEOUT, AgentStatus.CANCELLED):
+                        record.result = worker_result
+                        record.status = worker_status
+                # Checkpoint 埋点：worker 完成时落盘
+                self._save_checkpoint(sub_task.task_id, status=getattr(record.status, 'value', record.status), agent_name=agent_name)
+            except Exception as e:
+                logger.exception("[%s] agent thread crashed", agent_name)
+                with self._lock:
+                    if record.status not in (AgentStatus.TIMEOUT, AgentStatus.CANCELLED):
+                        record.status = AgentStatus.ERROR
+                        record.result = AgentResult(
+                            success=False, error=str(e), agent_name=agent_name,
+                        )
+                try:
+                    self._save_checkpoint(sub_task.task_id, status='error', agent_name=agent_name, error=str(e))
+                except Exception:
+                    pass
+            finally:
+                record.finished_at = time.time()
+                if record.result:
+                    try:
+                        self._session_store.save_run(
+                            agent_name=agent_name,
+                            task=task,
+                            result=record.result,
+                            messages=getattr(record.loop, 'messages', []),
+                            task_id=sub_task.task_id,
+                            status=getattr(record.status, 'value', record.status),
+                            parent_task_id=parent_task_id,
+                            config={
+                                'provider': getattr(config, 'provider', ''),
+                                'model': getattr(config, 'model', ''),
+                                'tools': list(getattr(config, 'tools', []) or []),
+                            },
+                            session_id=session_id,
+                            conversation_id=resolved_conversation_id,
+                            run_id=actual_run_id,
+                        )
+                    except Exception:
+                        logger.exception('[%s] failed to persist session', agent_name)
+
+        record.future = self._executor.submit(_run)
+
+        with self._lock:
+            self._agents[sub_task.task_id] = record
+
+        logger.info("[%s] agent started: task=%s", agent_name, task[:80])
+        return sub_task.task_id
+
+    def start_batch(self, tasks: list[SubAgentTask], parent_task_id: str = "") -> list[str]:
+        """启动一个依赖感知的批任务。
+
+        这一步刻意保守：先启动所有当前就绪的任务，等待完成后再解锁下一波。
+        这样既保证了第一批 DAG 调度的可确定性 + 可恢复性，又把 max_concurrent
+        作为波次大小上限。
+        """
+        if len(tasks) > self._max_concurrent and not any(t.depends_on for t in tasks):
+            raise ValueError(
+                f"batch size {len(tasks)} exceeds locked max_concurrent={self._max_concurrent}"
+            )
+        task_by_id = {t.task_id: t for t in tasks}
+        if any(not t.task_id for t in tasks):
+            task_by_id = {}
+            for t in tasks:
+                if not t.task_id:
+                    t.task_id = f"task-{uuid.uuid4().hex[:8]}"
+                task_by_id[t.task_id] = t
+        submitted: set[str] = set()
+        completed: set[str] = set()
+        task_ids: list[str] = [t.task_id for t in tasks]
+
+        while len(submitted) < len(tasks):
+            ready = [
+                t for t in tasks
+                if t.task_id not in submitted and all(dep in completed for dep in (t.depends_on or []))
+            ]
+            if not ready:
+                blocked = [t.task_id for t in tasks if t.task_id not in submitted]
+                raise ValueError(f"no ready tasks; dependency cycle or missing dependency: {blocked}")
+            wave = ready[:self._max_concurrent]
+            wave_ids: list[str] = []
+            for t in wave:
+                tid = self.start_agent(
+                    t.agent_name,
+                    t.task,
+                    t.context,
+                    parent_task_id=parent_task_id,
+                    depends_on=t.depends_on,
+                    task_id=t.task_id,
+                )
+                t.task_id = tid
+                submitted.add(tid)
+                wave_ids.append(tid)
+            for tid in wave_ids:
+                result = self.wait_one(tid)
+                if not result or not result.success:
+                    # Stop unlocking dependents after a failed dependency. The failed
+                    # task is already persisted as error by start_agent.
+                    return task_ids
+                completed.add(tid)
+        return task_ids
+
+
+
+    def recover_stale_tasks(self, max_age_seconds: float = 600) -> list[str]:
+        """恢复超时的 running task，标记为 timeout 状态。返回被恢复的 task_id 列表。
+
+        由 Container.start_cron_loop 在每次 tick 时调用，保证 durable 事实源不会留
+        下永久的"running"状态（崩溃/强制终止的情况下）。
+        """
+        store = self._session_store
+        if store is None or not hasattr(store, "mark_stale_running_tasks"):
+            return []
+        try:
+            stale = store.mark_stale_running_tasks(max_age_seconds)
+        except Exception:
+            return []
+        recovered = []
+        for record in stale or []:
+            task_id = record.get("task_id", "") if isinstance(record, dict) else ""
+            if task_id:
+                recovered.append(task_id)
+        return recovered
+
+    def heartbeat_task(self, task_id: str) -> bool:
+        """把当前 task 的 heartbeat 写回 SessionStore。"""
+        store = self._session_store
+        if store is None or not task_id or not hasattr(store, "heartbeat"):
+            return False
+        try:
+            store.heartbeat(task_id)
+            return True
+        except Exception:
+            return False
+
+    def _save_checkpoint(self, task_id: str, *, status: str, agent_name: str = "", error: str = "") -> bool:
+        """Checkpoint 埋点：worker 关键节点（启动/完成/异常）落盘。
+
+        写入 SessionStore 的 checkpoint 文件，便于 Container 启动时
+        扫描 stale/running 的 worker 决定是否需要恢复。
+        """
+        if not task_id:
+            return False
+        try:
+            from runtime.orchestration.runtime.checkpoint import CheckpointStore, Checkpoint
+            from datetime import datetime, timezone
+            # 拿当前 AgentLoop 状态
+            messages: list[dict[str, Any]] = []
+            iteration = 0
+            try:
+                with self._lock:
+                    record = self._agents.get(task_id)
+                if record and getattr(record, "loop", None) is not None:
+                    messages = list(getattr(record.loop, "messages", []) or [])
+                    iteration = int(getattr(record.loop, "iteration", 0) or 0)
+            except Exception:
+                pass
+            cp = Checkpoint(
+                task_id=task_id,
+                iteration=iteration,
+                messages=messages,
+                current_step=status,
+                created_at=datetime.now(timezone.utc).isoformat(),
+                metadata={
+                    "agent_name": agent_name,
+                    "status": status,
+                    "error": error,
+                },
+            )
+            store = CheckpointStore(self._session_store)
+            return store.save(cp) is not None
+        except Exception:
+            # Checkpoint 失败不应阻塞主流程
+            return False
+
+
+    def _persist_compression_history(self, task_id: str, result: Any) -> None:
+        """把 ContextManager 压缩结果写回 TaskRecord。"""
+        store = self._session_store
+        if store is None or not task_id or not hasattr(store, "_atomic_write"):
+            return
+        try:
+            path = store._find_path_by_task_id(task_id)
+        except Exception:
+            return
+        if path is None:
+            return
+        try:
+            payload = store._load_path(path) or {}
+        except Exception:
+            return
+        history = list(payload.get("compression_history", []) or [])
+        history.append({
+            "before_tokens": getattr(result, "before_tokens", 0),
+            "after_tokens": getattr(result, "after_tokens", 0),
+            "method": getattr(result, "method", "unknown"),
+            "pruned": getattr(result, "pruned_tool_results", 0),
+            "deduped": getattr(result, "deduplicated_files", 0),
+            "at": getattr(result, "at", ""),
+        })
+        payload["compression_history"] = history[-20:]
+        try:
+            store._atomic_write(path, payload)
+        except Exception:
+            return
+
+    def _persist_evidence(self, task_id: str, result: Any) -> None:
+        """把 AgentResult 里的结构化 evidence（tool.evidence dicts）写回 TaskRecord。"""
+        store = self._session_store
+        if store is None or not task_id or not hasattr(store, "get_task"):
+            return
+        try:
+            rec = store.get_task(task_id)
+        except Exception:
+            return
+        if rec is None:
+            return
+        evidence: list[dict[str, Any]] = []
+        steps = getattr(result, "steps", []) or []
+        for step in steps:
+            for tool_exec in getattr(step, "tool_execs", []) or []:
+                if not getattr(tool_exec, "success", False):
+                    continue
+                structured = dict(getattr(tool_exec, "evidence", {}) or {})
+                if structured:
+                    evidence.append({"tool": getattr(tool_exec, "name", ""), **structured})
+        if not evidence:
+            return
+        # 追加到 compression_history 后面（用同样的 append-only 模式）
+        existing = list(getattr(rec, "compression_history", []) or [])
+        existing.append({
+            "type": "structured_evidence",
+            "task_id": task_id,
+            "evidence": evidence[:20],  # 上限 20 条
+            "at": getattr(rec, "updated_at", ""),
+        })
+        try:
+            # 用 update_task 强制持久化（这里要直接 atomic_write；走 store 的方法）
+            path = store._find_path_by_task_id(task_id)
+            if path is None:
+                return
+            payload = store._load_path(path) or {}
+            payload["compression_history"] = existing[-20:]
+            store._atomic_write(path, payload)
+        except Exception:
+            return
+
+    def _update_task_status(self, task_id: str, status: str, **fields) -> None:
+        """把子 agent 状态写回 TaskRecord（如果 session_store 支持）。"""
+        store = self._session_store
+        if store is None or not task_id:
+            return
+        if not hasattr(store, "update_task"):
+            return
+        _TaskStatus = getattr(__import__('memory.task_contracts', fromlist=['TaskStatus']), 'TaskStatus')
+        try:
+            store.update_task(task_id, TaskStatus(status), **fields)
+        except Exception:
+            return
+
+    # ── 同步运行（方便 CLI 用）──────────────────────
+
+    def _verify_worker_result(self, task_id: str, config: AgentConfig, result: AgentResult) -> AgentResult:
+        rules = set(getattr(config, 'verification_rules', []) or [])
+        if 'worker_result' not in rules:
+            return result
+        evidence: list[str] = []
+        if result.content.strip():
+            # 文本本身只是 summary，不当作 evidence；证据必须来自工具、artifact 或显式步骤。
+            pass
+        for step in result.steps or []:
+            for tool_exec in getattr(step, 'tool_execs', []) or []:
+                if getattr(tool_exec, 'success', False):
+                    evidence.append(f"tool:{getattr(tool_exec, 'name', '')}")
+        worker_result = WorkerResult(
+            task_id=task_id,
+            status='success' if result.success else 'error',
+            summary=result.content or result.error,
+            evidence=evidence,
+            confidence=1.0 if result.success else 0.0,
+            blocking_issues=[result.error] if result.error else [],
+        )
+        # "worker_result" rule 强约束 evidence；其他情况松散
+        require_ev = "worker_result" in rules
+        verification = WorkerResultVerifier(require_evidence=require_ev).verify(worker_result)
+        if verification.passed:
+            return result
+        reason = '; '.join(verification.missing_items)
+        result.success = False
+        result.error = f"worker_result 验证未通过: {reason}"
+        return result
+
+
+
+    def build_worker_report(self, task_id: str, config: AgentConfig, result: AgentResult) -> dict[str, Any]:
+        """Machine-readable worker verification/failure propagation report."""
+        return {
+            "scope": "orchestration",
+            "network": "disabled",
+            "ui_gateway": "locked",
+            "task_id": task_id,
+            "agent": config.name,
+            "status": "success" if result.success else "error",
+            "failure_propagated": not result.success,
+            "error": result.error or "",
+            "summary": result.content or "",
+            "verification_rules": list(config.verification_rules or []),
+            "steps": len(result.steps or []),
+        }
+    def run_agent_sync(self, agent_name: str, task: str, context: str = "", session_id: str = "", task_id: str = "", conversation_id: str = "", run_id: str = "", on_chunk=None, think_mode: bool = False, deep_search: bool = False) -> AgentResult:
+        from runtime.memory.session.session_context import bind_identity, reset_identity
+        from runtime.memory.session.identity import ConversationIdentity
+        identity = ConversationIdentity.create(
+            conversation_id=conversation_id or session_id or task_id,
+            session_id=session_id,
+            run_id=run_id or f"run-{uuid.uuid4().hex}",
+            task_id=task_id,
+        )
+        identity_token = bind_identity(identity)
+        try:
+            return self._run_bound_agent_sync(
+                agent_name, task, context, session_id, conversation_id, run_id, task_id,
+                on_chunk, think_mode, deep_search,
+            )
+        finally:
+            reset_identity(identity_token)
+
+    @staticmethod
+    def _build_context_with_memory(context: str, memory_text: str) -> str:
+        """将跨会话记忆追加到 context 中。"""
+        if not memory_text or not memory_text.strip():
+            return context
+        if context:
+            return context + "\n\n" + memory_text
+        return memory_text
+
+    def _run_bound_agent_sync(self, agent_name, task, context, session_id, conversation_id, run_id, task_id, on_chunk, think_mode, deep_search):
+        initial_messages = None
+        checkpoint_cp = None
+        if session_id:
+            raw_messages = list(self._session_store.load_session_messages(session_id))
+            # P1-2: session 历史预压缩（去工具结果 + gate）
+            if raw_messages:
+                try:
+                    from runtime.context.management.context_manager import ContextManager
+                    cm = ContextManager(max_chars=60000, context_length=128000,
+                                        threshold_percent=0.50, protect_first_n=3, protect_last_n=12)
+                    compressed, comp_result = cm.compress_if_needed(raw_messages)
+                    if comp_result.method != "none":
+                        logger.info("Session history pre-compressed: method=%s removed=%d",
+                                    comp_result.method, comp_result.removed_count)
+                    initial_messages = compressed
+                except Exception as e:
+                    logger.warning("Session pre-compression failed: %s, fallback raw", e)
+                    initial_messages = raw_messages
+            else:
+                initial_messages = raw_messages
+        # 尝试加载 checkpoint（完整状态恢复）
+        if task_id:
+            try:
+                from runtime.orchestration.runtime.checkpoint import CheckpointStore
+                cp_store = CheckpointStore(self._session_store)
+                checkpoint_cp = cp_store.load(task_id)
+            except Exception:
+                pass
+
+        # P0-B: 跨会话记忆召回 — 从 LongTermMemory prefetch 相关历史
+        try:
+            from runtime.memory.providers.long_term import LongTermMemoryProvider
+            ltm_provider = LongTermMemoryProvider()
+            ltm_provider.initialize(session_id or "default", agent_name=agent_name)
+            memory_text = ltm_provider.prefetch(task, limit=3)
+            context = self._build_context_with_memory(context, memory_text)
+            if memory_text:
+                logger.info("[prefetch] injected cross-session memory for %s (%d chars)",
+                            agent_name, len(memory_text))
+        except Exception as e:
+            logger.debug("[prefetch] skipped (non-critical): %s", e)
+
+        # conversation_id 由外部传入；只有完全没有外部身份时才兼容回退到 session_id/task_id
+        resolved_conversation_id = conversation_id or session_id or task_id
+        actual_run_id = run_id or f"run-{uuid.uuid4().hex}"
+        actual_task_id = self.start_agent(
+            agent_name,
+            task,
+            context,
+            initial_messages=initial_messages,
+            task_id=task_id,
+            session_id=session_id,
+            conversation_id=resolved_conversation_id,
+            run_id=actual_run_id,
+            on_chunk=on_chunk,
+            think_mode=think_mode,
+            deep_search=deep_search,
+        )
+        if session_id:
+            with self._lock:
+                record = self._agents.get(actual_task_id)
+            if record and record.loop:
+                record.loop.session_id = session_id
+                # P1-2: 如果有 checkpoint，恢复完整状态
+                if checkpoint_cp:
+                    try:
+                        record.loop._tool_call_count = checkpoint_cp.tool_call_count
+                        if checkpoint_cp.current_model:
+                            record.loop._current_model = checkpoint_cp.current_model
+                        if checkpoint_cp.compression_results:
+                            record.loop.compression_results = list(checkpoint_cp.compression_results)
+                        record.loop._stall_count = checkpoint_cp.stall_count
+                        record.loop._last_progress_signature = checkpoint_cp.last_progress_signature
+                        logger.info(
+                            "[resume] restored from checkpoint: iteration=%d, tools=%d, model=%s",
+                            checkpoint_cp.iteration, checkpoint_cp.tool_call_count, checkpoint_cp.current_model,
+                        )
+                    except Exception:
+                        logger.exception("[resume] failed to restore checkpoint state")
+        return self.wait_one(actual_task_id)
+
+    # ── 监控 ───────────────────────────────────────
+
+    def get_status(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                tid: {
+                    "agent_name": r.task.agent_name,
+                    "task": r.task.task[:60],
+                    "status": getattr(r.status, "value", r.status),
+                    "running_time": round(time.time() - r.started_at, 1) if r.is_running else 0,
+                    "iterations": r.loop.current_iteration if r.loop else 0,
+                    "tool_calls": r.loop._tool_call_count if r.loop else 0,
+                    "last_step": r.loop.steps[-1].summary if r.loop and r.loop.steps else "",
+                }
+                for tid, r in self._agents.items()
+            }
+
+    def wait_all(self, timeout: float = 600) -> None:
+        with self._lock:
+            records = list(self._agents.values())
+        for r in records:
+            if r.future and not r.future.done():
+                r.future.result(timeout=timeout)
+
+    def wait_one(self, task_id: str, timeout: float = 600) -> Optional[AgentResult]:
+        """等待 worker；超时结果一旦写入即为终态。"""
+        from concurrent.futures import TimeoutError as FutureTimeoutError
+
+        with self._lock:
+            record = self._agents.get(task_id)
+        if not record or not record.future:
+            return None
+        try:
+            record.future.result(timeout=timeout)
+            return record.result
+        except FutureTimeoutError:
+            with self._lock:
+                if record.status in (AgentStatus.TIMEOUT, AgentStatus.CANCELLED):
+                    return record.result
+                if record.loop is not None:
+                    record.loop.cancel()
+                record.status = AgentStatus.TIMEOUT
+                record.result = AgentResult(
+                    success=False,
+                    error="timeout",
+                    content=f"等待任务 {task_id} 超时（{timeout}s）",
+                    agent_name=record.task.agent_name,
+                )
+                timeout_result = record.result
+            if self._session_store is not None:
+                self._session_store.update_task_status(
+                    task_id, "timeout", error=f"wait timeout after {timeout}s", event="wait_timeout"
+                )
+            return timeout_result
+
+    def get_results(self) -> dict[str, AgentResult]:
+        with self._lock:
+            return {tid: r.result for tid, r in self._agents.items() if r.result}
+
+
+
+    def can_spawn_child(self, current_depth: int = 0) -> dict[str, Any]:
+        """Return whether orchestration may spawn another child at this depth."""
+        max_depth = self.app_config.agents.global_config.max_spawn_depth
+        allowed = current_depth < max_depth
+        return {
+            "allowed": allowed,
+            "current_depth": current_depth,
+            "max_spawn_depth": max_depth,
+            "reason": "within locked orchestration depth" if allowed else "locked: max_spawn_depth reached",
+        }
+
+    def build_dry_run_plan(self, agent_name: str, task: str, current_depth: int = 0) -> dict[str, Any]:
+        """Build a machine-readable offline orchestration plan. No LLM/network call."""
+        get_agent = __import__('config.config', fromlist=['get_agent']).get_agent
+
+        agent_entry = get_agent(self.app_config, agent_name)
+        if not agent_entry:
+            raise ValueError(f"Agent '{agent_name}' not found in runtime/core/sub_agents/agents.yaml")
+        provider = self._resolve_provider(agent_entry)
+        model_chain = list(agent_entry.model_chain or [])
+        if not model_chain and getattr(agent_entry, "model", ""):
+            model_chain = [agent_entry.model]
+        tools = list(getattr(agent_entry, "tools", []) or [])
+        verification = list(getattr(agent_entry, "verification_rules", []) or [])
+        return {
+            "scope": "llm+orchestration",
+            "network": "disabled",
+            "ui_gateway": "locked",
+            "agent": agent_name,
+            "task": task,
+            "will_build_agent_loop": True,
+            "llm_call": "disabled",
+            "provider": agent_entry.provider or self.app_config.models.default_provider,
+            "api_mode": getattr(provider, "api_mode", "") if provider else "",
+            "model_chain": model_chain,
+            "keys": len(provider.all_keys) if provider else 0,
+            "tools": tools,
+            "verification": verification,
+            "timeout": getattr(agent_entry, "timeout", 0),
+            "max_iterations": getattr(agent_entry, "max_iterations", 0),
+            "spawn_boundary": self.can_spawn_child(current_depth=current_depth),
+            "contract": {"passed": True, "error_count": 0, "warning_count": 0, "items": []},
+        }
+    # ── 通信 ───────────────────────────────────────
+
+    def send_to_agent(self, task_id: str, message: str) -> bool:
+        with self._lock:
+            record = self._agents.get(task_id)
+        if record and record.loop and record.is_running:
+            record.loop.send_message(message)
+            return True
+        return False
+
+    def cancel_agent(self, task_id: str) -> bool:
+        with self._lock:
+            record = self._agents.get(task_id)
+        if record and record.loop and record.is_running:
+            record.loop.cancel()
+            return True
+        return False
+
+
+
+    # ── DAG 执行器 ───────────────────────────────────
+
+    def execute_dag(self, dag_json: str, parent_context: str = "") -> dict[str, Any]:
+        """执行一个 JSON DAG 计划。
+
+        流程：
+          1. 解析 planner 输出的 JSON DAG
+          2. 按依赖顺序（拓扑排序）逐步执行
+          3. 每步根据 agent 字段分配给对应子 agent
+          4. 前一步的结果作为后一步的 context
+          5. 失败则停止，返回已完成步骤
+
+        返回：
+          {
+            "success": bool,
+            "completed_steps": int,
+            "total_steps": int,
+            "results": {step_id: AgentResult},
+            "error": str,
+          }
+        """
+        import json as _json
+
+        # 解析 DAG
+        try:
+            dag = _json.loads(dag_json) if isinstance(dag_json, str) else dag_json
+        except (ValueError, TypeError):
+            # 尝试提取 JSON
+            s = dag_json.find("{")
+            e = dag_json.rfind("}")
+            if s >= 0 and e > s:
+                dag = _json.loads(dag_json[s:e+1])
+            else:
+                return {"success": False, "error": "无效 JSON", "completed_steps": 0, "total_steps": 0, "results": {}}
+
+        steps = dag.get("steps") or dag.get("dag", {}).get("steps", [])
+        if not steps:
+            return {"success": False, "error": "DAG 无 steps", "completed_steps": 0, "total_steps": 0, "results": {}}
+
+        # 拓扑排序
+        ordered = self._topo_sort(steps)
+        if ordered is None:
+            return {"success": False, "error": "DAG 依赖环", "completed_steps": 0, "total_steps": len(steps), "results": {}}
+
+        results: dict[str, AgentResult] = {}
+        step_contexts: dict[str, str] = {}
+        completed = 0
+
+        for step in ordered:
+            step_id = step.get("id", f"step_{completed+1}")
+            description = step.get("description") or step.get("name") or step.get("task", "")
+            agent_name = step.get("agent") or step.get("agent_name", "")
+            deps = step.get("depends_on") or step.get("dependencies") or step.get("deps", [])
+
+            # 收集依赖步骤的输出作为 context
+            dep_results = []
+            for dep_id in deps:
+                if dep_id in results and results[dep_id].success:
+                    dep_results.append(f"[{dep_id} 结果] {results[dep_id].content[:300]}")
+            dep_context = "\n".join(dep_results) if dep_results else parent_context
+
+            # 默认 agent：没有指定就用 code agent
+            if not agent_name:
+                agent_name = "code"
+
+            logger.info("[DAG] 执行步骤 %s: agent=%s, desc=%s", step_id, agent_name, description[:80])
+
+            # 检查 agent 是否存在
+            get_agent = __import__('config.config', fromlist=['get_agent']).get_agent
+            agent_entry = get_agent(self.app_config, agent_name)
+            if not agent_entry:
+                results[step_id] = AgentResult(
+                    success=False, error=f"Agent '{agent_name}' 不存在",
+                    agent_name=agent_name,
+                )
+                break
+
+            # 执行
+            try:
+                result = self.run_agent_sync(agent_name, description, context=dep_context)
+                results[step_id] = result
+                if result.success:
+                    completed += 1
+                else:
+                    # 失败：停止后续步骤
+                    logger.warning("[DAG] 步骤 %s 失败: %s", step_id, result.error)
+                    break
+            except Exception as e:
+                results[step_id] = AgentResult(
+                    success=False, error=str(e), agent_name=agent_name,
+                )
+                logger.exception("[DAG] 步骤 %s 异常", step_id)
+                break
+
+        all_success = completed == len(ordered)
+        return {
+            "success": all_success,
+            "completed_steps": completed,
+            "total_steps": len(ordered),
+            "results": {k: v for k, v in results.items()},
+            "error": "" if all_success else f"完成 {completed}/{len(ordered)} 步",
+        }
+
+    def _topo_sort(self, steps: list[dict]) -> list[dict] | None:
+        """拓扑排序 DAG 步骤。返回 None 表示有环。"""
+        # 建依赖图
+        step_map = {}
+        for s in steps:
+            sid = s.get("id", "")
+            deps = s.get("depends_on") or s.get("dependencies") or s.get("deps", [])
+            step_map[sid] = list(deps)
+
+        # Kahn 算法
+        result = []
+        no_deps = [s for s in steps if not (s.get("depends_on") or s.get("dependencies") or s.get("deps", []))]
+
+        resolved = set()
+        remaining = list(steps)
+
+        while remaining:
+            progressed = False
+            for s in list(remaining):
+                sid = s.get("id", "")
+                deps = s.get("depends_on") or s.get("dependencies") or s.get("deps", [])
+                if all(d in resolved for d in deps):
+                    result.append(s)
+                    resolved.add(sid)
+                    remaining.remove(s)
+                    progressed = True
+
+            if not progressed and remaining:
+                return None  # 环
+
+        return result
+
+    # ── 构建配置 ───────────────────────────────────
+
+    def _build_agent_config(self, agent_entry) -> AgentConfig:
+        """构建运行时 AgentConfig；运行时依赖必须来自 runtime_factory。"""
+        if self.runtime_factory is None:
+            raise RuntimeError("Orchestrator requires an injected runtime_factory")
+        cfg = self.runtime_factory.build_agent_config(agent_entry)
+        cfg.event_bus = self.event_bus
+        return cfg
+
+    def _resolve_provider(self, agent_entry):
+        """委托 runtime_factory 解析 provider；保持调用方兼容。"""
+        if self.runtime_factory is None:
+            return None
+        return self.runtime_factory.resolve_provider(agent_entry)
+
+    # _build_llm_client 已废弃 —— ModelRouter 接管了 client 创建 + fallback + key 轮转
+
+    # _load_system_prompt 已删除 — runtime_factory.load_system_prompt() 负责加载。
+
+    # ── 内部回调 ───────────────────────────────────
+
+    def _on_status(self, task_id: str, agent_name: str, status: AgentStatus):
+        with self._lock:
+            if task_id in self._agents:
+                record = self._agents[task_id]
+                if record.status not in (AgentStatus.TIMEOUT, AgentStatus.CANCELLED):
+                    record.status = status
+        if self.on_agent_status:
+            self.on_agent_status(task_id, agent_name, status)
+
+    def _on_step(self, task_id: str, agent_name: str, step: LoopStep):
+        if self.on_agent_step:
+            self.on_agent_step(task_id, agent_name, step)
+
+    def shutdown(self):
+        with self._lock:
+            for tid, r in self._agents.items():
+                if r.is_running and r.loop:
+                    r.loop.cancel()
+        self._executor.shutdown(wait=True)
+
+    def run_agents_with_dependencies(self, tasks: list[Any], parent_task_id: str = "", use_arbiter: bool = True):
+        """按 depends_on 拓扑执行多个 Agent。
+
+        tasks: list[SubAgentTask]
+        返回 (task_ids, merged_result_or_None)
+        merged_result 是 Arbiter 合并结果；use_arbiter=False 时返回 None。
+        """
+        from types import SimpleNamespace
+        from runtime.orchestration.runtime.arbiter import Arbiter
+
+        task_ids: list[str] = []
+        submitted: set[str] = set()
+        completed: set[str] = set()
+        worker_results: list[Any] = []
+
+        while len(submitted) < len(tasks):
+            ready = [
+                t for t in tasks
+                if t.task_id not in submitted
+                and all(dep in completed for dep in (getattr(t, "depends_on", None) or []))
+            ]
+            if not ready:
+                blocked = [t.task_id for t in tasks if t.task_id not in submitted]
+                raise ValueError(f"依赖阻塞或循环: {blocked}")
+
+            wave = ready[: self._max_concurrent]
+            wave_ids: list[str] = []
+            for t in wave:
+                tid = self.start_agent(
+                    t.agent_name,
+                    t.task,
+                    t.context,
+                    parent_task_id=parent_task_id,
+                    depends_on=getattr(t, "depends_on", None) or [],
+                    task_id=t.task_id,
+                )
+                t.task_id = tid
+                submitted.add(tid)
+                wave_ids.append(tid)
+
+            for tid in wave_ids:
+                result = self.wait_one(tid)
+                if result and result.success:
+                    completed.add(tid)
+                task_ids.append(tid)
+                # 收集 worker_result 供 Arbiter
+                if use_arbiter and result is not None:
+                    worker_results.append(SimpleNamespace(
+                        task_id=tid,
+                        status="success" if result.success else "error",
+                        summary=result.content or result.error or "",
+                        evidence=[],
+                        blocking_issues=[result.error] if (not result.success and result.error) else [],
+                        confidence=1.0 if result.success else 0.0,
+                    ))
+
+        merged = None
+        if use_arbiter and worker_results:
+            merged = Arbiter().merge(worker_results)
+        return task_ids, merged