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

ksadk/harness/stores/native_sqlite_audit.py

@@ -0,0 +1,29 @@
+"""Additive SQLite audit tables; records never rewrite execution facts."""
+
+import sqlite3
+
+CONSERVATIVE_MIGRATION_ID = "native.sqlite.schema2.conservative-session-heads/v1"
+
+
+def initialize_audit_tables(connection: sqlite3.Connection) -> None:
+    connection.execute("""CREATE TABLE IF NOT EXISTS native_store_migrations (
+        migration_id TEXT NOT NULL, reader_version TEXT NOT NULL,
+        source_digest TEXT NOT NULL, explicit_heads TEXT NOT NULL,
+        PRIMARY KEY(migration_id,source_digest)
+    )""")
+    connection.execute("""CREATE TABLE IF NOT EXISTS native_restore_audits (
+        audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        scope TEXT NOT NULL, run_id TEXT NOT NULL, data TEXT NOT NULL,
+        FOREIGN KEY(scope,run_id) REFERENCES native_runs(scope,run_id)
+    )""")
+    connection.execute("""CREATE INDEX IF NOT EXISTS native_restore_audits_run
+        ON native_restore_audits(scope,run_id,audit_id)""")
+
+
+def historical_migrations(connection: sqlite3.Connection) -> tuple[str, ...]:
+    return tuple(
+        row[0]
+        for row in connection.execute(
+            "SELECT DISTINCT migration_id FROM native_store_migrations ORDER BY migration_id"
+        )
+    )

ksadk/harness/stores/native_sqlite_migration.py

