refactor(runtime): restructure runs module with new execution architecture

Major refactoring of deerflow/runtime/:
- runs/callbacks/ - new callback system (builder, events, title, tokens)
- runs/internal/ - execution internals (executor, supervisor, stream_logic, registry)
- runs/internal/execution/ - execution artifacts and events handling
- runs/facade.py - high-level run facade
- runs/observer.py - run observation protocol
- runs/types.py - type definitions
- runs/store/ - simplified store interfaces (create, delete, query, event)

Refactor stream_bridge/:
- Replace old providers with contract.py and exceptions.py
- Remove async_provider.py, base.py, memory.py

Add documentation:
- README.md and README_zh.md for runtime module

Remove deprecated:
- manager.py moved to internal/
- worker.py, schemas.py
- user_context.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/packages/harness/deerflow/runtime/runs/store/__init__.py

@@ -1,4 +1,13 @@
-from deerflow.runtime.runs.store.base import RunStore
-from deerflow.runtime.runs.store.memory import MemoryRunStore
+"""Store boundary protocols for runs."""
 
-__all__ = ["MemoryRunStore", "RunStore"]
+from .create_store import RunCreateStore
+from .delete_store import RunDeleteStore
+from .event_store import RunEventStore
+from .query_store import RunQueryStore
+
+__all__ = [
+    "RunCreateStore",
+    "RunDeleteStore",
+    "RunEventStore",
+    "RunQueryStore",
+]

backend/packages/harness/deerflow/runtime/runs/store/base.py

@@ -1,95 +0,0 @@
-"""Abstract interface for run metadata storage.
-
-RunManager depends on this interface. Implementations:
-- MemoryRunStore: in-memory dict (development, tests)
-- Future: RunRepository backed by SQLAlchemy ORM
-
-All methods accept an optional user_id for user isolation.
-When user_id is None, no user filtering is applied (single-user mode).
-"""
-
-from __future__ import annotations
-
-import abc
-from typing import Any
-
-
-class RunStore(abc.ABC):
-    @abc.abstractmethod
-    async def put(
-        self,
-        run_id: str,
-        *,
-        thread_id: str,
-        assistant_id: str | None = None,
-        user_id: str | None = None,
-        status: str = "pending",
-        multitask_strategy: str = "reject",
-        metadata: dict[str, Any] | None = None,
-        kwargs: dict[str, Any] | None = None,
-        error: str | None = None,
-        created_at: str | None = None,
-    ) -> None:
-        pass
-
-    @abc.abstractmethod
-    async def get(self, run_id: str) -> dict[str, Any] | None:
-        pass
-
-    @abc.abstractmethod
-    async def list_by_thread(
-        self,
-        thread_id: str,
-        *,
-        user_id: str | None = None,
-        limit: int = 100,
-    ) -> list[dict[str, Any]]:
-        pass
-
-    @abc.abstractmethod
-    async def update_status(
-        self,
-        run_id: str,
-        status: str,
-        *,
-        error: str | None = None,
-    ) -> None:
-        pass
-
-    @abc.abstractmethod
-    async def delete(self, run_id: str) -> None:
-        pass
-
-    @abc.abstractmethod
-    async def update_run_completion(
-        self,
-        run_id: str,
-        *,
-        status: str,
-        total_input_tokens: int = 0,
-        total_output_tokens: int = 0,
-        total_tokens: int = 0,
-        llm_call_count: int = 0,
-        lead_agent_tokens: int = 0,
-        subagent_tokens: int = 0,
-        middleware_tokens: int = 0,
-        message_count: int = 0,
-        last_ai_message: str | None = None,
-        first_human_message: str | None = None,
-        error: str | None = None,
-    ) -> None:
-        pass
-
-    @abc.abstractmethod
-    async def list_pending(self, *, before: str | None = None) -> list[dict[str, Any]]:
-        pass
-
-    @abc.abstractmethod
-    async def aggregate_tokens_by_thread(self, thread_id: str) -> dict[str, Any]:
-        """Aggregate token usage for completed runs in a thread.
-
-        Returns a dict with keys: total_tokens, total_input_tokens,
-        total_output_tokens, total_runs, by_model (model_name → {tokens, runs}),
-        by_caller ({lead_agent, subagent, middleware}).
-        """
-        pass

backend/packages/harness/deerflow/runtime/runs/store/create_store.py

@@ -0,0 +1,13 @@
+"""Create-side boundary for durable run initialization."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..types import RunRecord
+
+
+class RunCreateStore(Protocol):
+    """Persist the initial durable row for a newly created run."""
+
+    async def create_run(self, record: RunRecord) -> None: ...

backend/packages/harness/deerflow/runtime/runs/store/delete_store.py

@@ -0,0 +1,11 @@
+"""Delete-side durable boundary for runs."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class RunDeleteStore(Protocol):
+    """Minimal protocol for removing durable run records."""
+
+    async def delete_run(self, run_id: str) -> bool: ...

