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

ksadk/harness/sandbox_conformance.py

@@ -0,0 +1,288 @@
+"""Sandbox Backend Conformance。
+
+这套校验针对 Harness 的异步 Sandbox 合同，而不是某个厂商 SDK。它验证
+后端声明与实际行为是否一致，并把无法验证或未声明的能力明确记为 skip，
+不把本地进程包装器包装成远程隔离环境。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+
+from ksadk.harness.sandbox_backend import (
+    ExecuteRequest,
+    FilesystemIsolation,
+    NetworkControl,
+    SandboxBackend,
+    SandboxClosedError,
+    SandboxPolicyViolation,
+    SandboxSpec,
+)
+
+
+@dataclass(frozen=True)
+class SandboxConformanceCase:
+    """后端无关的行为探针。
+
+    命令由调用方提供，是因为只读命令面、POSIX Shell、容器命令面不一定
+    相同。Conformance 验证语义，不强迫所有后端支持同一种 Shell。
+    """
+
+    smoke_command: str
+    expected_output: str = ""
+    timeout_command: str | None = None
+    artifact_command: str | None = None
+    expected_artifact: str | None = None
+
+
+@dataclass(frozen=True)
+class SandboxConformanceFinding:
+    rule: str
+    status: str
+    detail: str = ""
+
+
+@dataclass
+class SandboxConformanceReport:
+    backend_id: str
+    findings: list[SandboxConformanceFinding] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return not any(item.status == "failed" for item in self.findings)
+
+    def pass_rule(self, rule: str, detail: str = "") -> None:
+        self.findings.append(SandboxConformanceFinding(rule, "passed", detail))
+
+    def fail_rule(self, rule: str, detail: str) -> None:
+        self.findings.append(SandboxConformanceFinding(rule, "failed", detail))
+
+    def skip_rule(self, rule: str, detail: str) -> None:
+        self.findings.append(SandboxConformanceFinding(rule, "skipped", detail))
+
+
+async def run_sandbox_backend_conformance(
+    backend: SandboxBackend,
+    *,
+    spec: SandboxSpec,
+    case: SandboxConformanceCase,
+) -> SandboxConformanceReport:
+    """运行一组无网络、可重复的 Sandbox 行为校验。"""
+
+    capabilities = backend.capabilities
+    report = SandboxConformanceReport(backend_id=capabilities.backend_id)
+    _verify_declaration(report, capabilities)
+
+    handle = await backend.create(spec)
+    try:
+        result = await backend.execute(
+            handle,
+            ExecuteRequest(command=case.smoke_command, run_id="sandbox-conformance-smoke"),
+        )
+        if result.ok and case.expected_output in result.output:
+            report.pass_rule("execute.result_contract")
+        else:
+            report.fail_rule(
+                "execute.result_contract",
+                f"ok={result.ok}, exit_code={result.exit_code}, error={result.error!r}",
+            )
+
+        await _verify_timeout(backend, handle, case, report)
+        await _verify_artifacts(backend, handle, case, report)
+    finally:
+        await backend.close(handle)
+
+    if not handle.closed:
+        report.fail_rule("lifecycle.close_marks_handle", "close 后 handle.closed 仍为 false")
+    else:
+        report.pass_rule("lifecycle.close_marks_handle")
+
+    if capabilities.deterministic_cleanup:
+        try:
+            await backend.execute(handle, ExecuteRequest(command=case.smoke_command))
+        except SandboxClosedError:
+            report.pass_rule("lifecycle.closed_handle_rejected")
+        except Exception as exc:  # noqa: BLE001 - 报告非标准失败语义
+            report.fail_rule(
+                "lifecycle.closed_handle_rejected",
+                f"关闭后返回了非标准异常 {type(exc).__name__}: {exc}",
+            )
+        else:
+            report.fail_rule("lifecycle.closed_handle_rejected", "关闭后仍可执行命令")
+    else:
+        report.skip_rule("lifecycle.closed_handle_rejected", "后端未声明确定性清理")
+
+    await _verify_network_admission(backend, spec, report)
+    return report
+
+
+def _verify_declaration(report: SandboxConformanceReport, capabilities) -> None:
+    if not capabilities.backend_id.strip():
+        report.fail_rule("capabilities.backend_id", "backend_id 不能为空")
+    else:
+        report.pass_rule("capabilities.backend_id")
+
+    if (
+        capabilities.filesystem_isolation is FilesystemIsolation.NONE
+        and capabilities.artifact_collection
+    ):
+        report.fail_rule(
+            "capabilities.artifact_boundary",
+            "没有文件系统边界时不能声明受控 Artifact 收集",
+        )
+    else:
+        report.pass_rule("capabilities.artifact_boundary")
+
+    if capabilities.reconnect and not capabilities.deterministic_cleanup:
+        report.fail_rule(
+            "capabilities.reconnect_lifecycle",
+            "支持 reconnect 的后端必须定义确定性清理语义",
+        )
+    else:
+        report.pass_rule("capabilities.reconnect_lifecycle")
+
+    if capabilities.ownership_fencing and not capabilities.reconnect:
+        report.fail_rule(
+            "capabilities.ownership_fencing",
+            "ownership_fencing 依赖 reconnect 能力",
+        )
+    else:
+        report.pass_rule("capabilities.ownership_fencing")
+
+    if capabilities.command_reconnect and not (
+        capabilities.reconnect
+        and capabilities.ownership_fencing
+        and capabilities.cooperative_cancellation
+    ):
+        report.fail_rule(
+            "capabilities.command_reconnect",
+            "command_reconnect 依赖 reconnect、ownership_fencing 和 cooperative_cancellation",
+        )
+    else:
+        report.pass_rule("capabilities.command_reconnect")
+
+
+async def _verify_timeout(backend, handle, case, report) -> None:
+    capabilities = backend.capabilities
+    if not capabilities.request_timeout:
+        report.skip_rule("execute.request_timeout", "后端未声明按请求超时")
+        return
+    if not case.timeout_command:
+        report.fail_rule("execute.request_timeout", "声明支持超时但未提供超时探针")
+        return
+    result = await backend.execute(
+        handle,
+        ExecuteRequest(
+            command=case.timeout_command,
+            timeout_seconds=0.05,
+            run_id="sandbox-conformance-timeout",
+        ),
+    )
+    if not result.ok and result.exit_code != 0 and "超时" in result.error:
+        report.pass_rule("execute.request_timeout")
+    else:
+        report.fail_rule(
+            "execute.request_timeout",
+            f"超时未形成明确失败: ok={result.ok}, code={result.exit_code}, error={result.error!r}",
+        )
+
+
+async def _verify_artifacts(backend, handle, case, report) -> None:
+    capabilities = backend.capabilities
+    if not capabilities.artifact_collection:
+        report.skip_rule("artifact.collection", "后端未声明 Artifact 收集")
+        return
+    if not case.artifact_command or not case.expected_artifact:
+        report.fail_rule("artifact.collection", "声明支持 Artifact 但未提供 Artifact 探针")
+        return
+    result = await backend.execute(
+        handle,
+        ExecuteRequest(
+            command=case.artifact_command,
+            run_id="sandbox-conformance-artifact",
+        ),
+    )
+    artifacts = await backend.collect_artifacts(handle)
+    if result.ok and case.expected_artifact in artifacts:
+        report.pass_rule("artifact.collection")
+    else:
+        report.fail_rule(
+            "artifact.collection",
+            f"command_ok={result.ok}, artifacts={artifacts!r}",
+        )
+
+
+async def _verify_network_admission(backend, spec, report) -> None:
+    capabilities = backend.capabilities
+    if capabilities.network_control not in {
+        NetworkControl.COMMAND_SURFACE,
+        NetworkControl.ADMISSION_ONLY,
+        NetworkControl.ENFORCED,
+    }:
+        report.skip_rule("policy.network_admission", "后端未声明网络控制")
+        return
+    probe_spec = SandboxSpec(
+        workspace_root=spec.workspace_root,
+        read_only=spec.read_only,
+        network_egress=("sandbox-conformance.invalid",),
+        env=dict(spec.env),
+    )
+    try:
+        handle = await backend.create(probe_spec)
+    except SandboxPolicyViolation:
+        report.pass_rule("policy.network_admission")
+        return
+    except Exception as exc:  # noqa: BLE001 - 报告非标准失败语义
+        report.fail_rule(
+            "policy.network_admission",
+            f"网络策略返回非标准异常 {type(exc).__name__}: {exc}",
+        )
+        return
+    await backend.close(handle)
+    report.fail_rule("policy.network_admission", "声明网络控制但接受了未授权出网 spec")
+
+
+async def verify_cooperative_cancellation(
+    backend: SandboxBackend,
+    *,
+    spec: SandboxSpec,
+    command: str,
+) -> SandboxConformanceReport:
+    """单独验证取消窗口，避免主套件依赖长运行命令。"""
+
+    report = SandboxConformanceReport(backend_id=backend.capabilities.backend_id)
+    if not backend.capabilities.cooperative_cancellation:
+        report.skip_rule("execute.cooperative_cancellation", "后端未声明协作取消")
+        return report
+    handle = await backend.create(spec)
+    try:
+        task = asyncio.create_task(
+            backend.execute(
+                handle,
+                ExecuteRequest(command=command, run_id="sandbox-conformance-cancel"),
+            )
+        )
+        await asyncio.sleep(0.05)
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            report.pass_rule("execute.cooperative_cancellation")
+        else:
+            report.fail_rule(
+                "execute.cooperative_cancellation",
+                "取消后任务没有抛出 CancelledError",
+            )
+    finally:
+        await backend.close(handle)
+    return report
+
+
+__all__ = [
+    "SandboxConformanceCase",
+    "SandboxConformanceFinding",
+    "SandboxConformanceReport",
+    "run_sandbox_backend_conformance",
+    "verify_cooperative_cancellation",
+]

ksadk/harness/sandbox_lease.py

@@ -0,0 +1,77 @@
+"""Platform-owned Sandbox lease contract for Harness fencing.
+
+The SDK intentionally defines only the contract.  The authoritative lease
+store belongs to the runtime control plane so ownership is shared across
+hosts; an in-process or local SQLite lock must not be presented as a cloud
+fencing guarantee.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class SandboxLeaseConflict(RuntimeError):
+    """The caller no longer owns the current Sandbox fencing token."""
+
+
+@dataclass(frozen=True)
+class SandboxLeaseScope:
+    """Tenant/workspace namespace for one authoritative lease."""
+
+    tenant_id: str
+    workspace_id: str
+
+    def __post_init__(self) -> None:
+        if not self.tenant_id.strip() or not self.workspace_id.strip():
+            raise ValueError("Sandbox Lease Scope 缺少 tenant/workspace")
+
+
+@dataclass(frozen=True)
+class SandboxLeaseGrant:
+    """One time-bounded ownership grant returned by the control plane."""
+
+    backend_id: str
+    handle_id: str
+    scope: SandboxLeaseScope
+    owner_id: str
+    fencing_token: int
+    expires_at: float
+
+
+class SandboxLeaseProvider(Protocol):
+    """Authoritative, cross-process lease provider.
+
+    ``acquire`` must isolate tenant/workspace and monotonically increase
+    ``fencing_token`` whenever ownership changes within that scope. ``renew``
+    and ``release`` must reject stale owner/token/scope tuples with
+    :class:`SandboxLeaseConflict`.
+    """
+
+    async def acquire(
+        self,
+        *,
+        backend_id: str,
+        handle_id: str,
+        scope: SandboxLeaseScope,
+        owner_id: str,
+        ttl_seconds: float,
+    ) -> SandboxLeaseGrant: ...
+
+    async def renew(
+        self,
+        grant: SandboxLeaseGrant,
+        *,
+        ttl_seconds: float,
+    ) -> SandboxLeaseGrant: ...
+
+    async def release(self, grant: SandboxLeaseGrant) -> None: ...
+
+
+__all__ = [
+    "SandboxLeaseConflict",
+    "SandboxLeaseGrant",
+    "SandboxLeaseProvider",
+    "SandboxLeaseScope",
+]

