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

ksadk/plugins/teams/cloud_permits.py

@@ -0,0 +1,250 @@
+"""Short-lived, audience-separated permits for Teams trusted host traffic.
+
+Signatures establish the transport caller only. Callers must additionally
+compare immutable claims with the original persisted operation and enforce the
+current grant/attempt. This module never accepts public-key material from a
+permit and never generates a production signing key.
+"""
+
+from __future__ import annotations
+
+import base64
+from datetime import datetime, timezone
+from typing import Any, Literal, Mapping, Protocol
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from pydantic import Field, model_validator
+
+from .cloud_contracts import (
+    CommandId,
+    Digest,
+    ExecutionTarget,
+    Identifier,
+    Revision,
+    Timestamp,
+    WireModel,
+    canonical_bytes,
+)
+
+EXECUTE_OPERATIONS = frozenset(
+    {
+        "ensure_session",
+        "prepare",
+        "enqueue",
+        "renew_grant",
+        "set_grant",
+        "set_admission",
+        "invoke",
+        "respond_interaction",
+    }
+)
+RECOVERY_OPERATIONS = frozenset(
+    {
+        "lookup",
+        "get_result",
+        "observe",
+        "get_grant",
+        "revoke",
+        "cancel",
+    }
+)
+CALLBACK_EXECUTE_OPERATIONS = frozenset(
+    {
+        "policy",
+        "invoke",
+        "effects",
+        "read_material",
+        "create_artifact",
+        "upload_artifact",
+        "finalize_artifact",
+    }
+)
+
+
+def timestamp(value: datetime) -> str:
+    if value.tzinfo is None:
+        raise ValueError("timezone-aware clock required")
+    return value.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+class PermitError(ValueError):
+    """Redacted transport authorization error safe to map to an HTTP failure."""
+
+
+class PermitBase(WireModel):
+    schemaVersion: Literal[1] = 1
+    issuer: Identifier
+    kid: Identifier
+    authorityId: Identifier
+    issuedAt: Timestamp
+    expiresAt: Timestamp
+    nonce: Identifier
+    signature: str = Field(default="", max_length=128)
+
+    @model_validator(mode="after")
+    def validate_lifetime(self) -> PermitBase:
+        ttl = (_time(self.expiresAt) - _time(self.issuedAt)).total_seconds()
+        if not 0 < ttl <= 60:
+            raise ValueError("Teams permit lifetime must be at most 60 seconds")
+        return self
+
+    def signing_bytes(self) -> bytes:
+        return canonical_bytes(self.model_dump(mode="json", exclude={"signature"}))
+
+
+class BindingProbePermit(PermitBase):
+    audience: Literal["agentengine-teams-probe"] = "agentengine-teams-probe"
+    probeId: CommandId
+    bindingRef: Identifier
+    target: ExecutionTarget
+    expectedDigests: dict[Literal["bundle", "contract", "capabilities"], Digest] = Field(
+        min_length=3, max_length=3
+    )
+    allowedOperations: list[Literal["describe"]] = Field(min_length=1, max_length=1)
+
+
+class TeamsExecutionPermit(PermitBase):
+    audience: Literal["agentengine-teams-runtime"] = "agentengine-teams-runtime"
+    permitKind: Literal["execute", "recovery"]
+    subjectRef: Identifier
+    agentInstanceId: Identifier
+    sessionId: Identifier
+    commandId: CommandId
+    allowedOperations: list[str] = Field(min_length=1, max_length=16)
+    payloadDigest: Digest
+    policyDigest: Digest
+    leaderEpoch: Revision
+    dispatchEpoch: Revision
+    attemptEpoch: Revision
+    grantRevision: Revision
+
+    @model_validator(mode="after")
+    def validate_operations(self) -> TeamsExecutionPermit:
+        allowed = EXECUTE_OPERATIONS if self.permitKind == "execute" else RECOVERY_OPERATIONS
+        if not set(self.allowedOperations) <= allowed:
+            raise ValueError("operation is not allowed by this permit kind")
+        if len(self.allowedOperations) != len(set(self.allowedOperations)):
+            raise ValueError("duplicate permit operation")
+        return self
+
+
+class TeamsCallbackPermit(PermitBase):
+    audience: Literal["agentengine-teams-callback"] = "agentengine-teams-callback"
+    permitKind: Literal["execute", "recovery"]
+    groupId: Identifier
+    teamRunId: Identifier
+    memberId: Identifier
+    commandId: CommandId
+    sessionId: Identifier
+    agentInstanceId: Identifier
+    bundleDigest: Digest
+    policyDigest: Digest
+    attemptEpoch: Revision
+    leaderEpoch: Revision
+    grantRevision: Revision
+    allowedOperations: list[str] = Field(min_length=1, max_length=8)
+
+    @model_validator(mode="after")
+    def validate_operations(self) -> TeamsCallbackPermit:
+        if (_time(self.expiresAt) - _time(self.issuedAt)).total_seconds() > 30:
+            raise ValueError("callback permit lifetime must be at most 30 seconds")
+        allowed = (
+            CALLBACK_EXECUTE_OPERATIONS
+            if self.permitKind == "execute"
+            else {"append_effect_evidence"}
+        )
+        if not set(self.allowedOperations) <= allowed:
+            raise ValueError("operation is not allowed by callback permit kind")
+        if len(self.allowedOperations) != len(set(self.allowedOperations)):
+            raise ValueError("duplicate permit operation")
+        return self
+
+
+class Signer(Protocol):
+    key_id: str
+
+    def sign(self, message: bytes) -> str: ...
+
+
+def sign_permit(permit: PermitBase, signer: Signer) -> PermitBase:
+    if permit.kid != signer.key_id:
+        raise PermitError("signing key does not match permit")
+    return permit.model_copy(update={"signature": signer.sign(permit.signing_bytes())})
+
+
+class TeamsPermitVerifier:
+    """Trusted keys are supplied by the authenticated JWKS/configuration path."""
+
+    def __init__(self, keys: Mapping[str, Ed25519PublicKey], *, issuer: str):
+        self._keys = dict(keys)
+        self.issuer = issuer
+
+    def verify(
+        self,
+        value: Any,
+        model: type[BindingProbePermit] | type[TeamsExecutionPermit] | type[TeamsCallbackPermit],
+        *,
+        operation: str,
+        expected: Mapping[str, Any],
+        now: datetime,
+        grant_expires_at: datetime | None = None,
+    ) -> PermitBase:
+        try:
+            permit = model.model_validate(value)
+        except ValueError as exc:
+            raise PermitError("invalid Teams permit") from exc
+        key = self._keys.get(permit.kid)
+        if key is None or permit.issuer != self.issuer:
+            raise PermitError("untrusted Teams permit issuer or key")
+        try:
+            signature = base64.b64decode(
+                permit.signature + "=" * (-len(permit.signature) % 4), altchars=b"-_", validate=True
+            )
+            key.verify(signature, permit.signing_bytes())
+        except (ValueError, InvalidSignature) as exc:
+            raise PermitError("invalid Teams permit signature") from exc
+        if now.tzinfo is None:
+            raise ValueError("timezone-aware verification clock required")
+        if not _time(permit.issuedAt) <= now < _time(permit.expiresAt):
+            raise PermitError("Teams permit is not currently valid")
+        if operation not in permit.allowedOperations:
+            raise PermitError("Teams operation not permitted")
+        claims = permit.model_dump(mode="json")
+        required = {"authorityId"}
+        if isinstance(permit, BindingProbePermit):
+            required |= {"probeId", "bindingRef", "target", "expectedDigests"}
+        else:
+            required |= {
+                "agentInstanceId",
+                "sessionId",
+                "commandId",
+                "policyDigest",
+                "attemptEpoch",
+                "grantRevision",
+            }
+            if isinstance(permit, TeamsExecutionPermit):
+                required |= {"subjectRef", "payloadDigest"}
+            else:
+                required |= {"groupId", "teamRunId", "memberId", "bundleDigest"}
+        if not required <= expected.keys() or any(
+            key not in claims or claims[key] != value for key, value in expected.items()
+        ):
+            raise PermitError("Teams permit scope does not match persisted operation")
+        if getattr(permit, "permitKind", None) == "execute":
+            if grant_expires_at is None or grant_expires_at.tzinfo is None:
+                raise PermitError("active execution grant is required")
+            if now >= grant_expires_at or _time(permit.expiresAt) > grant_expires_at:
+                raise PermitError("Teams permit exceeds execution grant lifetime")
+        return permit
+
+
+PERMIT_MODELS = {
+    "binding-probe-permit": BindingProbePermit,
+    "execution-permit": TeamsExecutionPermit,
+    "callback-permit": TeamsCallbackPermit,
+}

