create-windy 0.2.33 → 0.3.0

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

@@ -1,39 +1,214 @@
 from __future__ import annotations
 
-from collections.abc import AsyncIterator, Mapping
+import asyncio
+from collections.abc import AsyncIterator
 
+from google.adk.agents import LlmAgent
+from google.adk.agents.run_config import RunConfig, StreamingMode
+from google.adk.events import Event
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+from .adk_failure import AdkFailureState
+from .adk_model import GovernedOpenAiLlm
+from .adk_tools import GovernedTool
+from .contracts import JsonValue
 from .engine import (
     AgentEngineAdapter,
+    EngineCompleted,
     EngineRunRequest,
     EngineSignal,
+    OutputDelta,
     SafeEngineError,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
 )
+from .openai_engine import cancelled, validate_runtime_request
+from .openai_provider import OpenAiCompatibleProvider
+from .provider_governance import ProviderRequestGovernance
+from .tool_host import ToolHostClient
 
 
 class AdkEngineAdapter(AgentEngineAdapter):
-    """Google ADK implementation skeleton.
-
-    Agent objects remain opaque and internal. A later slice will create ADK Runners,
-    consume ADK Events, and translate them into EngineSignal values at this seam.
-    """
+    """Google ADK Runner implementation behind the stable engine seam."""
 
-    def __init__(self, agents: Mapping[str, object] | None = None) -> None:
-        self._agents = dict(agents or {})
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider | None = None,
+        tool_host: ToolHostClient | None = None,
+        governance: ProviderRequestGovernance | None = None,
+    ) -> None:
+        self._provider = provider
+        self._tool_host = tool_host
+        self._governance = governance
+        self._cancellations: dict[str, asyncio.Event] = {}
 
     def supports(self, operation_key: str) -> bool:
-        return operation_key in self._agents
+        return bool(operation_key.strip())
 
     async def execute(
         self,
         request: EngineRunRequest,
     ) -> AsyncIterator[EngineSignal]:
