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

ksadk/kernel/contract_fingerprints.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""Package-resident fingerprints for the frozen Agent Kernel wire contract.
+
+The contract manifest lives at repository root for schema review, so it is not
+available from an installed wheel.  Hosted Runtime therefore cannot trust an
+environment value that merely *claims* compatibility: the supported aggregate
+digest is shipped in this Python module.  The contract regression test locks
+this constant to ``contracts/agent-kernel/v1/manifest.json``.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
+AGENT_KERNEL_V1_AGGREGATE_DIGEST = (
+    "b610a25aae957306b9f84a2cc2c948b30d1ce6218585cfd2a91f96736b92d102"
+)
+
+
+def runtime_capability_matrix_wire_value(matrix: Any) -> dict[str, Any]:
+    """Serialize the additive matrix without materializing absent v2 modes.
+
+    Pydantic includes optional ``None`` defaults in ``model_dump``.  Omitting
+    those additive top-level keys preserves the exact pre-extension wire value
+    and capability digest for runtimes that do not publish execution controls
+    or an interaction delivery mode.
+    """
+
+    dump = matrix.model_dump(mode="json")
+    for key in ("interaction_mode", "goal", "loop", "plan"):
+        if dump.get(key) is None:
+            dump.pop(key, None)
+    return dump
+
+
+def runtime_capability_matrix_digest(matrix: Any) -> str:
+    """Return the stable SHA-256 of the RuntimeCapabilityMatrix wire value.
+
+    ``model_dump(mode=\"json\")`` is deliberate: it binds the digest to the
+    public typed matrix rather than a framework object's in-memory layout.
+    JSON key sort and compact separators make the value independent of Python
+    dict insertion order and whitespace.
+    """
+
+    dump = runtime_capability_matrix_wire_value(matrix)
+    canonical = json.dumps(
+        dump,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+__all__ = [
+    "AGENT_KERNEL_V1_AGGREGATE_DIGEST",
+    "AGENT_KERNEL_V1_CONTRACT_SET",
+    "runtime_capability_matrix_digest",
+    "runtime_capability_matrix_wire_value",
+]

ksadk/kernel/contracts.py

@@ -0,0 +1,370 @@
+"""Agent Kernel v1 冻结合同（Pydantic 判别模型）。
+
+对应 docs/superpowers/plans/2026-08-17-agent-runtime-v2-phase1-agent-kernel.md 第 2 节。
+所有 envelope 使用 extra="allow" 保存未知 optional 字段，保证 forward-compatible round-trip；
+payload 按 command_type 判别为独立模型。
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Union
+from uuid import UUID
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, model_validator
+
+
+def _validate_json_value(value: Any) -> Any:
+    """运行时校验 JsonValue（py3.10 兼容取舍）。
+
+    Pydantic 2 对旧式递归 Union alias 在类型求值阶段直接 RecursionError
+    （实测 3.10/3.11 + pydantic 2.13 均如此），PEP 695 ``type`` 语句又是
+    3.12+ 语法。因此 ``JsonValue = Annotated[Any, AfterValidator(...)]``：
+    静态上不再递归，运行时保证值是合法 JSON（str key / 基本类型递归）。
+    """
+
+    def walk(node: Any) -> None:
+        if node is None or isinstance(node, (str, bool, int, float)):
+            return
+        if isinstance(node, dict):
+            for key, item in node.items():
+                if not isinstance(key, str):
+                    raise ValueError(
+                        f"JsonValue dict keys must be str, got {type(key).__name__}"
+                    )
+                walk(item)
+            return
+        if isinstance(node, list):
+            for item in node:
+                walk(item)
+            return
+        raise ValueError(f"value is not JSON-serializable: {type(node).__name__}")
+
+    walk(value)
+    return value
+
+
+JsonValue = Annotated[Any, AfterValidator(_validate_json_value)]
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+
+# ------------------------------------------------------------------ payloads
+
+
+class EnqueuePayload(WireModel):
+    content: JsonValue
+    reply_to: str | None = None
+
+
+class SteerPayload(WireModel):
+    content: JsonValue
+    run_id: str | None = None
+
+
+class InjectPayload(WireModel):
+    context: JsonValue
+    run_id: str | None = None
+
+
+class InterruptPayload(WireModel):
+    run_id: str | None = None
+    reason: str | None = None
+
+
+class PausePayload(WireModel):
+    run_id: str | None = None
+    reason: str | None = None
+
+
+class ResumeTarget(WireModel):
+    kind: Literal["checkpoint", "continuation", "run"]
+    id: str
+
+
+class ResumePayload(WireModel):
+    target: ResumeTarget
+    input: JsonValue = None
+
+
+class SubmitInteractionPayload(WireModel):
+    run_id: str
+    interaction_id: str
+    # token_ref 是一次性 interaction 授权引用，不是可持久化的原始 token。
+    token_ref: str
+    response: JsonValue
+    # 以下为 additive 字段（Task 6）：允许 wire 侧携带完整 submitInteractionRequest；
+    # 缺省时 Worker 以权威 InteractionRecord 补齐（expected_revision=当前 revision，
+    # action=submit，idempotency_key=command.idempotency_key）。
+    action: str | None = None
+    expected_revision: int | None = None
+    idempotency_key: str | None = None
+
+
+PAYLOAD_MODELS: dict[str, type[WireModel]] = {
+    "enqueue": EnqueuePayload,
+    "steer": SteerPayload,
+    "inject": InjectPayload,
+    "interrupt": InterruptPayload,
+    "pause": PausePayload,
+    "resume": ResumePayload,
+    "submit_interaction": SubmitInteractionPayload,
+}
+
+
+# ----------------------------------------------------------------- commands
+
+
+class ControlSource(WireModel):
+    kind: Literal[
+        "studio", "responses", "agui", "a2a", "parent_agent",
+        "scheduler", "workflow", "channel", "system",
+    ]
+    ref: str
+
+
+class AgentControlCommand(WireModel):
+    schema_version: Literal[1] = 1
+    command_id: UUID
+    idempotency_key: str
+    tenant_id: str
+    agent_instance_id: str
+    session_id: str
+    command_type: Literal[
+        "enqueue", "steer", "inject", "interrupt",
+        "pause", "resume", "submit_interaction",
+    ]
+    payload: dict[str, JsonValue]
+    source: ControlSource
+    authorization_ref: str
+    submitted_at: str
+    causation_id: str | None = None
+    correlation_id: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_payload_shape(self) -> "AgentControlCommand":
+        PAYLOAD_MODELS[self.command_type].model_validate(dict(self.payload))
+        return self
+
+
+class AgentControlPermit(WireModel):
+    schema_version: Literal[1] = 1
+    permit_id: str
+    subject_ref: str
+    tenant_id: str
+    agent_instance_id: str
+    session_id: str | None
+    allowed_operations: list[Literal[
+        "enqueue", "steer", "inject", "interrupt", "pause", "resume",
+        "submit_interaction", "get_status", "subscribe_events",
+    ]]
+    issued_at: str
+    expires_at: str
+    nonce: str
+    key_id: str
+    alg: Literal["Ed25519"] = "Ed25519"
+    claims_digest: str
+    signature: str
+
+
+# ----------------------------------------------------------------- receipts
+
+
+class ControlError(WireModel):
+    code: str
+    message: str
+    retryable: bool
+    details: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class AgentControlReceipt(WireModel):
+    schema_version: Literal[1] = 1
+    command_id: UUID
+    status: Literal[
+        "accepted", "duplicate", "rejected", "unsupported",
+        "queue_full", "persistence_uncertain",
+    ]
+    message_id: UUID | None = None
+    run_id: str | None = None
+    accepted_seq: int | None = None
+    error: ControlError | None = None
+
+    @model_validator(mode="after")
+    def _validate_receipt_constraints(self) -> "AgentControlReceipt":
+        if self.status in ("accepted", "duplicate"):
+            if self.message_id is None:
+                raise ValueError(f"{self.status} receipt must carry message_id")
+        else:
+            if self.error is None:
+                raise ValueError(f"{self.status} receipt must carry error")
+        return self
+
+
+class AgentStatusQuery(WireModel):
+    schema_version: Literal[1] = 1
+    tenant_id: str
+    agent_instance_id: str
+    authorization_ref: str
+    session_id: str | None = None
+
+
+class SessionEventSubscription(WireModel):
+    schema_version: Literal[1] = 1
+    tenant_id: str
+    agent_instance_id: str
+    session_id: str
+    authorization_ref: str
+    after_seq: int = 0
+
+
+# ------------------------------------------------------------- session events
+
+
+class SessionEventEnvelope(WireModel):
+    schema_version: Literal[1] = 1
+    event_id: UUID
+    session_id: str
+    seq: int
+    timestamp: str
+    family: Literal[
+        "control", "runtime", "workflow", "schedule", "job", "relationship",
+        "interaction",
+    ]
+    family_version: int
+    event_type: str
+    payload: dict[str, JsonValue]
+    run_id: str | None = None
+    causation_id: str | None = None
+    correlation_id: str | None = None
+    actor_ref: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_family_version(self) -> "SessionEventEnvelope":
+        expected = {"control": 1, "runtime": 2, "interaction": 1}.get(self.family)
+        if expected is not None and self.family_version != expected:
+            raise ValueError(
+                f"family {self.family} requires family_version {expected}, "
+                f"got {self.family_version}"
+            )
+        return self
+
+
+# ------------------------------------------------------------------- guards
+
+
+class AdmissionWriteGuard(WireModel):
+    authorization_ref: str
+    command_id: UUID
+
+
+class ActivationWriteGuard(WireModel):
+    activation_id: str
+    fencing_token: int
+
+
+SessionEventWriteGuard = Union[AdmissionWriteGuard, ActivationWriteGuard]
+WriteContext = ActivationWriteGuard
+
+
+# -------------------------------------------------------------------- lease
+
+
+class ActivationLease(WireModel):
+    schema_version: Literal[1] = 1
+    agent_instance_id: str
+    activation_id: str
+    fencing_token: int
+    lease_expires_at: str
+    bundle_digest: str
+    runtime_type: str
+    capability_digest: str
+
+
+# --------------------------------------------------------------- capability
+
+
+class RuntimeCapability(WireModel):
+    supported: bool
+    mode: Literal["native", "emulated", "unavailable"]
+    reason: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_unavailable(self) -> "RuntimeCapability":
+        if not self.supported:
+            if self.mode != "unavailable":
+                raise ValueError("supported=false must pair with mode=unavailable")
+            if not self.reason:
+                raise ValueError("supported=false must carry a stable reason code")
+        return self
+
+
+class RuntimeCapabilityMatrix(WireModel):
+    schema_version: Literal[1] = 1
+    cancel: RuntimeCapability
+    pause: RuntimeCapability
+    resume: RuntimeCapability
+    submit_interaction: RuntimeCapability
+    attach: RuntimeCapability
+    steer: RuntimeCapability
+    inject: RuntimeCapability
+    checkpoint: RuntimeCapability
+    durable_restore: RuntimeCapability
+    # Interaction delivery is deliberately separate from the verb matrix:
+    # ``submit_interaction`` alone does not tell a caller whether the reply
+    # reaches a live process, resumes a checkpoint, or has no native route.
+    # It remains optional so a v1 consumer can read records emitted before
+    # this additive declaration without inventing support.
+    interaction_mode: Literal[
+        "live_submit", "durable_resume", "unavailable"
+    ] | None = None
+    # Runtime v2 execution controls are additive optional capabilities. Older
+    # runtimes omit them; a runtime must never infer support from UI presence.
+    # ``loop`` specifically means an externally bounded, eval-driven
+    # improvement loop. It is not the runtime's ordinary agent loop and it is
+    # not an alias for collaboration_mode=default.
+    goal: RuntimeCapability | None = None
+    loop: RuntimeCapability | None = None
+    plan: RuntimeCapability | None = None
+
+
+class AgentStatusSnapshot(WireModel):
+    schema_version: Literal[1] = 1
+    agent_instance_id: str
+    instance_state: Literal["ready", "degraded", "unavailable"]
+    session_id: str | None = None
+    active_run_id: str | None = None
+    active_run_state: Literal["pending", "running", "paused", "waiting"] | None = None
+    inbox_depth: int
+    activation_id: str | None = None
+    lease_expires_at: str | None = None
+    capability: RuntimeCapabilityMatrix
+
+
+__all__ = [
+    "JsonValue",
+    "WireModel",
+    "EnqueuePayload",
+    "SteerPayload",
+    "InjectPayload",
+    "InterruptPayload",
+    "PausePayload",
+    "ResumeTarget",
+    "ResumePayload",
+    "SubmitInteractionPayload",
+    "ControlSource",
+    "AgentControlCommand",
+    "AgentControlPermit",
+    "ControlError",
+    "AgentControlReceipt",
+    "AgentStatusQuery",
+    "SessionEventSubscription",
+    "SessionEventEnvelope",
+    "AdmissionWriteGuard",
+    "ActivationWriteGuard",
+    "SessionEventWriteGuard",
+    "WriteContext",
+    "ActivationLease",
+    "RuntimeCapability",
+    "RuntimeCapabilityMatrix",
+    "AgentStatusSnapshot",
+]

ksadk/kernel/control.py

@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+"""深模块 AgentKernel control facade（Phase 1 Task 6 Step 3）。
+
+小接口 ``submit`` / ``status`` / ``subscribe``：
+
+- ``submit``：先 permit 验证（fail closed）、capability 判定、queue limit，
+  再进入单个 Store transaction（accept_command 内部完成 Inbox 行 +
+  ``control.command_accepted`` 事件的 persist-before-ack）。
+- ``status``：只读 Store（active Run / Inbox depth / lease）+ capability
+  matrix，不创建 Run。
+- ``subscribe``：直接委托 SessionEventStore cursor（replay 后 live）。
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from datetime import datetime
+from typing import Any
+
+from ksadk.events.session_event import SessionEventStore
+from ksadk.kernel.authorization import (
+    AgentControlPermitVerifier,
+    PermitExpiredError,
+)
+from ksadk.kernel.contracts import (
+    AgentControlCommand,
+    AgentControlPermit,
+    AgentControlReceipt,
+    AgentStatusQuery,
+    AgentStatusSnapshot,
+    RuntimeCapability,
+    RuntimeCapabilityMatrix,
+    SessionEventEnvelope,
+    SessionEventSubscription,
+)
+from ksadk.kernel.errors import InvalidPermitError
+from ksadk.kernel.mapping import (
+    CapabilityProvider,
+    capability_of,
+)
+from ksadk.kernel.store import AgentKernelStore, command_digest, now_utc
+
+
+def _unavailable(reason: str = "not_implemented") -> RuntimeCapability:
+    return RuntimeCapability(supported=False, mode="unavailable", reason=reason)
+
+
+def default_capability_matrix() -> RuntimeCapabilityMatrix:
+    """未提供 adapter capability 时的诚实默认值（全部 unavailable）。"""
+
+    return RuntimeCapabilityMatrix(
+        cancel=_unavailable(),
+        pause=_unavailable(),
+        resume=_unavailable(),
+        submit_interaction=_unavailable(),
+        attach=_unavailable(),
+        steer=_unavailable("runtime_no_native_steer"),
+        inject=_unavailable("runtime_no_native_inject"),
+        checkpoint=_unavailable(),
+        durable_restore=_unavailable(),
+        interaction_mode="unavailable",
+    )
+
+
+class AgentKernel:
+    def __init__(
+        self,
+        store: AgentKernelStore,
+        session_events: SessionEventStore,
+        permit_verifier: AgentControlPermitVerifier,
+        *,
+        queue_limit: int = 100,
+        capabilities: CapabilityProvider | None = None,
+        clock: Callable[[], datetime] = now_utc,
+    ) -> None:
+        self._store = store
+        self._events = session_events
+        self._permit_verifier = permit_verifier
+        self._queue_limit = int(queue_limit)
+        self._capabilities = capabilities or default_capability_matrix
+        self._clock = clock
+
+    def capabilities(self) -> RuntimeCapabilityMatrix:
+        """Return the runtime's current typed capability snapshot.
+
+        Readiness propagation uses this same source as admission, so an
+        Operator/Server never treats a deploy-time digest as a substitute for
+        the actual operation support matrix.
+        """
+
+        return self._capabilities()
+
+    # ---------------------------------------------------------------- submit
+
+    async def submit(
+        self, command: AgentControlCommand, *, permit: AgentControlPermit
+    ) -> AgentControlReceipt:
+        try:
+            await self._permit_verifier.verify(
+                permit, command, command.command_type, self._clock()
+            )
+        except PermitExpiredError:
+            return await self._expired_permit_receipt(command)
+        except InvalidPermitError as error:
+            return await self._store.reject_command(
+                command,
+                status="rejected",
+                code="invalid_permit",
+                message=error.message,
+            )
+
+        field, capability = capability_of(command.command_type, self._capabilities())
+        if field is not None and not capability.supported:
+            # steer/inject 等绝不降级为 enqueue：直接 unsupported。
+            return await self._store.reject_command(
+                command,
+                status="unsupported",
+                code=capability.reason or "not_implemented",
+                message=f"runtime capability {field} is unavailable",
+            )
+
+        return await self._store.accept_command(
+            command, queue_limit=self._queue_limit
+        )
+
+    async def _expired_permit_receipt(
+        self, command: AgentControlCommand
+    ) -> AgentControlReceipt:
+        """permit 过期：只有 Store 已有完全相同请求（同 digest/幂等域）才 duplicate。"""
+
+        existing = await self._store.load_by_idempotency(
+            command.session_id, command.idempotency_key
+        )
+        if existing is not None and existing.request_digest == command_digest(command):
+            return AgentControlReceipt(
+                command_id=command.command_id,
+                status="duplicate",
+                message_id=existing.message_id,
+                accepted_seq=existing.accepted_seq,
+            )
+        return await self._store.reject_command(
+            command,
+            status="rejected",
+            code="invalid_permit",
+            message="permit_expired",
+        )
+
+    # ---------------------------------------------------------------- status
+
+    async def status(
+        self, query: AgentStatusQuery, *, permit: AgentControlPermit
+    ) -> AgentStatusSnapshot:
+        try:
+            await self._permit_verifier.verify(
+                permit, query, "get_status", self._clock()
+            )
+        except (InvalidPermitError, PermitExpiredError):
+            return AgentStatusSnapshot(
+                agent_instance_id=query.agent_instance_id,
+                instance_state="unavailable",
+                session_id=query.session_id,
+                inbox_depth=0,
+                capability=self._capabilities(),
+            )
+        active = await self._store.find_active_run(
+            query.agent_instance_id, query.session_id
+        )
+        lease = await self._store.current_lease(
+            query.agent_instance_id, query.session_id
+        )
+        return AgentStatusSnapshot(
+            agent_instance_id=query.agent_instance_id,
+            instance_state="ready" if lease is not None else "degraded",
+            session_id=query.session_id or (active.session_id if active else None),
+            active_run_id=active.run_id if active else None,
+            active_run_state=active.state.value if active else None,
+            inbox_depth=await self._store.inbox_depth(
+                query.agent_instance_id, query.session_id
+            ),
+            activation_id=lease.activation_id if lease else None,
+            lease_expires_at=lease.lease_expires_at if lease else None,
+            capability=self._capabilities(),
+        )
+
+    # ------------------------------------------------------------- subscribe
+
+    async def subscribe(
+        self,
+        subscription: SessionEventSubscription,
+        *,
+        permit: AgentControlPermit,
+        should_stop: Callable[[], Awaitable[bool]] | None = None,
+        timeout: float | None = None,
+    ) -> AsyncIterator[SessionEventEnvelope]:
+        await self._permit_verifier.verify(
+            permit, subscription, "subscribe_events", self._clock()
+        )
+        subscribe = self._events.subscribe
+        kwargs: dict[str, Any] = {}
+        try:
+            signature = signature_of(subscribe)
+        except (TypeError, ValueError):
+            signature = None
+        parameters = getattr(signature, "parameters", {}) or {}
+        if should_stop is not None and "should_stop" in parameters:
+            kwargs["should_stop"] = should_stop
+        if timeout is not None and "timeout" in parameters:
+            kwargs["timeout"] = timeout
+        async for envelope in subscribe(
+            subscription.session_id, subscription.after_seq, **kwargs
+        ):
+            yield envelope
+
+
+def signature_of(func: Any) -> Any:
+    import inspect
+
+    return inspect.signature(func)
+
+
+__all__ = ["AgentKernel", "default_capability_matrix"]