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

ksadk/studio/native_gateway_stream.py

@@ -0,0 +1,69 @@
+"""Validate canonical Gateway facts before projecting a Native model turn."""
+
+from collections.abc import Mapping
+
+from ksadk._model_input import ProviderInputObservation
+from ksadk.harness.native.model import ModelUsage
+from ksadk.model_gateway.events import ModelStreamEvent, ModelStreamEventType
+from ksadk.studio.errors import StudioError
+
+
+def _invalid() -> StudioError:
+    # Provider text, model identities and raw malformed fields are not public
+    # diagnostics. Reuse the existing non-retryable host protocol rejection.
+    return StudioError(
+        "MODEL_RESPONSE_INVALID", "Canonical model stream contract mismatch", status_code=422
+    )
+
+
+def validate_gateway_event(event: ModelStreamEvent, *, model: str, sequence: int) -> None:
+    """The consumer must not hide foreign or lost events by renumbering them."""
+    if (
+        not isinstance(event, ModelStreamEvent)
+        or not isinstance(event.type, ModelStreamEventType)
+        or type(event.model) is not str
+        or event.model != model
+        or type(event.sequence) is not int
+        or event.sequence != sequence
+        or not isinstance(event.metadata, Mapping)
+    ):
+        raise _invalid()
+    if event.type in {ModelStreamEventType.TEXT_DELTA, ModelStreamEventType.REASONING_DELTA,
+                       ModelStreamEventType.PUBLIC_SUMMARY_DELTA}:
+        if type(event.text) is not str:
+            raise _invalid()
+    if (event.type is ModelStreamEventType.INPUT_TRANSFORMATIONS) != (
+        event.provider_input is not None
+    ) or (event.provider_input is not None
+          and not isinstance(event.provider_input, ProviderInputObservation)):
+        raise _invalid()
+    if event.provider_content is not None and (
+        event.type is not ModelStreamEventType.TURN_COMPLETED
+        or not isinstance(event.provider_content, tuple)
+        or any(not isinstance(block, Mapping) for block in event.provider_content)
+    ):
+        raise _invalid()
+
+
+def gateway_stream_usage(event: ModelStreamEvent) -> ModelUsage:
+    """A reported update requires both primary counters, without coercion.
+
+    Optional cache/reasoning subdivisions may be absent. No update means
+    unknown usage; an explicit pair of integer zeroes means reported zero.
+    """
+    value = event.usage
+    if (
+        not isinstance(value, Mapping)
+        or "input_tokens" not in value
+        or "output_tokens" not in value
+    ):
+        raise _invalid()
+    try:
+        return ModelUsage(
+            input_tokens=value["input_tokens"],
+            output_tokens=value["output_tokens"],
+            cached_input_tokens=value.get("cached_tokens", 0),
+            reasoning_tokens=value.get("reasoning_tokens", 0),
+        )
+    except (ValueError, TypeError):
+        raise _invalid() from None

ksadk/studio/native_hook_port.py