backend/packages/harness/deerflow/runtime/runs/store/event_store.py

@@ -0,0 +1,11 @@
+"""Run event store boundary used by runs callbacks."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class RunEventStore(Protocol):
+    """Minimal append-only event store protocol for execution callbacks."""
+
+    async def put_batch(self, events: list[dict[str, Any]]) -> list[dict[str, Any]]: ...

backend/packages/harness/deerflow/runtime/runs/store/memory.py

@@ -1,98 +0,0 @@
-"""In-memory RunStore. Used when database.backend=memory (default) and in tests.
-
-Equivalent to the original RunManager._runs dict behavior.
-"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime
-from typing import Any
-
-from deerflow.runtime.runs.store.base import RunStore
-
-
-class MemoryRunStore(RunStore):
-    def __init__(self) -> None:
-        self._runs: dict[str, dict[str, Any]] = {}
-
-    async def put(
-        self,
-        run_id,
-        *,
-        thread_id,
-        assistant_id=None,
-        user_id=None,
-        status="pending",
-        multitask_strategy="reject",
-        metadata=None,
-        kwargs=None,
-        error=None,
-        created_at=None,
-    ):
-        now = datetime.now(UTC).isoformat()
-        self._runs[run_id] = {
-            "run_id": run_id,
-            "thread_id": thread_id,
-            "assistant_id": assistant_id,
-            "user_id": user_id,
-            "status": status,
-            "multitask_strategy": multitask_strategy,
-            "metadata": metadata or {},
-            "kwargs": kwargs or {},
-            "error": error,
-            "created_at": created_at or now,
-            "updated_at": now,
-        }
-
-    async def get(self, run_id):
-        return self._runs.get(run_id)
-
-    async def list_by_thread(self, thread_id, *, user_id=None, limit=100):
-        results = [r for r in self._runs.values() if r["thread_id"] == thread_id and (user_id is None or r.get("user_id") == user_id)]
-        results.sort(key=lambda r: r["created_at"], reverse=True)
-        return results[:limit]
-
-    async def update_status(self, run_id, status, *, error=None):
-        if run_id in self._runs:
-            self._runs[run_id]["status"] = status
-            if error is not None:
-                self._runs[run_id]["error"] = error
-            self._runs[run_id]["updated_at"] = datetime.now(UTC).isoformat()
-
-    async def delete(self, run_id):
-        self._runs.pop(run_id, None)
-
-    async def update_run_completion(self, run_id, *, status, **kwargs):
-        if run_id in self._runs:
-            self._runs[run_id]["status"] = status
-            for key, value in kwargs.items():
-                if value is not None:
-                    self._runs[run_id][key] = value
-            self._runs[run_id]["updated_at"] = datetime.now(UTC).isoformat()
-
-    async def list_pending(self, *, before=None):
-        now = before or datetime.now(UTC).isoformat()
-        results = [r for r in self._runs.values() if r["status"] == "pending" and r["created_at"] <= now]
-        results.sort(key=lambda r: r["created_at"])
-        return results
-
-    async def aggregate_tokens_by_thread(self, thread_id: str) -> dict[str, Any]:
-        completed = [r for r in self._runs.values() if r["thread_id"] == thread_id and r.get("status") in ("success", "error")]
-        by_model: dict[str, dict] = {}
-        for r in completed:
-            model = r.get("model_name") or "unknown"
-            entry = by_model.setdefault(model, {"tokens": 0, "runs": 0})
-            entry["tokens"] += r.get("total_tokens", 0)
-            entry["runs"] += 1
-        return {
-            "total_tokens": sum(r.get("total_tokens", 0) for r in completed),
-            "total_input_tokens": sum(r.get("total_input_tokens", 0) for r in completed),
-            "total_output_tokens": sum(r.get("total_output_tokens", 0) for r in completed),
-            "total_runs": len(completed),
-            "by_model": by_model,
-            "by_caller": {
-                "lead_agent": sum(r.get("lead_agent_tokens", 0) for r in completed),
-                "subagent": sum(r.get("subagent_tokens", 0) for r in completed),
-                "middleware": sum(r.get("middleware_tokens", 0) for r in completed),
-            },
-        }

backend/packages/harness/deerflow/runtime/runs/store/query_store.py

@@ -0,0 +1,20 @@
+"""Read-side boundary for durable run queries."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..types import RunRecord
+
+
+class RunQueryStore(Protocol):
+    """Read durable run records for public query APIs."""
+
+    async def get_run(self, run_id: str) -> RunRecord | None: ...
+
+    async def list_runs(
+        self,
+        thread_id: str,
+        *,
+        limit: int = 100,
+    ) -> list[RunRecord]: ...