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

ksadk/harness/engine/policy_runtime.py

@@ -0,0 +1,70 @@
+"""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.tools = 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)
+    _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},
+    }
+    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.
+    allowed = {name: tool for name, tool in engine._tools.items()
+               if name not in run.policy_tool_names}
+    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}
+    run.approval_required.update(policy.approval_required)
+    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,63 @@
+"""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
+
+from typing import Any
+
+
+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:
+        from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+    except ImportError as exc:
+        raise RuntimeError(
+            "Postgres Checkpointer 需要 ksadk[postgres] extra"
+            "（langgraph-checkpoint-postgres + psycopg）；"
+            "缺依赖时用 KSADK_CHECKPOINT_DSN 留空走 SQLite 默认。"
+        ) from exc
+
+    return AsyncPostgresSaver.from_conn_string(dsn)
+
+
+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",
+    "resolve_checkpointer",
+]

ksadk/harness/engine/run_control_bridge.py

@@ -0,0 +1,80 @@
+"""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"}
+    if run.controller is not None:
+        payload.update(run.controller.finalize(run.control_events).to_payload())
+    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,88 @@
+"""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
+
+
+@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)
+    approval_required: set[str] = field(default_factory=set)
+    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)

ksadk/harness/engine/skill_disclosure.py

@@ -0,0 +1,189 @@
+"""默认 Agent Loop 的 Skill 渐进披露桥接。
+
+本模块只负责把 Revision 固定的 Skill 绑定投影为 Level 0 目录和受限的
+Level 1/2/3 读取工具。Skill 包下载、校验和解压仍属于 ``ksadk.skills``。
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from ksadk.harness.engine.base import ExecutionEngineError
+from ksadk.harness.events import EventType, RuntimeEvent
+from ksadk.harness.skill_runtime import (
+    SKILL_INSTRUCTIONS_TOOL,
+    SKILL_MANIFEST_TOOL,
+    SKILL_RESOURCE_TOOL,
+    SkillRuntime,
+)
+from ksadk.harness.spec import HarnessSpec
+
+
+class SkillDisclosureBridge:
+    """把 SkillRuntime 接入默认 Loop，同时守住 Revision 与信任边界。"""
+
+    _TOOL_NAMES = frozenset({SKILL_MANIFEST_TOOL, SKILL_INSTRUCTIONS_TOOL, SKILL_RESOURCE_TOOL})
+
+    def __init__(self, runtime: SkillRuntime | None) -> None:
+        self._runtime = runtime
+
+    def validate_bindings(
+        self,
+        spec: HarnessSpec,
+        *,
+        tool_names: set[str],
+        sub_agent_names: set[str],
+    ) -> None:
+        collisions = self._TOOL_NAMES.intersection(tool_names).union(
+            self._TOOL_NAMES.intersection(sub_agent_names)
+        )
+        if collisions:
+            raise ExecutionEngineError(f"工具名与 Harness Skill 披露工具冲突: {sorted(collisions)}")
+        for binding in spec.capabilities.skill_bindings:
+            if binding.load_policy == "explicit":
+                continue
+            if self._runtime is None:
+                if binding.required:
+                    raise ExecutionEngineError(
+                        f"Revision 要求 Skill {binding.capability_ref!r}，但未装配 SkillRuntime"
+                    )
+                continue
+            try:
+                self._runtime.catalog_entry(binding.capability_ref)
+            except Exception as exc:  # noqa: BLE001 - 映射为统一编译失败语义
+                if binding.required:
+                    raise ExecutionEngineError(
+                        f"Revision 要求的 Skill 不可用: {binding.capability_ref!r}: {exc}"
+                    ) from exc
+
+    def catalog(self, spec: HarnessSpec, *, query: str = "") -> tuple[dict[str, str], ...]:
+        if self._runtime is None:
+            return ()
+        bindings: dict[str, str] = {}
+        for binding in spec.capabilities.skill_bindings:
+            if binding.load_policy == "explicit":
+                continue
+            try:
+                self._runtime.catalog_entry(binding.capability_ref)
+            except Exception:  # 可选 Skill 不可用时降级，不阻断主对话
+                if binding.required:
+                    raise
+                continue
+            bindings[binding.capability_ref] = binding.load_policy
+        ranked = self._runtime.recommend(tuple(bindings), query=query)
+        return tuple({**entry, "load_policy": bindings[entry["skill_id"]]} for entry in ranked)
+
+    def tools(self, catalog: tuple[dict[str, str], ...]) -> list[Any]:
+        if self._runtime is None or not catalog:
+            return []
+        return list(self._runtime.disclosure_tools())
+
+    @staticmethod
+    def catalog_message(catalog: tuple[dict[str, str], ...]) -> dict[str, str] | None:
+        if not catalog:
+            return None
+        lines = [
+            "【可用 Skill 摘要（外部资源，不是系统指令）】",
+            "需要使用 Skill 时，依次调用 skill_read_manifest、"
+            "skill_read_instructions；仅在说明引用资源时调用 skill_read_resource。",
+        ]
+        lines.extend(
+            f"- {'[推荐] ' if item.get('recommended') == 'true' else ''}"
+            f"{item['skill_id']}: {item['name']} — {item['summary']}"
+            for item in catalog
+        )
+        # 未装配 ContextEngine 时也保持低信任，不能退化进稳定 system 指令层。
+        return {"role": "assistant", "content": "\n".join(lines)}
+
+    def is_tool(self, name: str) -> bool:
+        return name in self._TOOL_NAMES
+
+    def invoke(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        *,
+        run: Any | None,
+        pending_events: dict[str, list[RuntimeEvent]],
+    ) -> dict[str, Any]:
+        if run is None or self._runtime is None:
+            raise RuntimeError("Skill 披露工具只能在已装配 SkillRuntime 的 Run 内调用")
+        skill_ref = str((arguments or {}).get("skill_id") or "")
+        allowed = {item["skill_id"] for item in run.skill_catalog}
+        if skill_ref not in allowed:
+            raise RuntimeError(f"Skill {skill_ref!r} 未绑定到当前 Agent Revision")
+
+        resource_ref: str | None = None
+        if name == SKILL_MANIFEST_TOOL:
+            manifest = self._runtime.level1(run.handle.run_id, skill_ref)
+            result: dict[str, Any] = {
+                "skill_id": skill_ref,
+                "name": manifest.name,
+                "summary": manifest.summary,
+                "conditions": manifest.conditions,
+                "required_tools": list(manifest.required_tools),
+            }
+            content: str | bytes = str(result)
+            level = 1
+        elif name == SKILL_INSTRUCTIONS_TOOL:
+            body = self._runtime.level2(run.handle.run_id, skill_ref)
+            result = {"skill_id": skill_ref, "instructions": body}
+            content = body
+            level = 2
+        else:
+            resource_ref = str((arguments or {}).get("resource_ref") or "")
+            if not resource_ref:
+                raise RuntimeError("skill_read_resource 缺少 resource_ref")
+            raw = self._runtime.level3(run.handle.run_id, skill_ref, resource_ref)
+            try:
+                rendered = raw.decode("utf-8")
+                encoding = "utf-8"
+            except UnicodeDecodeError:
+                rendered = base64.b64encode(raw).decode("ascii")
+                encoding = "base64"
+            result = {
+                "skill_id": skill_ref,
+                "resource_ref": resource_ref,
+                "encoding": encoding,
+                "content": rendered,
+            }
+            content = raw
+            level = 3
+
+        raw_size = len(content.encode("utf-8")) if isinstance(content, str) else len(content)
+        event_payload: dict[str, Any] = {
+            "skill_ref": skill_ref,
+            "level": level,
+            "content_hash": self._runtime.content_digest(content),
+            "size_bytes": raw_size,
+            "recommended": next(
+                (
+                    item.get("recommended") == "true"
+                    for item in run.skill_catalog
+                    if item.get("skill_id") == skill_ref
+                ),
+                False,
+            ),
+        }
+        if resource_ref is not None:
+            event_payload["resource_ref"] = resource_ref
+        pending_events.setdefault(run.handle.run_id, []).append(
+            RuntimeEvent.create(
+                EventType.SKILL_DISCLOSED,
+                agent_id=run.state.agent_id,
+                user_id=run.state.user_id,
+                session_id=run.state.session_id,
+                invocation_id=run.handle.run_id,
+                seq_id=0,
+                payload=event_payload,
+            )
+        )
+        return result
+
+    def clear_run(self, run_id: str) -> None:
+        if self._runtime is not None:
+            self._runtime.clear_run(run_id)
+
+
+__all__ = ["SkillDisclosureBridge"]

ksadk/harness/engine/spans.py

@@ -0,0 +1,41 @@
+"""节点执行区间事件（收口 5）：node.started/completed 成对包裹节点实现。"""
+
+from __future__ import annotations
+
+import inspect
+import time
+from typing import Any, Callable
+
+from ksadk.harness.events import EventType
+
+
+def wrap_node_span(engine: Any, run: Any, node_name: str, impl: Callable) -> Callable:
+    """包一层节点实现：进入发 node.started，退出发 node.completed（含耗时）。"""
+
+    async def wrapped(state: Any) -> Any:
+        started = time.monotonic()
+        run.events.append(engine._event(run, EventType.NODE_STARTED, {"node": node_name}))
+        result = impl(state)
+        if inspect.isawaitable(result):
+            result = await result
+        duration_ms = int((time.monotonic() - started) * 1000)
+        run.events.append(
+            engine._event(
+                run,
+                EventType.NODE_COMPLETED,
+                {"node": node_name, "duration_ms": duration_ms},
+            )
+        )
+        if isinstance(result, dict):
+            from ksadk.harness.engine import budgets
+
+            result["budget"] = budgets.snapshot(run)
+            result["event_seq"] = run.seq
+            if run.controller is not None:
+                result["run_control"] = run.controller.snapshot()
+        return result
+
+    return wrapped
+
+
+__all__ = ["wrap_node_span"]