agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/conversations/semantic_summary.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import os
 from dataclasses import dataclass, field
 from typing import Any, Mapping, Sequence
@@ -72,6 +73,277 @@ class CompactionSummaryResult:
     fallback_reason: str | None = None
 
 
+# --- PR D2：Session Working State（方案 §9.3） ---
+
+
+@dataclass
+class WorkingState:
+    """压缩前后保持任务连续性的结构化工作面，随 ContextCheckpoint 持久化。
+
+    生成原则（方案 §9.3）：优先确定性提取——``pending_tools``/``pending_approvals``/receipt
+    从事实事件取；``current_goal`` 从最新 user_message/pinned_state 取；``active_files`` 从
+    workspace 工具调用参数取。仅 ``decisions``/``errors_and_corrections``/``next_action`` 等
+    难结构化项允许从摘要文本解析（带 fallback）。不跨 Session 召回，不写 MemoryProvider。
+    """
+
+    current_goal: str = ""
+    current_phase: str | None = None
+    completed_steps: list[str] = field(default_factory=list)
+    pending_steps: list[str] = field(default_factory=list)
+    next_action: str | None = None
+    active_files: list[dict[str, object]] = field(default_factory=list)
+    decisions: list[dict[str, object]] = field(default_factory=list)
+    errors_and_corrections: list[dict[str, object]] = field(default_factory=list)
+    pending_tools: list[dict[str, object]] = field(default_factory=list)
+    pending_approvals: list[dict[str, object]] = field(default_factory=list)
+    artifact_refs: list[dict[str, object]] = field(default_factory=list)
+    # §8.1：关键约束（"不得操作生产环境" 等），从摘要/pinned_state 提取，缺失时合并旧值。
+    constraints: list[str] = field(default_factory=list)
+    source_seq_range: tuple[int, int] = (0, 0)
+    schema_version: str = "v1"
+
+    def critical_fields_present(self) -> bool:
+        """§8.1：关键字段校验。四项必须全部非空（P0 严格验收，不可放宽）。
+
+        - current_goal 非空
+        - constraints 非空
+        - completed_steps 非空
+        - next_action 非空
+        """
+        return (
+            bool(self.current_goal and self.current_goal.strip())
+            and len(self.constraints) > 0
+            and len(self.completed_steps) > 0
+            and bool(self.next_action and self.next_action.strip())
+        )
+
+    def merge_missing_from(self, previous: "WorkingState | None") -> "WorkingState":
+        """§8.1：关键字段缺失时用压缩前 WorkingState 合并，不接受空值覆盖。
+
+        current_goal/constraints/completed_steps/next_action 空时回填 previous 的值
+        （避免压缩后丢失"不得操作生产环境"等关键约束和已完成进展）。pending_tools/approvals
+        始终以事实事件提取为准（不合并，防过期 pending）。
+        """
+        if previous is None:
+            return self
+        if not self.current_goal.strip():
+            self.current_goal = previous.current_goal
+        if not self.constraints:
+            self.constraints = list(previous.constraints)
+        if not self.next_action and previous.next_action:
+            self.next_action = previous.next_action
+        if not self.completed_steps and previous.completed_steps:
+            self.completed_steps = list(previous.completed_steps)
+        return self
+
+    def to_audit_dict(self) -> dict[str, Any]:
+        """审计用 plain dict（写 checkpoint metadata）。不含 prompt 明文，只含结构化字段。"""
+        return {
+            "current_goal": self.current_goal,
+            "next_action": self.next_action,
+            "completed_steps": list(self.completed_steps),
+            "completed_steps_count": len(self.completed_steps),
+            "pending_steps": list(self.pending_steps),
+            "pending_steps_count": len(self.pending_steps),
+            "active_files": list(self.active_files),
+            "decisions_count": len(self.decisions),
+            "errors_and_corrections_count": len(self.errors_and_corrections),
+            "pending_tools": list(self.pending_tools),
+            "pending_approvals": list(self.pending_approvals),
+            "artifact_refs": list(self.artifact_refs),
+            "constraints": list(self.constraints),
+            "source_seq_range": list(self.source_seq_range),
+            "schema_version": self.schema_version,
+            "content_hash": self.content_hash(),
+            "status": "succeeded",
+        }
+
+    def content_hash(self) -> str:
+        import hashlib
+
+        payload = json.dumps(
+            {
+                "current_goal": self.current_goal,
+                "next_action": self.next_action,
+                "completed_steps": self.completed_steps,
+                "pending_steps": self.pending_steps,
+                "active_files": self.active_files,
+                "decisions": self.decisions,
+                "errors_and_corrections": self.errors_and_corrections,
+                "pending_tools": self.pending_tools,
+                "pending_approvals": self.pending_approvals,
+                "artifact_refs": self.artifact_refs,
+                "constraints": self.constraints,
+                "source_seq_range": list(self.source_seq_range),
+                "schema_version": self.schema_version,
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+        return f"sha256:{hashlib.sha256(payload.encode('utf-8')).hexdigest()}"
+
+
+def _parse_summary_v2_sections(
+    summary_text: str,
+) -> tuple[
+    str | None,
+    list[dict[str, object]],
+    list[dict[str, object]],
+    str,
+    list[str],
+    list[str],
+]:
+    """从摘要 v2 结构化文本确定性解析 next_action / decisions / errors_and_corrections /
+    current_goal / constraints（方案 §9.4 / P0 Working State 验收）。
+
+    支持中文标记（"当前用户目标"/"关键约束"/"下一步工作位置"）与英文标记。纯文本解析，无 LLM。
+    容错：无标记时返回 ``(None, [], [], "", [])``。
+    """
+    text = str(summary_text or "").strip()
+    if not text:
+        return None, [], [], "", [], []
+
+    def _find_section(*labels: str) -> str:
+        for label in labels:
+            # 形如 "下一步工作位置：<内容>"，到下一个已知标记或末尾
+            for marker in (f"{label}：", f"{label}:", f"{label} "):
+                idx = text.find(marker)
+                if idx >= 0:
+                    body = text[idx + len(marker) :].strip()
+                    # 截到下一个已知 section 标记
+                    stop = len(body)
+                    for other in (
+                        "下一步",
+                        "下一步工作",
+                        "未完成事项",
+                        "重要决策",
+                        "错误修正",
+                        "当前用户目标",
+                        "关键约束",
+                        "已完成进展",
+                        "重要引用",
+                        "Next",
+                        "Next Step",
+                        "Decision",
+                        "Error",
+                        "Pending",
+                        "最新用户指令",
+                    ):
+                        if other.startswith(label):
+                            continue
+                        pos = body.find(other)
+                        if pos >= 0 and pos < stop:
+                            stop = pos
+                    return body[:stop].strip().strip("。.；;")
+        return ""
+
+    next_action = _find_section("下一步工作位置", "下一步", "Next Step", "Next") or None
+    decisions_text = _find_section("重要决策", "关键决策", "Decision")
+    errors_text = _find_section("错误修正", "错误与纠正", "Error")
+    decisions = [{"text": decisions_text}] if decisions_text else []
+    errors_and_corrections = [{"text": errors_text}] if errors_text else []
+    # P0：current_goal / constraints / completed_steps 从摘要解析（方案 §9.3/§9.4）
+    current_goal = _find_section("当前用户目标", "当前目标", "Current Goal", "Goal") or ""
+    constraints_text = _find_section("关键约束", "重要约束", "Constraints", "Constraint")
+    constraints = (
+        [c.strip() for c in constraints_text.split("；;") if c.strip()] if constraints_text else []
+    )
+    completed_text = _find_section("已完成进展", "已完成", "Completed", "Progress")
+    completed_steps = (
+        [s.strip() for s in completed_text.split("；;") if s.strip()] if completed_text else []
+    )
+    return (
+        next_action,
+        decisions,
+        errors_and_corrections,
+        current_goal,
+        constraints,
+        completed_steps,
+    )
+
+
+def extract_working_state(
+    events: Sequence[SessionEvent],
+    *,
+    pinned_state: Mapping[str, Any] | None = None,
+    summary_text: str = "",
+    source_seq_range: tuple[int, int] = (0, 0),
+) -> WorkingState:
+    """从事实事件确定性提取 WorkingState（方案 §9.3）。
+
+    ``pending_tools``/``pending_approvals``/``current_goal``/``active_files`` 来自事件，
+    不靠摘要模型猜测（与 ``extract_pinned_state`` 同源但结构化）。``decisions``/
+    ``errors_and_corrections``/``next_action`` 暂留空（v2 摘要文本解析留 follow-up，
+    当前优先确定性事实）。容错：v1 旧摘要或缺失字段时返回部分填充。
+    """
+    pinned = dict(pinned_state or {})
+    # pending_tools / pending_approvals：复用 pinned_state 的确定性提取结果（已去配对）。
+    pending_tools_raw = list(pinned.get("pending_tools") or [])
+    pending_approvals_raw = list(pinned.get("pending_approvals") or [])
+    artifact_refs_raw = list(pinned.get("attachment_refs") or [])
+    current_goal = str(pinned.get("current_user_goal") or "").strip()
+    # constraints 从 pinned_state 取（确定性），缺失时由摘要解析补充
+    constraints_raw = list(pinned.get("constraints") or [])
+    # completed_steps 从 pinned_state 取（确定性），缺失时由摘要解析补充
+    completed_steps_raw = list(pinned.get("completed_steps") or [])
+
+    # active_files：从 tool_call 事件的 tool_args.path 提取（workspace 类工具）。
+    active_files: list[dict[str, object]] = []
+    seen_paths: set[str] = set()
+    for event in events:
+        event_type = canonical_event_type(
+            event.event_type,
+            author=event.author,
+            role=str((event.content or {}).get("role") or ""),
+        )
+        if event_type != "tool_call":
+            continue
+        meta = event.metadata or {}
+        tool_args = meta.get("tool_args")
+        if isinstance(tool_args, Mapping):
+            path = str(tool_args.get("path") or tool_args.get("file") or "").strip()
+            if path and path not in seen_paths:
+                seen_paths.add(path)
+                active_files.append({"path": path, "tool_name": str(meta.get("tool_name") or "")})
+
+    # 摘要 v2 文本解析（方案 §9.3 / §9.4 / P0）：从结构化摘要确定性解析 next_action / decisions /
+    # errors_and_corrections / current_goal / constraints / completed_steps。
+    (
+        next_action,
+        decisions,
+        errors_and_corrections,
+        summary_goal,
+        summary_constraints,
+        summary_completed,
+    ) = _parse_summary_v2_sections(summary_text)
+    # current_goal 优先用 pinned_state，缺失时用摘要解析的 goal
+    if not current_goal.strip() and summary_goal:
+        current_goal = summary_goal
+    # constraints 优先用 pinned_state/事件，缺失时用摘要解析
+    if not constraints_raw and summary_constraints:
+        constraints_raw = list(summary_constraints)
+    # completed_steps 优先用 pinned_state，缺失时用摘要解析
+    completed_steps = (
+        list(completed_steps_raw)
+        if completed_steps_raw
+        else (list(summary_completed) if summary_completed else [])
+    )
+
+    return WorkingState(
+        current_goal=current_goal,
+        next_action=next_action,
+        decisions=decisions,
+        errors_and_corrections=errors_and_corrections,
+        completed_steps=completed_steps,
+        active_files=active_files[-10:],
+        pending_tools=[{"text": t} for t in pending_tools_raw],
+        pending_approvals=[{"text": t} for t in pending_approvals_raw],
+        artifact_refs=[{"ref": r} for r in artifact_refs_raw],
+        constraints=list(constraints_raw),
+        source_seq_range=source_seq_range,
+    )
+
+
 class SummaryModelClient:
     """独立的摘要模型客户端。
 
@@ -221,12 +493,35 @@ def find_pinned_group_indexes(groups: Sequence[Sequence[SessionEvent]]) -> set[i
 
 
 def extract_pinned_state(groups: Sequence[Sequence[SessionEvent]]) -> dict[str, Any]:
-    """提取必须在 checkpoint 里显式保留的状态。"""
+    """提取必须在 checkpoint 里显式保留的状态。
+
+    P0：除了 pending approvals/tools/attachment_refs/current_user_goal，还确定性提取
+    constraints（"不得操作生产环境" 等）和 completed_steps（"镜像已构建" 等），
+    从 user/assistant 消息文本中按标记提取，不依赖摘要模型。
+    """
 
     pending_approvals: list[str] = []
     pending_tools: list[str] = []
     attachment_refs: list[str] = []
     current_user_goal = ""
+    constraints: list[str] = []
+    completed_steps: list[str] = []
+
+    # 约束标记：用户说"不得/不要/禁止X"或 assistant 说"约束：X"
+    import re
+
+    constraint_patterns = [
+        re.compile(r"(?:不得|不要|禁止|不能|严禁)[^。\n；;]{2,50}"),
+    ]
+    # 完成标记：assistant 说"X已构建/X完成/X构建完成"
+    # 捕获完整短语（含"已构建"等），不拆开
+    completed_patterns = [
+        re.compile(
+            r"([\u4e00-\u9fa5A-Za-z0-9 ]{2,30}"
+            r"(?:已构建|已完成|已成功|构建完成|构建好了"
+            r"|做完了|搞定了|改完了|修好了|测完了|跑通了|部署完成|配置完成))"
+        ),
+    ]
 
     for group in groups:
         for event in group:
@@ -259,6 +554,19 @@ def extract_pinned_state(groups: Sequence[Sequence[SessionEvent]]) -> dict[str,
                     ).strip()
                     if label:
                         attachment_refs.append(label)
+                # P0：从 user 消息提取约束
+                for pattern in constraint_patterns:
+                    for m in pattern.findall(text):
+                        c = m.strip().rstrip("，。；;")
+                        if c and c not in constraints:
+                            constraints.append(c)
+            elif event_type == "assistant_message" and text:
+                # P0：从 assistant 消息提取已完成步骤
+                for pattern in completed_patterns:
+                    for m in pattern.findall(text):
+                        s = m.strip().rstrip("，。；;")
+                        if s and s not in completed_steps:
+                            completed_steps.append(s)
 
     unique_attachments: list[str] = []
     for item in attachment_refs:
@@ -271,6 +579,8 @@ def extract_pinned_state(groups: Sequence[Sequence[SessionEvent]]) -> dict[str,
         "pending_tools": pending_tools,
         "attachment_refs": unique_attachments[-5:],
         "current_user_goal": current_user_goal,
+        "constraints": constraints,
+        "completed_steps": completed_steps,
     }
 
 

ksadk/conversations/session_lock.py

@@ -0,0 +1,51 @@
+"""Session 级并发锁与 stale guard（方案 §9.6）。
+
+同一 Session 同时只允许一个 checkpoint/WorkingState 更新提交；并发 Turn 使用乐观版本或
+session lock，失败方重新读取最新 checkpoint 后规划（方案 §9.6）。本模块提供进程内
+per-session async lock（pod 重启清空，单进程内有效）；跨进程/云端需由 Session Store 的乐观
+锁或行锁兜底，本锁只做 best-effort 防同进程并发覆盖。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+_SESSION_LOCKS: dict[str, asyncio.Lock] = {}
+_REGISTRY_LOCK = asyncio.Lock()
+
+
+async def _get_or_create_lock(session_id: str) -> asyncio.Lock:
+    async with _REGISTRY_LOCK:
+        lock = _SESSION_LOCKS.get(session_id)
+        if lock is None:
+            lock = asyncio.Lock()
+            _SESSION_LOCKS[session_id] = lock
+        return lock
+
+
+@asynccontextmanager
+async def session_compaction_lock(session_id: str, *, timeout: float = 30.0) -> AsyncIterator[None]:
+    """获取 per-session compaction 锁（方案 §9.6）。
+
+    超时抛 ``asyncio.TimeoutError``，调用方按 stale guard 处理（重新读最新 checkpoint 再规划）。
+    """
+    lock = await _get_or_create_lock(session_id)
+    try:
+        await asyncio.wait_for(lock.acquire(), timeout=timeout)
+    except asyncio.TimeoutError:
+        # stale guard：拿不到锁说明另一 turn 正在 compaction，本方放弃提交避免覆盖
+        raise
+    try:
+        yield
+    finally:
+        lock.release()
+
+
+def clear_session_locks() -> None:
+    """测试/运维用：清空所有 per-session 锁。"""
+    _SESSION_LOCKS.clear()
+
+
+__all__ = ["clear_session_locks", "session_compaction_lock"]

ksadk/deployment/env_forward.py

@@ -0,0 +1,72 @@
+"""部署时的 shell 进程环境变量转发规则。
+
+通用 deploy (serverless/kcf/kce) 与 hermes/openclaw deploy 共用同一套规则：
+按前缀 (KSADK_/OPENAI_/KSYUN_/E2B_) + 显式 allowlist 转发 shell 环境变量，
+denylist 中的 CLI/builders/configs/web 模块本地键不转发。
+"""
+
+import os
+from typing import Mapping, MutableMapping, Optional
+
+from ksadk.configs.env_registry import ENV_VAR_REGISTRY
+
+DEPLOY_PROCESS_ENV_ALLOWLIST = frozenset(
+    {
+        spec.name
+        for spec in ENV_VAR_REGISTRY
+        if spec.module
+        not in {
+            "builders",
+            "cli",
+            "configs",
+            "web",
+        }
+    }
+) | frozenset(
+    {
+        "E2B_API_KEY",
+        "E2B_API_URL",
+        "OPENAI_API_BASE",
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL",
+        "OPENAI_MODEL_NAME",
+        "SKILL_SPACE_ID",
+        "KSYUN_ACCESS_KEY",
+        "KSYUN_ACCOUNT_ID",
+        "KSYUN_REGION",
+        "KSYUN_SECRET_KEY",
+    }
+)
+DEPLOY_PROCESS_ENV_PREFIXES = ("KSADK_", "OPENAI_", "KSYUN_", "E2B_")
+DEPLOY_PROCESS_ENV_DENYLIST = frozenset(
+    {spec.name for spec in ENV_VAR_REGISTRY if spec.module in {"builders", "cli", "configs", "web"}}
+) | frozenset(
+    {
+        "KSADK_GLOBAL_CONFIG_ENV_KEYS",
+        "KSADK_UPDATED_AT",
+        "KSADK_VERSION",
+    }
+)
+
+
+def should_forward_process_env(name: str) -> bool:
+    if name in DEPLOY_PROCESS_ENV_DENYLIST:
+        return False
+    return name in DEPLOY_PROCESS_ENV_ALLOWLIST or name.startswith(DEPLOY_PROCESS_ENV_PREFIXES)
+
+
+def forward_shell_process_env(
+    base_env: MutableMapping[str, str],
+    environ: Optional[Mapping[str, str]] = None,
+) -> MutableMapping[str, str]:
+    """把 shell 进程环境中符合转发规则的键补进 ``base_env`` (setdefault 语义)。
+
+    不覆盖 ``base_env`` 已有的键 —— 调用方已 resolve 的值 (如 OPENAI_BASE_URL)
+    优先；本函数只负责把白名单/前缀内、但调用方未显式处理的键 (如 KSYUN_*)
+    带进 deploy payload。显式 --env/--env-file 由调用方在之后覆盖。
+    """
+    source = os.environ if environ is None else environ
+    for key, value in sorted(source.items()):
+        if value and should_forward_process_env(key):
+            base_env.setdefault(key, value)
+    return base_env

ksadk/deployment/managed_runtime.py

@@ -0,0 +1,38 @@
+"""Local manifest assembly for server-managed runtime deployments."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ksadk.builders.managed_runtime_builder import ManagedRuntimeBuilder
+from ksadk.deployment.base import DeployTarget, PackageInfo
+
+
+def build_managed_runtime_package(
+    package_info: PackageInfo, target: DeployTarget
+) -> PackageInfo:
+    """Build the canonical manifest and retain its integrity digest for deploy."""
+
+    builder = ManagedRuntimeBuilder(
+        Path(package_info.project_dir),
+        runtime_version=str(target.extra.get("runtime_version") or ""),
+    )
+    result = builder.build()
+    if not result.success:
+        raise RuntimeError(f"构建失败: {result.error_message}")
+
+    package_info.metadata.update(result.metadata)
+    manifest_sha256 = str(result.metadata.get("manifest_sha256") or "").strip()
+    if manifest_sha256:
+        target.extra["manifest_sha256"] = manifest_sha256
+    if result.artifact_path is not None:
+        package_info.metadata["managed_manifest_path"] = str(result.artifact_path)
+        # ManagedRuntime deployment submits this exact YAML declaration to
+        # Server; it has no code ZIP, KS3 upload or CodeConfig.
+        package_info.metadata["managed_runtime_manifest"] = result.artifact_path.read_text(
+            encoding="utf-8"
+        )
+    return package_info
+
+
+__all__ = ["build_managed_runtime_package"]

ksadk/deployment/manager.py

@@ -224,9 +224,9 @@ try:
 except ImportError:
     pass
 
-from ksadk.runners import create_runner
 from ksadk.detection import DetectionResult, FrameworkType
-from ksadk.server import app, set_runner
+from ksadk.runtime import RuntimeExecutor, RuntimeLaunchContext, build_default_runtime_registry
+from ksadk.server import RuntimeAppConfig, configure_runtime_app, create_runtime_app
 import uvicorn
 
 # 检测结果 (部署时固化)
@@ -238,12 +238,28 @@ detection_result = DetectionResult(
     agent_variable="{detection_result.agent_variable}"
 )
 
-# 创建 Runner 并加载 Agent
-runner = create_runner(detection_result, "/app")
-runner.load_agent()
-
-# 设置 Runner 到 FastAPI app
-set_runner(runner, loaded=True)
+runtime_context = RuntimeLaunchContext(
+    runtime_type=detection_result.type.value,
+    project_dir="/app",
+    detection=detection_result,
+    config=dict(getattr(detection_result, "raw_config", None) or {{}}),
+)
+# managed A2A discovery-only card:KSADK_A2A_RUNTIME_ID 非空时挂
+# /.well-known/agent-card.json;注册前即可被 server 探测(a2a-runtime-inbound-wiring)。
+_managed_a2a_card = None
+if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():
+    from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+
+    _managed_a2a_card = build_managed_a2a_card_if_configured()
+app = create_runtime_app(
+    RuntimeAppConfig(
+        runtime_type=detection_result.type.value,
+        runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
+        launch_context=runtime_context,
+        a2a=_managed_a2a_card,
+    ),
+    configure_runtime_app,
+)
 
 if __name__ == "__main__":
     uvicorn.run(app, host="0.0.0.0", port=8000)