agentengine-sdk-python 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

ksadk/plugins/subagents.py

@@ -0,0 +1,333 @@
+"""Frozen SubagentProvider/v1 seam with explicit lineage and policy bounds.
+
+The Kernel does not know whether a child is implemented by Codex, DSH,
+Claude, another KsADK AgentProvider, or a remote service.  It only routes a
+bounded request to a named provider and retains the returned child identity.
+Provider-private state and event logs remain with that provider; projected
+child events keep their own ids and sequence numbers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping, Sequence
+from datetime import datetime
+from typing import Any, Literal, Protocol, cast, runtime_checkable
+
+from pydantic import Field, field_validator, model_validator
+
+from ksadk.plugins.contracts import PluginContractModel, PluginReference
+
+
+class SubagentPolicy(PluginContractModel):
+    """Parent-owned limits that a child provider may only narrow."""
+
+    max_depth: int = Field(default=1, ge=1, le=16)
+    timeout_seconds: int = Field(default=120, ge=1, le=86_400)
+    max_steps: int = Field(default=12, ge=1, le=10_000)
+    background: bool = False
+    allowed_tools: tuple[str, ...] = ()
+    allowed_permissions: tuple[str, ...] = ()
+
+    @field_validator("allowed_tools", "allowed_permissions")
+    @classmethod
+    def validate_unique_values(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("subagent policy entries must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("subagent policy entries must be unique")
+        return tuple(sorted(value))
+
+
+class SpawnSubagentRequest(PluginContractModel):
+    """One bounded child task requested by an authenticated parent Run."""
+
+    request_format: Literal["ksadk.subagent-spawn/v1"] = "ksadk.subagent-spawn/v1"
+    provider_ref: str
+    parent_session_id: str = Field(min_length=1, max_length=256)
+    parent_run_id: str = Field(min_length=1, max_length=256)
+    task: str = Field(min_length=1, max_length=131_072)
+    depth: int = Field(default=1, ge=1, le=16)
+    policy: SubagentPolicy = Field(default_factory=SubagentPolicy)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str) -> str:
+        return cast(str, PluginReference(ref=value).ref)
+
+    @field_validator("metadata")
+    @classmethod
+    def validate_metadata(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_secret_values(value)
+        return value
+
+    @model_validator(mode="after")
+    def validate_depth(self) -> "SpawnSubagentRequest":
+        if self.depth > self.policy.max_depth:
+            raise ValueError("subagent depth exceeds the parent policy maxDepth")
+        return self
+
+
+class ChildHandle(PluginContractModel):
+    """Stable lineage and recovery descriptor for one provider-owned child."""
+
+    handle_format: Literal["ksadk.child-handle/v1"] = "ksadk.child-handle/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    provider_ref: str
+    parent_session_id: str = Field(min_length=1, max_length=256)
+    parent_run_id: str = Field(min_length=1, max_length=256)
+    child_session_id: str | None = Field(default=None, max_length=256)
+    child_run_id: str | None = Field(default=None, max_length=256)
+    depth: int = Field(ge=1, le=16)
+    capabilities: tuple[str, ...] = ()
+    capability_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    created_at: datetime
+    resumable: bool = False
+    resume_descriptor: dict[str, Any] | None = None
+
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str) -> str:
+        return cast(str, PluginReference(ref=value).ref)
+
+    @field_validator("capabilities")
+    @classmethod
+    def validate_capabilities(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("child capabilities must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("child capabilities must be unique")
+        return tuple(sorted(value))
+
+    @field_validator("created_at")
+    @classmethod
+    def validate_created_at(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("child handle createdAt must include a timezone")
+        return value
+
+    @field_validator("resume_descriptor")
+    @classmethod
+    def validate_resume_descriptor(
+        cls, value: dict[str, Any] | None
+    ) -> dict[str, Any] | None:
+        if value is not None:
+            _reject_secret_values(value)
+        return value
+
+    @model_validator(mode="after")
+    def validate_recovery_shape(self) -> "ChildHandle":
+        if self.resumable and not self.resume_descriptor:
+            raise ValueError("resumable child handle requires a resumeDescriptor")
+        if not self.resumable and self.resume_descriptor is not None:
+            raise ValueError("non-resumable child handle cannot carry a resumeDescriptor")
+        return self
+
+
+class SubagentStatus(PluginContractModel):
+    status_format: Literal["ksadk.subagent-status/v1"] = "ksadk.subagent-status/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    state: Literal[
+        "accepted",
+        "running",
+        "waiting_input",
+        "succeeded",
+        "failed",
+        "cancelled",
+        "interrupted",
+        "disposed",
+    ]
+    last_seq: int = Field(default=0, ge=0)
+    updated_at: datetime
+    reason: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("updated_at")
+    @classmethod
+    def validate_updated_at(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("subagent status updatedAt must include a timezone")
+        return value
+
+
+class SubagentEvent(PluginContractModel):
+    """Identity-preserving child event; parent projection must not merge by text."""
+
+    event_format: Literal["ksadk.subagent-event/v1"] = "ksadk.subagent-event/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    event_id: str = Field(min_length=1, max_length=256)
+    seq: int = Field(ge=1)
+    kind: Literal["progress", "item", "interaction", "terminal"]
+    payload: dict[str, Any] = Field(default_factory=dict)
+    native_ref: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("payload")
+    @classmethod
+    def validate_payload(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_secret_values(value)
+        return value
+
+
+class SubagentResult(PluginContractModel):
+    result_format: Literal["ksadk.subagent-result/v1"] = "ksadk.subagent-result/v1"
+    handle_id: str = Field(min_length=1, max_length=256)
+    state: Literal["succeeded", "failed", "cancelled", "interrupted"]
+    output: Any = None
+    output_refs: tuple[str, ...] = ()
+    error_code: str | None = Field(default=None, max_length=256)
+    error_message: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("output_refs")
+    @classmethod
+    def validate_output_refs(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item.strip() for item in value):
+            raise ValueError("subagent output references must be non-empty")
+        if len(value) != len(set(value)):
+            raise ValueError("subagent output references must be unique")
+        return tuple(sorted(value))
+
+    @model_validator(mode="after")
+    def validate_terminal_shape(self) -> "SubagentResult":
+        if self.state == "succeeded" and (self.error_code or self.error_message):
+            raise ValueError("successful subagent result cannot carry an error")
+        if self.state == "failed" and not self.error_code:
+            raise ValueError("failed subagent result requires errorCode")
+        return self
+
+
+@runtime_checkable
+class SubagentProvider(Protocol):
+    """Named child execution provider; every method is provider-owned."""
+
+    async def describe(self) -> Mapping[str, Any]: ...
+
+    async def available(self) -> bool: ...
+
+    async def spawn(self, request: SpawnSubagentRequest) -> ChildHandle: ...
+
+    async def followup(self, handle: ChildHandle, input: Any) -> None: ...
+
+    async def status(self, handle: ChildHandle) -> SubagentStatus: ...
+
+    async def interrupt(self, handle: ChildHandle) -> None: ...
+
+    async def cancel(self, handle: ChildHandle) -> None: ...
+
+    def subscribe(
+        self, handle: ChildHandle, *, after_seq: int = 0
+    ) -> AsyncIterator[SubagentEvent]: ...
+
+    async def result(self, handle: ChildHandle) -> SubagentResult: ...
+
+    async def dispose(self, handle: ChildHandle) -> None: ...
+
+
+class SubagentProviderError(RuntimeError):
+    """Stable typed failure at the provider routing boundary."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class SubagentProviderRouter:
+    """Route child handles to exact providers without interpreting their state."""
+
+    def __init__(self, providers: Mapping[str, SubagentProvider]) -> None:
+        self._providers = dict(providers)
+
+    async def spawn(self, request: SpawnSubagentRequest) -> ChildHandle:
+        provider = self._provider(request.provider_ref)
+        if not await provider.available():
+            raise SubagentProviderError(
+                "subagent_provider_unavailable",
+                f"SubagentProvider {request.provider_ref} is unavailable",
+            )
+        handle = await provider.spawn(request)
+        self._validate_handle(request, handle)
+        return handle
+
+    async def status(self, handle: ChildHandle) -> SubagentStatus:
+        return await self._provider_for_handle(handle).status(handle)
+
+    async def followup(self, handle: ChildHandle, input: Any) -> None:
+        await self._provider_for_handle(handle).followup(handle, input)
+
+    async def interrupt(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).interrupt(handle)
+
+    async def cancel(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).cancel(handle)
+
+    def subscribe(
+        self, handle: ChildHandle, *, after_seq: int = 0
+    ) -> AsyncIterator[SubagentEvent]:
+        if after_seq < 0:
+            raise SubagentProviderError(
+                "subagent_cursor_invalid", "subagent after_seq cannot be negative"
+            )
+        return self._provider_for_handle(handle).subscribe(handle, after_seq=after_seq)
+
+    async def result(self, handle: ChildHandle) -> SubagentResult:
+        return await self._provider_for_handle(handle).result(handle)
+
+    async def dispose(self, handle: ChildHandle) -> None:
+        await self._provider_for_handle(handle).dispose(handle)
+
+    def _provider_for_handle(self, handle: ChildHandle) -> SubagentProvider:
+        return self._provider(handle.provider_ref)
+
+    def _provider(self, provider_ref: str) -> SubagentProvider:
+        provider = self._providers.get(provider_ref)
+        if provider is None:
+            raise SubagentProviderError(
+                "subagent_provider_not_found",
+                f"SubagentProvider {provider_ref} is not registered",
+            )
+        return provider
+
+    @staticmethod
+    def _validate_handle(
+        request: SpawnSubagentRequest,
+        handle: ChildHandle,
+    ) -> None:
+        if (
+            handle.provider_ref != request.provider_ref
+            or handle.parent_session_id != request.parent_session_id
+            or handle.parent_run_id != request.parent_run_id
+            or handle.depth != request.depth
+        ):
+            raise SubagentProviderError(
+                "subagent_handle_mismatch",
+                "SubagentProvider returned a child handle outside the requested lineage",
+            )
+
+
+_SECRET_KEY_PARTS = ("secret", "password", "token", "apikey", "api_key")
+_SECRET_REF_PREFIXES = ("secret://", "env://", "credential://", "vault://")
+
+
+def _reject_secret_values(value: Any, *, path: str = "payload") -> None:
+    if isinstance(value, Mapping):
+        for key, child in value.items():
+            key_text = str(key)
+            normalized = key_text.replace("-", "").lower()
+            if any(part in normalized for part in _SECRET_KEY_PARTS) and child is not None:
+                if not isinstance(child, str) or not child.startswith(_SECRET_REF_PREFIXES):
+                    raise ValueError(f"{path}.{key_text} must contain a secret reference")
+            _reject_secret_values(child, path=f"{path}.{key_text}")
+    elif isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        for index, child in enumerate(value):
+            _reject_secret_values(child, path=f"{path}[{index}]")
+
+
+__all__ = [
+    "ChildHandle",
+    "SpawnSubagentRequest",
+    "SubagentEvent",
+    "SubagentPolicy",
+    "SubagentProvider",
+    "SubagentProviderError",
+    "SubagentProviderRouter",
+    "SubagentResult",
+    "SubagentStatus",
+]