ksadk/plugins/teams/context.py

@@ -0,0 +1,96 @@
+"""Small execution context, separate from the complete owner UI snapshot."""
+
+
+def execution_context(domain, actor, current_task_id=None):
+    with domain.store.transaction() as tx:
+        domain.authorize(tx, actor, actor.group_id)
+        member = domain.run_member(tx, actor.team_run_id, actor.member_id)
+        run = tx.get("team_run", actor.team_run_id)
+        tasks = tx.list("task", actor.group_id, team_run_id=actor.team_run_id)
+        recent = tx.recent("message", actor.group_id, 12, team_run_id=actor.team_run_id)
+        artifacts = tx.recent("artifact", actor.group_id, 12, team_run_id=actor.team_run_id)
+        artifacts += [
+            tx.get("artifact", artifact_id) for artifact_id in run.get("_sharedArtifactIds", [])
+        ]
+        members = run["_roster"]
+        policy = domain.run_policy(tx, run)
+    relevant = sorted(
+        tasks,
+        key=lambda task: (
+            task["taskId"] != current_task_id,
+            task["ownerMemberId"] != actor.member_id,
+            task["status"] in {"succeeded", "failed", "cancelled"},
+        ),
+    )[:32]
+    projected = []
+    for task in relevant:
+        record = {
+            key: task.get(key)
+            for key in (
+                "taskId",
+                "title",
+                "status",
+                "ownerMemberId",
+                "revision",
+                "dependencies",
+            )
+        }
+        record["title"] = str(record["title"])[:120]
+        if task["taskId"] == current_task_id:
+            record["acceptanceCriteria"] = task["acceptanceCriteria"][:600]
+        if task["attempts"]:
+            attempt = task["attempts"][-1]
+            record["attemptId"] = attempt["attemptId"]
+            if attempt.get("result"):
+                record["resultSummary"] = attempt["result"][:500]
+            record["artifactIds"] = [item["artifactId"] for item in attempt["artifacts"]]
+        projected.append(record)
+    messages = []
+    for message in recent:
+        if message.get("visibility") == "internal" or message["senderName"] == "任务分派":
+            continue  # The accepted task delivery already contains the complete brief.
+        if (
+            member["role"] != "leader"
+            and message.get("mentions")
+            and actor.member_id not in message["mentions"]
+        ):
+            continue
+        parts = [
+            {"kind": "text", "text": str(part.get("text", ""))[:500]}
+            if part["kind"] == "text"
+            else part
+            for part in message["parts"]
+        ]
+        messages.append(
+            {
+                "messageId": message["messageId"],
+                "senderName": message["senderName"],
+                "parts": parts[:4],
+                "intent": message["intent"],
+            }
+        )
+    return {
+        "memberId": actor.member_id,
+        "role": member["role"],
+        "responsibility": member.get("responsibility", ""),
+        "teamRunId": run["teamRunId"],
+        "goal": run["goal"][:1200],
+        "currentTaskId": current_task_id,
+        "taskAcceptance": policy["taskAcceptance"],
+        "members": [
+            {
+                **{key: member[key] for key in ("memberId", "name", "role")},
+                "responsibility": member.get("responsibility", ""),
+            }
+            for member in members
+            if member["status"] == "active"
+        ],
+        "tasks": projected,
+        "taskCount": len(tasks),
+        "tasksTruncated": len(tasks) > len(projected),
+        "recentMessages": messages[-4:],
+        "artifacts": [
+            {key: item[key] for key in ("artifactId", "name", "digest")} for item in artifacts
+        ],
+        "budget": run["budget"],
+    }

