feat(studio): add Agent publication review with Runtime tags (#1104)

* feat(studio): add Agent publication review with runtime tags

* test(studio): avoid Agent review test module name collisions

* fix(studio): simplify Agent review tags and repair card layout

Author: evanlowe

frontend/README.md

@@ -12,6 +12,44 @@ See [deployment and operation](service/studio_release_notifier/README.md).
 
 ## Features
 
+- **Agent publication review**: Developers deploy privately and apply from an
+  Agent card. The review center's Agent tab lets administrators inspect the
+  submitted Runtime metadata, approve with an optional comment, or return with
+  a required reason. Administrators can also publish directly. The applicant
+  sees the reviewer name/avatar, decision time, comment and return reason
+
+  Agent review is independent of SkillSpaces. Runtime `TagResources` writes
+  `veadk:visibility` and explicit `veadk:review:*` fields for application ID,
+  status, submission time/message, reviewer ID/name, decision time/reason/comment,
+  and withdrawal/unpublication actors and times. Agent details are read live from
+  the Runtime; applicant identity reuses its `veadk:owner` and `veadk:author` tags
+  instead of storing another snapshot. Display profiles resolve through the
+  configured Identity user pool. Cloud error bodies and request IDs are
+  returned intact. The repository uses provider-scoped clients for Volcengine
+  and BytePlus
+
+  Only an approved Runtime tagged enterprise-visible is shared. Other users can
+  use it through the server proxy and access their own conversations; management,
+  logs, credentials and other users' sessions remain restricted. Pending Agents
+  must be withdrawn before editing/deleting; published Agents must be unpublished
+  first. Unpublishing revokes subsequent shared proxy requests, including when
+  connection credentials were cached. An already running stream is not terminated
+
+  This first iteration stores the latest application on each Runtime and
+  replaces it on resubmission. Review covers name, description, model and Runtime
+  configuration metadata, not source files or automatic scoring. A configuration
+  fingerprint rejects approval if the submitted Runtime has changed. Version
+  upgrades, public-version selection and archived application history are deferred.
+  Studio guards do not prevent direct cloud changes; concurrent decisions are
+  serialized within one process, without a cross-replica transaction. The record
+  limits application messages to 20 characters and decision reasons/comments to
+  256 characters. Text unsupported by cloud tags is encoded per field, splitting
+  long values into numbered continuations. Every tag value fits within 256 bytes;
+  continuation tags are written first, then field heads and visibility together
+  within the 20-tag call limit. Writes are read back before reporting success
+  and reject exceeding the 50-tag Runtime quota. Existing packed applications
+  remain readable; new writes use explicit fields
+
 - **Skill publication requests**: Each personal Skill version can be submitted
   from its action row. Studio copies its archive into an independent Skill in
   `studio_review_space`, preserving the original name and writing the signed-in

frontend/server/agent_reviews/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Agent visibility requests, independently stored on Runtime resources."""

frontend/server/agent_reviews/access.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Limit shared Agent access to conversation routes and the caller's sessions."""
+
+import re
+from typing import Any
+from urllib.parse import unquote
+
+from fastapi import HTTPException, Request
+
+
+async def authorize_shared_proxy(
+    request: Request, path: str, method: str, principal: Any
+) -> None:
+    if principal is None:
+        raise HTTPException(401, "Studio identity is required")
+    normalized = unquote(path).strip("/")
+    if (
+        "%" in normalized
+        or "\\" in normalized
+        or any(part in {".", ".."} for part in normalized.split("/"))
+    ):
+        raise HTTPException(403, "Shared Agent route is not allowed")
+    if method in {"GET", "HEAD"} and (
+        normalized == "list-apps" or re.fullmatch(r"web/agent-info/[^/]+", normalized)
+    ):
+        return
+    session = re.fullmatch(
+        r"apps/[^/]+/users/([^/]+)/sessions(?:/[^/]+(?:/.*)?)?", normalized
+    )
+    if session and session[1].casefold() in principal.identifiers:
+        return
+    if normalized in {"run", "run_sse"} and method == "POST":
+        try:
+            payload = await request.json()
+        except ValueError as error:
+            raise HTTPException(400, "Invalid conversation request") from error
+        if isinstance(payload, dict):
+            user_ids = [payload[key] for key in ("user_id", "userId") if key in payload]
+            if user_ids and all(
+                isinstance(value, str) and value.casefold() in principal.identifiers
+                for value in user_ids
+            ):
+                return
+    raise HTTPException(403, "Shared Agent access is limited to your own conversations")

frontend/server/agent_reviews/profiles.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resolve review actors through the deployment's existing Identity directory."""
+
+from typing import Any
+from urllib.parse import urlsplit
+
+from frontend.server.user_management.errors import UserManagementError
+
+
+def resolve_profile(directory: Any, person: dict[str, str]) -> dict[str, str]:
+    uid = person.get("identityUid", "")
+    if not directory:
+        return person
+    import volcenginesdkid as sdk
+
+    try:
+        if not uid:
+            # Deployment tags contain the trusted subject, not necessarily GetUser's UID
+            matches = [
+                user.uid
+                for user in directory.users()
+                if person.get("id") in {user.subject, user.uid}
+            ]
+            if len(matches) != 1:
+                return person
+            uid = matches[0]
+        user = directory._call(
+            "get_user",
+            sdk.GetUserRequest(user_pool_uid=directory.pool_uid, user_uid=uid),
+        )
+    except UserManagementError:
+        # A removed directory user must not erase the persisted audit identity
+        return person
+    if str(getattr(user, "uid", "")) != uid:
+        return person
+    picture = str(getattr(user, "picture", "") or "")
+    try:
+        parsed = urlsplit(picture)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+        ):
+            picture = ""
+    except ValueError:
+        picture = ""
+    name = next(
+        (
+            str(getattr(user, key))
+            for key in ("name", "preferred_username", "nickname", "email")
+            if getattr(user, key, None)
+        ),
+        person["name"],
+    )
+    return {
+        **person,
+        "name": name,
+        "email": str(getattr(user, "email", "") or ""),
+        "avatarUrl": picture,
+    }

