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

ksadk/harness/working_context.py

@@ -0,0 +1,81 @@
+"""Working Context 更新机制（plan §8.5 + 长任务方案 §6.1 Patch 化）。
+
+确定性规则维护 Session/Task 生命周期的影子工作上下文：
+- Tool 失败 / 审批拒绝 → ``recent_tool_failures``（有界滑动窗口）；
+- Tool 结果中的关键事实（ID/金额/日期/版本/审批号）→ ``verified_facts``
+  （有界，去重）。
+
+所有更新经 :mod:`working_context_patch` 的结构化 Patch（版本 + 来源 + 理由），
+不使用模型调用——与 PCM 的"纯计算 + 受控调用"分层一致。
+"""
+
+from __future__ import annotations
+
+from ksadk.harness.context_engine import extract_critical_facts
+from ksadk.harness.state import WorkingContext
+from ksadk.harness.working_context_patch import (
+    PatchOperation,
+    WorkingContextPatch,
+    apply_patch,
+)
+
+_MAX_TOOL_FAILURES = 8
+_MAX_VERIFIED_FACTS = 32
+
+
+def record_tool_failure(
+    working: WorkingContext,
+    *,
+    name: str,
+    error: str,
+    source_event_id: str = "",
+) -> WorkingContext:
+    """记录一次工具失败/审批拒绝（有界，保留最近 N 条；走结构化 Patch）。"""
+    entry = f"{name}: {error}"[:512]
+    bounded = (working.recent_tool_failures + (entry,))[-_MAX_TOOL_FAILURES:]
+    return apply_patch(
+        working,
+        WorkingContextPatch(
+            base_version=working.version,
+            operations=(
+                PatchOperation(
+                    op="set", field_name="recent_tool_failures", value=bounded
+                ),
+            ),
+            source_event_ids=(source_event_id,) if source_event_id else (),
+            reason=f"tool_failure:{name}",
+        ),
+    )
+
+
+def record_tool_result(
+    working: WorkingContext,
+    *,
+    name: str,
+    result_text: str,
+    source_event_id: str = "",
+) -> WorkingContext:
+    """从工具结果抽取关键事实记入 verified_facts（去重、有界；走结构化 Patch）。"""
+    facts = extract_critical_facts(result_text)
+    if not facts:
+        return working
+    existing = set(working.verified_facts)
+    merged = working.verified_facts + tuple(
+        entry for entry in (f"{name} -> {fact}" for fact in sorted(facts)) if entry not in existing
+    )
+    return apply_patch(
+        working,
+        WorkingContextPatch(
+            base_version=working.version,
+            operations=(
+                PatchOperation(
+                    op="set", field_name="verified_facts", value=merged[-_MAX_VERIFIED_FACTS:]
+                ),
+            ),
+            source_event_ids=(source_event_id,) if source_event_id else (),
+            reason=f"tool_result:{name}",
+        ),
+    )
+
+
+__all__ = ["record_tool_failure", "record_tool_result"]

ksadk/harness/working_context_patch.py