@@ -0,0 +1,145 @@
+"""Consume locked Harness Hook sources under current Studio Run authority.
+
+PluginHost owns source runtimes. This Port owns only callback Tasks; a selected
+source is not an authorization grant and a Hook output is never a verifier.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+
+from ksadk.harness.native.hook_executor import HookAuthorizer, HookBinding, ScopedHookExecutor
+from ksadk.harness.native.hook_runtime_contract import (
+    HookInvocationRequest,
+    HookInvocationResult,
+    _json_bytes,
+)
+from ksadk.harness.native.state import RunPhase, RunScope
+from ksadk.harness.native.studio_admission import studio_mapping_digest
+from ksadk.harness.stores.native_contract import RunStore
+from ksadk.plugins.contracts import plugin_lock_digest
+from ksadk.plugins.providers.harness import HarnessEngineActivationContext
+from ksadk.plugins.providers.harness_hooks import hook_configuration
+from ksadk.plugins.resolver import composition_profile_digest
+from ksadk.studio.native_hook_registration import validate_hook_authorization_policy
+from ksadk.studio.native_scope import native_scope_from_activation
+
+
+class StudioNativeHookPort:
+    def __init__(
+        self, context: HarnessEngineActivationContext, scope: RunScope, store: RunStore,
+        *, authorize: HookAuthorizer | None = None, authorization_version: str | None = None,
+    ):
+        if native_scope_from_activation(context) != scope or scope.agent_id != context.agent_name:
+            raise ValueError("native_hook_scope_unbound")
+        if not context.activation_generation or context.activation_available is None:
+            raise ValueError("native_hook_activation_unbound")
+        if (composition_profile_digest(context.bundle.composition.profile),
+                plugin_lock_digest(context.bundle.composition.plugin_lock)) != (
+            context.profile_digest, context.plugin_lock_digest,
+        ):
+            raise ValueError("native_hook_graph_unbound")
+        validate_hook_authorization_policy(authorize, authorization_version)
+        self._context, self._scope, self._store = context, scope.model_copy(deep=True), store
+        self._manifest = context.bundle.manifest.model_dump_json()
+        self._profile = context.bundle.composition.profile.model_dump_json()
+        self._lock = context.bundle.composition.plugin_lock.model_dump_json()
+        self._closed = False
+        self._executors = {}
+        self._definitions = []
+        stop_limits = set()
+        maximum_deadline = 0.0
+
+        async def admitted(request):
+            self._ensure_current(request)
+            decision = await authorize(request)  # Only constructed when a host policy exists.
+            self._ensure_current(request)
+            return decision
+
+        for source in context.hook_sources:
+            config = hook_configuration(context.bundle, source)
+            ref = f"plugin://{source.plugin_id}@{source.plugin_version}"
+            definitions = config.definitions(source_ref=ref, binding_digest=studio_mapping_digest({
+                "bundle_digest": context.bundle.bundle_digest,
+                "profile_digest": context.profile_digest,
+                "plugin_lock_digest": context.plugin_lock_digest,
+                "source_ref": ref, "slot": source.slot,
+                "policy": "studio.native-locked-hook-callback/v1",
+                "authorization_version": authorization_version or "deny-unconfigured/v1",
+                "configuration": config.model_dump(mode="json"),
+            }))
+            if config.stop_continuation_limit is not None:
+                stop_limits.add(config.stop_continuation_limit)
+            read = source.runtime.harness_hook  # Freeze the selected implementation, not its name.
+            if not inspect.iscoroutinefunction(read):
+                raise ValueError("native_hook_producer_invalid")
+
+            async def callback(request, read=read):
+                self._ensure_current(request)
+                output = await read(context.bundle, request)
+                self._ensure_current(request)
+                return output
+
+            executor = ScopedHookExecutor(
+                scope=self._scope,
+                bindings=tuple(
+                    HookBinding(item, callback, self._available) for item in definitions
+                ),
+                authorize=admitted if authorize is not None else None,
+                cleanup_timeout_seconds=config.cleanup_timeout_seconds,
+            )
+            for item in definitions:
+                if item.hook_id in self._executors:
+                    raise ValueError("native_hook_id_duplicate")
+                self._executors[item.hook_id] = executor
+                self._definitions.append(item)
+                maximum_deadline = max(
+                    maximum_deadline, item.timeout_seconds + config.cleanup_timeout_seconds,
+                )
+        if len(stop_limits) > 1:
+            raise ValueError("native_hook_stop_policy_conflict")
+        self.stop_continuation_limit = next(iter(stop_limits), None)
+        self.required_effect_timeout_seconds = maximum_deadline
+
+    @property
+    def definitions(self):
+        return tuple(item.model_copy(deep=True) for item in self._definitions)
+
+    def _available(self):
+        return (
+            not self._closed and self._context.activation_available() is True
+            and self._context.bundle.manifest.model_dump_json() == self._manifest
+            and self._context.bundle.composition.profile.model_dump_json() == self._profile
+            and self._context.bundle.composition.plugin_lock.model_dump_json() == self._lock
+        )
+
+    def _ensure_current(self, request):
+        if request.scope != self._scope or request.session_id != self._context.activation_key:
+            raise ValueError("native_hook_request_unbound")
+        snapshot = self._store.load(self._scope, request.run_id)
+        intent = self._store.get_intent(self._scope, request.run_id, request.operation_key)
+        expected_phase = (RunPhase.VERIFYING if request.event == "Stop" else RunPhase.COMPACTING
+                          if request.event == "PreCompact" else RunPhase.EXECUTING_TOOLS)
+        if (
+            snapshot.session_id != request.session_id or snapshot.turn_id != request.turn_id
+            or snapshot.goal != request.goal or snapshot.goal_revision != request.goal_revision
+            or snapshot.tool_calls != request.tool_call_count or snapshot.phase != expected_phase
+            or snapshot.pending_intent != request.operation_key
+            or intent is None or intent.kind != "hook" or intent.status != "running"
+            or _json_bytes(intent.payload.get("request"))
+            != _json_bytes(request.model_dump(mode="json"))
+        ):
+            raise ValueError("native_hook_request_unbound")
+
+    async def invoke(self, request: HookInvocationRequest) -> HookInvocationResult:
+        request = HookInvocationRequest.model_validate_json(request.model_dump_json())
+        self._ensure_current(request)
+        executor = self._executors.get(request.definition.hook_id)
+        if executor is None:
+            raise ValueError("native_hook_definition_unbound")
+        return await executor.invoke(request)
+
+    async def aclose(self):
+        self._closed = True
+        await asyncio.gather(*(item.aclose() for item in set(self._executors.values())))

ksadk/studio/native_hook_registration.py

@@ -0,0 +1,70 @@
+"""Trusted distribution selection of a Python Hook capability for exact Agents.
+
+These inputs come from the Studio host, not an Agent draft or a tool response.
+PluginHost still stages the registered factory and checks declared permissions.
+This does not add a plugin installer, Cordis Hook export or management API.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+
+from ksadk.harness.native.hook_executor import HookAuthorizer
+from ksadk.plugins.composition import PluginCapabilitySelection
+from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.host import PluginFactory
+from ksadk.plugins.providers.harness_hooks import HARNESS_HOOK_DEFINITION, HarnessHookConfiguration
+
+
+def validate_hook_authorization_policy(authorize: HookAuthorizer | None, version: str | None):
+    if (authorize is None) != (version is None) or (authorize is not None and (
+        not (inspect.iscoroutinefunction(authorize)
+             or inspect.iscoroutinefunction(getattr(authorize, "__call__", None)))
+        or type(version) is not str or not version.strip()
+    )):
+        raise ValueError("native_hook_authorization_policy_invalid")
+
+
+@dataclass(frozen=True, init=False)
+class StudioNativeHookRegistration:
+    _manifest_json: str
+    _configuration_json: str
+    factory: PluginFactory
+    agent_ids: frozenset[str]
+
+    def __init__(self, *, manifest: PluginManifest, factory: PluginFactory,
+                 configuration: HarnessHookConfiguration, agent_ids: frozenset[str]):
+        manifest = PluginManifest.model_validate_json(manifest.model_dump_json())
+        configuration = HarnessHookConfiguration.model_validate_json(
+            configuration.model_dump_json(),
+        )
+        offers = manifest.spec.provides
+        if (manifest.spec.runtime != "python" or manifest.spec.isolation != "in-process"
+                or len(offers) != 1 or offers[0].definition != HARNESS_HOOK_DEFINITION
+                or not isinstance(factory, PluginFactory)):
+            raise ValueError("Native Hook requires one registered Python capability factory")
+        if not agent_ids or any(type(item) is not str or not item.strip() or item != item.strip()
+                                or item == "*" for item in agent_ids):
+            raise ValueError("Native Hook registration requires exact Agent IDs")
+        ref = f"plugin://{manifest.metadata.id}@{manifest.metadata.version}"
+        configuration.definitions(source_ref=ref, binding_digest=manifest.spec.provenance.digest)
+        object.__setattr__(self, "_manifest_json", manifest.model_dump_json())
+        object.__setattr__(self, "_configuration_json", configuration.model_dump_json())
+        object.__setattr__(self, "factory", factory)
+        object.__setattr__(self, "agent_ids", frozenset(agent_ids))
+
+    @property
+    def manifest(self):
+        return PluginManifest.model_validate_json(self._manifest_json)
+
+    @property
+    def selection(self):
+        manifest = self.manifest
+        return PluginCapabilitySelection(
+            ref=f"plugin://{manifest.metadata.id}@{manifest.metadata.version}",
+            definition=HARNESS_HOOK_DEFINITION, slot=manifest.spec.provides[0].slot,
+            config=HarnessHookConfiguration.model_validate_json(
+                self._configuration_json,
+            ).model_dump(mode="json"),
+        )

