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

ksadk/harness/capability_runtime.py

@@ -24,6 +24,17 @@ from ksadk.harness.tool_policy import ToolCallContext, ToolDecision, ToolPolicy
 from ksadk.harness.tool_receipts import ToolReceipt, ToolReceiptStore
 from ksadk.harness.tool_reliability import ToolReliability, classify_tool_reliability
 
+# G23 ① bypass 免疫默认清单（ApprovalPolicy.immune_prefixes/paths 可覆盖）
+_DEFAULT_IMMUNE_PREFIXES: tuple[str, ...] = (
+    "delete", "drop", "rm", "remove", "truncate", "purge", "wipe",
+    "sudo", "chmod", "chown", "shutdown", "reboot",
+)
+_DEFAULT_IMMUNE_PATHS: tuple[str, ...] = (
+    "~/.ssh", "~/.aws", "~/.config/gcloud", "~/.kube",
+    "/etc/", "/root/", "~/.bashrc", "~/.zshrc", "~/.profile",
+    ".env", "id_rsa", "credentials", "secrets",
+)
+
 #: side_effect（Studio ToolContract）→ 是否存在外部副作用。
 _SIDE_EFFECT_EXTERNAL = frozenset({"write", "external"})
 
@@ -69,12 +80,22 @@ class CapabilityRuntime:
         profiles: dict[str, ToolProfile] | None = None,
         environment: str = "draft",
         approval_mode: str = "policy",
+        classifier_available: bool = True,
+        immune_prefixes: tuple[str, ...] = (),
+        immune_paths: tuple[str, ...] = (),
     ) -> None:
         self._policy = policy or ToolPolicy()
         self._receipts = receipts
         self._profiles = dict(profiles or {})
         self._environment = environment
         self._approval_mode = approval_mode
+        # G23 审批治理面
+        self._classifier_available = classifier_available
+        self._immune_prefixes = immune_prefixes or _DEFAULT_IMMUNE_PREFIXES
+        self._immune_paths = immune_paths or _DEFAULT_IMMUNE_PATHS
+        # 熔断状态（per-runtime 内存，不跨进程；G32 范围才做跨进程）
+        self._consecutive_denials: dict[str, int] = {}
+        self._total_denials: dict[str, int] = {}
 
     # -------------------------------------------------------------- policy
 
@@ -116,22 +137,17 @@ class CapabilityRuntime:
         arguments: dict[str, Any] | None = None,
     ) -> ToolDecision:
         profile = self._profiles.get(tool_name)
-        if self._approval_mode == "never":
-            return ToolDecision(
-                action="allow",
-                reason="approval_policy.mode=never",
-                policy_ref=self._policy.policy_ref,
-                risk_level=profile.risk_level if profile else RiskLevel.LOW,
-            )
+        risk = profile.risk_level if profile else RiskLevel.LOW
+        policy_ref = self._policy.policy_ref
         prior = self.check_receipt_idempotency_only(tenant_id, tool_name)
