agent-Specialization/server/runtime/context.py

"""运行时上下文模型（RuntimeContext 三层分离）。

契约见 docs/runtime_contract.md §4.1：

- ``TrustedPrincipal``：可信身份与资源范围。只能由适配层在完成认证后构造；
  禁止接受客户端或未来 Schedule payload 自报的 role/is_api_user。
- ``TaskParams``：本次任务参数（消息、媒体、模型/模式覆盖等）。
- ``InternalDirectives``：内部执行信息（门闸 token、通知回放等），
  仅内部调用方（通知链/工作流/派发器）使用，普通客户端不可提交。

默认值解析优先级：本次显式传参（TaskParams）> 对话元数据绑定 >
用户偏好快照（TrustedPrincipal.preferred_*）> 系统默认。
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional


@dataclass(frozen=True)
class TrustedPrincipal:
    """可信身份与资源范围（适配层认证后构造）。

    preferred_* 是「用户偏好快照」：资源装配（get_user_resources）新建 terminal 时
    的默认值来源；与 TaskParams 中的「本次覆盖」字段语义不同，不要混用。
    """

    username: str
    workspace_id: str
    role: str = "user"
    is_api_user: bool = False
    host_mode: bool = False
    host_workspace_id: Optional[str] = None
    preferred_model_key: Optional[str] = None
    preferred_run_mode: Optional[str] = None
    preferred_thinking_mode: Optional[bool] = None

    def validate(self) -> None:
        if not str(self.username or "").strip():
            raise ValueError("runtime_context: username 不能为空")
        if not str(self.workspace_id or "").strip():
            raise ValueError("runtime_context: workspace_id 不能为空")


@dataclass(frozen=True)
class TaskParams:
    """本次任务参数（优先级最高的覆盖层）。"""

    message: str = ""
    images: List[Any] = field(default_factory=list)
    videos: List[Any] = field(default_factory=list)
    files: List[str] = field(default_factory=list)
    conversation_id: Optional[str] = None
    model_key: Optional[str] = None
    run_mode: Optional[str] = None
    thinking_mode: Optional[bool] = None
    max_iterations: Optional[int] = None
    goal_mode: bool = False
    skill_context_messages: List[Dict[str, str]] = field(default_factory=list)
    message_source: Optional[str] = None
    task_type: str = "chat"
    # 审批/提问等待超时透传（秒）。None = 保持既有默认语义（3600s）不变；
    # 超时后的语义（拒绝当前动作继续 vs 结束任务）属阶段三产品决策，
    # 本阶段仅建立透传机制，适配层暂不向 Web 客户端暴露该字段。
    approval_timeout_seconds: Optional[int] = None

    def validate(self) -> None:
        if self.run_mode is not None:
            normalized = str(self.run_mode).lower()
            if normalized not in {"fast", "thinking", "deep"}:
                raise ValueError("runtime_context: run_mode 只支持 fast/thinking/deep")


@dataclass(frozen=True)
class InternalDirectives:
    """内部执行信息。仅内部调用方使用；HTTP 适配层禁止从请求体构造本结构。"""

    # 派发方预占的主任务门闸 token，随任务移交由任务线程认领
    main_task_gate_token: Optional[str] = None
    # 通知类任务：把 user 消息写入任务事件流，保证轮询客户端/刷新后可见
    auto_user_message_event: bool = False
    auto_user_message_payload: Optional[Dict[str, Any]] = None
    # 本批通知池中除触发消息外的前置通知，随任务事件流回放
    preceding_user_notices: Optional[List[Dict[str, Any]]] = None


@dataclass(frozen=True)
class RuntimeContext:
    """一轮 Run 的完整显式上下文：可信身份 + 任务参数 + 内部指令。"""

    principal: TrustedPrincipal
    params: TaskParams
    directives: InternalDirectives = field(default_factory=InternalDirectives)

    def validate(self) -> None:
        self.principal.validate()
        self.params.validate()

    @classmethod
    def from_terminal(
        cls,
        terminal: Any,
        workspace: Any,
        username: str,
        params: TaskParams,
        directives: Optional[InternalDirectives] = None,
    ) -> "RuntimeContext":
        """从对话级 terminal/工作区构造（通知链、多智能体派发等内部调用方）。

        与既有 session_data 手工构造逐字段对齐：
        host_mode 取 workspace.username == "host"；偏好快照取 terminal 当前值。
        """
        workspace_id = getattr(workspace, "workspace_id", None) or "default"
        host_mode = bool(getattr(workspace, "username", None) == "host")
        role = getattr(terminal, "user_role", None) or "user"
        return cls(
            principal=TrustedPrincipal(
                username=username,
                workspace_id=workspace_id,
                role=role,
                is_api_user=(role == "api"),
                host_mode=host_mode,
                host_workspace_id=workspace_id if host_mode else None,
                preferred_model_key=getattr(terminal, "model_key", None),
                preferred_run_mode=getattr(terminal, "run_mode", None),
                preferred_thinking_mode=getattr(terminal, "thinking_mode", None),
            ),
            params=params,
            directives=directives or InternalDirectives(),
        )

    def to_session_data(self) -> Dict[str, Any]:
        """兼容转换：合并为现有 ``create_chat_task`` 的 session_data 快照 dict。

        快照在受理时固化、随任务线程传递：身份/偏好由 ``_run_chat_task`` 还原为
        ``RuntimeIdentity`` 驱动资源装配（无 Flask 隐式上下文）；门闸移交
        （main_task_gate_token）、事件注入（auto_user_message_*）、terminal 属性
        设置（message_source/goal_mode/skill_context_messages）语义不变。

        其中 run_mode/thinking_mode/model_key 取「用户偏好快照」层
        （principal.preferred_*），供资源装配新建 terminal 时恢复默认值；
        本次覆盖值（params.*）由 RuntimeService.create_task 走显式参数传递，
        不进入本快照。
        """
        p = self.principal
        session_data: Dict[str, Any] = {
            "username": p.username,
            "role": p.role,
            "is_api_user": p.is_api_user,
            "host_mode": p.host_mode,
            "host_workspace_id": p.host_workspace_id or (p.workspace_id if p.host_mode else None),
            "workspace_id": p.workspace_id,
            "run_mode": p.preferred_run_mode,
            "thinking_mode": p.preferred_thinking_mode,
            "model_key": p.preferred_model_key,
            "message_source": self.params.message_source,
            "goal_mode": bool(self.params.goal_mode),
            "skill_context_messages": list(self.params.skill_context_messages or []),
        }
        if self.params.approval_timeout_seconds is not None:
            session_data["approval_timeout_seconds"] = int(self.params.approval_timeout_seconds)
        d = self.directives
        if d.main_task_gate_token:
            session_data["main_task_gate_token"] = d.main_task_gate_token
        if d.auto_user_message_event:
            session_data["auto_user_message_event"] = True
        if d.auto_user_message_payload:
            session_data["auto_user_message_payload"] = dict(d.auto_user_message_payload)
        if d.preceding_user_notices:
            session_data["preceding_user_notices"] = list(d.preceding_user_notices)
        return session_data


def principal_from_session_snapshot(
    session_snapshot: Dict[str, Any],
    workspace_id: str,
    username: Optional[str] = None,
) -> TrustedPrincipal:
    """适配层工具：从 Flask session（或其 dict 快照）构造可信 principal。

    调用方必须在完成认证后调用；``session_snapshot`` 由适配层显式传入
    （本模块不 import flask，保持服务层可测试、无隐式上下文依赖）。
    """
    snap = session_snapshot or {}
    resolved_workspace = str(workspace_id or snap.get("workspace_id") or "default")
    host_mode = bool(snap.get("host_mode"))
    return TrustedPrincipal(
        username=str(username or snap.get("username") or ""),
        workspace_id=resolved_workspace,
        role=str(snap.get("role") or "user"),
        is_api_user=bool(snap.get("is_api_user")),
        host_mode=host_mode,
        host_workspace_id=str(snap.get("host_workspace_id") or (resolved_workspace if host_mode else "") or "") or None,
        preferred_model_key=snap.get("model_key"),
        preferred_run_mode=snap.get("run_mode"),
        preferred_thinking_mode=snap.get("thinking_mode"),
    )