ksadk/studio/native_inventory_disclosure.py

@@ -0,0 +1,223 @@
+"""Reject missing disclosure of a host-known empty capability inventory.
+
+This checks one fact from the locked Build, not arbitrary answer semantics or
+whether a resource exists online. The unchanged Native verification/repair
+protocol handles a missing statement; no extra tools or retries are granted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+from ksadk.harness.native.completion import (
+    AcceptanceItem,
+    HostResolvedAnswer,
+    TaskContract,
+    VerificationItemResult,
+    VerificationRepairTarget,
+    VerificationReport,
+)
+from ksadk.harness.native.ports import VerificationBundle, VerificationPort, VerificationRequest
+from ksadk.harness.native.state import RunScope
+from ksadk.studio.native_final_shape import EVIDENCE_VERIFIER_REF, EVIDENCE_VERIFIER_VERSION
+
+VERIFIER_REF = "studio.locked-empty-inventory-disclosure"
+VERIFIER_VERSION = "1"
+ACCEPTANCE_ID = "locked_inventory_disclosure"
+
+
+def _digest(value: str) -> str:
+    return "sha256:" + hashlib.sha256(value.encode()).hexdigest()
+
+
+def _has_plain_statement(text: str, statement: str) -> bool:
+    fence = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        marker = next((prefix for prefix in ("```", "~~~") if stripped.startswith(prefix)), None)
+        if marker is not None:
+            if fence is None:
+                fence = marker
+            elif fence == marker:
+                fence = None
+            continue
+        if fence is None and not line.startswith(("    ", "\t")) and stripped == statement:
+            return True
+    return False
+
+
+@dataclass(frozen=True)
+class EmptyInventoryDisclosure:
+    """Constructed by the host after resolving the immutable Build bindings."""
+
+    capability_label: str
+
+    def __post_init__(self):
+        if self.capability_label not in {"Skill", "MCP", "工具"}:
+            raise ValueError("unsupported inventory label")
+
+    @property
+    def statement(self) -> str:
+        return f"当前 Agent 没有绑定 {self.capability_label}。"
+
+    @property
+    def description(self) -> str:
+        return json.dumps(
+            {"authority": "locked_agent_build", "required_statement": self.statement},
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+
+    def extend(self, contract: TaskContract) -> TaskContract:
+        item = AcceptanceItem(
+            acceptance_id=ACCEPTANCE_ID,
+            verifier_ref=VERIFIER_REF,
+            verifier_version=VERIFIER_VERSION,
+            verification_method="deterministic",
+            description=self.description,
+        )
+        return contract.model_copy(
+            update={
+                "revision": f"{contract.revision}+inventory-{_digest(self.description)[7:23]}",
+                "items": (*contract.items, item),
+            }
+        )
+
+    def resolve(self, contract: TaskContract, goal: str) -> TaskContract:
+        # Custom action/output acceptance belongs to the normal Agent loop.
+        # Resolve only the plain informational goal plus this one known fact.
+        if (
+            contract.allowed_tool_names != ()
+            or contract.final_submission_schema is not None
+            or {item.acceptance_id for item in contract.items}
+            != {"current_user_goal", ACCEPTANCE_ID}
+        ):
+            return contract
+        goal_item = next(i for i in contract.items if i.acceptance_id == "current_user_goal")
+        identity = (
+            goal_item.verifier_ref, goal_item.verifier_version, goal_item.verification_method
+        )
+        if identity not in {
+            ("studio.independent-evidence-unavailable", "1", "human"),
+            (EVIDENCE_VERIFIER_REF, EVIDENCE_VERIFIER_VERSION, "deterministic"),
+        }:
+            # Resolve only the host's unverified baseline. A deterministic
+            # semantic extension still needs its own execution and evidence.
+            return contract
+        return TaskContract.model_validate(
+            contract.model_dump(mode="json")
+            | {
+                "host_resolved_answer": HostResolvedAnswer(
+                    goal_digest=hashlib.sha256(goal.encode()).hexdigest(),
+                    goal_revision=0,
+                    text=self.statement,
+                    authority="locked_agent_build",
+                    evidence_ref=_digest(self.description),
+                ).model_dump(mode="json"),
+            }
+        )
+
+
+class StudioInventoryDisclosureVerifier:
+    """An additive fact gate; all other goals delegate without modification."""
+
+    def __init__(
+        self,
+        *,
+        scope: RunScope,
+        baseline: VerificationPort,
+        disclosure: EmptyInventoryDisclosure | None,
+    ):
+        self.scope = scope.model_copy(deep=True)
+        self.baseline = baseline
+        self.disclosure = disclosure
+
+    async def verify(self, request: VerificationRequest) -> VerificationBundle:
+        item = next(
+            (item for item in request.contract.items if item.acceptance_id == ACCEPTANCE_ID),
+            None,
+        )
+        if item is None:
+            return await self.baseline.verify(request)
+        if request.scope != self.scope:
+            raise ValueError("native_inventory_scope_mismatch")
+        if (
+            self.disclosure is None
+            or item.verifier_ref != VERIFIER_REF
+            or item.verifier_version != VERIFIER_VERSION
+            or item.verification_method != "deterministic"
+            or item.description != self.disclosure.description
+        ):
+            raise ValueError("native_inventory_contract_mismatch")
+        # The baseline sees its original contract. Its results remain evidence
+        # for the original acceptance items; the composition binds both here.
+        baseline_contract = request.contract.model_copy(
+            update={"items": tuple(i for i in request.contract.items if i != item)}
+        )
+        bundle = await self.baseline.verify(
+            request.model_copy(update={"contract": baseline_contract})
+        )
+        results = (
+            list(bundle.report.items)
+            if bundle.report is not None
+            else [
+                VerificationItemResult(
+                    acceptance_id=i.acceptance_id,
+                    status="not_run",
+                    verifier_id=i.verifier_ref,
+                    verifier_version=i.verifier_version,
+                    verification_method=i.verification_method,
+                    evidence_refs=(),
+                    safe_summary="No independent semantic verifier is available.",
+                )
+                for i in baseline_contract.items
+            ]
+        )
+        # Require the host-supplied fact as a plain answer statement. A quoted
+        # rule, JSON field, inline code, or promise is not this disclosure.
+        is_final = request.purpose == "final"
+        present = is_final and _has_plain_statement(request.final_text, self.disclosure.statement)
+        missing_final = is_final and not present
+        result = VerificationItemResult(
+            acceptance_id=item.acceptance_id,
+            status="passed" if present else "failed" if is_final else "not_run",
+            verifier_id=VERIFIER_REF,
+            verifier_version=VERIFIER_VERSION,
+            verification_method="deterministic",
+            evidence_refs=(_digest(self.disclosure.description + "\0" + request.final_text),),
+            safe_summary=(
+                "The locked Build inventory statement is present. "
+                "Broader semantics remain unverified."
+                if present
+                else "Final inventory disclosure has not been submitted."
+                if not is_final
+                else "Answer using this known fact from the locked Agent Build on a plain line: "
+                + self.disclosure.statement
+                + " Workspace or network inspection cannot change the binding."
+            ),
+            repairable=missing_final,
+            repair_target=VerificationRepairTarget(kind="final_output") if missing_final else None,
+        )
+        results.append(result)
+        candidate = bundle.candidate
+        report = VerificationReport(
+            candidate_id=candidate.candidate_id,
+            contract_revision=request.contract.revision,
+            subject_digest=candidate.subject_digest,
+            subject_context_digest=candidate.subject_context_digest,
+            environment_digest=candidate.environment_digest,
+            items=tuple(results),
+            repairable=(missing_final or bool(bundle.report and bundle.report.repairable)),
+            failure_fingerprint=(
+                _digest(f"{VERIFIER_REF}\0{request.contract.revision}\0missing-disclosure")
+                if missing_final
+                else bundle.report.failure_fingerprint
+                if bundle.report
+                else ""
+            ),
+        )
+        return VerificationBundle(
+            candidate=candidate, report=report, post_workspace=bundle.post_workspace
+        )

ksadk/studio/native_kernel_admission.py

@@ -0,0 +1,84 @@
+"""Admit trusted Build Kernel starts without importing projected model history."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.kernel.state import TERMINAL_RUN_STATES
+from ksadk.runtime import StartRequest
+from ksadk.studio.contracts import RunStatus
+from ksadk.studio.native_user_input import admit_native_user_input
+
+
+async def admit_native_kernel_start(
+    *, spec: Any, request: StartRequest, native: Any, runtime: Any, run_events: Any,
+) -> StartRequest:
+    """Check immutable Build pins and both trusted host history indexes.
+
+    Ordinary Studio Runs and Kernel Runs have separate host indexes. Neither
+    supplies model context to Native: its scoped ledger remains the history
+    owner. A ledger head must be accounted for by a compatible host Run before
+    continuing, and a prior Managed Run must never be silently imported.
+    """
+    if request.agent_id != spec.agent_id or not isinstance(request.input, str):
+        raise ValueError("native_studio_kernel_identity_unavailable")
+    native.admit_studio_build(
+        build_id=spec.build_id,
+        manifest_sha256=spec.manifest_sha256,
+        model=request.model,
+        request_config=request.config,
+        project_dir=spec.launch_context.project_dir,
+        launch_config=spec.launch_context.config,
+        require_pin=True,
+    )
+    normalized_input = admit_native_user_input(request.input, request.input)
+    known_heads: set[str] = set()
+    for previous in run_events.list_runs(session_id=request.session_id):
+        if previous.agent_id != spec.agent_id:
+            continue
+        if previous.status not in {
+            RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED,
+            RunStatus.INTERRUPTED, RunStatus.TIMED_OUT,
+        }:
+            continue
+        handle = previous.runtime_handle
+        if previous.status is not RunStatus.COMPLETED and not handle.get("run_id"):
+            continue
+        if (
+            previous.build_id != spec.build_id
+            or previous.manifest_sha256 != spec.manifest_sha256
+            or (handle.get("native_ref") or {}).get("engine_kind") != "native"
+        ):
+            raise ValueError("native_studio_cross_runtime_history_unavailable")
+        known_heads.add(str(handle.get("run_id") or ""))
+
+    instance_id = runtime.config.agent_instance_id
+    command_id = str(request.metadata.get("command_id") or "")
+    if not command_id:
+        raise ValueError("native_studio_kernel_command_unavailable")
+    messages = await runtime.kernel_store.list_messages(instance_id, request.session_id)
+    for message in messages:
+        command = message.command
+        if command is None or command.command_type != "enqueue":
+            continue
+        if str(command.command_id) == command_id:
+            continue
+        previous = await runtime.kernel_store.find_command_run(
+            instance_id, request.session_id, str(command.command_id),
+        )
+        handle = None if previous is None else previous.metadata.get("handle")
+        if not handle:
+            continue
+        if (
+            previous.state not in TERMINAL_RUN_STATES
+            or (handle.get("native_ref") or {}).get("engine_kind") != "native"
+        ):
+            raise ValueError("native_studio_cross_runtime_history_unavailable")
+        known_heads.add(str(handle.get("run_id") or ""))
+
+    parent = native.session_parent_run_id(request.session_id)
+    if (known_heads and parent not in known_heads) or (not known_heads and parent is not None):
+        raise ValueError("native_studio_session_parent_mismatch")
+    return request.model_copy(update={
+        "metadata": {}, "config": {}, "model": None, "input": normalized_input,
+    })