-        del request
-        raise SafeEngineError(
-            "RUNTIME_UNAVAILABLE",
-            "Agent Runtime 尚未配置",
-            retryable=True,
+        provider, tool_host, governance = self._configured()
+        validate_runtime_request(request, provider.config.deployment_key)
+        cancellation = self._cancellations.setdefault(
+            request.run_id,
+            asyncio.Event(),
         )
-        yield  # pragma: no cover - keeps this method an async generator
+        output = ""
+        output_bytes = 0
+        failures = AdkFailureState()
+        event_failure: SafeEngineError | None = None
+        try:
+            session_service = InMemorySessionService()  # type: ignore[no-untyped-call]
+            await session_service.create_session(
+                app_name="southwind_runtime",
+                user_id="platform",
+                session_id=request.run_id,
+            )
+            runner = Runner(
+                app_name="southwind_runtime",
+                agent=LlmAgent(
+                    name="southwind_operation",
+                    model=GovernedOpenAiLlm(
+                        request,
+                        provider,
+                        governance,
+                        cancellation,
+                        failures,
+                    ),
+                    instruction=request.instructions,
+                    tools=[
+                        GovernedTool(
+                            tool,
+                            request,
+                            tool_host,
+                            cancellation,
+                            failures,
+                        )
+                        for tool in request.allowed_tools
+                    ],
+                ),
+                session_service=session_service,
+            )
+            async for event in runner.run_async(
+                user_id="platform",
+                session_id=request.run_id,
+                new_message=types.Content(
+                    role="user",
+                    parts=[types.Part(text=request.user_prompt)],
+                ),
+                run_config=RunConfig(
+                    streaming_mode=StreamingMode.SSE,
+                    max_llm_calls=provider.config.max_tool_rounds,
+                ),
+            ):
+                cancelled(cancellation)
+                if event.error_code:
+                    event_failure = failures.failure or SafeEngineError(
+                        "PROVIDER_UNAVAILABLE",
+                        "模型服务暂不可用",
+                        retryable=True,
+                    )
+                    continue
+                async for signal in signals_for_event(event):
+                    if isinstance(signal, OutputDelta):
+                        output_bytes += len(signal.text.encode())
+                        if output_bytes > request.limits.max_output_bytes:
+                            raise SafeEngineError(
+                                "BUDGET_EXCEEDED",
+                                "Agent 输出超过 Operation 上限",
+                                retryable=False,
+                            )
+                        output += signal.text
+                    yield signal
+            if event_failure is not None:
+                raise event_failure
+            cancelled(cancellation)
+            yield EngineCompleted({"text": output})
+        except SafeEngineError:
+            raise
+        except asyncio.CancelledError:
+            raise SafeEngineError(
+                "RUN_CANCELLED",
+                "Agent Run 已取消",
+                retryable=False,
+            ) from None
+        except Exception:
+            raise SafeEngineError(
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 执行失败",
+                retryable=True,
+            ) from None
+        finally:
+            self._cancellations.pop(request.run_id, None)
 
     async def cancel(self, run_id: str) -> None:
-        del run_id
+        cancellation = self._cancellations.get(run_id)
+        if cancellation is not None:
+            cancellation.set()
+
+    async def health(self) -> None:
+        provider, _, _ = self._configured()
+        await provider.health()
+
+    def governance_health(self) -> dict[str, int | float | str | None]:
+        _, _, governance = self._configured()
+        return governance.health()
+
+    def _configured(
+        self,
+    ) -> tuple[
+        OpenAiCompatibleProvider,
+        ToolHostClient,
+        ProviderRequestGovernance,
+    ]:
+        if not self._provider or not self._tool_host or not self._governance:
+            raise SafeEngineError(
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 尚未配置",
+                retryable=True,
+            )
+        return self._provider, self._tool_host, self._governance
+
+
+async def signals_for_event(event: Event) -> AsyncIterator[EngineSignal]:
+    for call in event.get_function_calls():
+        if not call.id or not call.name:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "模型请求了无效 Tool",
+                retryable=False,
+            )
+        yield ToolRequested(call.id, call.name)
+    for response in event.get_function_responses():
+        if not response.id:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "Agent Tool 响应缺少稳定标识",
+                retryable=False,
+            )
+        yield ToolCompleted(response.id)
+    if event.partial and event.content:
+        for part in event.content.parts or []:
+            if part.text and not part.thought:
+                yield OutputDelta(part.text)
+    usage = southwind_usage(event)
+    if usage is not None:
+        yield UsageReported(usage)
+
+
+def southwind_usage(event: Event) -> dict[str, JsonValue] | 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))
+    }

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

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .engine import SafeEngineError
+
+
+@dataclass
+class AdkFailureState:
+    failure: SafeEngineError | None = None
+
+    def capture(self, error: SafeEngineError) -> None:
+        self.failure = error

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

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncGenerator
+
+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.genai import types
+from pydantic import PrivateAttr
+
+from .adk_failure import AdkFailureState
+from .contracts import JsonValue
+from .engine import EngineRunRequest, SafeEngineError
+from .openai_engine import cancelled, parse_arguments
+from .openai_provider import OpenAiCompatibleProvider, ProviderTurn
+from .provider_governance import ProviderRequestGovernance
+
+
+class GovernedOpenAiLlm(BaseLlm):
+    """ADK model bridge that preserves Southwind's provider governance."""
+
+    _request: EngineRunRequest = PrivateAttr()
+    _provider: OpenAiCompatibleProvider = PrivateAttr()
+    _governance: ProviderRequestGovernance = PrivateAttr()
+    _cancellation: asyncio.Event = PrivateAttr()
+    _failures: AdkFailureState = PrivateAttr()
+    _attempt: int = PrivateAttr(default=0)
+
+    def __init__(
+        self,
+        request: EngineRunRequest,
+        provider: OpenAiCompatibleProvider,
+        governance: ProviderRequestGovernance,
+        cancellation: asyncio.Event,
+        failures: AdkFailureState,
+    ) -> None:
+        super().__init__(model=provider.config.model)
+        self._request = request
+        self._provider = provider
+        self._governance = governance
+        self._cancellation = cancellation
+        self._failures = failures
+
+    async def generate_content_async(
+        self,
+        llm_request: LlmRequest,
+        stream: bool = False,
+    ) -> AsyncGenerator[LlmResponse, None]:
+        del stream
+        try:
+            cancelled(self._cancellation)
+            self._attempt += 1
+            if self._attempt > self._provider.config.max_tool_rounds:
+                raise SafeEngineError(
+                    "BUDGET_EXCEEDED",
+                    "Agent Tool 调用轮次超过上限",
+                    retryable=False,
+                )
+            messages = adk_messages(llm_request, self._request.instructions)
+            governed = self._governance.authorize(
+                deployment_key=self._provider.config.deployment_key,
+                operation_key=self._request.operation_key,
+                run_id=self._request.run_id,
+                attempt=self._attempt,
+                messages=messages,
+                tools=self._request.allowed_tools,
+                policy=self._request.provider_data_policy,
+                input_value=self._request.input,
+                measure=lambda values, tools: len(
+                    self._provider.request_body(values, tools)
+                ),
+            )
+            turn = await self._provider.complete_turn(
+                governed.messages,
+                governed.tools,
+            )
+            cancelled(self._cancellation)
+            validate_tool_calls(
+                turn,
+                {tool.key for tool in self._request.allowed_tools},
+            )
+            async for response in responses_for_turn(turn):
+                yield response
+        except SafeEngineError as error:
+            self._failures.capture(error)
+            raise
+
+
+def adk_messages(
+    request: LlmRequest,
+    instructions: str,
+) -> list[dict[str, JsonValue]]:
+    result: list[dict[str, JsonValue]] = [{"role": "system", "content": instructions}]
+    for content in request.contents:
+        parts = content.parts or []
+        calls = [part.function_call for part in parts if part.function_call]
+        responses = [part.function_response for part in parts if part.function_response]
+        text = "".join(
+            part.text or "" for part in parts if not part.thought and part.text
+        )
+        if calls:
+            result.append(
+                {
+                    "role": "assistant",
+                    "content": text or None,
+                    "tool_calls": [
+                        {
+                            "id": call.id or "",
+                            "type": "function",
+                            "function": {
+                                "name": call.name or "",
+                                "arguments": json.dumps(
+                                    call.args or {},
+                                    ensure_ascii=False,
+                                    separators=(",", ":"),
+                                ),
+                            },
+                        }
+                        for call in calls
+                    ],
+                }
+            )
+        elif responses:
+            result.extend(tool_response_messages(responses))
+        elif text:
+            result.append(
+                {
+                    "role": "assistant" if content.role == "model" else "user",
+                    "content": text,
+                }
+            )
+    return result
+
+
+def tool_response_messages(
+    responses: list[types.FunctionResponse],
+) -> list[dict[str, JsonValue]]:
+    return [
+        {
+            "role": "tool",
+            "tool_call_id": response.id or "",
+            "content": json.dumps(
+                response.response or {},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+        }
+        for response in responses
+    ]
+
+
+def validate_tool_calls(turn: ProviderTurn, allowed: set[str]) -> None:
+    for call in turn.tool_calls:
+        if not call.call_id or not call.name or call.name not in allowed:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "模型请求了未授权 Tool",
+                retryable=False,
+            )
+        parse_arguments(call.arguments)
+
+
+async def responses_for_turn(
+    turn: ProviderTurn,
+) -> AsyncGenerator[LlmResponse, None]:
+    usage = turn.usage or {"source": "unknown"}
+    metadata = {"southwindUsage": usage}
+    if turn.tool_calls:
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[
+                    types.Part(
+                        function_call=types.FunctionCall(
+                            id=call.call_id,
+                            name=call.name,
+                            args=parse_arguments(call.arguments),
+                        )
+                    )
+                    for call in turn.tool_calls
+                ],
+            ),
+            partial=False,
+            custom_metadata=metadata,
+            usage_metadata=adk_usage(usage),
+        )
+        return
+    for delta in turn.text_deltas:
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[types.Part(text=delta)],
+            ),
+            partial=True,
+        )
+    yield LlmResponse(
+        content=types.Content(
+            role="model",
+            parts=[types.Part(text=turn.text)],
+        ),
+        partial=False,
+        custom_metadata=metadata,
+        usage_metadata=adk_usage(usage),
+    )
+
+
+def adk_usage(
+    usage: dict[str, JsonValue],
+) -> types.GenerateContentResponseUsageMetadata | None:
+    input_tokens = usage.get("inputTokens")
+    output_tokens = usage.get("outputTokens")
+    total_tokens = usage.get("totalTokens")
+    if not any(
+        isinstance(value, int) for value in (input_tokens, output_tokens, total_tokens)
+    ):
+        return None
+    return types.GenerateContentResponseUsageMetadata(
+        prompt_token_count=input_tokens if isinstance(input_tokens, int) else None,
+        candidates_token_count=(
+            output_tokens if isinstance(output_tokens, int) else None
+        ),
+        total_token_count=total_tokens if isinstance(total_tokens, int) else None,
+    )

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

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+from .adk_failure import AdkFailureState
+from .contracts import JsonValue, RuntimeToolDefinition
+from .engine import EngineRunRequest, SafeEngineError
+from .openai_engine import cancelled
+from .tool_host import ToolHostClient, ToolInvocation
+
+
+class GovernedTool(BaseTool):
+    """ADK declaration whose only execution path is the governed Tool Host."""
+
+    def __init__(
+        self,
+        definition: RuntimeToolDefinition,
+        request: EngineRunRequest,
+        tool_host: ToolHostClient,
+        cancellation: asyncio.Event,
+        failures: AdkFailureState,
+    ) -> None:
+        super().__init__(
+            name=definition.key,
+            description=definition.description,
+        )
+        self._request = request
+        self._tool_host = tool_host
+        self._cancellation = cancellation
+        self._failures = failures
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters_json_schema={
+                "type": "object",
+                "additionalProperties": True,
+            },
+        )
+
+    async def run_async(
+        self,
+        *,
+        args: dict[str, Any],
+        tool_context: ToolContext,
+    ) -> JsonValue:
+        try:
+            cancelled(self._cancellation)
+            call_id = tool_context.function_call_id
+            if not call_id:
+                raise SafeEngineError(
+                    "TOOL_DENIED",
+                    "Agent Tool Call 缺少稳定标识",
+                    retryable=False,
+                )
+            result = await self._tool_host.execute(
+                self._request.tool_host_url,
+                ToolInvocation(
+                    self._request.run_id,
+                    call_id,
+                    self.name,
+                    cast(dict[str, JsonValue], args),
+                    self._request.execution_grant,
+                ),
+            )
+            cancelled(self._cancellation)
+            return result
+        except SafeEngineError as error:
+            self._failures.capture(error)
+            raise

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