@@ -0,0 +1,252 @@
+"""Conservative legacy session admission inside the schema upgrade transaction."""
+
+import hashlib
+import json
+import os
+import sqlite3
+import tempfile
+import time
+from collections.abc import Sequence
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+
+from ksadk.harness.native.state import RunScope, RunSnapshot
+
+from .native_contract import StoreConflict, encode
+
+READER_VERSION = "ksadk.native-local-migration/v1"
+EXPORT_MIGRATION_ID = "native.sqlite.schema2.explicit-session-heads/v1"
+
+
+@dataclass(frozen=True)
+class LegacySessionHead:
+    scope: RunScope
+    session_id: str
+    run_id: str
+
+
+@dataclass(frozen=True)
+class LegacySessionCandidates:
+    scope: RunScope
+    session_id: str
+    run_ids: tuple[str, ...]
+    pinned_run_id: str | None
+
+
+@dataclass(frozen=True)
+class NativeStoreInspection:
+    schema_version: int
+    source_digest: str
+    sessions: tuple[LegacySessionCandidates, ...]
+
+
+@dataclass(frozen=True)
+class NativeStoreExport:
+    source_digest: str
+    schema_version: int
+    migration_id: str = EXPORT_MIGRATION_ID
+    reader_version: str = READER_VERSION
+
+
+def _legacy_sessions(connection: sqlite3.Connection):
+    groups: dict[tuple[str, str], list[str]] = {}
+    identities: dict[tuple[str, str], str] = {}
+    scopes: dict[str, RunScope] = {}
+    for scope, run_id, raw in connection.execute("SELECT scope, run_id, snapshot FROM native_runs"):
+        try:
+            snapshot = RunSnapshot.model_validate_json(raw)
+        except ValueError as exc:
+            raise StoreConflict("legacy snapshot cannot be safely migrated") from exc
+        if snapshot.run_id != run_id or encode(snapshot.scope) != scope:
+            raise StoreConflict("legacy snapshot identity mismatch")
+        scopes[scope] = snapshot.scope
+        groups.setdefault((scope, snapshot.session_id), []).append(run_id)
+        identities[(scope, run_id)] = snapshot.session_id
+    return groups, identities, scopes
+
+
+def _pins(connection: sqlite3.Connection, identities) -> dict[tuple[str, str], str]:
+    exists = connection.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='native_session_heads'"
+    ).fetchone()
+    if not exists:
+        return {}
+    pins = {}
+    for scope, session_id, run_id in connection.execute(
+        "SELECT scope, session_id, run_id FROM native_session_heads"
+    ):
+        if identities.get((scope, run_id)) != session_id:
+            raise StoreConflict("legacy session head identity mismatch")
+        pins[(scope, session_id)] = run_id
+    return pins
+
+
+def _fingerprint(connection: sqlite3.Connection) -> str:
+    digest = hashlib.sha256()
+    digest.update(str(connection.execute("PRAGMA user_version").fetchone()[0]).encode())
+    # Logical SQLite image: includes fences, receipts, commands, unknown
+    # auxiliary tables and migration history, independent of WAL/page layout.
+    for statement in connection.iterdump():
+        digest.update(statement.encode("utf-8"))
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def inspect_native_store(path: str | Path) -> NativeStoreInspection:
+    """Read a consistent source image without constructing a writable Store."""
+    path = Path(path).resolve(strict=True)
+    with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True)) as connection:
+        connection.execute("BEGIN")
+        version = connection.execute("PRAGMA user_version").fetchone()[0]
+        if version not in {0, 1, 2}:
+            raise StoreConflict("unsupported native store schema")
+        groups, identities, scopes = _legacy_sessions(connection)
+        pins = _pins(connection, identities)
+        return NativeStoreInspection(
+            version,
+            _fingerprint(connection),
+            tuple(
+                LegacySessionCandidates(
+                    scopes[scope], session, tuple(sorted(runs)), pins.get((scope, session))
+                )
+                for (scope, session), runs in sorted(groups.items())
+            ),
+        )
+
+
+def export_native_store(
+    source: str | Path,
+    destination: str | Path,
+    *,
+    expected_source_digest: str,
+    session_heads: Sequence[LegacySessionHead] = (),
+    offline_acknowledged: bool = False,
+) -> NativeStoreExport:
+    """Publish an offline upgraded copy; never replace or execute the source.
+
+    The operator must stop all users of the source first. Original unleased
+    schemas cannot prove process death, so this acknowledgement is a host
+    precondition, not a claim of hot migration or ownership transfer.
+    Existing live leases are refused even when that precondition is asserted.
+    """
+    if offline_acknowledged is not True:
+        raise ValueError("native store export requires an explicitly offline source")
+    source = Path(source).resolve(strict=True)
+    destination = Path(destination)
+    destination.parent.resolve(strict=True)
+    if source == destination.resolve():
+        raise ValueError("migration destination must differ from the source")
+    if destination.exists() or destination.is_symlink():
+        raise FileExistsError(destination)
+    descriptor, staging_name = tempfile.mkstemp(prefix=".native-migration-", dir=destination.parent)
+    os.close(descriptor)
+    staging = Path(staging_name)
+    try:
+        with closing(sqlite3.connect(source.as_uri() + "?mode=ro", uri=True)) as original:
+            with closing(sqlite3.connect(staging)) as copied:
+                original.backup(copied)
+        with closing(sqlite3.connect(staging, isolation_level=None)) as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            source_digest = _fingerprint(connection)
+            if source_digest != expected_source_digest:
+                raise StoreConflict("native store changed after inspection")
+            version = connection.execute("PRAGMA user_version").fetchone()[0]
+            if version not in {0, 1, 2}:
+                raise StoreConflict("unsupported native store schema")
+            groups, identities, _ = _legacy_sessions(connection)
+            pins = _pins(connection, identities)
+            has_leases = connection.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='native_run_leases'"
+            ).fetchone()
+            if (
+                has_leases
+                and connection.execute(
+                    "SELECT 1 FROM native_run_leases WHERE expires_at > ? LIMIT 1", (time.time(),)
+                ).fetchone()
+            ):
+                raise StoreConflict("native store has a live lease")
+            chosen = {}
+            for head in session_heads:
+                key = (encode(head.scope), head.session_id)
+                if key in chosen or head.run_id not in groups.get(key, ()):
+                    raise StoreConflict("invalid explicit legacy session head")
+                if key in pins and pins[key] != head.run_id:
+                    raise StoreConflict("existing legacy session pin cannot be replaced")
+                chosen[key] = head.run_id
+            # Import at invocation time: SQLiteRunStore imports this module.
+            from .native_sqlite import _SCHEMA
+
+            # executescript commits a pending transaction; restart it in the
+            # script before schema/heads are touched. The staged copy is private.
+            connection.executescript("BEGIN IMMEDIATE;\n" + _SCHEMA)
+            for (scope, session), run_id in chosen.items():
+                if (scope, session) not in pins:
+                    connection.execute(
+                        "INSERT INTO native_session_heads VALUES (?,?,?)", (scope, session, run_id)
+                    )
+            restore_legacy_session_heads(connection)
+            connection.execute("""CREATE TABLE IF NOT EXISTS native_store_migrations (
+                migration_id TEXT NOT NULL, reader_version TEXT NOT NULL,
+                source_digest TEXT NOT NULL, explicit_heads TEXT NOT NULL,
+                PRIMARY KEY(migration_id,source_digest)
+            )""")
+            connection.execute(
+                "INSERT INTO native_store_migrations VALUES (?,?,?,?)",
+                (
+                    EXPORT_MIGRATION_ID,
+                    READER_VERSION,
+                    source_digest,
+                    json.dumps(
+                        [
+                            {"scope": json.loads(scope), "session_id": session, "run_id": run}
+                            for (scope, session), run in sorted(chosen.items())
+                        ],
+                        sort_keys=True,
+                    ),
+                ),
+            )
+            connection.execute("PRAGMA user_version=2")
+            connection.commit()
+            if connection.execute("PRAGMA integrity_check").fetchone()[0] != "ok":
+                raise StoreConflict("native store export integrity check failed")
+            if connection.execute("PRAGMA foreign_key_check").fetchone() is not None:
+                raise StoreConflict("native store export foreign key check failed")
+        with staging.open("rb") as stream:
+            os.fsync(stream.fileno())
+        # link is atomic and refuses an existing destination, including a race
+        # after the first check. No partially migrated image becomes visible.
+        os.link(staging, destination)
+        directory = os.open(destination.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+        return NativeStoreExport(source_digest, 2)
+    finally:
+        for path in (
+            staging,
+            Path(str(staging) + "-wal"),
+            Path(str(staging) + "-shm"),
+            Path(str(staging) + "-journal"),
+        ):
+            path.unlink(missing_ok=True)
+
+
+def restore_legacy_session_heads(connection: sqlite3.Connection) -> None:
+    """Restore only facts proven by an existing pin or a unique legacy Run.
+
+    The original schema had no chronological Run identity or Session CAS.
+    Multiple unpinned Runs cannot safely be ordered by rowid or UUID. Keep the
+    whole upgrade reversible rather than authorizing a guessed parent.
+    """
+    groups, identities, _ = _legacy_sessions(connection)
+    pinned = _pins(connection, identities)
+    for (scope, session_id), runs in groups.items():
+        if (scope, session_id) in pinned:
+            continue
+        if len(runs) != 1:
+            raise StoreConflict("legacy session head is ambiguous; explicit migration required")
+        connection.execute(
+            "INSERT INTO native_session_heads VALUES (?, ?, ?)", (scope, session_id, runs[0])
+        )

ksadk/harness/strategies.py

@@ -0,0 +1,149 @@
+"""Harness Execution Strategy Registry（plan §14）——多 Agent 是可选能力。
+
+一期策略：
+- ``single-agent``：默认（对应 engine.base.single_agent_plan）；
+- ``plan-execute``：规划与执行分离；
+- ``plan-execute-review``：增加独立审查；
+- ``custom-imported``：兼容导入路径占位。
+
+模板可推荐策略，但不把技术拓扑写成模板核心描述（§14.2）——策略由创建者
+或平台策略选择。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ksadk.harness.engine.base import ExecutionPlan, single_agent_plan
+from ksadk.harness.spec import HarnessSpec
+
+
+class StrategyRegistryError(ValueError):
+    """未知/冲突策略注册。"""
+
+
+@dataclass(frozen=True)
+class StrategyDescriptor:
+    strategy_kind: str
+    description: str
+    #: 单 Agent 模板无关性守卫：默认策略不得携带多 Agent 专属字符串。
+    is_default: bool = False
+
+
+def plan_execute_plan() -> ExecutionPlan:
+    """plan-execute：规划与执行分离（§14.1）。"""
+    return ExecutionPlan(
+        strategy_kind="plan-execute",
+        nodes=("prepare_context", "plan", "execute", "reason", "tool_calls", "final"),
+        edges=(
+            ("prepare_context", "plan"),
+            ("plan", "execute"),
+            ("execute", "reason"),
+            ("reason", "tool_calls"),
+            ("tool_calls", "reason"),
+            ("reason", "final"),
+        ),
+    )
+
+
+def plan_execute_review_plan() -> ExecutionPlan:
+    """plan-execute-review：增加独立审查节点（§14.1）。"""
+    return ExecutionPlan(
+        strategy_kind="plan-execute-review",
+        nodes=(
+            "prepare_context",
+            "plan",
+            "execute",
+            "reason",
+            "tool_calls",
+            "review",
+            "final",
+        ),
+        edges=(
+            ("prepare_context", "plan"),
+            ("plan", "execute"),
+            ("execute", "reason"),
+            ("reason", "tool_calls"),
+            ("tool_calls", "reason"),
+            ("reason", "review"),
+            ("review", "final"),
+        ),
+    )
+
+
+#: 多 Agent 专属节点名——single-agent 拓扑不得包含（§17 多 Agent 拓扑 验收）。
+_MULTI_AGENT_NODES = frozenset({"plan", "execute", "review", "manager", "reviewer"})
+
+
+class ExecutionStrategyRegistry:
+    """策略注册表：compile(spec) → ExecutionPlan（纯数据，引擎无关）。"""
+
+    def __init__(self) -> None:
+        self._strategies: dict[str, StrategyDescriptor] = {
+            "single-agent": StrategyDescriptor(
+                strategy_kind="single-agent",
+                description="默认单 Agent 循环（reason 自环 + final）",
+                is_default=True,
+            ),
+            "plan-execute": StrategyDescriptor(
+                strategy_kind="plan-execute",
+                description="规划与执行分离",
+            ),
+            "plan-execute-review": StrategyDescriptor(
+                strategy_kind="plan-execute-review",
+                description="规划-执行-独立审查",
+            ),
+            "custom-imported": StrategyDescriptor(
+                strategy_kind="custom-imported",
+                description="导入已有项目的兼容路径",
+            ),
+        }
+        self._compilers = {
+            "single-agent": single_agent_plan,
+            "plan-execute": plan_execute_plan,
+            "plan-execute-review": plan_execute_review_plan,
+        }
+
+    def register(self, descriptor: StrategyDescriptor, compiler=None) -> None:
+        if descriptor.strategy_kind in self._strategies:
+            raise StrategyRegistryError(f"strategy 重复注册: {descriptor.strategy_kind}")
+        self._strategies[descriptor.strategy_kind] = descriptor
+        if compiler is not None:
+            self._compilers[descriptor.strategy_kind] = compiler
+
+    def list_strategies(self) -> list[StrategyDescriptor]:
+        return list(self._strategies.values())
+
+    def default(self) -> str:
+        for descriptor in self._strategies.values():
+            if descriptor.is_default:
+                return descriptor.strategy_kind
+        return "single-agent"
+
+    def compile(self, spec: HarnessSpec, *, strategy: str | None = None) -> ExecutionPlan:
+        """按策略编译拓扑；未指定时使用注册表默认。"""
+        kind = strategy or self.default()
+        if kind == "custom-imported":
+            raise StrategyRegistryError("custom-imported 策略无通用拓扑：由导入的 Graph 自行提供")
+        compiler = self._compilers.get(kind)
+        if compiler is None:
+            raise StrategyRegistryError(f"unknown strategy: {kind}")
+        return compiler()
+
+    # ------------------------------------------------------------- 守卫
+
+    @staticmethod
+    def assert_single_agent_purity(plan: ExecutionPlan) -> None:
+        """验收守卫：single-agent 拓扑不包含多 Agent 专属节点。"""
+        polluted = _MULTI_AGENT_NODES & set(plan.nodes)
+        if polluted:
+            raise StrategyRegistryError(f"single-agent 拓扑混入多 Agent 节点: {sorted(polluted)}")
+
+
+__all__ = [
+    "ExecutionStrategyRegistry",
+    "StrategyDescriptor",
+    "StrategyRegistryError",
+    "plan_execute_plan",
+    "plan_execute_review_plan",
+]

ksadk/harness/subagent.py

@@ -0,0 +1,263 @@
+"""子 Agent 执行（收口 6 / plan §14）：多 Agent 作为可选能力。
+
+Engine 支持 ``sub_agents``：工具名 → 子 Agent 配置（instructions + 可选
+tools）。父 Agent 的模型像调用普通工具一样发起子任务；引擎在 tool_calls
+节点内联运行一个子 ManagedLangGraphEngine 到完成，子事件（含
+agent.started/completed、自己的 turn/node/model/usage）以**子 agent_id**
+写入父事件流——事件树（event_tree）据此把子 Agent 展示为独立树节点。
+
+约束：
+- 子 Agent 不再嵌套子 Agent（单层，避免失控递归）；
+- 子 Agent 共享父 Reasoner 与工具注册表（数据面由宿主装配）；
+- 每次委派使用独立 Checkpoint namespace、轮数预算和墙钟超时；
+- Skill 默认继承，MCP 必须显式授权后才继承；
+- 子 Agent 结果以其最终文本作为工具结果回流父对话。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from jsonschema import ValidationError, validate
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.harness.events import RuntimeEvent
+from ksadk.harness.spec import (
+    CapabilityBindings,
+    ExecutionStrategySpec,
+    HarnessSpec,
+    PromptSpec,
+    SubAgentBinding,
+)
+
+
+@dataclass
+class SubAgentSpec:
+    """子 Agent 配置（宿主声明，引擎内联执行）。"""
+
+    name: str
+    instructions: str
+    #: 允许子 Agent 使用的工具名（空 = 不用工具，只做文本推理）。
+    tools: tuple[str, ...] = ()
+    description: str = ""
+    #: 子 Agent 的墙钟预算。原默认 120s **没有任何参照依据**：Claude Code 的子 Agent
+    #: 是后台跑到底的（`AgentTool.tsx` 里只有 1 秒的清理超时，没有墙钟限制）。
+    #: 2026-09-18 实测：120s 让"实现核心规则/界面交互/自动化测试"这类子任务必然被判
+    #: 取消，父 Agent 随即放弃委派并自己硬做，交付链路因此断开。
+    timeout_seconds: float = 1800.0
+    #: 子 Agent 回合上限。原默认 4 在参照实现里找不到对应：
+    #: DeepAgents 给子图 `recursion_limit: 9999`（graph.py:781，实质跑到完）；
+    #: Claude Code 的 maxTurns 是可配置项，唯一具体数字是 DreamTask 的
+    #: `MAX_TURNS = 30`（src/tasks/DreamTask/DreamTask.ts:12）。取 30 作默认。
+    #: 4 回合连"读规范 → 写文件 → 自检"都走不完，实现类子任务必然半途而废。
+    max_turns: int = 30
+    max_total_tokens: int | None = None
+    max_artifacts: int | None = None
+    max_tool_calls: int | None = None
+    concurrent_safe: bool = False
+    output_schema: dict[str, Any] | None = None
+    depends_on: tuple[str, ...] = ()
+    failure_policy: str = "propagate"
+    max_retries: int = 0
+    inherit_skills: bool = True
+    inherit_mcp: bool = False
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_binding(cls, binding: SubAgentBinding) -> "SubAgentSpec":
+        """把不可变 Revision 声明投影为本次 Run 的执行配置。"""
+        return cls(**binding.model_dump())
+
+    @property
+    def openai_schema(self) -> dict[str, Any]:
+        """模型可见的工具 schema（子 Agent 即工具，任务描述入参）。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description or f"委托子 Agent {self.name} 完成任务并返回其结论",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"task": {"type": "string", "description": "要完成的子任务描述"}},
+                    "required": ["task"],
+                },
+            },
+        }
+
+
+class SubAgentResult(BaseModel):
+    """父 Agent 可消费、平台可审计的稳定子任务结果。"""
+
+    model_config = ConfigDict(extra="allow")
+
+    status: str
+    output: Any = None
+    artifact_refs: tuple[str, ...] = ()
+    usage: dict[str, int] = Field(default_factory=dict)
+    evidence: dict[str, Any] = Field(default_factory=dict)
+    error_category: str | None = None
+    error: str | None = None
+
+
+class SubAgentOutputValidationError(ValueError):
+    """子任务最终输出不满足 Revision 声明的 Schema。"""
+
+
+def validate_subagent_output(text: str, schema: dict[str, Any] | None) -> Any:
+    """按声明解析并校验最终输出；无 Schema 时保持原文本。"""
+    text = text.strip()
+    if not text:
+        raise SubAgentOutputValidationError("sub-agent did not produce a final result")
+    if re.search(r"DSML", text.replace("｜", "|"), re.IGNORECASE):
+        raise SubAgentOutputValidationError(
+            "sub-agent returned an unexecuted tool call instead of a result"
+        )
+    if schema is None:
+        return text
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise SubAgentOutputValidationError(
+            f"sub-agent output_schema requires JSON output: {exc.msg}"
+        ) from exc
+    try:
+        validate(instance=value, schema=schema)
+    except ValidationError as exc:
+        raise SubAgentOutputValidationError(
+            f"sub-agent output_schema validation failed: {exc.message}"
+        ) from exc
+    return value
+
+
+def order_subagent_tool_calls(
+    calls: list[dict[str, Any]], specs: dict[str, "SubAgentSpec"]
+) -> list[dict[str, Any]]:
+    """对同批子任务稳定拓扑排序；普通工具与无依赖子任务保持原顺序。"""
+    positions = {str(call.get("name") or ""): index for index, call in enumerate(calls)}
+    call_names = set(positions)
+    dependencies = {
+        name: {dependency for dependency in spec.depends_on if dependency in call_names}
+        for name, spec in specs.items()
+        if name in call_names
+    }
+
+    def rank(name: str, trail: frozenset[str] = frozenset()) -> int:
+        if name in trail:
+            raise SubAgentExecutionError("dependency_cycle", f"sub-agent dependency cycle: {name}")
+        parents = dependencies.get(name, set())
+        if not parents:
+            return 0
+        return 1 + max(rank(parent, trail | {name}) for parent in parents)
+
+    return sorted(
+        calls,
+        key=lambda call: (
+            rank(str(call.get("name") or "")),
+            positions[str(call.get("name") or "")],
+        ),
+    )
+
+
+def child_spec(parent_spec: HarnessSpec, sub: SubAgentSpec) -> HarnessSpec:
+    """由父 Spec 派生子 Spec（同模型绑定，独立指令）。"""
+    # Skill 是只读知识能力，默认继承；MCP 可能触达外部系统，只有 Revision
+    # 明确授权时才继承，防止委派扩大权限面。
+    return HarnessSpec(
+        agent_revision_ref=parent_spec.agent_revision_ref,
+        model=parent_spec.model,
+        prompt=PromptSpec(instructions=sub.instructions),
+        capabilities=CapabilityBindings(
+            skill_bindings=(parent_spec.capabilities.skill_bindings if sub.inherit_skills else ()),
+            mcp_bindings=(parent_spec.capabilities.mcp_bindings if sub.inherit_mcp else ()),
+        ),
+        context_policy=parent_spec.context_policy,
+        memory_policy=parent_spec.memory_policy,
+        approval_policy=parent_spec.approval_policy,
+        sandbox_policy=parent_spec.sandbox_policy,
+        observability_policy=parent_spec.observability_policy,
+        execution_strategy=ExecutionStrategySpec(
+            config={
+                "max_tool_calls": sub.max_tool_calls,
+                "max_artifacts": sub.max_artifacts,
+                "max_total_tokens": sub.max_total_tokens,
+            }
+        ),
+    )
+
+
+async def run_subagent(
+    *,
+    engine: Any,
+    parent_run: Any,
+    sub: SubAgentSpec,
+    task: str,
+    call_id: str = "",
+) -> tuple[dict[str, Any], list[RuntimeEvent]]:
+    """运行子 Agent 到完成，返回 (最终文本, 以父 seq 重排的子事件)。
+
+    子事件信封：invocation_id 同父 Run（单一审计流），agent_id 为
+    ``{父agent_id}:{子名}``（事件树按 agent 分组展示子 Agent）。
+    """
+    from ksadk.harness.engine.subagents import execute_subagent
+
+    return await execute_subagent(
+        engine=engine, parent_run=parent_run, sub=sub, task=task, call_id=call_id
+    )
+
+
+class SubAgentExecutionError(RuntimeError):
+    """Classified child failure safe to project into Tool events."""
+
+    def __init__(self, category: str, message: str) -> None:
+        super().__init__(message)
+        self.category = category
+
+
+def resequence_child_events(
+    parent_run: Any, events: list[RuntimeEvent], *, observe: bool = False
+) -> None:
+    """把缓冲的子事件按父 seq 重排后并入父流（tool.call 事件之后统一落盘）。"""
+    for ev in events:
+        parent_run.seq += 1
+        payload = dict(ev.payload)
+        if ev.event_type in {"agent.started", "agent.completed"}:
+            payload.setdefault("parent_agent_id", parent_run.state.agent_id)
+        parent_run.events.append(
+            RuntimeEvent.create(
+                ev.event_type,
+                agent_id=ev.agent_id,
+                user_id=ev.user_id,
+                session_id=ev.session_id,
+                # v1 invocation_id 保持父审计流兼容；v2 run_id 保留独立子 Run。
+                invocation_id=parent_run.handle.run_id,
+                seq_id=parent_run.seq,
+                payload=payload,
+                phase=ev.phase,
+                run_id=ev.run_id or ev.invocation_id,
+                scope_id=ev.scope_id or f"agent:{ev.agent_id}",
+                parent_scope_id=ev.parent_scope_id or f"agent:{parent_run.state.agent_id}",
+                parent_run_id=ev.parent_run_id or parent_run.handle.run_id,
+            )
+        )
+
+        if observe:
+            projected = parent_run.events[-1]
+            if parent_run.controller is not None:
+                parent_run.control_events.append(projected)
+                parent_run.controller.observe(projected)
+            parent_run.observed_event_ids.add(projected.event_id)
+
+
+__all__ = [
+    "SubAgentOutputValidationError",
+    "SubAgentResult",
+    "SubAgentSpec",
+    "child_spec",
+    "order_subagent_tool_calls",
+    "resequence_child_events",
+    "run_subagent",
+    "validate_subagent_output",
+]