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

ksadk/studio/contracts.py

@@ -43,10 +43,37 @@ class Instructions(ContractModel):
     task: str = Field(default="", max_length=32768)
 
 
+class SoulDocument(ContractModel):
+    """Reviewed identity/boundary source that compiles ahead of task prompts.
+
+    This is deliberately an immutable revision input, not a mutable memory
+    file.  Runtime may read the compiled snapshot but cannot promote a new
+    SoulDocument from a conversation.
+    """
+
+    schema_version: Literal["agentkit.soul/v1"] = "agentkit.soul/v1"
+    identity: str = Field(min_length=1, max_length=4096)
+    principles: list[str] = Field(default_factory=list, max_length=64)
+    boundaries: list[str] = Field(default_factory=list, max_length=64)
+    tone: str | None = Field(default=None, max_length=1024)
+
+    @field_validator("principles", "boundaries")
+    @classmethod
+    def validate_nonempty_items(cls, value: list[str]) -> list[str]:
+        if any(not item.strip() for item in value):
+            raise ValueError("soul principles and boundaries must not contain empty items")
+        return value
+
+
 class ModelParameters(ContractModel):
-    temperature: float = Field(default=0.2, ge=0, le=2)
-    max_tokens: int = Field(default=2048, ge=1, le=131072)
+    # 三者 None=未配置：请求 payload 一律不携带该字段，使用服务端默认，
+    # 规避各模型族对 temperature/max_tokens 的硬约束（如 kimi 只接受默认温度）。
+    temperature: float | None = Field(default=None, ge=0, le=2)
+    max_tokens: int | None = Field(default=None, ge=1, le=131072)
     top_p: float | None = Field(default=None, gt=0, le=1)
+    # 是否允许在 chat 请求中携带 response_format（json_object 结构化输出）。
+    # 关闭后 compose 等结构化调用退回纯文本输出，兼容不支持该字段的网关。
+    allow_json_response_format: bool = Field(default=True)
 
 
 class ModelSpec(ContractModel):
@@ -218,20 +245,92 @@ class ExecutionSpec(ContractModel):
 class CompactionSpec(ContractModel):
     enabled: bool = True
     threshold_ratio: float = Field(default=0.8, gt=0, le=1)
+    # PCM：双阈值（方案 §8.2 / §9.1）。soft=主动整理，hard=强制压缩。
+    soft_threshold_ratio: float = Field(default=0.50, gt=0, le=1)
+    hard_threshold_ratio: float = Field(default=0.85, gt=0, le=1)
+    preserve_working_state: bool = True
+    flush_memory_before_compaction: bool = True
+
+    @model_validator(mode="after")
+    def validate_ratios(self) -> "CompactionSpec":
+        if self.soft_threshold_ratio >= self.hard_threshold_ratio:
+            raise ValueError("softThresholdRatio 必须小于 hardThresholdRatio")
+        return self
+
+
+class ContextContributorsSpec(ContractModel):
+    """ContextContributor 开关与预算（方案 §5.1 / §8.7）。默认按 policy，可显式开关。"""
+
+    workspace_rules: bool | None = None
+    skill_manifest: bool | None = None
+    memory_recall: bool | None = None
+
+
+class RolloutSpec(ContractModel):
+    """AgentVersion 级灰度/回退状态（方案 §8.5）。替代环境变量控制正式灰度。"""
+
+    context_engine: Literal["off", "shadow", "enabled"] = "shadow"
+    memory_write: Literal["off", "shadow", "enabled"] = "shadow"
 
 
 class ContextSpec(ContractModel):
     max_input_tokens: int = Field(default=32000, ge=1024)
     reserve_output_tokens: int = Field(default=4096, ge=1)
     compaction: CompactionSpec = Field(default_factory=CompactionSpec)