@@ -3,7 +3,7 @@ from __future__ import annotations
 import hmac
 import os
 import uuid
-from typing import Annotated
+from typing import Annotated, cast
 
 from fastapi import FastAPI, Header, Query, Request
 from fastapi.exceptions import RequestValidationError
@@ -21,8 +21,9 @@ from .contracts import (
     StartRunResponse,
 )
 from .engine import AgentEngineAdapter
-from .openai_engine import OpenAiCompatibleEngineAdapter
 from .openai_provider import OpenAiCompatibleProvider
+from .provider_audit import ProviderAuditStore
+from .provider_governance import ProviderRequestGovernance
 from .service import (
     AgentRunService,
     IdempotencyConflictError,
@@ -71,6 +72,24 @@ def create_app(
                 True,
             )
 
+    @application.get("/health/provider-governance", response_model=None)
+    async def provider_governance_health(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, int | float | str | None] | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        health = getattr(runtime_engine, "governance_health", None)
+        if not health:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Provider 字段治理尚未配置",
+                True,
+            )
+        return provider_governance_snapshot(
+            cast(dict[str, int | float | str | None], health())
+        )
+
     @application.exception_handler(OperationNotFoundError)
     async def operation_not_found(
         _request: Request,
@@ -209,12 +228,18 @@ def default_engine() -> AgentEngineAdapter:
     internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
     if not internal_token:
         raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
-    return OpenAiCompatibleEngineAdapter(
+    return AdkEngineAdapter(
         OpenAiCompatibleProvider(
             config,
             EnvironmentSecretResolver(os.environ),
         ),
         ToolHostClient(internal_token),
+        ProviderRequestGovernance(
+            ProviderAuditStore(
+                required_environment("AI_PROVIDER_AUDIT_STORE_PATH"),
+                retention_days=provider_audit_retention_days(),
+            )
+        ),
     )
 
 
@@ -223,6 +248,41 @@ def default_store() -> RunStore:
     return SqliteRunStore(path) if path else InMemoryRunStore()
 
 
+def required_environment(key: str) -> str:
+    value = os.environ.get(key, "").strip()
+    if not value:
+        raise ValueError(f"Provider 已配置但缺少 {key}")
+    return value
+
+
+def provider_audit_retention_days() -> int:
+    raw = os.environ.get("AI_PROVIDER_AUDIT_RETENTION_DAYS", "90")
+    try:
+        value = int(raw)
+    except ValueError as error:
+        raise ValueError("AI_PROVIDER_AUDIT_RETENTION_DAYS 必须是整数") from error
+    if not 1 <= value <= 3650:
+        raise ValueError("AI_PROVIDER_AUDIT_RETENTION_DAYS 超出允许范围")
+    return value
+
+
+def provider_governance_snapshot(
+    value: dict[str, int | float | str | None],
+) -> dict[str, int | float | str | None]:
+    allowed = (
+        "status",
+        "retentionDays",
+        "retainedRecords",
+        "rejectedAttempts",
+        "redactedAttempts",
+        "lastAttemptAt",
+        "lastPurgeAt",
+        "lastDeletedRecords",
+        "totalDeletedRecords",
+    )
+    return {key: value.get(key) for key in allowed}
+
+
 def authorized(provided: str | None, expected: str | None) -> bool:
     if expected is None:
         return True

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

@@ -74,6 +74,40 @@ class ProviderEgress(CanonicalModel):
         return self
 
 
+type ProviderDataField = Literal[
+    "instructions",
+    "user-prompt",
+    "tool-definitions",
+    "provider-output",
+    "tool-results",
+]
+
+
+class ProviderFieldPolicy(CanonicalModel):
+    field: ProviderDataField
+    classification: Literal["public", "internal", "sensitive"]
+    dlp_action: Literal["reject", "redact"]
+
+
+class ProviderInputFieldPolicy(CanonicalModel):
+    json_pointer: str = Field(pattern=r"^/[^/]+(?:/[^/]+)*$")
+    classification: Literal["public", "internal", "sensitive"]
+    dlp_action: Literal["reject", "redact"]
+
+
+class ProviderDataPolicy(CanonicalModel):
+    input_fields: list[ProviderInputFieldPolicy] = Field(default_factory=list)
+    envelope_fields: list[ProviderFieldPolicy] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_fields(self) -> Self:
+        names = [rule.field for rule in self.envelope_fields]
+        pointers = [rule.json_pointer for rule in self.input_fields]
+        if len(names) != len(set(names)) or len(pointers) != len(set(pointers)):
+            raise ValueError("Provider 字段发送规则重复")
+        return self
+
+
 class ToolNetworkPolicy(CanonicalModel):
     mode: Literal["forbidden"] = "forbidden"
 
@@ -86,6 +120,7 @@ class StartRunRequest(CanonicalModel):
     allowed_tools: list[RuntimeToolDefinition] = Field(default_factory=list)
     limits: RuntimeLimits = Field(default_factory=RuntimeLimits)
     provider_egress: ProviderEgress = Field(default_factory=ProviderEgress)
+    provider_data_policy: ProviderDataPolicy = Field(default_factory=ProviderDataPolicy)
     tool_network_policy: ToolNetworkPolicy = Field(default_factory=ToolNetworkPolicy)
     execution_grant: str = ""
     tool_host_url: str = ""