ksadk/prompts/__init__.py

@@ -0,0 +1,71 @@
+"""Prompt 分区与编译数据模型（方案第 7 节）。
+
+第一个 PR 只导出稳定类型：``PromptSection`` / ``CompiledPrompt`` / ``PromptProjectionResult``。
+``PromptCompiler`` 的确定性编译、merge、hash、指令文件发现与预算留第二个 PR。
+"""
+
+from ksadk.prompts.compiler import (
+    InconsistentSectionError,
+    PromptCompiler,
+    ProtectedSectionOverrideError,
+    compile_prompt,
+)
+from ksadk.prompts.models import (
+    PROMPT_COMPILER_VERSION,
+    CompiledPrompt,
+    PromptMergePolicy,
+    PromptProjectionResult,
+    PromptSection,
+    PromptSectionKind,
+    PromptStability,
+    PromptTrustLevel,
+)
+from ksadk.prompts.resolved import (
+    RESOLVED_PROMPT_SOURCES_VERSION,
+    EnvPlatformPolicySource,
+    PlatformPolicySource,
+    ResolvedPromptSources,
+    compile_resolved_prompt_dict,
+    get_default_platform_policy_source,
+    sections_from_resolved_sources,
+)
+from ksadk.prompts.sources import (
+    PLATFORM_SAFETY_TEXT,
+    agent_identity_section,
+    agent_policy_section,
+    discover_instruction_files,
+    platform_safety_section,
+    request_instructions_section,
+    resource_manifest_section,
+    sections_from_instructions,
+)
+
+__all__ = [
+    "PLATFORM_SAFETY_TEXT",
+    "PROMPT_COMPILER_VERSION",
+    "RESOLVED_PROMPT_SOURCES_VERSION",
+    "CompiledPrompt",
+    "EnvPlatformPolicySource",
+    "InconsistentSectionError",
+    "PlatformPolicySource",
+    "PromptCompiler",
+    "PromptMergePolicy",
+    "PromptProjectionResult",
+    "PromptSection",
+    "PromptSectionKind",
+    "PromptStability",
+    "PromptTrustLevel",
+    "ProtectedSectionOverrideError",
+    "ResolvedPromptSources",
+    "agent_identity_section",
+    "agent_policy_section",
+    "compile_prompt",
+    "compile_resolved_prompt_dict",
+    "discover_instruction_files",
+    "get_default_platform_policy_source",
+    "platform_safety_section",
+    "request_instructions_section",
+    "resource_manifest_section",
+    "sections_from_instructions",
+    "sections_from_resolved_sources",
+]