+    # prompt_ownership：标记本 Agent 的 system prompt 归属。
+    # framework（默认）= 框架自带 SystemMessage，ksadk 不接管 Runner 输入；
+    # ksadk = 由 ksadk 的 PromptCompiler 编译 CompiledPrompt 并接管 instructions。
+    prompt_ownership: Literal["framework", "ksadk"] = "framework"
+    # PCM：ownership 高阶字段（方案 §5.1）。auto=按 capability 推导，向后兼容现有
+    # prompt_ownership；显式 ksadk/framework/native 时覆盖。Studio 据 capability 限制选项。
+    ownership: Literal["auto", "ksadk", "framework", "native"] = "auto"
+    tokenizer: Literal["auto", "heuristic"] = "auto"
+    policy_version: str = Field(default="context-v2", max_length=64)
+    contributors: ContextContributorsSpec = Field(default_factory=ContextContributorsSpec)
+    rollout: RolloutSpec = Field(default_factory=RolloutSpec)
 
     @model_validator(mode="after")
     def validate_budget(self) -> "ContextSpec":
         if self.reserve_output_tokens >= self.max_input_tokens:
             raise ValueError("reserveOutputTokens 必须小于 maxInputTokens")
+        # ownership 与 prompt_ownership 一致性：显式 ownership 收窄 prompt_ownership（§5.2）。
+        if self.ownership == "ksadk":
+            self.prompt_ownership = "ksadk"
+        elif self.ownership == "framework":
+            self.prompt_ownership = "framework"
+        # native 不收窄 prompt_ownership（native runtime 的 prompt 投影由 Adapter 决定）。
         return self
 
 
+class MemoryRecallSpec(ContractModel):
+    enabled: bool = True
+    max_tokens: int = Field(default=1600, ge=0)
+    top_k: int = Field(default=8, ge=1, le=64)
+    min_score: float = Field(default=0.45, ge=0, le=1)
+
+
+class MemoryWriteSpec(ContractModel):
+    mode: Literal["off", "explicit_only", "candidate"] = "candidate"
+    flush_before_compaction: bool = True
+
+
+MemoryScope = Literal["tenant", "workspace", "agent", "user"]
+
+
+def _default_memory_scopes() -> list[MemoryScope]:
+    return ["workspace", "agent", "user"]
+
+
+class MemorySpec(ContractModel):
+    """AgentVersion 级 Memory 策略（方案 §5.1 / §10）。Build 只存 providerRef，不存凭证。"""
+
+    enabled: bool = False
+    provider_ref: str = Field(default="local-default", max_length=128)
+    recall: MemoryRecallSpec = Field(default_factory=MemoryRecallSpec)
+    write: MemoryWriteSpec = Field(default_factory=MemoryWriteSpec)
+    scopes: list[MemoryScope] = Field(default_factory=_default_memory_scopes)
+
+
 class NetworkPolicy(ContractModel):
     mode: Literal["restricted", "open"] = "restricted"
     allowed_hosts: list[str] = Field(default_factory=list)