ksadk/plugins/teams/contracts.py

@@ -0,0 +1,136 @@
+"""Teams v1 inputs and trusted identities, independent of Studio and Providers.
+
+Actor is constructed by the host/verified tool invocation, never decoded from
+browser JSON. Public names mirror the shared Web Teams contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+API_VERSION = "teams.ksadk.io/v1"
+PLUGIN_VERSION = "0.1.0"
+TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
+
+
+@dataclass(frozen=True)
+class Actor:
+    tenant_id: str
+    subject: str
+    kind: Literal["human", "member", "host"] = "human"
+    group_id: str | None = None
+    member_id: str | None = None
+    team_run_id: str | None = None
+    run_id: str | None = None
+    attempt_id: str | None = None
+
+
+class InputModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class MemberInput(InputModel):
+    memberId: str = Field(min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+    name: str = Field(min_length=1, max_length=80)
+    bindingRef: str = Field(min_length=1, max_length=256)
+    responsibility: str = Field(default="", max_length=2000)
+
+
+class GroupCreateInput(InputModel):
+    name: str = Field(min_length=1, max_length=120)
+    members: list[MemberInput] = Field(min_length=1, max_length=8)
+    leaderMemberId: str
+    idempotencyKey: str = Field(min_length=1, max_length=200)
+    taskAcceptance: Literal["leader", "human", "result"] = "leader"
+    leaderStandbyBindingRef: str | None = Field(default=None, min_length=1, max_length=256)
+
+    @model_validator(mode="after")
+    def validate_roster(self) -> GroupCreateInput:
+        ids = [member.memberId for member in self.members]
+        if len(ids) != len(set(ids)):
+            raise ValueError("团队成员标识不能重复")
+        if self.leaderMemberId not in ids:
+            raise ValueError("Leader 必须属于已选成员")
+        return self
+
+
+class MessagePart(InputModel):
+    kind: Literal["text", "attachment"]
+    text: str | None = Field(default=None, max_length=100_000)
+    attachmentRef: str | None = Field(default=None, max_length=256)
+    mediaType: str | None = Field(default=None, max_length=200)
+    name: str | None = Field(default=None, max_length=256)
+
+    @model_validator(mode="after")
+    def validate_part(self) -> MessagePart:
+        if self.kind == "text" and not self.text:
+            raise ValueError("消息正文不能为空")
+        if self.kind == "attachment" and (not self.attachmentRef or not self.mediaType):
+            raise ValueError("附件需要已授权的引用和类型")
+        return self
+
+
+class WorkspaceInput(InputModel):
+    sourcePath: str = Field(min_length=1, max_length=4096)
+    baseRef: str | None = Field(default=None, min_length=1, max_length=256)
+    inputs: list[str] = Field(default_factory=list, max_length=32)
+    mode: Literal["auto", "directory"] = "auto"
+
+
+class MessageInput(InputModel):
+    parts: list[MessagePart] = Field(min_length=1, max_length=32)
+    mentions: list[str] = Field(default_factory=list, max_length=8)
+    intent: Literal["start_goal", "followup", "directed", "note"]
+    idempotencyKey: str = Field(min_length=1, max_length=200)
+    replyTo: str | None = Field(default=None, max_length=128)
+    teamRunId: str | None = Field(default=None, min_length=1, max_length=128)
+    workspace: WorkspaceInput | None = None
+
+    @model_validator(mode="after")
+    def validate_targets(self) -> MessageInput:
+        self.mentions = list(dict.fromkeys(self.mentions))
+        if self.intent == "directed" and not self.mentions:
+            raise ValueError("定向消息需要选择成员")
+        if self.intent == "start_goal" and self.teamRunId:
+            raise ValueError("新目标不能引用已有轮次")
+        if self.workspace is not None and self.intent != "start_goal":
+            raise ValueError("工作区只能在创建新目标时指定")
+        return self
+
+
+class Budget(InputModel):
+    maxMembers: int = Field(default=8, ge=1, le=8)
+    maxConcurrent: int = Field(default=4, ge=1, le=8)
+    maxStarts: int = Field(default=32, ge=1, le=256)
+    startsUsed: int = Field(default=0, ge=0)
+    maxHops: int = Field(default=8, ge=1, le=32)
+    maxTokens: int = Field(default=100_000, ge=1, le=10_000_000)
+    tokensUsed: int = Field(default=0, ge=0)
+    maxDurationSeconds: int = Field(default=3600, ge=30, le=86400)
+
+
+class TaskCreateInput(InputModel):
+    title: str = Field(min_length=1, max_length=200)
+    description: str = Field(default="", max_length=20000)
+    ownerMemberId: str | None = None
+    dependencies: list[str] = Field(default_factory=list, max_length=64)
+    acceptanceCriteria: str = Field(default="提交可核验结果", max_length=5000)
+    acceptancePolicy: Literal["leader", "human", "result"] | None = None
+
+
+class ControlInput(InputModel):
+    action: Literal["suspend_dispatch", "resume_dispatch", "stop"]
+    expectedRevision: int = Field(ge=1)
+    idempotencyKey: str = Field(min_length=1, max_length=200)
+
+
+def plain_text(parts: list[dict[str, Any]]) -> str:
+    return "\n".join(
+        str(part.get("text", ""))
+        if part.get("kind") == "text"
+        else f"附件：{part.get('name') or '交付物'}（artifactId={part.get('attachmentRef')}）"
+        for part in parts
+    )