-        return self._policy.decide(
+        policy_decision = self._policy.decide(
             ToolCallContext(
                 tenant_id=tenant_id,
                 user_id=user_id,
                 agent_id=agent_id,
                 tool_name=tool_name,
                 tool_version=profile.version if profile else "1.0.0",
-                risk_level=profile.risk_level if profile else RiskLevel.LOW,
+                risk_level=risk,
                 has_external_side_effects=(
                     profile.side_effect in _SIDE_EFFECT_EXTERNAL if profile else False
                 ),
@@ -141,6 +157,85 @@ class CapabilityRuntime:
                 prior_receipt_id=prior or "",
             )
         )
+        # Approval can authorize an ask, never override a revision's hard deny.
+        # This also applies to never mode and an unavailable classifier.
+        if policy_decision.action == "deny":
+            return policy_decision
+        # G23 ③ 熔断：连续 3 拒/累计 20 拒 → deny
+        breaker_key = f"{tenant_id}:{user_id}:{agent_id}"
+        if (
+            self._consecutive_denials.get(breaker_key, 0) >= 3
+            or self._total_denials.get(breaker_key, 0) >= 20
+        ):
+            return ToolDecision(
+                action="deny",
+                reason="approval circuit breaker open (3 consecutive or 20 total denials)",
+                policy_ref=policy_ref,
+                risk_level=risk,
+                disclosure="熔断器打开，拒绝调用",
+                decided_by="circuit_breaker",
+            )
+        # G23 ① bypass 免疫：敏感路径/敏感动词不得被 never 模式覆盖
+        immune_reason = self._check_immune(tool_name, arguments)
+        if immune_reason:
+            return ToolDecision(
+                action="require_approval",
+                reason=immune_reason,
+                policy_ref=policy_ref,
+                risk_level=risk,
+                disclosure="bypass 免疫：敏感面不可被 never 模式覆盖",
+                decided_by="immune",
+            )
+        # G23 ③ fail-closed：分类器不可用 → require_approval（不 allow）
+        if not self._classifier_available:
+            return ToolDecision(
+                action="require_approval",
+                reason="classifier unavailable (fail-closed)",
+                policy_ref=policy_ref,
+                risk_level=risk,
+                disclosure="分类器不可用，fail-closed",
+                decided_by="config",
+            )
+        if self._approval_mode == "never":
+            return ToolDecision(
+                action="allow",
+                reason="approval_policy.mode=never",
+                policy_ref=policy_ref,
+                risk_level=risk,
+                decided_by="config",
+            )
+        return policy_decision
+
+    def _check_immune(self, tool_name: str, arguments: dict[str, Any] | None) -> str:
+        """G23 ① bypass 免疫检查：敏感动词/敏感路径/敏感命令。"""
+        name_lower = tool_name.lower()
+        for prefix in self._immune_prefixes:
+            if name_lower.startswith(prefix):
+                return f"immune: tool name matches sensitive prefix {prefix!r}"
+        if arguments:
+            for key in ("path", "file_path", "command", "script"):
+                val = str(arguments.get(key) or "")
+                for immune_path in self._immune_paths:
+                    if immune_path in val:
+                        return f"immune: argument {key} matches sensitive path {immune_path!r}"
+                # command/script 参数内的敏感命令动词（rm -rf / 、sudo ... 等）
+                if key in ("command", "script"):
+                    val_lower = val.lower()
+                    for verb in self._immune_prefixes:
+                        if verb in val_lower:
+                            return f"immune: {key} contains sensitive command {verb!r}"
+        return ""
+
+    def record_denial(self, tenant_id: str, user_id: str, agent_id: str) -> None:
+        """G23 ③ 记录一次拒绝（供熔断计数）。外部审批 denied 后调用。"""
+        key = f"{tenant_id}:{user_id}:{agent_id}"
+        self._consecutive_denials[key] = self._consecutive_denials.get(key, 0) + 1
+        self._total_denials[key] = self._total_denials.get(key, 0) + 1
+
+    def reset_denials(self, tenant_id: str, user_id: str, agent_id: str) -> None:
+        """审批通过后重置连续拒绝计数（总计数保留，用于累计熔断）。"""
+        key = f"{tenant_id}:{user_id}:{agent_id}"
+        self._consecutive_denials.pop(key, None)
 
     # ------------------------------------------------------------- receipts
 

ksadk/harness/compaction_record.py

@@ -39,6 +39,22 @@ class CompactionRecord:
     dropped_critical_facts: tuple[str, ...] = field(default=())
     #: 摘要缺失但经重注入保留在模型输入中的关键事实（§8.4.1）。
     reinjected_critical_facts: tuple[str, ...] = field(default=())
+    #: 压缩边界是否落在一个进行中回合的内部（尾部以非 user/system 开头，
+    #: head 中已有 user）——G3 一期 split-turn 留痕，供恢复侧接续 pending 工具调用。
+    split_turn: bool = False
+    #: 摘要输入是否经脱敏（G12 §15.2：tool result 正文不进摘要模型输入）。
+    sanitized_input: bool = False
+    #: 摘要输入中被替换的 tool result 段数 + 敏感正则命中次数（G12）。
+    sanitized_replacements: int = 0
+    #: G3 二期 §3.2.3 摘要链：上一次 CompactionRecord 的 id（链头为空）。
+    previous_compaction_id: str = ""
+    # G21 压缩后重建预算 + boundary 一等消息 + preserved segment 锚点：
+    #: 压缩后保留的首条 entry_id（锚点，映射我们的 entry_id 而非 uuid）。
+    first_kept_entry_id: str = ""
+    #: 重建预算（压缩后重建上下文的 token 上限）。
+    rebuild_budget_tokens: int = 0
+    #: preserved segment key 集合（锚点集合）。
+    preserved_segments: tuple[str, ...] = field(default=())
 
     # ---- 质量校验（§6.4 quality_checks） ----
     tool_pairs_complete: bool = True
@@ -69,6 +85,13 @@ class CompactionRecord:
             "retained_critical_facts": list(self.retained_critical_facts),
             "dropped_critical_facts": list(self.dropped_critical_facts),
             "reinjected_critical_facts": list(self.reinjected_critical_facts),
+            "split_turn": self.split_turn,
+            "sanitized_input": self.sanitized_input,
+            "sanitized_replacements": self.sanitized_replacements,
+            "previous_compaction_id": self.previous_compaction_id,
+            "first_kept_entry_id": self.first_kept_entry_id,
+            "rebuild_budget_tokens": self.rebuild_budget_tokens,
+            "preserved_segments": list(self.preserved_segments),
             "quality_checks": self.quality_checks(),
         }
 