@@ -257,12 +356,17 @@ class RuntimeRef(ContractModel):
     project entrypoint that is snapshotted by its Build.
     """
 
-    type: Literal["codex", "adk", "langgraph"]
+    type: Literal["codex", "adk", "langgraph", "harness", "plugin"]
     project_path: str | None = Field(default=None, min_length=1, max_length=1024)
     entry_point: str | None = Field(default=None, min_length=1, max_length=1024)
     agent_variable: str = Field(default="root_agent", min_length=1, max_length=256)
     version: str | None = Field(default=None, min_length=1, max_length=64)
     detection: Literal["declared", "auto"] = "declared"
+    provider_ref: str | None = Field(default=None, min_length=12, max_length=256)
+    provider_config: dict[str, Any] = Field(
+        default_factory=dict,
+        exclude_if=lambda value: not value,
+    )
 
     @field_validator("project_path", "entry_point")
     @classmethod
@@ -280,8 +384,32 @@ class RuntimeRef(ContractModel):
             raise ValueError("Runtime 路径必须是工作区内的相对路径")
         return normalized
 
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if not re.fullmatch(
+            r"plugin://[a-z0-9]+(?:[._-][a-z0-9]+)*@"
+            r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?",
+            value,
+        ):
+            raise ValueError("Provider 引用必须固定为 plugin://<id>@<exact-version>")
+        return value
+
+    @field_validator("provider_config")
+    @classmethod
+    def validate_provider_config(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_clear_runtime_secrets(value)
+        return value
+
     @model_validator(mode="after")
     def validate_framework_source(self) -> "RuntimeRef":
+        if self.type == "plugin":
+            if not self.provider_ref:
+                raise ValueError("plugin Runtime 必须配置 providerRef")
+        elif self.provider_ref is not None or self.provider_config:
+            raise ValueError("只有 plugin Runtime 可以配置 providerRef/providerConfig")
         if self.type in {"adk", "langgraph"}:
             if not self.project_path:
                 raise ValueError(f"{self.type} Runtime 必须配置 projectPath")
@@ -290,15 +418,45 @@ class RuntimeRef(ContractModel):
         return self
 
 
+_RUNTIME_SECRET_KEY = re.compile(
+    r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE
+)
+_RUNTIME_SECRET_REF_PREFIXES = (
+    "secret://",
+    "env://",
+    "credential://",
+    "vault://",
+)
+
+
+def _reject_clear_runtime_secrets(value: Any, *, path: str = "providerConfig") -> None:
+    """Provider config is revision data: it may only retain secret references."""
+
+    if isinstance(value, dict):
+        for key, child in value.items():
+            child_path = f"{path}.{key}"
+            if _RUNTIME_SECRET_KEY.search(str(key)) and child is not None:
+                if not isinstance(child, str) or not child.startswith(
+                    _RUNTIME_SECRET_REF_PREFIXES
+                ):
+                    raise ValueError(f"{child_path} 必须保存 Secret 引用，不能保存明文")
+            _reject_clear_runtime_secrets(child, path=child_path)
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            _reject_clear_runtime_secrets(child, path=f"{path}[{index}]")
+
+
 class AgentSpec(ContractModel):
     description: str = Field(default="", max_length=1024)
     runtime: RuntimeRef | None = None
     instructions: Instructions = Field(default_factory=Instructions)
+    soul: SoulDocument | None = None
     model: ModelSpec | None = None
     capabilities: CapabilitiesSpec = Field(default_factory=CapabilitiesSpec)
     bindings: AgentBindings = Field(default_factory=AgentBindings)
     execution: ExecutionSpec = Field(default_factory=ExecutionSpec)
     context: ContextSpec = Field(default_factory=ContextSpec)
+    memory: MemorySpec = Field(default_factory=MemorySpec)
     security: SecuritySpec = Field(default_factory=SecuritySpec)
     evaluation: EvaluationSpec = Field(default_factory=EvaluationSpec)
 
@@ -383,9 +541,23 @@ class AgentTemplateRecommendation(ContractModel):
     resource_id: str | None = None
 
 
+class AgentBehaviorDesign(ContractModel):
+    """Human-readable explanation of the generated Agent behavior contract."""
+
+    role: str
+    objective: str
+    operating_principles: list[str] = Field(default_factory=list)
+    workflow: list[str] = Field(default_factory=list)
+    explicit_boundaries: list[str] = Field(default_factory=list)
+    safety_boundaries: list[str] = Field(default_factory=list)
+    output_expectations: list[str] = Field(default_factory=list)
+    source_notes: list[str] = Field(default_factory=list)
+
+
 class AgentTemplateComposition(ContractModel):
     template_id: Literal["blank", "research"]
     spec: AgentSpec
+    behavior_design: AgentBehaviorDesign | None = None
     recommendations: list[AgentTemplateRecommendation] = Field(default_factory=list)
     warnings: list[str] = Field(default_factory=list)
 
@@ -411,10 +583,12 @@ class ResolvedAgentSpec(ContractModel):
     source_revision: int
     compiler_version: str = "1"
     instructions: Instructions
+    soul: SoulDocument | None = None
     model: ResolvedModel
     capabilities: ResolvedCapabilities
     execution: ExecutionSpec
     context: ContextSpec
+    memory: MemorySpec
     security: SecuritySpec
     evaluation: EvaluationSpec
     source_digest: str
@@ -446,17 +620,55 @@ class FileEntry(ContractModel):
 
 
 class BundleManifest(ContractModel):
-    bundle_format: Literal["agentkit.bundle/v1"] = "agentkit.bundle/v1"
+    # v1 remains readable for existing local Build records. Every new Studio
+    # build uses v2 because Server admission requires a deterministic plugin
+    # lock even when the lock is empty.
+    bundle_format: Literal["agentkit.bundle/v1", "agentkit.bundle/v2"] = "agentkit.bundle/v1"
     agent_id: str
     source_revision: int
     resolved_digest: str
     runtime_type: str = ""
     source_digest: str = ""
     runtime_contract: Literal["agentkit.runtime/v1"] = "agentkit.runtime/v1"
+    plugin_lock_digest: str = ""
+    # A v0.8.2 bundle already used the v2 envelope without a composition.
+    # Keep that wire shape readable as the explicit legacy execution profile;
+    # newly built bundles write ``composition_mode`` so consumers never need
+    # to infer whether PluginHost admission is required from missing files.
+    composition_mode: Literal["legacy", "composed"] | None = None
+    composition_profile_digest: str | None = None
+    hosted_kernel_requirement_digest: str = ""
     files: list[FileEntry]
     created_at: str = "1970-01-01T00:00:00Z"
     bundle_digest: str = ""
 
+    @model_validator(mode="after")
+    def validate_composition_mode(self) -> "BundleManifest":
+        if self.composition_mode == "composed" and not self.composition_profile_digest:
+            raise ValueError("composed Bundle v2 requires compositionProfileDigest")
+        if self.composition_mode == "legacy" and self.composition_profile_digest:
+            raise ValueError("legacy Bundle v2 cannot declare compositionProfileDigest")
+        return self
+
+    @property
+    def execution_profile(self) -> Literal["legacy", "composed"]:
+        """Normalize historical v2 manifests without rewriting their bytes.
+
+        ``compositionMode`` was added after the v0.8.2 envelope.  Its absence
+        remains a backward-compatible projection: an embedded composition
+        digest is composed; its absence selects the established runtime path.
+        """
+
+        if self.composition_mode is not None:
+            return self.composition_mode
+        return "composed" if self.composition_profile_digest else "legacy"
+
+
+# ``BundleManifest`` is the existing, installed source type.  The explicit
+# name documents that its ``agentkit.bundle/v2`` branch is the Phase 2
+# AgentBundleManifest/v2 contract; it is an alias, not a parallel manifest.
+AgentBundleManifest = BundleManifest
+
 
 class BuildRecord(ContractModel):
     id: str
@@ -495,6 +707,7 @@ class Operation(ContractModel):
     kind: OperationKind
     status: OperationStatus = OperationStatus.QUEUED
     resource_id: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
     error: dict[str, Any] | None = None
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
     completed_at: datetime | None = None
@@ -551,6 +764,11 @@ class RunRecord(ContractModel):
     completed_at: datetime | None = None
     duration_ms: int | None = None
     duration_source: Literal["runtime", "studio"] | None = None
+    # PR-S4：PCM evidence（方案 §6.3）。由 run_service 以 shadow 方式捕获（不进真实输入），
+    # 供 Context Inspector 展示 planned/projected/actual + 精度。默认空（未捕获）。
+    context_plan: dict[str, Any] | None = None
+    prompt_evidence: dict[str, Any] | None = None
+    working_state: dict[str, Any] | None = None
 
 
 class RunEvent(ContractModel):
@@ -642,3 +860,15 @@ class DeploymentRecord(ContractModel):
     version_id: str
     status: Literal["ADMITTING", "DEPLOYING", "READY", "FAILED", "ROLLED_BACK"]
     target: DeploymentTarget
+    # These are receipts from the existing Agent creation control plane, not
+    # Studio-generated deployment identities.
+    agent_id: str | None = None
+    instance_id: str | None = None
+    endpoint: str | None = None
+    # Immutable KS3 object selected by this receipt. It is a deployment fact,
+    # not a browser-supplied credential or a mutable "latest" alias.
+    bundle_uri: str | None = None
+    artifact_id: str | None = None
+    # New direct-cloud receipts are expected to pass AgentKernel/v1 admission.
+    # Older receipts intentionally default to false for read compatibility.
+    requires_kernel: bool = False