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

ksadk/plugins/resolver.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import hashlib
 import json
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Iterable
 
 from ksadk.plugins.contracts import (
@@ -43,6 +43,11 @@ class ResolvedComposition:
     # This is an internal immutable projection, not another wire manifest: the
     # public Bundle continues to bind only CompositionProfile and PluginLock.
     manifests: tuple[PluginManifest, ...] = ()
+    # Studio stamps the exact AgentDraft snapshot used to select resources.
+    # Generic resolver callers leave this empty; a composed Studio build must
+    # require it so a composition from another revision cannot be paired with
+    # a newly compiled resolved-agent-spec.
+    source_digest: str = field(default="", compare=False, repr=False)
 
 
 def canonical_composition_profile(profile: CompositionProfile) -> bytes:
@@ -223,6 +228,8 @@ class PluginRegistry:
                     source=manifest.spec.provenance.source,
                     signature_ref=manifest.spec.provenance.signature_ref,
                     license=manifest.spec.provenance.license,
+                    upstream=manifest.spec.provenance.upstream,
+                    components=manifest.spec.provenance.components,
                     provides=[
                         LockedCapability(
                             definition=offer.definition,

ksadk/plugins/subagent_providers/codex.py

@@ -32,6 +32,7 @@ from ksadk.plugins.subagents import (
 DEFAULT_CODEX_CHILD_PROVIDER_REF = "plugin://io.ksadk.codex-child@1.0.0"
 _CAPABILITIES = ("cancel", "interrupt", "streaming")
 _TERMINAL_STATES = frozenset({"succeeded", "failed", "cancelled", "interrupted"})
+_NATIVE_SHUTDOWN_TIMEOUT_SECONDS = 5.0
 
 
 def _now() -> datetime:
@@ -69,12 +70,14 @@ class CodexOneShotSubagentProvider:
         provider_ref: str = DEFAULT_CODEX_CHILD_PROVIDER_REF,
         model: str | None = None,
         base_instructions: str | None = None,
+        sandbox_read_only: bool = True,
         client_factory: Callable[[Path], Any] | None = None,
     ) -> None:
         self._project_dir = Path(project_dir).resolve()
         self._provider_ref = provider_ref
         self._model = model
         self._base_instructions = base_instructions
+        self._sandbox_read_only = sandbox_read_only
         self._client_factory = client_factory
         self._states: dict[str, _ChildState] = {}
 
@@ -83,7 +86,7 @@ class CodexOneShotSubagentProvider:
             "providerRef": self._provider_ref,
             "mode": "one-shot",
             "capabilities": list(_CAPABILITIES),
-            "sandbox": "read-only",
+            "sandbox": "read-only" if self._sandbox_read_only else "workspace-write",
             "resumable": False,
         }
 
@@ -132,7 +135,7 @@ class CodexOneShotSubagentProvider:
                     "providerRef": self._provider_ref,
                     "mode": "one-shot",
                     "capabilities": _CAPABILITIES,
-                    "sandbox": "read-only",
+                    "sandbox": "read-only" if self._sandbox_read_only else "workspace-write",
                 },
                 sort_keys=True,
                 separators=(",", ":"),
@@ -219,7 +222,13 @@ class CodexOneShotSubagentProvider:
         if not state.closed:
             state.closed = True
             try:
-                await state.client.close()
+                await asyncio.wait_for(
+                    state.client.close(), timeout=_NATIVE_SHUTDOWN_TIMEOUT_SECONDS
+                )
+            except (TimeoutError, asyncio.TimeoutError):
+                # The isolated native process may be wedged in a command. Its
+                # lifecycle is no longer allowed to keep the parent run open.
+                pass
             finally:
                 shutil.rmtree(state.home, ignore_errors=True)
         state.state = "disposed"
@@ -239,7 +248,8 @@ class CodexOneShotSubagentProvider:
     def _thread_config(self) -> dict[str, Any]:
         config: dict[str, Any] = {
             "cwd": str(self._project_dir),
-            "sandbox_read_only": True,
+            "sandbox_read_only": self._sandbox_read_only,
+            "sandbox": "read-only" if self._sandbox_read_only else "workspace-write",
             "approval_mode": "deny_all",
             "ephemeral": True,
         }
@@ -265,7 +275,14 @@ class CodexOneShotSubagentProvider:
             await self._finish(state, terminal)
         except asyncio.TimeoutError:
             try:
-                await state.client.interrupt_active_turn(state.native_thread_id)
+                await asyncio.wait_for(
+                    state.client.interrupt_active_turn(state.native_thread_id),
+                    timeout=_NATIVE_SHUTDOWN_TIMEOUT_SECONDS,
+                )
+            except Exception:
+                # Timeout is already authoritative. A stuck interrupt RPC must
+                # not suppress the terminal child result or wedge its parent.
+                pass
             finally:
                 await self._finish(
                     state,
@@ -346,7 +363,12 @@ class CodexOneShotSubagentProvider:
             return
         state.requested_terminal = terminal
         try:
-            await state.client.interrupt_active_turn(state.native_thread_id)
+            await asyncio.wait_for(
+                state.client.interrupt_active_turn(state.native_thread_id),
+                timeout=_NATIVE_SHUTDOWN_TIMEOUT_SECONDS,
+            )
+        except (TimeoutError, asyncio.TimeoutError):
+            state.reason = "native interrupt timed out"
         except Exception as error:
             # A dead or already-finished native process must not prevent local
             # cancellation and, critically, must not prevent ``dispose`` from

ksadk/plugins/teams/__init__.py

@@ -0,0 +1,5 @@
+"""Plugin-owned Teams domain; importing this package starts no workers or storage."""
+
+from .errors import TeamsError
+
+__all__ = ["TeamsError"]

ksadk/plugins/teams/api.py

@@ -0,0 +1,405 @@
+"""Plugin-owned Teams HTTP facade, mounted by the generic workspace router."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, Literal
+from urllib.parse import quote
+
+from fastapi import APIRouter, Query, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+from fastapi.routing import APIRoute
+from pydantic import Field
+
+from .application import TeamsApplication
+from .artifacts import read_workspace_artifact
+from .contracts import (
+    ControlInput,
+    GroupCreateInput,
+    InputModel,
+    MemberInput,
+    MessageInput,
+    TaskCreateInput,
+)
+from .errors import TeamsError
+
+
+class TeamsRoute(APIRoute):
+    def get_route_handler(self):
+        handler = super().get_route_handler()
+
+        async def wrapped(request):
+            try:
+                return await handler(request)
+            except TeamsError as error:
+                return JSONResponse({"error": error.public()}, status_code=error.status)
+            except ValueError as error:
+                if hasattr(error, "code") and hasattr(error, "status"):
+                    return JSONResponse(
+                        {"error": {"code": error.code, "message": "团队请求无法处理"}},
+                        status_code=error.status,
+                    )
+                raise
+
+        return wrapped
+
+
+class Mutation(InputModel):
+    idempotencyKey: str = Field(min_length=1, max_length=200)
+
+
+class RevisionMutation(Mutation):
+    expectedRevision: int = Field(ge=1)
+
+
+class GroupPatch(RevisionMutation):
+    name: str | None = None
+    leaderMemberId: str | None = None
+    removeMemberId: str | None = None
+    taskAcceptance: Literal["leader", "human", "result"] | None = None
+    peerWake: bool | None = None
+    archived: bool | None = None
+    addMember: MemberInput | None = None
+    rebindMember: MemberInput | None = None
+
+
+class StartInput(Mutation):
+    goalMessageId: str
+
+
+class AcceptanceInput(RevisionMutation):
+    accepted: bool | None = None
+    action: Literal["accept", "request_changes", "reject"] | None = None
+    reason: str | None = Field(default=None, max_length=2000)
+
+
+class TaskActionInput(RevisionMutation):
+    action: Literal["assign", "claim", "retry", "accept", "reject"]
+    memberId: str | None = None
+    reason: str | None = Field(default=None, max_length=2000)
+
+
+class CreateTaskInput(TaskCreateInput):
+    idempotencyKey: str = Field(min_length=1, max_length=200)
+
+
+class ReadInput(InputModel):
+    watermark: int = Field(ge=0)
+
+
+class MemberRef(InputModel):
+    authorityRef: str
+    groupId: str
+    memberId: str
+    bindingRef: str
+    providerRef: str
+    sessionId: str
+    runId: str
+    itemId: str | None = None
+
+
+class InteractionRef(MemberRef):
+    interactionId: str
+
+
+class MemberCancelInput(Mutation):
+    ref: MemberRef
+
+
+class InteractionInput(RevisionMutation):
+    ref: InteractionRef
+    action: Literal["approve", "reject", "submit", "cancel"]
+    response: dict[str, Any] = Field(default_factory=dict)
+
+
+def _frame(event: str, value: Any, cursor: int | None = None) -> str:
+    prefix = f"id: {cursor}\n" if cursor is not None else ""
+    return prefix + f"event: {event}\ndata: {json.dumps(value, ensure_ascii=False)}\n\n"
+
+
+def create_router(application: TeamsApplication) -> APIRouter:
+    router = APIRouter(prefix="/groups", route_class=TeamsRoute)
+
+    @router.get("")
+    async def groups(cursor: str | None = None, limit: int = Query(default=50, ge=1, le=100)):
+        return application.domain.list_groups(application.actor(), cursor=cursor, limit=limit)
+
+    @router.get("/bindings")
+    async def bindings():
+        return await application.bindings_catalog()
+
+    @router.post("", status_code=201)
+    async def create(payload: GroupCreateInput):
+        return await application.create_group(payload)
+
+    @router.get("/{group_id}")
+    async def snapshot(group_id: str, teamRunId: str | None = None):
+        return application.domain.snapshot(application.actor(), group_id, teamRunId)
+
+    @router.patch("/{group_id}")
+    async def update(group_id: str, payload: GroupPatch):
+        bindings = (
+            await application.validate_bindings(
+                [m.bindingRef for m in (payload.addMember, payload.rebindMember) if m]
+            )
+            if payload.addMember or payload.rebindMember
+            else None
+        )
+        return application.domain.update_group(
+            application.actor(),
+            group_id,
+            payload.expectedRevision,
+            payload.idempotencyKey,
+            name=payload.name,
+            leader_member_id=payload.leaderMemberId,
+            remove_member_id=payload.removeMemberId,
+            task_acceptance=payload.taskAcceptance,
+            peer_wake=payload.peerWake,
+            archived=payload.archived,
+            add_member=payload.addMember,
+            rebind_member=payload.rebindMember,
+            bindings=bindings,
+        )
+
+    @router.post("/{group_id}/messages", status_code=202)
+    async def send(group_id: str, payload: MessageInput):
+        from .workspaces import validate_workspace_plan
+
+        validate_workspace_plan(
+            payload.workspace.model_dump() if payload.workspace else None,
+            require_pinned_git=application.require_pinned_workspace_commit,
+        )
+        for part in payload.parts:
+            if part.kind == "attachment":
+                with application.domain.store.transaction() as tx:
+                    application.domain.authorize(tx, application.actor(), group_id, owner=True)
+                    artifact = tx.get("artifact", part.attachmentRef)
+                    if artifact["groupId"] != group_id:
+                        raise TeamsError("attachment_forbidden", "附件不属于该团队", status=403)
+        return application.domain.send(application.actor(), group_id, payload)
+
+    @router.post("/{group_id}/team-runs", status_code=202)
+    async def start(group_id: str, payload: StartInput):
+        run = application.domain.start_goal(
+            application.actor(), group_id, payload.goalMessageId, payload.idempotencyKey
+        )
+        return {"status": "accepted", "groupId": group_id, "teamRunId": run["teamRunId"]}
+
+    @router.post("/{group_id}/team-runs/{run_id}/control", status_code=202)
+    async def control(group_id: str, run_id: str, payload: ControlInput):
+        application.domain.control(
+            application.actor(),
+            group_id,
+            run_id,
+            payload.action,
+            payload.expectedRevision,
+            payload.idempotencyKey,
+        )
+        return {"status": "accepted", "groupId": group_id, "teamRunId": run_id}
+
+    @router.post("/{group_id}/team-runs/{run_id}/acceptance")
+    async def accept(group_id: str, run_id: str, payload: AcceptanceInput):
+        application.domain.accept_run(
+            application.actor(),
+            group_id,
+            run_id,
+            payload.expectedRevision,
+            payload.idempotencyKey,
+            accepted=payload.accepted,
+            action=payload.action,
+            reason=payload.reason,
+        )
+        return {"status": "accepted", "groupId": group_id, "teamRunId": run_id}
+
+    @router.post("/{group_id}/team-runs/{run_id}/tasks", status_code=201)
+    async def create_task(group_id: str, run_id: str, payload: CreateTaskInput):
+        return application.domain.create_task(
+            application.actor(),
+            group_id,
+            run_id,
+            TaskCreateInput.model_validate(payload.model_dump(exclude={"idempotencyKey"})),
+            payload.idempotencyKey,
+        )
+
+    @router.post("/{group_id}/tasks/{task_id}/actions")
+    async def task_action(group_id: str, task_id: str, payload: TaskActionInput):
+        application.domain.task_action(
+            application.actor(),
+            group_id,
+            task_id,
+            payload.action,
+            payload.expectedRevision,
+            payload.idempotencyKey,
+            owner_member_id=payload.memberId,
+            reason=payload.reason,
+        )
+        return {"status": "accepted", "groupId": group_id}
+
+    @router.post("/{group_id}/read")
+    async def read(group_id: str, payload: ReadInput):
+        return application.domain.mark_read(application.actor(), group_id, payload.watermark)
+
+    @router.get("/{group_id}/execution")
+    async def execution(
+        group_id: str, team_run_id: str | None = Query(default=None, alias="teamRunId")
+    ):
+        snapshot = application.domain.snapshot(application.actor(), group_id)
+        if team_run_id is None:
+            if not snapshot["teamRuns"]:
+                return {
+                    "groupId": group_id,
+                    "teamRunId": "",
+                    "watermark": snapshot["watermark"],
+                    "nodes": [],
+                    "edges": [],
+                }
+            active = [
+                run
+                for run in snapshot["teamRuns"]
+                if run["status"] not in {"succeeded", "failed", "cancelled"}
+            ]
+            if len(active) > 1:
+                raise TeamsError(
+                    "team_run_ambiguous", "团队有多个进行中的任务，请选择要查看的执行", status=422
+                )
+            team_run_id = (active[-1] if active else snapshot["teamRuns"][-1])["teamRunId"]
+        return application.domain.execution(application.actor(), group_id, team_run_id)
+
+    @router.get("/{group_id}/events")
+    async def events(group_id: str, request: Request, after: int = Query(default=0, ge=0)):
+        application.domain.snapshot(application.actor(), group_id)
+
+        async def stream():
+            cursor, heartbeat = after, time.monotonic()
+            while not await request.is_disconnected():
+                try:
+                    domain = application.domain
+                    with domain.store.transaction() as tx:
+                        domain.authorize(tx, application.actor(), group_id)
+                    batch = domain.store.events(group_id, after=cursor)
+                except TeamsError as error:
+                    if error.code == "reset_required":
+                        yield _frame("reset_required", {"groupId": group_id})
+                    break
+                for event in batch:
+                    cursor = event["groupSeq"]
+                    yield _frame("group.event", event, cursor)
+                if time.monotonic() - heartbeat >= 15:
+                    yield _frame("heartbeat", {"watermark": cursor})
+                    heartbeat = time.monotonic()
+                await asyncio.sleep(0.2)
+
+        return StreamingResponse(
+            stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+        )
+
+    @router.get("/{group_id}/members/{member_id}/conversation")
+    async def conversation(
+        group_id: str,
+        member_id: str,
+        session_id: str = Query(alias="sessionId"),
+        run_id: str = Query(alias="runId"),
+    ):
+        return await application.conversation(group_id, member_id, session_id, run_id)
+
+    @router.get("/{group_id}/members/{member_id}/events", include_in_schema=False)
+    @router.get("/{group_id}/members/{member_id}/conversation/events")
+    async def member_events(
+        group_id: str,
+        member_id: str,
+        request: Request,
+        session_id: str = Query(alias="sessionId"),
+        run_id: str = Query(alias="runId"),
+        after: int = Query(default=0, ge=0),
+    ):
+        scope, ref = application.member_scope(group_id, member_id, session_id, run_id)
+
+        async def stream():
+            cursor, heartbeat = after, time.monotonic()
+            while not await request.is_disconnected():
+                batch = await application.host.conversation_events(
+                    scope, run_id=run_id, after=cursor
+                )
+                for entry in batch["items"]:
+                    yield _frame(
+                        "conversation.item",
+                        {"ref": {**ref, "itemId": entry["item"]["itemId"]}, **entry},
+                        entry["cursor"],
+                    )
+                cursor = batch["cursor"]
+                if time.monotonic() - heartbeat >= 15:
+                    yield _frame("heartbeat", {"cursor": cursor})
+                    heartbeat = time.monotonic()
+                await asyncio.sleep(0.15)
+
+        return StreamingResponse(
+            stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+        )
+
+    @router.post("/{group_id}/interactions", status_code=202)
+    async def interaction(group_id: str, payload: InteractionInput):
+        submitted = payload.ref
+        if submitted.groupId != group_id:
+            raise TeamsError("interaction_scope_mismatch", "审批不属于此团队", status=403)
+        scope, ref = application.member_scope(
+            group_id, submitted.memberId, submitted.sessionId, submitted.runId
+        )
+        if any(getattr(submitted, key) != value for key, value in ref.items()):
+            raise TeamsError("interaction_scope_mismatch", "审批完整引用不匹配", status=403)
+        receipt = await application.host.submit_interaction(
+            scope,
+            run_id=submitted.runId,
+            interaction_id=submitted.interactionId,
+            expected_revision=payload.expectedRevision,
+            action=payload.action,
+            response=payload.response,
+            idempotency_key=payload.idempotencyKey,
+            actor_subject=application.actor().subject,
+        )
+        return {**receipt, "groupId": group_id}
+
+    @router.post("/{group_id}/members/{member_id}/cancel", status_code=202)
+    async def cancel_member(group_id: str, member_id: str, payload: MemberCancelInput):
+        submitted = payload.ref
+        if submitted.groupId != group_id or submitted.memberId != member_id:
+            raise TeamsError("member_scope_mismatch", "执行不属于此成员", status=403)
+        _, ref = application.member_scope(group_id, member_id, submitted.sessionId, submitted.runId)
+        if any(getattr(submitted, key) != value for key, value in ref.items()):
+            raise TeamsError("member_scope_mismatch", "执行完整引用不匹配", status=403)
+        return application.cancel_member(
+            group_id,
+            member_id,
+            submitted.sessionId,
+            submitted.runId,
+            payload.idempotencyKey,
+        )
+
+    @router.get("/{group_id}/artifacts/{artifact_id}/download")
+    async def artifact(group_id: str, artifact_id: str):
+        with application.domain.store.transaction() as tx:
+            application.domain.authorize(tx, application.actor(), group_id, owner=True)
+            item = tx.get("artifact", artifact_id)
+            if item["groupId"] != group_id:
+                raise TeamsError("artifact_forbidden", "文件不属于此团队", status=403)
+        artifact_root = (application.runtime.path.parent / "artifacts").resolve()
+        _name, content = read_workspace_artifact(artifact_root, item["_path"])
+        filename = str(item["name"])
+        return Response(
+            content=content,
+            media_type=item["mediaType"],
+            headers={
+                "Content-Disposition": (
+                    'attachment; filename="artifact"; '
+                    f"filename*=UTF-8''{quote(filename, safe='')}"
+                ),
+                "X-Content-Type-Options": "nosniff",
+            },
+        )
+
+    return router