@@ -0,0 +1,99 @@
+"""WorkingContextPatch（长任务方案 §6.1 / P1）。
+
+Working Context 更新必须走结构化 Patch——带版本（乐观并发）、来源事件和
+理由，禁止每轮无条件全量重写：
+
+- ``PatchOperation``：set / append / remove 单字段操作；
+- ``WorkingContextPatch``：base_version + operations + 来源 + 理由；
+- :func:`apply_patch`：校验版本 → 逐操作应用 → version+1。版本冲突抛
+  :class:`WorkingContextVersionError`（不静默覆盖）。
+
+确定性维护函数（``record_tool_result`` 等）内部也走 Patch——Working Context
+的每次变化都有版本和审计锚点，可从 Transcript 重放重建。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ksadk.harness.state import WorkingContext
+
+#: 单个 Patch 的操作数上限——防御异常膨胀的全量重写。
+_MAX_OPERATIONS = 32
+
+
+class WorkingContextVersionError(RuntimeError):
+    """Patch 的 base_version 与当前 version 不一致（并发更新冲突）。"""
+
+
+@dataclass(frozen=True)
+class PatchOperation:
+    """单个字段操作。"""
+
+    op: str  # "set" | "append" | "remove"
+    field_name: str
+    value: Any = None
+
+
+@dataclass(frozen=True)
+class WorkingContextPatch:
+    """一次 Working Context 更新（版本 + 操作 + 来源 + 理由）。"""
+
+    base_version: int
+    operations: tuple[PatchOperation, ...] = field(default=())
+    source_event_ids: tuple[str, ...] = field(default=())
+    reason: str = ""
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "base_version": self.base_version,
+            "operations": [
+                {"op": o.op, "field": o.field_name, "value": o.value}
+                for o in self.operations
+            ],
+            "source_event_ids": list(self.source_event_ids),
+            "reason": self.reason,
+        }
+
+
+def apply_patch(working: WorkingContext, patch: WorkingContextPatch) -> WorkingContext:
+    """应用 Patch：版本校验 → 逐操作应用（走 pydantic 校验）→ version+1。
+
+    版本不匹配抛 :class:`WorkingContextVersionError`；未知字段/非法值由
+    WorkingContext 的 pydantic 校验兜底（``ValidationError``）。
+    """
+    if patch.base_version != working.version:
+        raise WorkingContextVersionError(
+            f"working context version conflict: patch base={patch.base_version}, "
+            f"current={working.version}"
+        )
+    if len(patch.operations) > _MAX_OPERATIONS:
+        raise ValueError(f"patch operations exceed limit {_MAX_OPERATIONS}")
+    updates: dict[str, Any] = {}
+    for operation in patch.operations:
+        if operation.field_name not in WorkingContext.model_fields:
+            raise ValueError(f"unknown working context field: {operation.field_name!r}")
+        current = getattr(working, operation.field_name, updates.get(operation.field_name))
+        if operation.op == "set":
+            new_value = operation.value
+        elif operation.op == "append":
+            if not isinstance(current, tuple):
+                raise ValueError(f"append 仅支持 tuple 字段: {operation.field_name}")
+            new_value = current + (operation.value,)
+        elif operation.op == "remove":
+            if not isinstance(current, tuple):
+                raise ValueError(f"remove 仅支持 tuple 字段: {operation.field_name}")
+            new_value = tuple(v for v in current if v != operation.value)
+        else:
+            raise ValueError(f"unknown patch op: {operation.op!r}")
+        updates[operation.field_name] = new_value
+    return working.model_copy(update={**updates, "version": working.version + 1})
+
+
+__all__ = [
+    "PatchOperation",
+    "WorkingContextPatch",
+    "WorkingContextVersionError",
+    "apply_patch",
+]

ksadk/identity/resolver.py

@@ -99,6 +99,24 @@ def _should_retry_intranet(error: Exception | None) -> bool:
     return "InnerAccountCanOnlyAccessThroughIntranet" in str(error)
 
 
+def iam_endpoint_candidates(primary: str) -> tuple[str, ...]:
+    """Return the configured IAM endpoint followed by the inner-account fallback.
+
+    Keep endpoint selection in one place so callers that need strict identity
+    verification and callers that only enrich request headers cannot drift.
+    The fallback is attempted only after the primary request reports the
+    explicit inner-account error.
+    """
+    normalized = str(primary or "").strip() or "https://iam.api.ksyun.com"
+    intranet = "http://iam.inner.api.ksyun.com"
+    return (normalized,) if normalized == intranet else (normalized, intranet)
+
+
+def is_inner_account_error(error: Exception | None) -> bool:
+    """Whether an IAM failure explicitly requires the intranet endpoint."""
+    return _should_retry_intranet(error)
+
+
 # ---------------------------------------------------------------------------
 # ksyun SDK 惰性导入
 # ---------------------------------------------------------------------------

ksadk/interaction/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Durable Interaction ledger（Phase 1 Task 5，Interaction/v1）。"""
+"""Durable Interaction ledger（Kernel Task 5，Interaction/v1）。"""
 
 from ksadk.interaction.contracts import (
     InteractionRecord,

ksadk/interaction/ledger.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""``InteractionLedger`` port 与跨后端共享的台账语义（Phase 1 Task 5）。
+"""``InteractionLedger`` port 与跨后端共享的台账语义（Kernel Task 5）。
 
 所有 mutation 都接受 :class:`~ksadk.kernel.contracts.ActivationWriteGuard`
 并在 store 事务内与 activation lease 做 fence CAS；request 写 pending 行 +

ksadk/interaction/provider.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""InteractionProvider seam（Phase 1 Task 6 Step 1）。
+"""InteractionProvider seam（Kernel Task 6 Step 1）。
 
 Interaction 回包的分发 seam：Worker 载入权威 :class:`InteractionRecord`
 后，把回包交给 record 绑定的 provider，由 provider 用 **activation 持有的**

ksadk/interaction/providers/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""框架原生 InteractionProvider 注册表（Phase 1 Task 6）。
+"""框架原生 InteractionProvider 注册表（Kernel Task 6）。
 
 provider 是无状态映射器（adapter/handle 由
 :class:`~ksadk.interaction.provider.InteractionResolveContext` 注入），
@@ -17,6 +17,7 @@ from ksadk.interaction.provider import (
 )
 from ksadk.interaction.providers.adk import ADKInteractionProvider
 from ksadk.interaction.providers.codex import CodexInteractionProvider
+from ksadk.interaction.providers.harness import HarnessInteractionProvider
 from ksadk.interaction.providers.langgraph import LangGraphInteractionProvider
 
 
@@ -27,6 +28,7 @@ def default_interaction_providers() -> dict[str, InteractionProvider]:
         CodexInteractionProvider(),
         LangGraphInteractionProvider(),
         ADKInteractionProvider(),
+        HarnessInteractionProvider(),
     ]
     registry: dict[str, InteractionProvider] = {}
     for provider in providers:

ksadk/interaction/providers/adk.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""ADK InteractionProvider：诚实声明 unavailable（Phase 1 Task 6 Step 6）。
+"""ADK InteractionProvider：诚实声明 unavailable（Kernel Task 6 Step 6）。
 
 ADK 的 confirmation/function-response 回包语义上要求以原 invocation 的
 native 身份续跑；当前生产 ``ADKRuntimeAdapter``（forward-only resume 经

ksadk/interaction/providers/codex.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Codex InteractionProvider：live JSON-RPC approval 回包（Phase 1 Task 6 Step 6）。
+"""Codex InteractionProvider：live JSON-RPC approval 回包（Kernel Task 6 Step 6）。
 
 Codex 的 HITL 模型是**事件流 + 独立 live 命令通道**：审批卡阻塞在
 ``item/commandExecution/requestApproval``，回包必须经

ksadk/interaction/providers/harness.py

@@ -0,0 +1,50 @@
+"""Managed Harness interactions resume the original durable thread checkpoint."""
+
+from __future__ import annotations
+
+from ksadk.interaction.contracts import InteractionRecord, InteractionSubmission
+from ksadk.interaction.provider import InteractionResolveContext, require_capability
+from ksadk.runtime.adapter import CancelResult, ResumePayload, ResumeTarget, RunHandle
+
+
+class HarnessInteractionProvider:
+    provider_id = "harness"
+    mode = "durable_resume"
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle:
+        require_capability(context, "resume", provider_id=self.provider_id)
+        require_capability(context, "submit_interaction", provider_id=self.provider_id)
+        native_target = record.native_target or {}
+        thread_id = str(native_target.get("thread_id") or "")
+        if not thread_id or thread_id != context.handle.native_ref.get("thread_id"):
+            raise ValueError("Harness interaction must target its original checkpoint thread")
+        if submission.action == "cancel":
+            require_capability(context, "cancel", provider_id=self.provider_id)
+            result = await context.adapter.cancel(context.handle)
+            if result == CancelResult.FAILED:
+                raise RuntimeError("Harness could not cancel the pending interaction")
+            return context.handle
+        response = submission.response
+        if record.kind == "approval":
+            if submission.action in {"approve", "reject"}:
+                response = {"decision": submission.action}
+            if not isinstance(response, dict) or response.get("decision") not in {
+                "approve",
+                "reject",
+            }:
+                raise ValueError("Harness approval requires an explicit approve or reject decision")
+        return await context.adapter.resume(
+            context.handle,
+            ResumeTarget(kind="thread_id", id=thread_id),
+            ResumePayload(
+                kind="approval_decision" if record.kind == "approval" else "hitl_answer",
+                call_id=str(native_target.get("call_id") or record.interaction_id),
+                data=response,
+                session_context=context.session_context,
+            ),
+        )

ksadk/interaction/providers/langgraph.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""LangGraph InteractionProvider：checkpoint resume 回包（Phase 1 Task 6 Step 6）。
+"""LangGraph InteractionProvider：checkpoint resume 回包（Kernel Task 6 Step 6）。
 
 LangGraph 的 HITL 模型是 interrupt + checkpoint：graph 停在
 ``__interrupt__``，durable 状态保存在 thread 的 checkpoint。回包必须映射为

ksadk/kernel/__init__.py

@@ -51,6 +51,12 @@ from ksadk.kernel.errors import (
     StaleFenceError,
     UnsupportedError,
 )
+from ksadk.kernel.execution_grants import (
+    ExecutionGrantBarrier,
+    ExecutionGrantCommand,
+    ExecutionGrantRecord,
+    ExecutionGrantSpec,
+)
 
 # worker 依赖 ksadk.runtime.adapter；runtime.adapter 又经 ksadk.events 回指本包的
 # contracts，急切导入会成环，故用 PEP 562 惰性导出。
@@ -70,6 +76,10 @@ __all__ = [
     "AgentControlPermitVerifier",
     "AgentKernel",
     "AgentKernelWorker",
+    "ExecutionGrantBarrier",
+    "ExecutionGrantCommand",
+    "ExecutionGrantRecord",
+    "ExecutionGrantSpec",
     "JwksSource",
     "PermitExpiredError",
     "VerifiedAdmission",

ksadk/kernel/approval_presentation.py

@@ -0,0 +1,91 @@
+"""Bounded, redacted approval previews; native continuation data stays private."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+
+from ksadk.events.canonical import ApprovalRequest
+from ksadk.interaction.contracts import InteractionPresentation
+
+_SECRET_FIELD = re.compile(
+    r"secret|password|passphrase|token|credential|api[_-]?key|access[_-]?key|private[_-]?key|authorization|cookie",
+    re.IGNORECASE,
+)
+_TRUNCATED = "…（预览已截断）"
+
+
+class _Preview:
+    def __init__(self):
+        self.remaining = 12_000
+        self.nodes = 128
+        self.truncated = False
+
+    def value(self, value, depth=0):
+        self.nodes -= 1
+        if depth > 6 or self.nodes < 0 or self.remaining <= 0:
+            self.truncated = True
+            return _TRUNCATED
+        if isinstance(value, str):
+            size = min(4096, self.remaining)
+            text = value[:size]
+            self.remaining -= len(text)
+            if len(text) < len(value):
+                self.truncated = True
+                return text + _TRUNCATED
+            return text
+        if isinstance(value, Mapping):
+            result = {}
+            for key, item in value.items():
+                if len(result) >= 32 or self.nodes <= 0:
+                    self.truncated = True
+                    break
+                key = str(key)
+                display_key = key[:128]
+                if len(key) > 128:
+                    self.truncated = True
+                result[display_key] = (
+                    "[REDACTED]" if _SECRET_FIELD.search(key) else self.value(item, depth + 1)
+                )
+            return result
+        if isinstance(value, (list, tuple)):
+            if len(value) > 32:
+                self.truncated = True
+            return [self.value(item, depth + 1) for item in value[:32]]
+        return value
+
+
+def approval_presentation(request: ApprovalRequest) -> InteractionPresentation:
+    detail = request.detail if isinstance(request.detail, Mapping) else {}
+    # Unwrap only the typed child request. Handles, policy references and other
+    # surrounding execution metadata are never copied into the public preview.
+    for _ in range(32):
+        child = detail.get("child_approval")
+        if not isinstance(child, Mapping):
+            break
+        detail = child
+    title = {
+        "command_execution": "run_command",
+        "file_change": "apply_patch",
+        "permissions": "request_permission",
+        "dynamic_tool_call": "tool_call",
+    }.get(request.kind, request.kind)
+    arguments = {
+        key: detail[key]
+        for key in ("command", "cwd", "reason", "grantRoot", "proposedExecpolicyAmendment")
+        if key in detail and detail[key] is not None
+    }
+    if isinstance(detail.get("name"), str) and isinstance(detail.get("args"), Mapping):
+        title, arguments = detail["name"], detail["args"]
+    preview = _Preview()
+    payload = {"arguments": preview.value(arguments)}
+    risk = detail.get("risk")
+    if isinstance(risk, str) and risk in {"low", "medium", "high", "critical"}:
+        payload["risk"] = risk
+    if preview.truncated:
+        payload["previewTruncated"] = True
+    return InteractionPresentation(
+        title=title[:128],
+        description=json.dumps(payload, ensure_ascii=False, separators=(",", ":")),
+    )

ksadk/kernel/authorization.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""AgentControlPermit 验证（Phase 1 Task 6 Step 4）。
+"""AgentControlPermit 验证（Kernel Task 6 Step 4）。
 
 - 签名：Ed25519，输入为除 ``signature`` 外、key-sort、无空白 UTF-8 JSON；
   时间戳归一化为 UTC RFC3339 秒精度；签名为 base64url 无 padding。