ksadk/prompts/compiler.py

@@ -0,0 +1,215 @@
+"""PromptCompiler —— 确定性编译 Prompt 分区（方案第 7 节）。
+
+第一个 PR 只落地稳定数据模型；本（第二个）PR 实现 ``compile()`` 的确定性行为：排序、
+标准化、merge policy、protected 覆盖检测、SHA-256、section token 与 stable_prefix_hash。
+
+PR2 仍是 shadow：``CompiledPrompt`` 仅用于 hash/可观测/未来 projection，**不替换** Runner
+实际发送的 instructions→new_message/SystemMessage/base_instructions 拼装，线上行为不变。
+``CompiledPrompt.content`` 不保证等于 Runner 最终物理输入（方案 7.2）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, replace
+from typing import Iterable
+
+from ksadk.context_engine.tokenizer import get_default_token_counter
+from ksadk.prompts.models import (
+    PROMPT_COMPILER_VERSION,
+    CompiledPrompt,
+    PromptSection,
+    PromptSectionKind,
+)
+
+# canonical 顺序：按 priority 升序，priority 相同按 kind 字典序。同一 section_id 的
+# source/stability/merge_policy 必须固定，不因 Runner 遍历顺序变化（方案 7.3 第 8 条）。
+_KIND_ORDER: tuple[PromptSectionKind, ...] = (
+    "platform_safety",
+    "agent_identity",
+    "agent_policy",
+    "runtime_capabilities",
+    "resource_manifest",
+    "request_instructions",
+)
+
+
+def _section_sort_key(section: PromptSection) -> tuple[int, str, str]:
+    kind_rank = _KIND_ORDER.index(section.kind) if section.kind in _KIND_ORDER else len(_KIND_ORDER)
+    kind_key = _KIND_ORDER[kind_rank] if kind_rank < len(_KIND_ORDER) else section.kind
+    return (section.priority, kind_key, section.section_id)
+
+
+def _normalize_text(text: str) -> str:
+    """标准化换行与尾部空白，但不改变正文语义（方案 7.3 第 2 条）。
+
+    - CRLF/CR → LF
+    - 去除每行尾部空白
+    - 合并 3+ 连续空行为 1 行，去除首尾空白
+    """
+    if not text:
+        return ""
+    normalized = str(text).replace("\r\n", "\n").replace("\r", "\n")
+    lines = [line.rstrip() for line in normalized.split("\n")]
+    # 合并 2+ 连续空行 → 单空行（统一段落间距，不改变正文语义）
+    collapsed: list[str] = []
+    blank_run = 0
+    for line in lines:
+        if line == "":
+            blank_run += 1
+            if blank_run >= 2:
+                continue
+            collapsed.append(line)
+        else:
+            blank_run = 0
+            collapsed.append(line)
+    return "\n".join(collapsed).strip()
+
+
+def _content_sha256(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _wrap_section(section: PromptSection, content: str) -> str:
+    """用标签消除区段歧义，但不应把所有动态上下文拼成 XML（方案 7.3 推荐格式）。"""
+    body = content.strip()
+    if not body:
+        return ""
+    return f"<{section.kind}>\n{body}\n</{section.kind}>"
+
+
+def _merge_sections(sections: list[PromptSection]) -> list[PromptSection]:
+    """同 kind 多来源时执行显式 merge policy，禁止"最后写入悄悄覆盖"（方案 7.3 第 3 条）。
+
+    - ``replace``: 保留最后一条（同 section_id 之内）
+    - ``append``: 按顺序拼接
+    - ``merge_unique``: 去重拼接
+    - ``protected``: 不允许覆盖；发生覆盖尝试时抛 ``ProtectedSectionOverrideError``
+    """
+    grouped: dict[str, list[PromptSection]] = {}
+    order: list[str] = []
+    for section in sections:
+        if section.section_id not in grouped:
+            grouped[section.section_id] = []
+            order.append(section.section_id)
+        grouped[section.section_id].append(section)
+
+    merged: list[PromptSection] = []
+    for section_id in order:
+        bucket = grouped[section_id]
+        head = bucket[0]
+        if len(bucket) == 1:
+            merged.append(head)
+            continue
+        policy = head.merge_policy
+        # 同一 section_id 的来源/稳定性/merge_policy 必须固定（方案 7.3 第 8 条）。
+        inconsistent = any(
+            b.merge_policy != policy or b.stability != head.stability or b.kind != head.kind
+            for b in bucket[1:]
+        )
+        if inconsistent:
+            raise InconsistentSectionError(
+                f"section {section_id!r} 的来源/稳定性/merge_policy 不一致"
+            )
+        if policy == "replace":
+            merged.append(replace(head, content=bucket[-1].content))
+        elif policy == "protected":
+            # 任意两条同 section_id 内容不同即视为覆盖尝试。
+            contents = {b.content for b in bucket}
+            if len(contents) > 1:
+                raise ProtectedSectionOverrideError(
+                    f"protected section {section_id!r} 发生覆盖尝试"
+                )
+            merged.append(head)
+        elif policy == "merge_unique":
+            seen: set[str] = set()
+            parts: list[str] = []
+            for b in bucket:
+                for chunk in re.split(r"\n{2,}", b.content.strip()):
+                    chunk = chunk.strip()
+                    if chunk and chunk not in seen:
+                        seen.add(chunk)
+                        parts.append(chunk)
+            merged.append(replace(head, content="\n\n".join(parts)))
+        else:  # append
+            merged.append(
+                replace(
+                    head,
+                    content="\n\n".join(b.content.strip() for b in bucket if b.content.strip()),
+                )
+            )
+    return merged
+
+
+class ProtectedSectionOverrideError(RuntimeError):
+    """``protected`` section 被尝试覆盖。编译失败并产生审计事件，不静默忽略（方案 7.3 第 9 条）。"""
+
+
+class InconsistentSectionError(RuntimeError):
+    """同一 section_id 的来源/稳定性/merge_policy 不固定。"""
+
+
+@dataclass(frozen=True)
+class PromptCompiler:
+    """确定性 Prompt 编译器。
+
+    ``compile()`` 必须对相同输入产生相同输出（方案 7.3）。构造器无状态，可复用。
+    """
+
+    compiler_version: str = PROMPT_COMPILER_VERSION
+
+    def compile(self, sections: Iterable[PromptSection]) -> CompiledPrompt:
+        # 1. 排序（确定性）
+        ordered = sorted(sections, key=_section_sort_key)
+        # 2. merge（同 section_id 的多来源按 merge policy 合并）
+        merged = _merge_sections(ordered)
+        # 3. platform_safety 不允许被 request_instructions 覆盖（方案 7.3 第 4 条）。
+        #    protected/replace 在 _merge_sections 内已处理；这里额外校验跨 section_id 的
+        #    信任边界：request_instructions 不得声明 platform 的 kind。
+        for section in merged:
+            if (
+                section.kind == "platform_safety"
+                and section.trust_level in ("untrusted", "user")
+            ):
+                raise ProtectedSectionOverrideError(
+                    "platform_safety 不得由 untrusted/user 来源声明"
+                )
+
+        counter = get_default_token_counter()
+        # 4. 空 section 不输出占位文本（方案 7.3 第 5 条）。
+        section_hashes: dict[str, str] = {}
+        tokens_by_section: dict[str, int] = {}
+        wrapped_blocks: list[str] = []
+        for section in merged:
+            body = _normalize_text(section.content)
+            section_hashes[section.section_id] = _content_sha256(body)
+            tokens_by_section[section.section_id] = counter.count_text(body)
+            if body:
+                wrapped_blocks.append(_wrap_section(section, body))
+        canonical_content = "\n\n".join(block for block in wrapped_blocks if block).strip()
+
+        # 5. stable_prefix_hash：仅覆盖 stability="stable" 的 section（platform_safety /
+        #    agent_identity / agent_policy）。部署级/动态 section 不进稳定前缀（方案 7.4）。
+        stable_body = "\n\n".join(
+            _wrap_section(s, _normalize_text(s.content))
+            for s in merged
+            if s.stability == "stable" and _normalize_text(s.content)
+        ).strip()
+        stable_prefix_hash = _content_sha256(stable_body) if stable_body else ""
+
+        return CompiledPrompt(
+            sections=tuple(merged),
+            content=canonical_content,
+            content_hash=_content_sha256(canonical_content),
+            estimated_tokens=counter.count_text(canonical_content),
+            stable_prefix_hash=stable_prefix_hash,
+            section_hashes=section_hashes,
+            tokens_by_section=tokens_by_section,
+            compiler_version=self.compiler_version,
+        )
+
+
+def compile_prompt(sections: Iterable[PromptSection]) -> CompiledPrompt:
+    """便捷入口：用默认 compiler 编译。"""
+    return PromptCompiler().compile(sections)