@@ -86,6 +109,10 @@ def build_compaction_record(
     reinjected_critical_facts: tuple[str, ...] = (),
     summary_model_ref: str = "",
     memory_candidate_refs: tuple[str, ...] = (),
+    split_turn: bool = False,
+    sanitized_input: bool = False,
+    sanitized_replacements: int = 0,
+    previous_compaction_id: str = "",
     tool_pairs_complete: bool = True,
     approvals_preserved: bool = True,
     goal_preserved: bool = True,
@@ -112,6 +139,10 @@ def build_compaction_record(
         retained_critical_facts=retained_critical_facts,
         dropped_critical_facts=dropped_critical_facts,
         reinjected_critical_facts=reinjected_critical_facts,
+        split_turn=split_turn,
+        sanitized_input=sanitized_input,
+        sanitized_replacements=sanitized_replacements,
+        previous_compaction_id=previous_compaction_id,
         tool_pairs_complete=tool_pairs_complete,
         approvals_preserved=approvals_preserved,
         goal_preserved=goal_preserved,

ksadk/harness/compiler.py

@@ -53,10 +53,10 @@ class OrchestrationInput(_RevisionInputModel):
 
 
 class RevisionModelProviderPolicyInput(_RevisionInputModel):
-    max_attempts_per_model: int = Field(default=10, ge=1, le=10)
-    total_attempt_budget: int = Field(default=20, ge=1, le=40)
+    max_attempts_per_model: int = Field(default=3, ge=1, le=10)
+    total_attempt_budget: int = Field(default=6, ge=1, le=40)
     initial_backoff_ms: int = Field(default=1_000, ge=0, le=30_000)
-    max_backoff_ms: int = Field(default=60_000, ge=0, le=60_000)
+    max_backoff_ms: int = Field(default=4_000, ge=0, le=60_000)
     retryable_categories: tuple[ModelFailureCategory, ...] = tuple(ModelFailureCategory)
     failover_categories: tuple[ModelFailureCategory, ...] = tuple(ModelFailureCategory)
 

ksadk/harness/config.py

@@ -1,8 +1,10 @@
 """HarnessApp yaml 配置 — 最小子集 + 严格校验 (goal-08)。
 
 本期硬边界(防膨胀):**只支持最小子集** ``model`` / ``prompt``(instruction)/
-``mcp_tools`` / ``sandbox``。超出子集的字段(memory/knowledge/workflow/tracing 等)
-**明确报"暂不支持"**,不硬翻、不静默忽略。
+``mcp_tools`` / ``sandbox``,以及已进入支持子集的 ``runtime``(yaml|codex,
+已在运行时接线)与 ``skill_paths``(外部 Skill 目录挂载声明;解析/校验已完成,
+运行时消费接线在后续里程碑交付)。超出子集的字段(memory/knowledge/workflow/
+tracing 等)**明确报"暂不支持"**,不硬翻、不静默忽略。
 """
 
 from __future__ import annotations
@@ -14,7 +16,9 @@ from typing import Any, Optional
 import yaml  # type: ignore[import-untyped]
 
 #: 顶层允许的最小子集字段。
-_ALLOWED_TOP_LEVEL = frozenset({"model", "prompt", "mcp_tools", "sandbox", "runtime"})
+_ALLOWED_TOP_LEVEL = frozenset(
+    {"model", "prompt", "mcp_tools", "sandbox", "runtime", "skill_paths"}
+)
 #: runtime 允许的值。
 _ALLOWED_RUNTIME = frozenset({"yaml", "codex"})
 #: mcp_tools 单项允许字段。
@@ -28,7 +32,7 @@ _KNOWN_UNSUPPORTED = {
     "knowledge": "knowledge(知识库)暂不支持,后续阶段提供",
     "workflow": "workflow(工作流编排)暂不支持,后续阶段提供",
     "tracing": "tracing(可观测)暂不支持,后续阶段提供",
-    "skills": "skills(技能)暂不支持,后续阶段提供",
+    "skills": "skills(技能)暂不支持,请使用 skill_paths 挂载本地技能目录",
 }
 
 
@@ -45,6 +49,9 @@ class McpToolSpec:
     api_key: Optional[str] = field(default=None, repr=False)
     tool_filter: tuple[str, ...] = ()
     tool_name_prefix: Optional[str] = None
+    #: 静态已知的服务描述（G9 §12.3.2）：来源为 Provider 声明而非 MCP initialize
+    #: 活体信息；为空时 L0 目录沿用 Provider 默认占位。
+    description: str = ""
 
 
 @dataclass(frozen=True)
@@ -64,6 +71,11 @@ class HarnessConfig:
     sandbox: SandboxPolicy = field(default_factory=SandboxPolicy)
     runtime: str = "yaml"
     """runtime 后端:``yaml``(HarnessRuntimeAdapter)| ``codex``(CodexRuntimeAdapter)。"""
+    skill_paths: tuple[str, ...] = ()
+    # G26 声明式注册面：hooks 固化在 Config→编译产物（不进 Spec 数据面；
+    # Spec 是 revision 冻结内容，不可含可执行对象）。元素为 HookDeclaration 或
+    # 裸 ProviderHook（后者自动包成默认 non_blocking 声明）。
+    hooks: list = field(default_factory=list)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any], *, source: str = "yaml") -> "HarnessConfig":
@@ -88,8 +100,19 @@ class HarnessConfig:
             )
         )
         sandbox = _parse_sandbox(data.get("sandbox", {}), source)
