create-windy 0.2.20 → 0.2.21

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

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import ipaddress
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import urlsplit, urlunsplit
+
+
+@dataclass(frozen=True)
+class SecretRef:
+    provider: str
+    locator: str
+
+    def __str__(self) -> str:
+        return "[SecretRef]"
+
+
+class EnvironmentSecretResolver:
+    def __init__(self, environment: Mapping[str, str]) -> None:
+        self._environment = environment
+
+    def resolve(self, ref: SecretRef) -> str | None:
+        if ref.provider != "env":
+            raise ValueError("Secret Provider 不匹配")
+        return self._environment.get(ref.locator)
+
+
+@dataclass(frozen=True)
+class OpenAiCompatibleConfig:
+    base_url: str
+    model: str
+    api_key_ref: SecretRef | None
+    connect_timeout_seconds: float = 5.0
+    request_timeout_seconds: float = 60.0
+    max_response_bytes: int = 2 * 1024 * 1024
+    max_tool_rounds: int = 8
+
+    @classmethod
+    def from_environment(
+        cls,
+        environment: Mapping[str, str] = os.environ,
+    ) -> OpenAiCompatibleConfig | None:
+        base_url = environment.get("QWEN_API_URL", "").strip()
+        model = environment.get("QWEN_MODEL", "").strip()
+        if not base_url and not model:
+            return None
+        if not base_url or not model:
+            raise ValueError("OpenAI-compatible Endpoint 与 Model 必须同时配置")
+        return cls(
+            base_url=normalize_base_url(base_url),
+            model=model,
+            api_key_ref=(
+                SecretRef("env", "QWEN_API_KEY")
+                if environment.get("QWEN_API_KEY", "").strip()
+                else None
+            ),
+            connect_timeout_seconds=read_milliseconds(
+                environment,
+                "AI_PROVIDER_CONNECT_TIMEOUT_MS",
+                5_000,
+                100,
+                30_000,
+            )
+            / 1_000,
+            request_timeout_seconds=read_milliseconds(
+                environment,
+                "AI_PROVIDER_REQUEST_TIMEOUT_MS",
+                60_000,
+                1_000,
+                300_000,
+            )
+            / 1_000,
+            max_response_bytes=read_integer(
+                environment,
+                "AI_PROVIDER_MAX_RESPONSE_BYTES",
+                2 * 1024 * 1024,
+                1_024,
+                16 * 1024 * 1024,
+            ),
+        )
+
+
+def normalize_base_url(raw: str) -> str:
+    parsed = urlsplit(raw.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("OpenAI-compatible Endpoint 无效")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("OpenAI-compatible Endpoint 不允许凭据、查询串或片段")
+    hostname = parsed.hostname.lower()
+    if hostname in {
+        "169.254.169.254",
+        "metadata.google.internal",
+        "metadata.azure.internal",
+    }:
+        raise ValueError("OpenAI-compatible Endpoint 禁止访问云 metadata")
+    if parsed.scheme == "http" and not private_hostname(hostname):
+        raise ValueError("公网 OpenAI-compatible Endpoint 必须使用 HTTPS")
+    path = parsed.path.rstrip("/")
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def private_hostname(hostname: str) -> bool:
+    if (
+        hostname == "localhost"
+        or hostname.endswith((".localhost", ".internal", ".local"))
+        or "." not in hostname
+    ):
+        return True
+    try:
+        address = ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    return address.is_private or address.is_loopback
+
+
+def read_milliseconds(
+    environment: Mapping[str, str],
+    key: str,
+    default: int,
+    minimum: int,
+    maximum: int,
+) -> int:
+    return read_integer(environment, key, default, minimum, maximum)
+
+
+def read_integer(
+    environment: Mapping[str, str],
+    key: str,
+    default: int,
+    minimum: int,
+    maximum: int,
+) -> int:
+    raw = environment.get(key)
+    try:
+        value = default if raw is None else int(raw)
+    except ValueError as error:
+        raise ValueError(f"{key} 必须是整数") from error
+    if not minimum <= value <= maximum:
+        raise ValueError(f"{key} 超出允许范围")
+    return value

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

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+type JsonValue = (
+    str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
+)
+type RunStatus = Literal[
+    "accepted",
+    "running",
+    "awaiting-approval",
+    "completed",
+    "failed",
+    "cancelled",
+]
+type AgentErrorCode = Literal[
+    "OPERATION_NOT_FOUND",
+    "OPERATION_DISABLED",
+    "INVALID_INPUT",
+    "FORBIDDEN",
+    "LICENSE_NOT_ALLOWED",
+    "RUNTIME_UNAVAILABLE",
+    "MODEL_ROUTE_UNAVAILABLE",
+    "PROVIDER_UNAVAILABLE",
+    "RATE_LIMITED",
+    "BUDGET_EXCEEDED",
+    "TOOL_DENIED",
+    "APPROVAL_REQUIRED",
+    "OUTPUT_VALIDATION_FAILED",
+    "RUN_CONFLICT",
+    "RUN_TIMEOUT",
+    "RUN_CANCELLED",
+    "STREAM_INTERRUPTED",
+]
+
+
+def to_camel(value: str) -> str:
+    first, *rest = value.split("_")
+    return first + "".join(part.capitalize() for part in rest)
+
+
+class CanonicalModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+
+class RuntimeToolDefinition(CanonicalModel):
+    key: str = Field(min_length=1)
+    label: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+
+
+class RuntimeLimits(CanonicalModel):
+    max_duration_seconds: int = Field(default=60, ge=1, le=300)
+    max_output_bytes: int = Field(default=1_048_576, ge=1_024, le=16_777_216)
+
+
+class StartRunRequest(CanonicalModel):
+    operation_key: str = Field(min_length=1)
+    input: JsonValue
+    instructions: str = ""
+    user_prompt: str = ""
+    allowed_tools: list[RuntimeToolDefinition] = Field(default_factory=list)
+    limits: RuntimeLimits = Field(default_factory=RuntimeLimits)
+    execution_grant: str = ""
+    tool_host_url: str = ""
+
+
+class StartRunResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+    events_url: str
+
+
+class RunResultResponse(CanonicalModel):
+    run_id: str
+    status: Literal["completed"]
+    output: JsonValue
+
+
+class CancelRunRequest(CanonicalModel):
+    reason: str | None = None
+
+
+class CancelRunResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+
+
+class AgentError(CanonicalModel):
+    code: AgentErrorCode
+    message: str
+    request_id: str
+    retryable: bool

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

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from .engine import (
+    EngineCompleted,
+    EngineRunRequest,
+    EngineSignal,
+    OutputDelta,
+    UsageReported,
+)
+
+
+class DeterministicEngineAdapter:
+    """Deterministic test adapter. It never calls a model or remote service."""
+
+    operations = frozenset({"test.echo", "test.wait", "test.fail"})
+
+    def __init__(self) -> None:
+        self._cancellations: dict[str, asyncio.Event] = {}
+
+    def supports(self, operation_key: str) -> bool:
+        return operation_key in self.operations
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        cancellation = self._cancellations.setdefault(request.run_id, asyncio.Event())
+        try:
+            if request.operation_key == "test.fail":
+                raise RuntimeError("upstream-secret-body")
+            if request.operation_key == "test.wait":
+                await cancellation.wait()
+                return
+
+            text = "deterministic"
+            if isinstance(request.input, dict):
+                input_text = request.input.get("text")
+                if isinstance(input_text, str):
+                    text = input_text
+            yield OutputDelta(text)
+            yield UsageReported({"source": "unknown"})
+            yield EngineCompleted(request.input)
+        finally:
+            self._cancellations.pop(request.run_id, None)
+
+    async def cancel(self, run_id: str) -> None:
+        cancellation = self._cancellations.get(run_id)
+        if cancellation is not None:
+            cancellation.set()

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

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .contracts import AgentErrorCode, JsonValue, RuntimeLimits, RuntimeToolDefinition
+
+
+@dataclass(frozen=True)
+class EngineRunRequest:
+    run_id: str
+    operation_key: str
+    input: JsonValue
+    instructions: str = ""
+    user_prompt: str = ""
+    allowed_tools: tuple[RuntimeToolDefinition, ...] = ()
+    limits: RuntimeLimits = field(default_factory=RuntimeLimits)
+    execution_grant: str = ""
+    tool_host_url: str = ""
+
+
+@dataclass(frozen=True)
+class OutputDelta:
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolRequested:
+    tool_call_id: str
+    tool_key: str
+
+
+@dataclass(frozen=True)
+class ApprovalRequired:
+    work_item_id: str
+
+
+@dataclass(frozen=True)
+class ToolCompleted:
+    tool_call_id: str
+
+
+@dataclass(frozen=True)
+class UsageReported:
+    usage: dict[str, JsonValue]
+
+
+@dataclass(frozen=True)
+class EngineCompleted:
+    output: JsonValue
+
+
+type EngineSignal = (
+    OutputDelta
+    | ToolRequested
+    | ApprovalRequired
+    | ToolCompleted
+    | UsageReported
+    | EngineCompleted
+)
+
+
+class SafeEngineError(Exception):
+    def __init__(
+        self,
+        code: AgentErrorCode,
+        message: str,
+        *,
+        retryable: bool,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.safe_message = message
+        self.retryable = retryable
+
+
+class AgentEngineAdapter(Protocol):
+    """Internal engine seam. HTTP DTO and ADK types must not cross it."""
+
+    def supports(self, operation_key: str) -> bool: ...
+
+    def execute(self, request: EngineRunRequest) -> AsyncIterator[EngineSignal]: ...
+
+    async def cancel(self, run_id: str) -> None: ...

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

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+
+from .contracts import JsonValue
+from .engine import (
+    AgentEngineAdapter,
+    EngineCompleted,
+    EngineRunRequest,
+    EngineSignal,
+    OutputDelta,
+    SafeEngineError,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
+)
+from .openai_provider import OpenAiCompatibleProvider, ProviderToolCall
+from .tool_host import ToolHostClient, ToolInvocation
+
+
+class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider,
+        tool_host: ToolHostClient,
+    ) -> None:
+        self._provider = provider
+        self._tool_host = tool_host
+        self._cancellations: dict[str, asyncio.Event] = {}
+
+    def supports(self, operation_key: str) -> bool:
+        return bool(operation_key.strip())
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        validate_runtime_request(request)
+        cancellation = self._cancellations.setdefault(
+            request.run_id,
+            asyncio.Event(),
+        )
+        allowed = {tool.key for tool in request.allowed_tools}
+        messages: list[dict[str, JsonValue]] = [
+            {"role": "system", "content": request.instructions},
+            {"role": "user", "content": request.user_prompt},
+        ]
+        output_bytes = 0
+        try:
+            for _round in range(self._provider.config.max_tool_rounds):
+                cancelled(cancellation)
+                turn = await self._provider.complete_turn(
+                    messages,
+                    request.allowed_tools,
+                )
+                if turn.tool_calls:
+                    messages.append(assistant_tool_message(turn.tool_calls))
+                    async for signal in self._execute_tools(
+                        request,
+                        turn.tool_calls,
+                        allowed,
+                        messages,
+                        cancellation,
+                    ):
+                        yield signal
+                    continue
+                for delta in turn.text_deltas:
+                    output_bytes += len(delta.encode())
+                    if output_bytes > request.limits.max_output_bytes:
+                        raise SafeEngineError(
+                            "BUDGET_EXCEEDED",
+                            "Agent 输出超过 Operation 上限",
+                            retryable=False,
+                        )
+                    yield OutputDelta(delta)
+                yield UsageReported(turn.usage or {"source": "unknown"})
+                yield EngineCompleted({"text": turn.text})
+                return
+            raise SafeEngineError(
+                "BUDGET_EXCEEDED",
+                "Agent Tool 调用轮次超过上限",
+                retryable=False,
+            )
+        finally:
+            self._cancellations.pop(request.run_id, None)
+
+    async def _execute_tools(
+        self,
+        request: EngineRunRequest,
+        calls: list[ProviderToolCall],
+        allowed: set[str],
+        messages: list[dict[str, JsonValue]],
+        cancellation: asyncio.Event,
+    ) -> AsyncIterator[EngineSignal]:
+        for call in calls:
+            cancelled(cancellation)
+            if not call.call_id or not call.name or call.name not in allowed:
+                raise SafeEngineError(
+                    "TOOL_DENIED",
+                    "模型请求了未授权 Tool",
+                    retryable=False,
+                )
+            arguments = parse_arguments(call.arguments)
+            yield ToolRequested(call.call_id, call.name)
+            result = await self._tool_host.execute(
+                request.tool_host_url,
+                ToolInvocation(
+                    request.run_id,
+                    call.call_id,
+                    call.name,
+                    arguments,
+                    request.execution_grant,
+                ),
+            )
+            yield ToolCompleted(call.call_id)
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call.call_id,
+                    "content": json.dumps(
+                        result,
+                        ensure_ascii=False,
+                        separators=(",", ":"),
+                    ),
+                }
+            )
+
+    async def cancel(self, run_id: str) -> None:
+        event = self._cancellations.get(run_id)
+        if event is not None:
+            event.set()
+
+    async def health(self) -> None:
+        await self._provider.health()
+
+
+def validate_runtime_request(request: EngineRunRequest) -> None:
+    if (
+        not request.instructions.strip()
+        or not request.user_prompt.strip()
+        or not request.execution_grant.strip()
+        or not request.tool_host_url.strip()
+    ):
+        raise SafeEngineError(
+            "INVALID_INPUT",
+            "Agent Operation 运行计划不完整",
+            retryable=False,
+        )
+
+
+def cancelled(event: asyncio.Event) -> None:
+    if event.is_set():
+        raise SafeEngineError(
+            "RUN_CANCELLED",
+            "Agent Run 已取消",
+            retryable=False,
+        )
+
+
+def parse_arguments(raw: str) -> dict[str, JsonValue]:
+    try:
+        value = json.loads(raw or "{}")
+    except json.JSONDecodeError:
+        raise SafeEngineError(
+            "TOOL_DENIED",
+            "Agent Tool 参数无效",
+            retryable=False,
+        ) from None
+    if not isinstance(value, dict):
+        raise SafeEngineError(
+            "TOOL_DENIED",
+            "Agent Tool 参数必须是对象",
+            retryable=False,
+        )
+    return value
+
+
+def assistant_tool_message(
+    calls: list[ProviderToolCall],
+) -> dict[str, JsonValue]:
+    return {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [
+            {
+                "id": call.call_id,
+                "type": "function",
+                "function": {
+                    "name": call.name,
+                    "arguments": call.arguments,
+                },
+            }
+            for call in calls
+        ],
+    }