frontend/server/agent_reviews/repository.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Provider-scoped Runtime transport for Agent review metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from agentkit.sdk.runtime import types as sdk
+from agentkit.sdk.runtime.client import AgentkitRuntimeClient
+
+from frontend.server.agentkit_clients import create_agentkit_client
+from frontend.server.storage import StudioProvider
+
+from .tags import write_runtime_tags
+
+
+class AgentReviewRepository:
+    def __init__(
+        self,
+        provider: StudioProvider,
+        credentials: Callable[[], tuple[str, str, str | None]],
+    ):
+        self.provider: StudioProvider = provider
+        self.credentials = credentials
+
+    def client(self, region: str) -> Any:
+        access_key, secret_key, token = self.credentials()
+        return create_agentkit_client(
+            AgentkitRuntimeClient,
+            provider=self.provider,
+            access_key=access_key,
+            secret_key=secret_key,
+            session_token=token or "",
+            region=region,
+        )
+
+    def get(self, region: str, runtime_id: str) -> Any:
+        return self.client(region).get_runtime(
+            sdk.GetRuntimeRequest.model_validate({"RuntimeId": runtime_id})
+        )
+
+    def list(self, region: str) -> Iterator[Any]:
+        client = self.client(region)
+        token = ""
+        seen: set[str] = set()
+        while True:
+            response = client.list_runtimes(
+                sdk.ListRuntimesRequest.model_validate(
+                    {"MaxResults": 100, **({"NextToken": token} if token else {})}
+                )
+            )
+            yield from response.agent_kit_runtimes or []
+            token = str(response.next_token or "")
+            if not token:
+                return
+            if token in seen:
+                raise RuntimeError("AgentKit returned a repeated Runtime page token")
+            seen.add(token)
+
+    def write(self, region: str, runtime_id: str, values: dict[str, str]) -> None:
+        write_runtime_tags(self.client(region), runtime_id, values)