+        raw_skill_paths = data.get("skill_paths", [])
+        if not isinstance(raw_skill_paths, list) or any(
+            not isinstance(item, str) or not item.strip() for item in raw_skill_paths
+        ):
+            raise HarnessConfigError(f"{source}: 字段 'skill_paths' 必须是非空字符串列表")
+        skill_paths = tuple(item.strip() for item in raw_skill_paths)
         return cls(
-            model=model, prompt=prompt, mcp_tools=mcp_tools, sandbox=sandbox, runtime=runtime
+            model=model,
+            prompt=prompt,
+            mcp_tools=mcp_tools,
+            sandbox=sandbox,
+            runtime=runtime,
+            skill_paths=skill_paths,
         )
 
     @classmethod

ksadk/harness/conformance/contract.py

@@ -269,9 +269,7 @@ def verify_tool_failure_honesty(events: list[RuntimeEvent], report: ConformanceR
             )
 
 
-def verify_tool_reliability_honesty(
-    events: list[RuntimeEvent], report: ConformanceReport
-) -> None:
+def verify_tool_reliability_honesty(events: list[RuntimeEvent], report: ConformanceReport) -> None:
     """Tool 可靠性声明必须与 Receipt/Transport 事实一致。
 
     旧 Runner 没有该 metadata 时保持兼容；一旦声明，就不允许把只有 Receipt 的
@@ -293,9 +291,7 @@ def verify_tool_reliability_honesty(
         side_effect = str(reliability.get("side_effect") or "unknown")
         if semantics not in valid_semantics:
             report.fail("tool-reliability", f"{call_id} 交付语义非法: {semantics!r}")
-        if semantics == "effectively_once" and not (
-            receipt_enabled and transport_idempotent
-        ):
+        if semantics == "effectively_once" and not (receipt_enabled and transport_idempotent):
             report.fail(
                 "tool-reliability",
                 f"{call_id} effectively_once 缺少 Receipt 或 Transport 幂等",
@@ -317,10 +313,11 @@ def verify_tool_reliability_honesty(
 
 
 def verify_approval_flow(events: list[RuntimeEvent], report: ConformanceReport) -> None:
-    """approval.requested → run.interrupted(审批) → approval.resolved → run.resumed 顺序守恒。"""
+    """Approval needs its own interrupt; any resume needs a prior interrupt."""
     requested: set[str] = set()
     resolved: set[str] = set()
     seen_interrupt = False
+    seen_approval_interrupt = False
     for event in events:
         if event.event_type == EventType.APPROVAL_REQUESTED:
             approval_id = str(_payload(event).get("approval_id", ""))
@@ -328,8 +325,9 @@ def verify_approval_flow(events: list[RuntimeEvent], report: ConformanceReport)
                 report.fail("approval-idempotency", f"approval_id 重复 requested: {approval_id}")
             requested.add(approval_id)
         elif event.event_type == EventType.RUN_INTERRUPTED:
+            seen_interrupt = True
             if str(_payload(event).get("reason", "")) == "tool_approval":
-                seen_interrupt = True
+                seen_approval_interrupt = True
         elif event.event_type == EventType.APPROVAL_RESOLVED:
             approval_id = str(_payload(event).get("approval_id", ""))
             if approval_id and approval_id not in requested:
@@ -337,12 +335,13 @@ def verify_approval_flow(events: list[RuntimeEvent], report: ConformanceReport)
             if approval_id in resolved:
                 report.fail("approval-idempotency", f"approval_id 重复 resolved: {approval_id}")
             resolved.add(approval_id)
-            if not seen_interrupt:
+            if not seen_approval_interrupt:
                 report.fail("approval-flow", "approval.resolved 出现在 run.interrupted 之前")
         elif event.event_type == EventType.RUN_RESUMED:
             if not seen_interrupt:
                 report.fail("recovery", "run.resumed 必须出现在 run.interrupted 之后")
             seen_interrupt = False
+            seen_approval_interrupt = False
 
 
 def verify_checkpoint_honesty(events: list[RuntimeEvent], report: ConformanceReport) -> None:
@@ -471,8 +470,7 @@ def run_conformance_suite(
     # model/tool call namespace. Validate every native run independently.
     streams: dict[str, list[RuntimeEvent]] = {}
     for event in events:
-        native_run = str(getattr(event, "run_id", None) or
-                         getattr(event, "invocation_id", ""))
+        native_run = str(getattr(event, "run_id", None) or getattr(event, "invocation_id", ""))
         streams.setdefault(native_run, []).append(event)
     for stream in streams.values() or [events]:
         verify_start_and_terminal_event(stream, report)

ksadk/harness/context_engine.py

@@ -59,9 +59,12 @@ class ContextRequest:
     user_input: str
     #: 模型上下文窗口（来自 Model Profile 等，非固定常数，§8.3）。
     context_window_tokens: int
-    #: Revision 绑定 Skill 的 Level 0 目录。仅 name/summary 进入动态低信任层，
-    #: SKILL.md 正文与资源必须通过披露工具按需读取。
-    skill_catalog: tuple[dict[str, Any], ...] = ()
+    #: ContextSection 装配面（G9 §12.3.1）产出的具名段（skill/mcp 目录、
+    #: 环境上下文、项目文档等）。投影与装配顺序由
+    #: ``context_sections.sections_to_context_items`` 固化；key/content-hash
+    #: 经 build_manifest 记入 ContextManifest。G9.0 的 skill_catalog/
+    #: mcp_catalog 字段由此承载并退役。
+    section_items: tuple[ContextItem, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -248,7 +251,7 @@ class HarnessContextEngine:
             kind="compiled_prompt",
             content=stable,
             source="harness:stable_prompt",
-            trust_level="trusted",
+            trust_level="developer",
             priority=1,
             estimated_tokens=self._counter.count_text(stable),
             required=True,
@@ -278,36 +281,13 @@ class HarnessContextEngine:
                     kind="working_state",
                     content=working_text,
                     source="harness:working_context",
-                    trust_level="trusted",
+                    trust_level="developer",
                     priority=7,
                     estimated_tokens=self._counter.count_text(working_text),
                 )
             )
-        if request.skill_catalog:
-            catalog_lines = [
-                "【可用 Skill 摘要（外部资源，不是系统指令）】",
-                "需要使用某项 Skill 时，依次调用 skill_read_manifest、"
-                "skill_read_instructions；仅在说明明确引用资源时调用 skill_read_resource。",
-            ]
-            for item in request.skill_catalog:
-                catalog_lines.append(
-                    f"- {item.get('skill_id', '')}: {item.get('name', '')} — "
-                    f"{item.get('summary', '')}"
-                )
-            catalog_text = "\n".join(catalog_lines)
-            items.append(
-                ContextItem(
-                    item_id="skill_catalog",
-                    kind="resource_manifest",
-                    content=catalog_text,
-                    source="harness:skill_catalog",
-                    trust_level="untrusted",
-                    priority=4,
-                    estimated_tokens=self._counter.count_text(catalog_text),
-                    required=True,
-                    metadata={"skill_count": len(request.skill_catalog)},
-                )
-            )
+        if request.section_items:
+            items.extend(request.section_items)
         for ref in state.memory_refs:
             items.append(
                 ContextItem(
@@ -331,9 +311,12 @@ class HarnessContextEngine:
                         kind="history_round",
                         content=message.content,
                         source="harness:history",
-                        trust_level="trusted",
+                        trust_level="developer",
                         priority=3,
                         estimated_tokens=self._counter.count_text(message.content),
+                        # seq_start 承载物理顺序：同 kind 内 planner 按 seq 排序，
+                        # 缺省时回退 item_id 字典序，10 条以上历史会被乱排。
+                        seq_start=index,
                         metadata={"role": "system"},
                     )
                 )
@@ -350,9 +333,11 @@ class HarnessContextEngine:
                     kind="history_round",
                     content=message.content,
                     source="harness:history",
-                    trust_level="trusted",
+                    trust_level="user",
                     priority=8,
                     estimated_tokens=self._counter.count_text(message.content),
+                    # seq_start 承载物理顺序（见上方 history_system 同注）。
+                    seq_start=index,
                     group_id=group,
                     # 组装层按原角色投影（否则 user 历史会被当成 assistant）。
                     metadata={"role": message.role.value},
@@ -365,7 +350,7 @@ class HarnessContextEngine:
                     kind="current_input",
                     content=request.user_input,
                     source="harness:current_input",
-                    trust_level="trusted",
+                    trust_level="user",
                     priority=2,
                     estimated_tokens=self._counter.count_text(request.user_input),
                     required=True,