create-windy 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "50d32b9470dbf55110aba320338f5e54ed896c77",
-  "generatorVersion": "0.4.0",
+  "templateCommit": "647dac095fa843d7c6eaa3e734d3fbf0d80d81d8",
+  "generatorVersion": "0.5.0",
   "modules": [
     {
       "name": "system",

package/template/apps/agent-server/adk_web_agents/canonical_debug/agent.py

@@ -8,6 +8,7 @@ from google.adk.agents import LlmAgent
 from google.adk.models.base_llm import BaseLlm
 from google.adk.models.llm_request import LlmRequest
 from google.adk.models.llm_response import LlmResponse
+from google.adk.tools.tool_context import ToolContext
 from google.genai import types
 
 from southwind_agent_server.adk_debug import (
@@ -15,13 +16,20 @@ from southwind_agent_server.adk_debug import (
     TextOperationDebugConfig,
     load_text_operation_debug_config,
 )
+from southwind_agent_server.adk_debug_sessions import (
+    IMPORTED_SESSION_STATE_KEY,
+    ImportedDebugSessionReadOnlyError,
+)
 
 TOOL_NAME = "run_canonical_operation"
 PROJECT_OPERATION = load_text_operation_debug_config()
 
 
-async def run_canonical_operation(question: str) -> dict[str, object]:
+async def run_canonical_operation(
+    question: str, tool_context: ToolContext
+) -> dict[str, object]:
     """Run the project-selected text Operation through canonical platform APIs."""
+    ensure_debug_session_writable(tool_context.state.get(IMPORTED_SESSION_STATE_KEY))
     if PROJECT_OPERATION is None:
         raise RuntimeError("项目尚未选择可调试的文本 Operation")
     return await CanonicalRunDebugClient.from_environment(
@@ -29,6 +37,13 @@ async def run_canonical_operation(question: str) -> dict[str, object]:
     ).run(question)
 
 
+def ensure_debug_session_writable(imported_marker: object) -> None:
+    if imported_marker is True:
+        raise ImportedDebugSessionReadOnlyError(
+            "导入的业务会话是实时只读投影；请新建本地会话继续提问"
+        )
+
+
 class CanonicalDebugLlm(BaseLlm):
     """ADK dispatcher; real model and Tool execution stay in canonical Run."""
 
@@ -42,7 +57,8 @@ class CanonicalDebugLlm(BaseLlm):
         stream: bool = False,
     ) -> AsyncGenerator[LlmResponse, None]:
         del stream
-        tool_response = latest_tool_response(llm_request)
+        question, user_turn_index = latest_user_turn(llm_request)
+        tool_response = latest_tool_response(llm_request, user_turn_index)
         if tool_response is not None:
             yield text_response(render_result(tool_response))
             return
@@ -52,7 +68,6 @@ class CanonicalDebugLlm(BaseLlm):
                 "选择真实文本 Operation。"
             )
             return
-        question = latest_user_text(llm_request)
         if not question:
             yield text_response("请输入要交给真实 Agent Runtime 调试的业务问题。")
             return
@@ -72,18 +87,23 @@ class CanonicalDebugLlm(BaseLlm):
         )
 
 
-def latest_user_text(request: LlmRequest) -> str:
-    for content in reversed(request.contents):
+def latest_user_turn(request: LlmRequest) -> tuple[str, int]:
+    for index in range(len(request.contents) - 1, -1, -1):
+        content = request.contents[index]
         if content.role != "user":
             continue
         text = "".join(part.text or "" for part in content.parts or [])
         if text.strip():
-            return text.strip()
-    return ""
+            return text.strip(), index
+    return "", -1
 
 
-def latest_tool_response(request: LlmRequest) -> dict[str, object] | None:
-    for content in reversed(request.contents):
+def latest_tool_response(
+    request: LlmRequest, user_turn_index: int
+) -> dict[str, object] | None:
+    if user_turn_index < 0:
+        return None
+    for content in reversed(request.contents[user_turn_index + 1 :]):
         for part in content.parts or []:
             response = part.function_response
             if response and response.name == TOOL_NAME:

package/template/apps/agent-server/adk_web_agents/services.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.cli.service_registry import get_service_registry
+
+from southwind_agent_server.adk_debug_sessions import (
+    WindyDebugSessionClientV1,
+    WindyDebugSessionServiceV1,
+)
+
+SESSION_SERVICE_URI = "windy-debug://v1"
+
+
+def create_windy_debug_session_service(
+    uri: str, **_kwargs: Any
+) -> WindyDebugSessionServiceV1:
+    if uri != SESSION_SERVICE_URI:
+        raise ValueError("Windy ADK debug session URI 版本不受支持")
+    return WindyDebugSessionServiceV1(WindyDebugSessionClientV1.from_environment())
+
+
+get_service_registry().register_session_service(
+    "windy-debug", create_windy_debug_session_service
+)

package/template/apps/agent-server/src/southwind_agent_server/adk_adapter.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import AsyncIterator
+from typing import cast
 
 from google.adk.agents import LlmAgent
 from google.adk.agents.run_config import RunConfig, StreamingMode
@@ -13,7 +14,6 @@ from google.genai import types
 from .adk_failure import AdkFailureState
 from .adk_model import GovernedOpenAiLlm
 from .adk_tools import ApprovalSignalState, GovernedTool
-from .contracts import JsonValue
 from .engine import (
     AgentEngineAdapter,
     EngineCompleted,
@@ -26,9 +26,11 @@ from .engine import (
     UsageReported,
 )
 from .multimodal import final_output
-from .openai_engine import cancelled, validate_runtime_request
+from .openai_engine_validation import cancelled, validate_runtime_request
 from .openai_provider import OpenAiCompatibleProvider
 from .provider_governance import ProviderRequestGovernance
+from .report_store import AgentRuntimeReportStore
+from .report_types import CacheStatus, UsageFacts, UsageSource
 from .tool_host import ToolHostClient, canonical_tool_call_id
 
 
@@ -40,10 +42,12 @@ class AdkEngineAdapter(AgentEngineAdapter):
         provider: OpenAiCompatibleProvider | None = None,
         tool_host: ToolHostClient | None = None,
         governance: ProviderRequestGovernance | None = None,
+        report_store: AgentRuntimeReportStore | None = None,
     ) -> None:
         self._provider = provider
         self._tool_host = tool_host
         self._governance = governance
+        self._report_store = report_store
         self._cancellations: dict[str, asyncio.Event] = {}
 
     @property
@@ -95,6 +99,7 @@ class AdkEngineAdapter(AgentEngineAdapter):
                         governance,
                         cancellation,
                         failures,