ksadk/harness/sandbox_lease_conformance.py

@@ -0,0 +1,259 @@
+"""Storage-agnostic conformance suite for authoritative Sandbox leases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from ksadk.harness.sandbox_lease import (
+    SandboxLeaseConflict,
+    SandboxLeaseGrant,
+    SandboxLeaseProvider,
+    SandboxLeaseScope,
+)
+
+
+@dataclass(frozen=True)
+class SandboxLeaseConformanceFinding:
+    rule: str
+    status: str
+    detail: str = ""
+
+
+@dataclass
+class SandboxLeaseConformanceReport:
+    findings: list[SandboxLeaseConformanceFinding] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return not any(item.status == "failed" for item in self.findings)
+
+    def pass_rule(self, rule: str) -> None:
+        self.findings.append(SandboxLeaseConformanceFinding(rule, "passed"))
+
+    def fail_rule(self, rule: str, detail: str) -> None:
+        self.findings.append(SandboxLeaseConformanceFinding(rule, "failed", detail))
+
+
+async def run_sandbox_lease_conformance(
+    provider: SandboxLeaseProvider,
+    *,
+    scope: SandboxLeaseScope,
+    backend_id: str,
+    handle_id: str,
+) -> SandboxLeaseConformanceReport:
+    """Verify fencing and namespace semantics with a unique test handle.
+
+    The caller must provide a dedicated test scope and a never-reused
+    ``handle_id``.  The suite releases every successfully acquired live grant,
+    but authoritative providers may retain their normal audit history.
+    """
+
+    report = SandboxLeaseConformanceReport()
+    first = await _acquire_first(
+        provider,
+        scope=scope,
+        backend_id=backend_id,
+        handle_id=handle_id,
+        report=report,
+    )
+    if first is None:
+        return report
+
+    await _verify_exclusive_acquire(provider, first, report)
+    await _verify_scope_isolation(provider, first, report)
+    renewed = await _verify_renew(provider, first, report)
+    if renewed is None:
+        await _best_effort_release(provider, first)
+        return report
+    await _verify_wrong_owner_rejected(provider, renewed, report)
+    if not await _verify_release(provider, renewed, report):
+        return report
+    replacement = await _verify_monotonic_takeover(provider, renewed, report)
+    if replacement is None:
+        return report
+    await _verify_stale_grant_rejected(provider, renewed, report)
+    await _best_effort_release(provider, replacement)
+    return report
+
+
+async def _acquire_first(
+    provider,
+    *,
+    scope,
+    backend_id,
+    handle_id,
+    report,
+) -> SandboxLeaseGrant | None:
+    try:
+        grant = await provider.acquire(
+            backend_id=backend_id,
+            handle_id=handle_id,
+            scope=scope,
+            owner_id="conformance-owner-a",
+            ttl_seconds=30,
+        )
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.acquire", _exception_detail(exc))
+        return None
+    if (
+        grant.backend_id == backend_id
+        and grant.handle_id == handle_id
+        and grant.scope == scope
+        and grant.owner_id == "conformance-owner-a"
+        and grant.fencing_token > 0
+        and grant.expires_at > 0
+    ):
+        report.pass_rule("lease.acquire")
+        return grant
+    report.fail_rule("lease.acquire", "provider returned a mismatched grant")
+    return grant
+
+
+async def _verify_exclusive_acquire(provider, grant, report) -> None:
+    try:
+        await provider.acquire(
+            backend_id=grant.backend_id,
+            handle_id=grant.handle_id,
+            scope=grant.scope,
+            owner_id="conformance-owner-b",
+            ttl_seconds=30,
+        )
+    except SandboxLeaseConflict:
+        report.pass_rule("lease.exclusive_acquire")
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.exclusive_acquire", _exception_detail(exc))
+    else:
+        report.fail_rule("lease.exclusive_acquire", "overlapping acquire was accepted")
+
+
+async def _verify_scope_isolation(provider, grant, report) -> None:
+    other_scope = SandboxLeaseScope(
+        tenant_id=f"{grant.scope.tenant_id}-other",
+        workspace_id=grant.scope.workspace_id,
+    )
+    other = None
+    try:
+        other = await provider.acquire(
+            backend_id=grant.backend_id,
+            handle_id=grant.handle_id,
+            scope=other_scope,
+            owner_id="conformance-other-scope",
+            ttl_seconds=30,
+        )
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.scope_isolation", _exception_detail(exc))
+        return
+    try:
+        if other.scope == other_scope:
+            report.pass_rule("lease.scope_isolation")
+        else:
+            report.fail_rule("lease.scope_isolation", "provider changed lease scope")
+    finally:
+        await _best_effort_release(provider, other)
+
+
+async def _verify_renew(provider, grant, report) -> SandboxLeaseGrant | None:
+    try:
+        renewed = await provider.renew(grant, ttl_seconds=60)
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.renew", _exception_detail(exc))
+        return None
+    if (
+        renewed.backend_id == grant.backend_id
+        and renewed.handle_id == grant.handle_id
+        and renewed.scope == grant.scope
+        and renewed.owner_id == grant.owner_id
+        and renewed.fencing_token == grant.fencing_token
+        and renewed.expires_at > grant.expires_at
+    ):
+        report.pass_rule("lease.renew")
+        return renewed
+    report.fail_rule("lease.renew", "renew changed identity/token or did not extend expiry")
+    return renewed
+
+
+async def _verify_wrong_owner_rejected(provider, grant, report) -> None:
+    tampered = replace(grant, owner_id="conformance-intruder")
+    try:
+        await provider.renew(tampered, ttl_seconds=60)
+    except SandboxLeaseConflict:
+        report.pass_rule("lease.wrong_owner_rejected")
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.wrong_owner_rejected", _exception_detail(exc))
+    else:
+        report.fail_rule("lease.wrong_owner_rejected", "tampered owner was accepted")
+
+
+async def _verify_release(provider, grant, report) -> bool:
+    try:
+        await provider.release(grant)
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.release", _exception_detail(exc))
+        return False
+    report.pass_rule("lease.release")
+    return True
+
+
+async def _verify_monotonic_takeover(provider, previous, report):
+    try:
+        replacement = await provider.acquire(
+            backend_id=previous.backend_id,
+            handle_id=previous.handle_id,
+            scope=previous.scope,
+            owner_id="conformance-owner-b",
+            ttl_seconds=30,
+        )
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.monotonic_takeover", _exception_detail(exc))
+        return None
+    if replacement.fencing_token > previous.fencing_token:
+        report.pass_rule("lease.monotonic_takeover")
+    else:
+        report.fail_rule(
+            "lease.monotonic_takeover",
+            "replacement fencing token was not monotonic",
+        )
+    return replacement
+
+
+async def _verify_stale_grant_rejected(provider, stale, report) -> None:
+    renew_rejected = release_rejected = False
+    try:
+        await provider.renew(stale, ttl_seconds=30)
+    except SandboxLeaseConflict:
+        renew_rejected = True
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.stale_grant_rejected", _exception_detail(exc))
+        return
+    try:
+        await provider.release(stale)
+    except SandboxLeaseConflict:
+        release_rejected = True
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("lease.stale_grant_rejected", _exception_detail(exc))
+        return
+    if renew_rejected and release_rejected:
+        report.pass_rule("lease.stale_grant_rejected")
+    else:
+        report.fail_rule(
+            "lease.stale_grant_rejected",
+            "stale renew or release was accepted",
+        )
+
+
+async def _best_effort_release(provider, grant) -> None:
+    try:
+        await provider.release(grant)
+    except Exception:  # noqa: BLE001 - cleanup must not mask the finding
+        pass
+
+
+def _exception_detail(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {exc}"
+
+
+__all__ = [
+    "SandboxLeaseConformanceFinding",
+    "SandboxLeaseConformanceReport",
+    "run_sandbox_lease_conformance",
+]