agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/engine/policy_runtime.py

@@ -0,0 +1,81 @@
+"""Run-local host authority: isolate grants and revalidate before side effects."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ksadk.harness.execution_policy import ExecutionPolicy, apply_execution_policy
+from ksadk.harness.subagent import SubAgentSpec
+
+
+def configure_run(engine, run, *, policy=None, resolver=None, request=None):
+    inherited = getattr(engine, "_inherited_policy_tool_names", None)
+    if policy is not None and inherited is None:
+        run.compiled = replace(run.compiled, spec=apply_execution_policy(run.compiled.spec, policy))
+    run.execution_policy = policy
+    run.execution_policy_resolver = resolver
+    run.execution_policy_request = request
+    run.exclusive_tools = bool(policy and policy.exclusive_tools)
+    run.tools = {} if run.exclusive_tools and inherited is None else dict(engine._tools)
+    run.policy_tool_names = set(inherited or ())
+    if policy is not None and inherited is None:
+        run.tools.update(policy.tools)
+        run.policy_tool_names.update(policy.tools)
+    run.approval_required = set(engine._approval_required)
+    if policy is not None:
+        run.approval_required.update(policy.approval_required)
+    _apply_request_approval_mode(run, request)
+    run.sub_agents = {
+        **engine._sub_agents,
+        **{b.name: SubAgentSpec.from_binding(b) for b in run.compiled.spec.sub_agents},
+    }
+    if run.exclusive_tools:
+        run.sub_agents = {}
+    run.controller = engine._new_run_controller(run.compiled)
+
+
+async def revalidate_policy(engine, run):
+    resolver, request = run.execution_policy_resolver, run.execution_policy_request
+    if resolver is None:
+        return
+    policy = await resolver.resolve(request.metadata["execution_policy_ref"], request=request)
+    if not isinstance(policy, ExecutionPolicy):
+        raise TypeError("host resolver must return ExecutionPolicy")
+    # A refreshed grant can narrow an admitted run, never grow its tool surface.
+    run.exclusive_tools = run.exclusive_tools or policy.exclusive_tools
+    if run.exclusive_tools:
+        run.sub_agents = {}
+    allowed = {
+        name: tool
+        for name, tool in engine._tools.items()
+        if name not in run.policy_tool_names and not run.exclusive_tools
+    }
+    allowed.update(
+        {name: tool for name, tool in policy.tools.items() if name in run.policy_tool_names}
+    )
+    run.tools = {name: allowed[name] for name in run.tools if name in allowed}
+    if not run.session_approval_granted:
+        run.approval_required.update(policy.approval_required)
+    else:
+        run.approval_required = set()
+    limits_only = ExecutionPolicy(limits=policy.limits)
+    run.compiled = replace(
+        run.compiled, spec=apply_execution_policy(run.compiled.spec, limits_only)
+    )
+    run.execution_policy = policy
+
+
+def _apply_request_approval_mode(run, request) -> None:
+    """回合级审批档位（composer 的 完全访问/严格/询问）覆盖静态合同。
+
+    ``full`` = 免确认（用户已明确授权本次运行的工具副作用）；
+    ``ask`` = 全部需要确认；缺省保持合同与执行策略的静态判定。
+    """
+    request = request or getattr(run, "execution_policy_request", None)
+    mode = ""
+    if request is not None:
+        mode = str((getattr(request, "metadata", None) or {}).get("tool_approval_mode") or "")
+    if mode == "full":
+        run.approval_required = set()
+    elif mode == "ask":
+        run.approval_required.update(name for name in getattr(run, "tools", {}) or {})

ksadk/harness/engine/postgres_checkpointer.py

@@ -0,0 +1,386 @@
+"""Postgres 异步 Checkpointer 工厂（plan §6 / 分布式后端）。
+
+按 ``KSADK_CHECKPOINT_DSN`` 选择 sqlite/postgres。langgraph Postgres import
+不越出本模块（架构守卫守卫 engine/ 包外不引 langgraph）。
+
+依赖：``ksadk[postgres]`` extra（langgraph-checkpoint-postgres + psycopg）。
+缺依赖时显式报错（不静默降级）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import Any
+
+from ksadk.sessions.db_budget import (
+    DatabaseBudget,
+    DatabaseOperationDeadline,
+    session_db_budget,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CheckpointCommitUnknown(RuntimeError):
+    """A checkpoint write may have committed; never replay graph/tool work."""
+
+    def __init__(self, thread_id: str, checkpoint_id: str, operation: str) -> None:
+        self.thread_id = thread_id
+        self.checkpoint_id = checkpoint_id
+        self.operation = operation
+        super().__init__(
+            f"{operation} commit outcome unknown for thread={thread_id} checkpoint={checkpoint_id}"
+        )
+
+
+def _commit_outcome_uncertain(exc: Exception) -> bool:
+    """Only transport/timeout failures can hide a successful COMMIT."""
+    current: BaseException | None = exc
+    seen: set[int] = set()
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        sqlstate = getattr(current, "sqlstate", None) or getattr(current, "pgcode", None)
+        if sqlstate and not str(sqlstate).startswith(("08", "57P", "58")):
+            return False
+        current = current.__cause__ or current.__context__
+    return isinstance(exc, (TimeoutError, ConnectionError, OSError)) or type(exc).__name__ in {
+        "OperationalError",
+        "InterfaceError",
+    }
+
+
+def bounded_postgres_saver_class() -> Any:
+    """Build a saver that bounds storage phases without timing graph execution."""
+    from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+    from psycopg.rows import dict_row
+    from psycopg_pool import AsyncConnectionPool
+
+    class BoundedAsyncPostgresSaver(AsyncPostgresSaver):
+        def __init__(self, conn: AsyncConnectionPool, *, budget: DatabaseBudget | None = None):
+            super().__init__(conn)
+            self.db_budget = budget or session_db_budget()
+            self._write_phase: ContextVar[bool] = ContextVar(
+                "checkpoint_write_phase", default=False
+            )
+            self._active_connections: dict[asyncio.Task[Any], Any] = {}
+            self._cleanup_deadlines: dict[asyncio.Task[Any], float] = {}
+
+        async def _run_write(
+            self, operation: Any, deadline: DatabaseOperationDeadline | None = None
+        ) -> Any:
+            seconds = (
+                deadline.remaining_seconds()
+                if deadline is not None
+                else self.db_budget.write_operation_seconds
+            )
+            if seconds <= 0:
+                if hasattr(operation, "close"):
+                    operation.close()
+                raise TimeoutError("checkpoint write operation deadline exceeded")
+            token = self._write_phase.set(True)
+            try:
+                task = asyncio.create_task(operation)
+            finally:
+                self._write_phase.reset(token)
+            try:
+                return await asyncio.wait_for(asyncio.shield(task), seconds)
+            except (asyncio.CancelledError, TimeoutError):
+                cleanup_deadline = (
+                    asyncio.get_running_loop().time() + self.db_budget.cleanup_seconds
+                )
+                self._cleanup_deadlines[task] = cleanup_deadline
+                task.cancel()
+                connection = self._active_connections.get(task)
+                if connection is not None:
+                    try:
+                        remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                        if remaining:
+                            await asyncio.wait_for(connection.close(), remaining)
+                        else:
+                            connection.pgconn.finish()
+                    except Exception:
+                        logger.exception("Could not close cancelled checkpoint connection")
+                        connection.pgconn.finish()
+                remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                done, _ = await asyncio.wait(
+                    (task,), timeout=min(remaining, self.db_budget.cleanup_seconds / 2)
+                )
+                if not done:
+                    task.cancel()
+                    remaining = max(0.0, cleanup_deadline - asyncio.get_running_loop().time())
+                    done, _ = await asyncio.wait((task,), timeout=remaining)
+                if done:
+                    await asyncio.gather(task, return_exceptions=True)
+                else:
+                    task.add_done_callback(
+                        lambda finished: finished.exception() if not finished.cancelled() else None
+                    )
+                raise
+            finally:
+                self._cleanup_deadlines.pop(task, None)
+
+        @asynccontextmanager
+        async def _cursor(self, *, pipeline: bool = False):
+            budget = self.db_budget
+            write = pipeline or self._write_phase.get()
+            acquire = budget.write_acquire_seconds if write else budget.read_acquire_seconds
+            sql = budget.write_sql_seconds if write else budget.read_sql_seconds
+            await asyncio.wait_for(self.lock.acquire(), budget.lock_seconds)
+            try:
+                async with self.conn.connection(timeout=acquire) as conn:
+                    current = asyncio.current_task()
+                    if current is not None:
+                        self._active_connections[current] = conn
+                    # Pool connections use autocommit. Restore session GUCs
+                    # before returning them so reads never inherit write limits.
+                    original_error: BaseException | None = None
+                    configured = False
+                    try:
+                        await conn.execute(
+                            f"SET statement_timeout TO '{max(1, int(sql * 1000))}ms'"
+                        )
+                        await conn.execute(
+                            f"SET lock_timeout TO '{max(1, int(budget.lock_seconds * 1000))}ms'"
+                        )
+                        configured = True
+                        if pipeline:
+                            if self.supports_pipeline:
+                                async with (
+                                    conn.pipeline(),
+                                    conn.cursor(binary=True, row_factory=dict_row) as cur,
+                                ):
+                                    yield cur
+                            else:
+                                async with (
+                                    conn.transaction(),
+                                    conn.cursor(binary=True, row_factory=dict_row) as cur,
+                                ):
+                                    yield cur
+                        else:
+                            async with conn.cursor(binary=True, row_factory=dict_row) as cur:
+                                yield cur
+                    except BaseException as exc:
+                        original_error = exc
+                        raise
+                    finally:
+                        try:
+                            if not configured:
+                                await conn.close()
+                            elif not conn.closed:
+                                deadline = self._cleanup_deadlines.get(current)
+                                remaining = (
+                                    max(0.001, deadline - asyncio.get_running_loop().time())
+                                    if deadline is not None
+                                    else budget.cleanup_seconds
+                                )
+                                async with asyncio.timeout(remaining):
+                                    await conn.execute("RESET statement_timeout")
+                                    await conn.execute("RESET lock_timeout")
+                        except BaseException:
+                            try:
+                                await conn.close()
+                            except Exception:
+                                logger.exception(
+                                    "Could not close checkpoint connection after reset failure"
+                                )
+                            if original_error is None:
+                                raise
+                            logger.warning(
+                                "Checkpoint connection reset failed after operation error"
+                            )
+            finally:
+                if current := asyncio.current_task():
+                    self._active_connections.pop(current, None)
+                self.lock.release()
+
+        async def setup(self) -> None:
+            await self._run_write(super().setup())
+
+        async def aput(self, *args: Any, **kwargs: Any) -> Any:
+            deadline = DatabaseOperationDeadline(self.db_budget)
+            try:
+                return await self._run_write(super().aput(*args, **kwargs), deadline)
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                config = args[0] if args else kwargs["config"]
+                checkpoint = args[1] if len(args) > 1 else kwargs["checkpoint"]
+                configurable = config["configurable"]
+                receipt = {
+                    "configurable": {
+                        "thread_id": configurable["thread_id"],
+                        "checkpoint_ns": configurable.get("checkpoint_ns", ""),
+                        "checkpoint_id": checkpoint["id"],
+                    }
+                }
+                try:
+                    outcome = await deadline.run(self.reconcile_checkpoint_commit(receipt))
+                except Exception:
+                    outcome = "unknown"
+                if outcome == "committed":
+                    return receipt
+                raise CheckpointCommitUnknown(
+                    configurable["thread_id"], checkpoint["id"], "aput"
+                ) from exc
+
+        async def aput_writes(self, *args: Any, **kwargs: Any) -> Any:
+            deadline = DatabaseOperationDeadline(self.db_budget)
+            try:
+                return await self._run_write(super().aput_writes(*args, **kwargs), deadline)
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                config = args[0] if args else kwargs["config"]
+                writes = args[1] if len(args) > 1 else kwargs["writes"]
+                task_id = args[2] if len(args) > 2 else kwargs["task_id"]
+                try:
+                    stored = await deadline.run(self.aget_tuple(config))
+                except Exception:
+                    stored = None
+                if stored is not None and all(
+                    (task_id, channel, value) in stored.pending_writes for channel, value in writes
+                ):
+                    return None
+                address = config["configurable"]
+                raise CheckpointCommitUnknown(
+                    address["thread_id"], address.get("checkpoint_id", ""), "aput_writes"
+                ) from exc
+
+        async def adelete_thread(self, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return await self._run_write(super().adelete_thread(*args, **kwargs))
+            except Exception as exc:
+                if not _commit_outcome_uncertain(exc):
+                    raise
+                thread_id = args[0] if args else kwargs["thread_id"]
+                raise CheckpointCommitUnknown(thread_id, "", "adelete_thread") from exc
+
+        async def aget_tuple(self, *args: Any, **kwargs: Any) -> Any:
+            budget = self.db_budget
+            async with asyncio.timeout(budget.read_acquire_seconds + budget.read_sql_seconds):
+                return await super().aget_tuple(*args, **kwargs)
+
+        async def alist(self, *args: Any, **kwargs: Any):
+            # Upstream fetches all rows before yielding, but keeps its cursor
+            # open while the caller consumes them. Materialize and close first
+            # so consumer/Agent time is never part of a DB deadline.
+            async with asyncio.timeout(
+                self.db_budget.read_acquire_seconds + self.db_budget.read_sql_seconds
+            ):
+                items = [item async for item in super().alist(*args, **kwargs)]
+            for item in items:
+                yield item
+
+        async def reconcile_checkpoint_commit(self, config: Any) -> str:
+            """Confirm a stable checkpoint ID without replaying graph work."""
+            checkpoint_id = str(config.get("configurable", {}).get("checkpoint_id") or "")
+            if not checkpoint_id:
+                return "unknown"
+            try:
+                stored = await self.aget_tuple(config)
+            except Exception:
+                return "unknown"
+            if stored is not None and stored.checkpoint.get("id") == checkpoint_id:
+                return "committed"
+            return "unknown"
+
+    return BoundedAsyncPostgresSaver
+
+
+async def create_bounded_postgres_saver(
+    dsn: str, *, budget: DatabaseBudget | None = None
+) -> tuple[Any, Any]:
+    """Open a bounded psycopg pool and return its saver and owned pool."""
+    from psycopg.rows import dict_row
+    from psycopg_pool import AsyncConnectionPool
+
+    budget = budget or session_db_budget()
+    pool = AsyncConnectionPool(
+        conninfo=dsn,
+        min_size=1,
+        max_size=10,
+        open=False,
+        timeout=budget.write_acquire_seconds,
+        kwargs={
+            "autocommit": True,
+            "prepare_threshold": 0,
+            "row_factory": dict_row,
+            "connect_timeout": max(1, int(budget.connect_seconds + 0.999)),
+            "options": f"-c statement_timeout={max(1, int(budget.write_sql_seconds * 1000))} "
+            f"-c lock_timeout={max(1, int(budget.lock_seconds * 1000))}",
+        },
+    )
+    try:
+        await pool.open(wait=True, timeout=budget.connect_seconds)
+        saver = bounded_postgres_saver_class()(pool, budget=budget)
+        await saver.setup()
+        return saver, pool
+    except BaseException:
+        await pool.close(timeout=budget.cleanup_seconds)
+        raise
+
+
+def postgres_checkpointer(dsn: str) -> Any:
+    """Postgres 异步 Checkpointer 的上下文管理器（调用方负责 __aenter__）。
+
+    经由本工厂获取，避免 langgraph import 越出引擎模块
+    （tests/architecture/test_harness_contract.py 守卫）。
+
+    Args:
+        dsn: Postgres 连接串，如 ``postgresql://user:pass@host:5432/db``。
+    """
+    try:
+        import langgraph.checkpoint.postgres.aio  # noqa: F401
+    except ImportError as exc:
+        raise RuntimeError(
+            "Postgres Checkpointer 需要 ksadk[postgres] extra"
+            "（langgraph-checkpoint-postgres + psycopg）；"
+            "缺依赖时用 KSADK_CHECKPOINT_DSN 留空走 SQLite 默认。"
+        ) from exc
+
+    return _postgres_checkpointer_context(dsn)
+
+
+@asynccontextmanager
+async def _postgres_checkpointer_context(dsn: str) -> Any:
+    saver, pool = await create_bounded_postgres_saver(dsn)
+    try:
+        yield saver
+    finally:
+        await pool.close(timeout=session_db_budget().cleanup_seconds)
+
+
+def is_postgres_configured() -> bool:
+    """检查是否配置了 Postgres Checkpoint（KSADK_CHECKPOINT_DSN 非空）。"""
+    import os
+
+    return bool(os.getenv("KSADK_CHECKPOINT_DSN", "").strip())
+
+
+def resolve_checkpointer(checkpoint_path: str | None = None) -> Any:
+    """按配置解析 Checkpointer：有 DSN → Postgres，否则 SQLite。
+
+    Args:
+        checkpoint_path: SQLite 路径（无 DSN 时使用）。
+    """
+    import os
+
+    dsn = os.getenv("KSADK_CHECKPOINT_DSN", "").strip()
+    if dsn:
+        return postgres_checkpointer(dsn)
+    from ksadk.harness.engine.langgraph import sqlite_checkpointer
+
+    return sqlite_checkpointer(str(checkpoint_path or ":memory:"))
+
+
+__all__ = [
+    "is_postgres_configured",
+    "postgres_checkpointer",
+    "bounded_postgres_saver_class",
+    "create_bounded_postgres_saver",
+    "CheckpointCommitUnknown",
+    "resolve_checkpointer",
+]

ksadk/harness/engine/run_control_bridge.py

@@ -0,0 +1,100 @@
+"""Managed engine integration helpers for the optional long-task controller."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ksadk.harness.events import EventType
+from ksadk.harness.run_control import RunController, RunControlStop, run_control_spec_from_config
+from ksadk.harness.state import RunStatus
+
+
+def new_run_controller(compiled: Any) -> RunController | None:
+    spec = run_control_spec_from_config(compiled.spec.execution_strategy.config)
+    return RunController(spec) if spec is not None else None
+
+
+async def invoke_graph_with_control(
+    graph: Any,
+    invoke_input: Any,
+    config: dict[str, Any],
+    controller: RunController | None,
+) -> Any:
+    """Invoke a graph under the remaining wall-clock budget."""
+
+    if controller is None or controller.spec.limits.max_wall_seconds is None:
+        return await graph.ainvoke(invoke_input, config=config)
+    wall_limit = controller.spec.limits.max_wall_seconds
+    elapsed = float(controller.snapshot()["elapsed_seconds"])
+    remaining = wall_limit - elapsed
+    if remaining <= 0:
+        controller.before_model()
+        raise RunControlStop(controller.stop_reason or "wall_time_hard_limit")
+    try:
+        return await asyncio.wait_for(graph.ainvoke(invoke_input, config=config), remaining)
+    except (TimeoutError, asyncio.TimeoutError) as exc:
+        controller.stop_reason = "wall_time_hard_limit"
+        controller.budget_exhausted = True
+        raise RunControlStop("wall_time_hard_limit") from exc
+
+
+def completion_payload(run: Any) -> dict[str, Any]:
+    payload: dict[str, Any] = {"status": "completed"}
+    # 会话串轮修复（交接记录 2026-09-22 §7）：把当前 turn_id 写进 RUN_COMPLETED
+    # payload，让 managed_runtime._project_event 把 output_refs 指向当前轮的
+    # turn 级 final item_id，而不是无 turn 分量的 run 级身份。
+    turn_count = int(getattr(run.state, "turn_count", 0) or 0)
+    if turn_count > 0:
+        run_id = getattr(run.handle, "run_id", "") or ""
+        payload["turn_id"] = f"{run_id}:t{turn_count}"
+    if run.controller is not None:
+        result = run.controller.finalize(run.control_events)
+        payload.update(result.to_payload())
+        # A model response produced only because the controller asked it to
+        # close at a soft budget boundary is a useful partial delivery, not a
+        # verified task completion.  Preserve that distinction for runtime
+        # adapters and Studio instead of flattening it into ``completed``.
+        # Explicit acceptance failures receive the same treatment even when
+        # the model stopped before a budget boundary.
+        if result.outcome.value != "verified" and (
+            run.controller.closing_requested or run.controller.spec.acceptance
+        ):
+            payload["control_reason"] = (
+                run.controller.closing_reason or result.reason
+            )
+    return payload
+
+
+def append_controlled_stop(engine: Any, run: Any, reason: str) -> None:
+    """Finish a deterministic controller stop without reporting generic failure."""
+
+    run.state.status = RunStatus.COMPLETED
+    run.done = True
+    result = run.controller.finalize(run.control_events) if run.controller else None
+    run.events.append(
+        engine._event(
+            run,
+            EventType.AGENT_COMPLETED,
+            {"agent_id": run.state.agent_id, "status": "controlled_stop"},
+        )
+    )
+    run.events.append(
+        engine._event(
+            run,
+            EventType.RUN_COMPLETED,
+            {
+                "status": "completed",
+                "control_reason": reason,
+                **(result.to_payload() if result is not None else {}),
+            },
+        )
+    )
+
+
+__all__ = [
+    "append_controlled_stop",
+    "completion_payload",
+    "invoke_graph_with_control",
+    "new_run_controller",
+]

ksadk/harness/engine/run_types.py

@@ -0,0 +1,98 @@
+"""Internal checkpoint and live-state records for the Managed engine."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+from ksadk.harness.engine.base import CompiledHarness
+from ksadk.harness.events import RuntimeEvent
+from ksadk.harness.run_control import RunController
+from ksadk.harness.state import HarnessState
+from ksadk.runtime import RunHandle, StartRequest
+
+
+class _GraphState(TypedDict, total=False):
+    """图 State——只存最小路由信息（plan §6.2.1），正文活在 HarnessState。"""
+
+    messages: list[dict[str, Any]]  # OpenAI 形态消息（含 tool_calls）
+    pending_tool_calls: list[dict[str, Any]]
+    turn_count: int
+    route: str  # "reason" | "final"
+    # MCP 披露游标（P0.1）：随图状态进 Checkpoint，跨进程审批恢复不丢。
+    mcp_listed: list[tuple[str, str]]
+    mcp_schema_read: list[tuple[str, str, str]]
+    usage_tokens: int
+    finalization_retries: int
+    delegation_synthesis_pending: bool
+    run_control: dict[str, Any]
+    budget: dict[str, Any]
+    tool_batch_succeeded: list[str]
+    tool_batch_failed: bool
+    execution_terminal: str
+    child_approval: dict[str, Any]
+    child_approval_decision: dict[str, Any]
+    event_seq: int
+    # Keep a successful fallback only for a bounded cooldown.  Permanent
+    # stickiness can silently replace the user-selected model for a long run
+    # and strand every later turn on a rate-limited fallback.
+    active_model_ref: str
+    active_model_turns: int
+
+
+@dataclass
+class _EngineRun:
+    handle: RunHandle
+    request: StartRequest
+    compiled: CompiledHarness
+    state: HarnessState
+    thread_id: str
+    task: asyncio.Task[list[RuntimeEvent]] | None = None
+    events: list[RuntimeEvent] = field(default_factory=list)
+    seq: int = 0
+    cancel_requested: bool = False
+    pause_requested: bool = False
+    done: bool = False
+    started_emitted: bool = False
+    pending_approval_call_id: str | None = None
+    pending_approval: dict[str, Any] = field(default_factory=dict)
+    child_approval_decision: dict[str, Any] | None = None
+    #: 最近一次 ContextManifest（Actual Token 由 usage 回填，长任务方案 §6.2）。
+    context_manifest: Any | None = None
+    #: 本 Run 的 CompactionRecord 列表（长任务方案 §6.4）。
+    compaction_records: list[Any] = field(default_factory=list)
+    #: Revision 绑定且可由默认 Loop 按需披露的 Level 0 Skill 目录。
+    skill_catalog: tuple[dict[str, str], ...] = ()
+    #: Revision 绑定的 Level 0 MCP Server 目录（名称/描述/风险等级）。
+    mcp_catalog: tuple[dict[str, str], ...] = ()
+    #: 本 Revision 的子 Agent 工具；Run 级冻结，避免多 Spec 并发串配置。
+    sub_agents: dict[str, Any] = field(default_factory=dict)
+    tools: dict[str, Any] = field(default_factory=dict)
+    policy_tool_names: set[str] = field(default_factory=set)
+    exclusive_tools: bool = False
+    approval_required: set[str] = field(default_factory=set)
+    # A Studio ``approve_session`` decision authorizes the remaining tool
+    # calls in this run.  Keep the grant on the run object so graph checkpoint
+    # replays do not immediately ask for the next write again.
+    session_approval_granted: bool = False
+    execution_policy: Any = None
+    execution_policy_resolver: Any = None
+    execution_policy_request: StartRequest | None = None
+    budget_usage: dict[str, int] = field(default_factory=dict)
+    child_budget_usage: dict[str, dict[str, int]] = field(default_factory=dict)
+    budget_tool_calls: set[str] = field(default_factory=set)
+    dynamic_calls: set[str] = field(default_factory=set)
+    budget_parent: Any = None
+    execution_elapsed_seconds: float = 0.0
+    execution_started_at: float | None = None
+    artifact_refs: list[str] = field(default_factory=list)
+    tool_calls_started: int = 0
+    artifacts_created: int = 0
+    #: 可选长任务控制器；合同来自不可变 Revision execution config。
+    controller: RunController | None = None
+    #: 验收只读取这份追加式证据，不依赖会被 stream 消费的输出队列。
+    control_events: list[RuntimeEvent] = field(default_factory=list)
+    observed_event_ids: set[str] = field(default_factory=set)
+    public_tool_activity_kinds: set[str] = field(default_factory=set)
+    public_tool_activity_batches: set[str] = field(default_factory=set)