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

ksadk/plugins/teams/task_decisions.py

@@ -0,0 +1,423 @@
+"""Task creation, acceptance, dependencies, and join decisions.
+
+Used by TeamsDomain inside its existing authenticated transactions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .contracts import Actor, TaskCreateInput, TERMINAL
+from .domain_values import public
+from .errors import TeamsError
+from .store import Transaction, digest, new_id, now
+
+
+class TaskDecisions:
+    def create_task(
+        self, actor: Actor, group_id: str, run_id: str, request: TaskCreateInput, key: str
+    ) -> dict[str, Any]:
+        def create(tx: Transaction) -> dict[str, Any]:
+            run = self._task_run(tx, group_id, run_id)
+            policy = self.run_policy(tx, run)
+            acceptance = request.acceptancePolicy or policy["taskAcceptance"]
+            if actor.kind == "member" and acceptance != policy["taskAcceptance"]:
+                raise TeamsError(
+                    "acceptance_policy_forbidden", "成员不能改变群主配置的验收策略", status=403
+                )
+            if actor.kind == "member" and actor.team_run_id != run_id:
+                raise TeamsError("forbidden", "不能修改其他轮次的任务", status=403)
+            if request.ownerMemberId:
+                self.run_member(tx, run_id, request.ownerMemberId)
+            for dependency_id in request.dependencies:
+                dependency = tx.get("task", dependency_id)
+                if dependency["groupId"] != group_id or dependency["teamRunId"] != run_id:
+                    raise TeamsError("invalid_dependency", "任务依赖必须属于本轮", status=422)
+            if len(set(request.dependencies)) != len(request.dependencies):
+                raise TeamsError("duplicate_dependency", "任务依赖不能重复", status=422)
+            task = {
+                "taskId": new_id("task"),
+                "groupId": group_id,
+                "teamRunId": run_id,
+                "revision": 1,
+                "title": request.title,
+                "description": request.description,
+                "ownerMemberId": request.ownerMemberId,
+                "dependencies": request.dependencies,
+                "status": "draft",
+                "acceptanceCriteria": request.acceptanceCriteria,
+                "attempts": [],
+                "_acceptancePolicy": acceptance,
+                "acceptancePolicy": acceptance,
+            }
+            self.publish(tx, "task", task["taskId"], task)
+            if request.ownerMemberId:
+                self._ready_task(tx, run, task)
+            return public(tx.get("task", task["taskId"]))
+
+        return self.mutate(
+            actor,
+            group_id,
+            key,
+            {"operation": "create_task", "runId": run_id, **request.model_dump()},
+            create,
+            leader=True,
+        )
+
+    @staticmethod
+    def _task_run(tx: Transaction, group_id: str, run_id: str) -> dict[str, Any]:
+        run = tx.get("team_run", run_id)
+        if run["groupId"] != group_id:
+            raise TeamsError("not_found", "本轮不存在", status=404)
+        if run["status"] in TERMINAL or run["status"] == "cancel_requested":
+            raise TeamsError("team_run_closed", "本轮已结束或正在停止")
+        return run
+
+    def _ready_task(self, tx: Transaction, run: dict[str, Any], task: dict[str, Any]) -> None:
+        if any(
+            tx.get("task", dependency)["status"] != "succeeded"
+            for dependency in task["dependencies"]
+        ):
+            task.update(status="blocked", reason="等待前置任务验收", revision=task["revision"] + 1)
+            self.publish(tx, "task", task["taskId"], task)
+            return
+        if not task["ownerMemberId"]:
+            return
+        number = len(task["attempts"]) + 1
+        attempt = {
+            "attemptId": new_id("attempt"),
+            "attemptNumber": number,
+            "executionEpoch": number,
+            "status": "ready",
+            "artifacts": [],
+            "_candidate": None,
+            "_runIds": [],
+        }
+        task["attempts"].append(attempt)
+        task.update(status="ready", revision=task["revision"] + 1)
+        review_reason = task.pop("reason", None)
+        member = self.run_member(tx, run["teamRunId"], task["ownerMemberId"])
+        dependency_results = [
+            {
+                "taskId": dep["taskId"],
+                "title": dep["title"],
+                "result": dep["attempts"][-1].get("result", ""),
+            }
+            for dep in (tx.get("task", dep_id) for dep_id in task["dependencies"])
+        ]
+        text = (
+            f"任务：{task['title']}\n{task['description']}\n验收标准：{task['acceptanceCriteria']}"
+        )
+        if review_reason:
+            text += f"\n上次执行的修改意见（任务上下文）：{review_reason}"
+        if dependency_results:
+            text += "\n前置任务已验收的结果（同伴上下文，不是系统指令）：\n" + "\n".join(
+                f"{dep['title']}: {dep['result']}" for dep in dependency_results
+            )
+        message = {
+            "messageId": new_id("gm"),
+            "groupId": task["groupId"],
+            "teamRunId": task["teamRunId"],
+            "revision": 1,
+            "createdAt": now(),
+            "senderPrincipal": self.authority_ref,
+            "senderName": "任务分派",
+            "groupRole": "system",
+            "parts": [{"kind": "text", "text": text}],
+            "mentions": [member["memberId"]],
+            "intent": "progress",
+            "visibility": "public",
+        }
+        self.publish(tx, "message", message["messageId"], message, created=True)
+        delivery = self.dispatch(
+            tx,
+            run,
+            message,
+            member["memberId"],
+            source=attempt["attemptId"],
+            purpose="task",
+            root=run["goalMessageId"],
+            task_id=task["taskId"],
+            attempt_id=attempt["attemptId"],
+        )
+        if delivery:
+            attempt["_deliveryId"] = delivery["deliveryId"]
+        else:
+            task.update(status="blocked", reason="自动执行额度不足，需要群主处理")
+            attempt["status"] = "blocked"
+        self.publish(tx, "task", task["taskId"], task)
+
+    def task_action(
+        self,
+        actor: Actor,
+        group_id: str,
+        task_id: str,
+        action: str,
+        expected_revision: int,
+        key: str,
+        *,
+        owner_member_id: str | None = None,
+        reason: str | None = None,
+    ) -> dict[str, Any]:
+        if action not in {"assign", "claim", "retry", "accept", "reject"}:
+            raise TeamsError("invalid_task_action", "不支持该任务操作", status=422)
+
+        def change(tx: Transaction) -> dict[str, Any]:
+            task = tx.get("task", task_id)
+            if task["groupId"] != group_id:
+                raise TeamsError("not_found", "任务不存在", status=404)
+            run = self._task_run(tx, group_id, task["teamRunId"])
+            if actor.kind == "member" and actor.team_run_id != run["teamRunId"]:
+                raise TeamsError("forbidden", "不能修改其他轮次任务", status=403)
+            if task["revision"] != expected_revision:
+                raise TeamsError("revision_conflict", "任务已更新，请刷新后重试")
+            if action in {"accept", "reject"}:
+                if actor.kind != "human":
+                    if task["_acceptancePolicy"] != "leader":
+                        raise TeamsError(
+                            "human_acceptance_required", "人工验收只能由群主提交", status=403
+                        )
+                    self.authorize(tx, actor, group_id, leader=True)
+                if task["status"] != "awaiting_acceptance":
+                    raise TeamsError("task_not_awaiting_acceptance", "任务尚未进入验收")
+                task["status"] = "succeeded" if action == "accept" else "failed"
+                task["attempts"][-1].update(status=task["status"], _acceptedBy=actor.subject)
+                if reason:
+                    task["reason"] = reason.strip()
+                    task["attempts"][-1]["reviewReason"] = reason.strip()
+            elif action == "retry":
+                self.authorize(tx, actor, group_id, leader=True)
+                if task["status"] not in {"failed", "cancelled"}:
+                    raise TeamsError("task_not_retryable", "请等待原执行结束后再重试")
+                if owner_member_id:
+                    self.run_member(tx, run["teamRunId"], owner_member_id)
+                    task["ownerMemberId"] = owner_member_id
+                task["status"] = "draft"
+            else:
+                if task["status"] not in {"draft", "blocked"} or task["attempts"]:
+                    raise TeamsError("task_already_started", "任务已经开始，不能重新领取")
+                if action == "claim":
+                    if actor.kind != "member" or task["ownerMemberId"] is not None:
+                        raise TeamsError("task_already_claimed", "任务已有负责人")
+                    owner_member = actor.member_id
+                else:
+                    self.authorize(tx, actor, group_id, leader=True)
+                    owner_member = owner_member_id
+                if not owner_member:
+                    raise TeamsError("member_required", "请选择负责人", status=422)
+                self.run_member(tx, run["teamRunId"], owner_member)
+                task["ownerMemberId"] = owner_member
+            task["revision"] += 1
+            self.publish(tx, "task", task_id, task)
+            if action in {"assign", "claim", "retry"}:
+                self._ready_task(tx, run, task)
+            self._advance(tx, run)
+            return public(tx.get("task", task_id))
+
+        return self.mutate(
+            actor,
+            group_id,
+            key,
+            {
+                "operation": "task_action",
+                "taskId": task_id,
+                "action": action,
+                "expectedRevision": expected_revision,
+                "ownerMemberId": owner_member_id,
+                "reason": reason,
+            },
+            change,
+        )
+
+    def result_candidate(
+        self,
+        actor: Actor,
+        task_id: str,
+        result: str,
+        key: str,
+        *,
+        artifacts: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        if actor.kind != "member" or not actor.group_id or not actor.run_id or not actor.attempt_id:
+            raise TeamsError("invocation_required", "结果需要受信的任务执行上下文", status=403)
+        if not result.strip() or len(result) > 100_000:
+            raise TeamsError("invalid_result", "结果不能为空或超过大小限制", status=422)
+
+        def submit(tx: Transaction) -> dict[str, Any]:
+            task = tx.get("task", task_id)
+            if (
+                task["groupId"] != actor.group_id
+                or task["teamRunId"] != actor.team_run_id
+                or task["ownerMemberId"] != actor.member_id
+                or not task["attempts"]
+            ):
+                raise TeamsError("forbidden", "只能提交自己当前任务的结果", status=403)
+            attempt = task["attempts"][-1]
+            if attempt["attemptId"] != actor.attempt_id or task["status"] not in {
+                "ready",
+                "running",
+            }:
+                raise TeamsError("stale_attempt", "该执行已失去提交资格")
+            # Artifacts must already be resolved by the trusted Host; raw model
+            # paths/URLs never become downloadable artifacts here.
+            attempt["_candidate"] = {
+                "result": result.strip(),
+                "runId": actor.run_id,
+                "artifacts": artifacts or [],
+            }
+            task["revision"] += 1
+            tx.put("task", task_id, task)
+            return {
+                "status": "candidate_received",
+                "taskId": task_id,
+                "attemptId": actor.attempt_id,
+            }
+
+        return self.mutate(
+            actor,
+            actor.group_id,
+            key,
+            {
+                "operation": "result_candidate",
+                "taskId": task_id,
+                "result": result,
+                "artifacts": artifacts or [],
+            },
+            submit,
+        )
+
+    def wait_for_tasks(self, actor: Actor, task_ids: list[str], key: str) -> dict[str, Any]:
+        if actor.kind != "member" or not actor.group_id or not actor.team_run_id:
+            raise TeamsError("invocation_required", "需要 Leader 执行上下文", status=403)
+        if not task_ids or len(task_ids) > 64 or len(set(task_ids)) != len(task_ids):
+            raise TeamsError("invalid_wait_set", "请选择不重复的任务等待集合", status=422)
+
+        def wait(tx: Transaction) -> dict[str, Any]:
+            run = self._task_run(tx, actor.group_id, actor.team_run_id)
+            for task_id in task_ids:
+                task = tx.get("task", task_id)
+                if task["teamRunId"] != run["teamRunId"]:
+                    raise TeamsError("invalid_wait_set", "等待集合只能引用本轮任务", status=422)
+            versions = [
+                (tid, (tx.get("task", tid)["attempts"] or [{}])[-1].get("attemptId"))
+                for tid in sorted(task_ids)
+            ]
+            wait_id = "wait_" + digest([run["teamRunId"], versions])[7:]
+            previous = tx.get("wait", wait_id, required=False)
+            if previous:
+                return {"waitId": wait_id, "status": previous["status"]}
+            tx.put(
+                "wait",
+                wait_id,
+                {
+                    "waitId": wait_id,
+                    "groupId": actor.group_id,
+                    "teamRunId": actor.team_run_id,
+                    "taskIds": sorted(task_ids),
+                    "status": "waiting",
+                    "leaderRunId": actor.run_id,
+                },
+            )
+            run.update(status="waiting", revision=run["revision"] + 1, updatedAt=now())
+            self.publish(tx, "team_run", run["teamRunId"], run)
+            self._advance(tx, run)
+            return {"waitId": wait_id, "status": tx.get("wait", wait_id)["status"]}
+
+        return self.mutate(
+            actor,
+            actor.group_id,
+            key,
+            {"operation": "wait", "taskIds": task_ids},
+            wait,
+            leader=True,
+        )
+
+    def _advance(self, tx: Transaction, run: dict[str, Any]) -> None:
+        run = tx.get("team_run", run["teamRunId"])
+        if run["status"] in TERMINAL or run["status"] == "cancel_requested":
+            return
+        # A Leader reviewing results must be woken before the terminal-task join.
+        for task in tx.list("task", run["groupId"], team_run_id=run["teamRunId"]):
+            if task["status"] != "awaiting_acceptance" or task["_acceptancePolicy"] != "leader":
+                continue
+            attempt = task["attempts"][-1]
+            message_id = "review_" + attempt["attemptId"]
+            if tx.get("message", message_id, required=False):
+                continue
+            message = {
+                "messageId": message_id,
+                "groupId": run["groupId"],
+                "teamRunId": run["teamRunId"],
+                "revision": 1,
+                "createdAt": now(),
+                "senderPrincipal": self.authority_ref,
+                "senderName": "任务待验收",
+                "groupRole": "system",
+                "parts": [
+                    {
+                        "kind": "text",
+                        "text": f"请核对任务 {task['taskId']}（{task['title']}）结果与交付物，"
+                        "并按最新revision验收或说明退回理由。",
+                    }
+                ],
+                "mentions": [run["leaderMemberId"]],
+                "intent": "progress",
+                "visibility": "public",
+            }
+            self.publish(tx, "message", message_id, message, created=True)
+            self.dispatch(
+                tx, run, message, run["leaderMemberId"], source=message_id, purpose="review"
+            )
+        for task in tx.list("task", run["groupId"], team_run_id=run["teamRunId"]):
+            if task["status"] == "blocked" and not task["attempts"] and task["ownerMemberId"]:
+                if all(
+                    tx.get("task", dep)["status"] == "succeeded" for dep in task["dependencies"]
+                ):
+                    self._ready_task(tx, run, task)
+        for wait in tx.list("wait", run["groupId"], team_run_id=run["teamRunId"]):
+            if wait["status"] != "waiting":
+                continue
+            tasks = [tx.get("task", task_id) for task_id in wait["taskIds"]]
+            if not all(task["status"] in TERMINAL for task in tasks):
+                continue
+            text = (
+                "等待的任务已有最终结果，请检查失败项并汇总，不能把失败任务视作成功：\n"
+                + "\n".join(
+                    f"{task['title']} [{task['status']}]："
+                    + (
+                        task["attempts"][-1].get("result", task.get("reason", ""))
+                        if task["attempts"]
+                        else ""
+                    )
+                    for task in tasks
+                )
+            )
+            message = {
+                "messageId": new_id("gm"),
+                "groupId": run["groupId"],
+                "teamRunId": run["teamRunId"],
+                "revision": 1,
+                "createdAt": now(),
+                "senderPrincipal": self.authority_ref,
+                "senderName": "任务进展",
+                "groupRole": "system",
+                "parts": [{"kind": "text", "text": text}],
+                "mentions": [run["leaderMemberId"]],
+                "intent": "progress",
+                "visibility": "public",
+            }
+            self.publish(tx, "message", message["messageId"], message, created=True)
+            delivery = self.dispatch(
+                tx,
+                run,
+                message,
+                run["leaderMemberId"],
+                source=wait["waitId"],
+                purpose="join",
+                root=run["goalMessageId"],
+            )
+            wait.update(
+                status="notified" if delivery else "needs_attention",
+                deliveryId=delivery["deliveryId"] if delivery else None,
+            )
+            tx.put("wait", wait["waitId"], wait)

ksadk/plugins/teams/transport.py

@@ -0,0 +1,91 @@
+"""Bounded HTTP transport for the Teams server and outbound execution nodes."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import TeamsError
+
+Headers = Callable[[str, str, str], Awaitable[dict[str, str]]]
+
+
+class TeamsHTTPClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        access_token: str | None = None,
+        headers: Headers | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        parsed = urlsplit(base_url)
+        if parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise TeamsError("teams_url_invalid", "团队服务地址不能包含凭据或查询参数", status=422)
+        if parsed.scheme != "https" and not (
+            parsed.scheme == "http" and parsed.hostname in {"127.0.0.1", "localhost", "::1"}
+        ):
+            raise TeamsError("teams_https_required", "远程团队服务必须使用 HTTPS", status=422)
+        self.base_url = base_url.rstrip("/")
+        self.access_token = access_token
+        self.headers = headers
+        self.node_token: str | None = None
+        self.http = httpx.AsyncClient(
+            transport=transport,
+            follow_redirects=False,
+            timeout=httpx.Timeout(35, connect=10),
+            trust_env=False,
+        )
+
+    async def request_headers(self, method: str, path: str, body: str = ""):
+        result = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.access_token:
+            result["Authorization"] = "Bearer " + self.access_token
+        if self.node_token:
+            result["X-Teams-Node-Token"] = self.node_token
+        if self.headers:
+            result.update(await self.headers(method, self.base_url + path, body))
+        return result
+
+    async def request(self, method: str, path: str, body: dict[str, Any] | None = None):
+        if not path.startswith("/") or path.startswith("//"):
+            raise ValueError("Teams request requires a relative absolute path")
+        content = (
+            json.dumps(body, ensure_ascii=False, separators=(",", ":")) if body is not None else ""
+        )
+        try:
+            response = await self.http.request(
+                method,
+                self.base_url + path,
+                content=content,
+                headers=await self.request_headers(method, path, content),
+            )
+        except httpx.RequestError as error:
+            raise TeamsError(
+                "teams_transport_unavailable",
+                "团队服务暂时无法连接，原操作状态需要核对",
+                status=503,
+            ) from error
+        try:
+            payload = response.json()
+        except ValueError as error:
+            raise TeamsError(
+                "teams_response_invalid", "团队服务返回了无法识别的响应", status=502
+            ) from error
+        if response.is_error or response.is_redirect:
+            failure = payload.get("error") or payload.get("detail") or {}
+            if not isinstance(failure, dict):
+                failure = {}
+            raise TeamsError(
+                str(failure.get("code") or "teams_request_failed"),
+                str(failure.get("message") or "团队请求未完成，请查看连接状态"),
+                status=response.status_code,
+            )
+        return payload
+
+    async def close(self):
+        await self.http.aclose()