+                        self._report_store,
                     ),
                     instruction=request.instructions,
                     tools=[
@@ -241,21 +246,45 @@ async def signals_for_event(
             if part.text and not part.thought:
                 yield OutputDelta(part.text)
     usage = southwind_usage(event)
-    if usage is not None:
-        yield UsageReported(usage)
+    attempt_sequence = southwind_attempt_sequence(event)
+    if usage is not None and attempt_sequence is not None:
+        yield UsageReported(attempt_sequence, usage)
 
 
-def southwind_usage(event: Event) -> dict[str, JsonValue] | None:
+def southwind_usage(event: Event) -> UsageFacts | None:
     metadata = event.custom_metadata or {}
     value = metadata.get("southwindUsage")
     if not isinstance(value, dict):
         return None
-    return {
-        key: item
-        for key, item in value.items()
-        if isinstance(key, str)
-        and (item is None or isinstance(item, str | int | float | bool | list | dict))
-    }
+    source = value.get("source")
+    cache_status = value.get("cacheStatus")
+    if source not in {"provider-reported", "estimated", "unknown"}:
+        return None
+    if cache_status not in {"hit", "miss", "unknown"}:
+        return None
+    return UsageFacts(
+        source=cast(UsageSource, source),
+        cache_status=cast(CacheStatus, cache_status),
+        input_tokens=measurement(value.get("inputTokens")),
+        output_tokens=measurement(value.get("outputTokens")),
+        cached_input_tokens=measurement(value.get("cachedInputTokens")),
+        reasoning_tokens=measurement(value.get("reasoningTokens")),
+        total_tokens=measurement(value.get("totalTokens")),
+        first_token_latency_ms=measurement(value.get("firstTokenLatencyMs")),
+    )
+
+
+def southwind_attempt_sequence(event: Event) -> int | None:
+    value = (event.custom_metadata or {}).get("southwindAttemptSequence")
+    return value if isinstance(value, int) and value > 0 else None
+
+
+def measurement(value: object) -> int | None:
+    return (
+        value
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 0
+        else None
+    )
 
 
 async def merge_adk_events(

package/template/apps/agent-server/src/southwind_agent_server/adk_debug_sessions.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import logging
+import os
+import re
+from datetime import datetime
+from typing import Literal, Protocol, cast, override
+
+import httpx
+from google.adk.events.event import Event
+from google.adk.sessions.base_session_service import (
+    BaseSessionService,
+    GetSessionConfig,
+    ListSessionsResponse,
+)
+from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from google.adk.sessions.session import Session
+from google.genai import types
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .config import normalize_base_url
+
+CANONICAL_DEBUG_APP = "canonical_debug"
+CANONICAL_DEBUG_USER = "user"
+IMPORTED_SESSION_ID_PREFIX = "wdbg1_"
+IMPORTED_SESSION_ID_PATTERN = re.compile(r"^wdbg1_[A-Za-z0-9_-]{43}$")
+IMPORTED_SESSION_STATE_KEY = "__windy_debug_session_v1__"
+MAX_MESSAGES = 64
+MAX_TOTAL_MESSAGE_CHARS = 128_000
+logger = logging.getLogger(__name__)
+
+
+class ImportedDebugSessionReadOnlyError(RuntimeError):
+    pass
+
+
+class _StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class DebugSessionSummaryV1(_StrictModel):
+    id: str = Field(pattern=r"^wdbg1_[A-Za-z0-9_-]{43}$")
+    title: str = Field(min_length=1, max_length=200)
+    scopeLabel: str | None = Field(default=None, min_length=1, max_length=120)
+    updatedAt: str = Field(min_length=1, max_length=40)
+    revision: str = Field(min_length=1, max_length=200)
+
+
+class DebugSessionMessageV1(_StrictModel):
+    sequence: int = Field(ge=0)
+    role: Literal["user", "assistant"]
+    content: str = Field(min_length=1, max_length=16_000)
+    createdAt: str = Field(min_length=1, max_length=40)
+
+
+class DebugSessionDetailV1(DebugSessionSummaryV1):
+    messages: list[DebugSessionMessageV1] = Field(max_length=MAX_MESSAGES)
+
+
+class DebugSessionListEnvelopeV1(_StrictModel):
+    schemaVersion: Literal[1]
+    sessions: list[DebugSessionSummaryV1]
+    truncated: bool
+
+
+class DebugSessionDetailEnvelopeV1(_StrictModel):
+    schemaVersion: Literal[1]
+    session: DebugSessionDetailV1
+
+
+class DebugSessionClientPortV1(Protocol):
+    async def list(self) -> DebugSessionListEnvelopeV1: ...
+
+    async def get(self, session_id: str) -> DebugSessionDetailV1 | None: ...
+
+
+class WindyDebugSessionClientV1:
+    def __init__(
+        self,
+        base_url: str,
+        bearer_token: str,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._base_url = normalize_base_url(base_url)
+        self._bearer_token = bearer_token.strip()
+        self._transport = transport
+        if not self._bearer_token:
+            raise RuntimeError("ADK_DEBUG_PLATFORM_TOKEN 未配置，拒绝读取调试会话")
+
+    @classmethod
+    def from_environment(cls) -> WindyDebugSessionClientV1:
+        return cls(
+            os.environ.get("ADK_DEBUG_PLATFORM_URL", "http://server:9747"),
+            os.environ.get("ADK_DEBUG_PLATFORM_TOKEN", ""),
+        )
+
+    async def list(self) -> DebugSessionListEnvelopeV1:
+        value = await self._get("api/agent/debug/sessions/v1")
+        try:
+            envelope = DebugSessionListEnvelopeV1.model_validate(value)
+            for session in envelope.sessions:
+                parse_timestamp(session.updatedAt)
+            return envelope
+        except (ValidationError, ValueError) as error:
+            raise RuntimeError("平台调试会话列表响应无效") from error
+
+    async def get(self, session_id: str) -> DebugSessionDetailV1 | None:
+        if not IMPORTED_SESSION_ID_PATTERN.fullmatch(session_id):
+            raise RuntimeError("平台调试会话 ID 无效")
+        value = await self._get(
+            f"api/agent/debug/sessions/v1/{session_id}",
+            allow_not_found=True,
+        )
+        if value is None:
+            return None
+        try:
+            session = DebugSessionDetailEnvelopeV1.model_validate(value).session
+            validate_detail(session)
+            return session
+        except (ValidationError, ValueError) as error:
+            raise RuntimeError("平台调试会话详情响应无效") from error
+
+    async def _get(self, path: str, *, allow_not_found: bool = False) -> object | None:
+        headers = {
+            "authorization": f"Bearer {self._bearer_token}",
+            "user-agent": "Windy-ADK-Web-Dev",
+        }
+        async with httpx.AsyncClient(
+            base_url=f"{self._base_url}/",
+            headers=headers,
+            timeout=httpx.Timeout(15),
+            transport=self._transport,
+        ) as client:
+            response = await client.get(path)
+        if allow_not_found and response.status_code == 404:
+            return None
+        if not response.is_success:
+            raise RuntimeError("平台调试会话读取失败")
+        try:
+            return cast(object, response.json())
+        except ValueError as error:
+            raise RuntimeError("平台调试会话响应不是有效 JSON") from error
+
+
+class WindyDebugSessionServiceV1(BaseSessionService):
+    """Keep normal ADK sessions local and overlay live read-only projections."""
+
+    def __init__(
+        self,
+        client: DebugSessionClientPortV1,
+        local: InMemorySessionService | None = None,
+    ) -> None:
+        self._client = client
+        self._local = (
+            local if local is not None else InMemorySessionService()  # type: ignore[no-untyped-call]
+        )
+        self._deleted_imports: set[str] = set()
+
+    @override
+    async def create_session(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        state: dict[str, object] | None = None,
+        session_id: str | None = None,
+    ) -> Session:
+        if session_id and session_id.startswith(IMPORTED_SESSION_ID_PREFIX):
+            raise ImportedDebugSessionReadOnlyError("导入的业务会话 ID 为只读保留值")
+        return await self._local.create_session(
+            app_name=app_name,
+            user_id=user_id,
+            state=state,
+            session_id=session_id,
+        )
+
+    @override
+    async def get_session(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        config: GetSessionConfig | None = None,
+    ) -> Session | None:
+        if not self._is_imported_request(app_name, user_id, session_id):
+            return await self._local.get_session(
+                app_name=app_name,
+                user_id=user_id,
+                session_id=session_id,
+                config=config,
+            )
+        if session_id in self._deleted_imports:
+            return None
+        detail = await self._client.get(session_id)
+        return project_detail(detail, config) if detail else None
+
+    @override
+    async def list_sessions(
+        self, *, app_name: str, user_id: str | None = None
+    ) -> ListSessionsResponse:
+        local = await self._local.list_sessions(app_name=app_name, user_id=user_id)
+        if app_name != CANONICAL_DEBUG_APP or user_id != CANONICAL_DEBUG_USER:
+            return local
+        try:
+            remote = await self._client.list()
+        except Exception:
+            # Discovery is best-effort; cancellation and other BaseException values
+            # still propagate instead of being mistaken for an offline platform.
+            logger.warning("平台调试会话不可用，仅返回本地 ADK 会话")
+            return local
+        imported = [
+            project_summary(session)
+            for session in remote.sessions
+            if session.id not in self._deleted_imports
+        ]
+        return ListSessionsResponse(sessions=[*local.sessions, *imported])
+
+    @override
+    async def delete_session(
+        self, *, app_name: str, user_id: str, session_id: str
+    ) -> None:
+        if self._is_imported_request(app_name, user_id, session_id):
+            self._deleted_imports.add(session_id)
+            return
+        await self._local.delete_session(
+            app_name=app_name, user_id=user_id, session_id=session_id
+        )
+
+    @override
+    async def append_event(self, session: Session, event: Event) -> Event:
+        if session.state.get(IMPORTED_SESSION_STATE_KEY) is True:
+            raise ImportedDebugSessionReadOnlyError(
+                "导入的业务会话是实时只读投影；请新建本地会话继续提问"
+            )
+        return await self._local.append_event(session=session, event=event)
+
+    @override
+    async def get_user_state(self, *, app_name: str, user_id: str) -> dict[str, object]:
+        return await self._local.get_user_state(app_name=app_name, user_id=user_id)
+
+    @staticmethod
+    def _is_imported_request(app_name: str, user_id: str, session_id: str) -> bool:
+        return (
+            app_name == CANONICAL_DEBUG_APP
+            and user_id == CANONICAL_DEBUG_USER
+            and IMPORTED_SESSION_ID_PATTERN.fullmatch(session_id) is not None
+        )
+
+
+def project_summary(value: DebugSessionSummaryV1) -> Session:
+    return Session(
+        id=value.id,
+        app_name=CANONICAL_DEBUG_APP,
+        user_id=CANONICAL_DEBUG_USER,
+        state=imported_state(value),
+        events=[],
+        last_update_time=parse_timestamp(value.updatedAt),
+    )
+
+
+def project_detail(
+    value: DebugSessionDetailV1,
+    config: GetSessionConfig | None,
+) -> Session:
+    events = [project_message(value.id, message) for message in value.messages]
+    if config and config.after_timestamp is not None:
+        events = [
+            event for event in events if event.timestamp >= config.after_timestamp
+        ]
+    if config and config.num_recent_events is not None:
+        events = (
+            [] if config.num_recent_events == 0 else events[-config.num_recent_events :]
+        )
+    return Session(
+        id=value.id,
+        app_name=CANONICAL_DEBUG_APP,
+        user_id=CANONICAL_DEBUG_USER,
+        state=imported_state(value),
+        events=events,
+        last_update_time=parse_timestamp(value.updatedAt),
+    )
+
+
+def project_message(session_id: str, value: DebugSessionMessageV1) -> Event:
+    role = "user" if value.role == "user" else "model"
+    return Event(
+        id=f"{session_id}-{value.sequence}",
+        invocation_id=f"{session_id}-projection",
+        author="user" if value.role == "user" else CANONICAL_DEBUG_APP,
+        content=types.Content(role=role, parts=[types.Part(text=value.content)]),
+        timestamp=parse_timestamp(value.createdAt),
+    )
+
+
+def imported_state(value: DebugSessionSummaryV1) -> dict[str, object]:
+    display_name = (
+        f"{value.title} · {value.scopeLabel}" if value.scopeLabel else value.title
+    )
+    return {
+        IMPORTED_SESSION_STATE_KEY: True,
+        "__session_metadata__": {"displayName": display_name},
+    }
+
+
+def validate_detail(value: DebugSessionDetailV1) -> None:
+    parse_timestamp(value.updatedAt)
+    total_chars = 0
+    previous_sequence = -1
+    for message in value.messages:
+        parse_timestamp(message.createdAt)
+        if message.sequence <= previous_sequence:
+            raise ValueError("调试会话消息顺序无效")
+        previous_sequence = message.sequence
+        total_chars += len(message.content)
+    if total_chars > MAX_TOTAL_MESSAGE_CHARS:
+        raise ValueError("调试会话消息总量超过上限")
+
+
+def parse_timestamp(value: str) -> float:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("调试会话时间必须包含时区")
+    return parsed.timestamp()