create-windy 0.2.20 → 0.2.22

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

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hmac
+import os
+import uuid
+from typing import Annotated
+
+from fastapi import FastAPI, Header, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import ValidationError
+
+from .adk_adapter import AdkEngineAdapter
+from .config import EnvironmentSecretResolver, OpenAiCompatibleConfig
+from .contracts import (
+    AgentError,
+    CancelRunRequest,
+    CancelRunResponse,
+    RunResultResponse,
+    StartRunRequest,
+    StartRunResponse,
+)
+from .engine import AgentEngineAdapter
+from .openai_engine import OpenAiCompatibleEngineAdapter
+from .openai_provider import OpenAiCompatibleProvider
+from .service import (
+    AgentRunService,
+    IdempotencyConflictError,
+    OperationNotFoundError,
+    RunNotFoundError,
+)
+from .sqlite_store import RunStoreCapacityError, SqliteRunStore
+from .sse import event_stream
+from .store import InMemoryRunStore, RunStore
+from .tool_host import ToolHostClient
+
+
+def create_app(
+    engine: AgentEngineAdapter | None = None,
+    *,
+    heartbeat_seconds: float = 15.0,
+    internal_token: str | None = None,
+    store: RunStore | None = None,
+) -> FastAPI:
+    runtime_engine = engine or default_engine()
+    runtime = AgentRunService(runtime_engine, store or default_store())
+    application = FastAPI(title="Southwind AI Agent Server", version="0.1.0")
+
+    @application.get("/health/live")
+    async def live() -> dict[str, str]:
+        return {"status": "live"}
+
+    @application.get("/health/ready", response_model=None)
+    async def ready() -> dict[str, str] | JSONResponse:
+        health = getattr(runtime_engine, "health", None)
+        if not health:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 尚未配置",
+                True,
+            )
+        try:
+            await health()
+            return {"status": "ready"}
+        except Exception:
+            return safe_error(
+                503,
+                "PROVIDER_UNAVAILABLE",
+                "模型服务暂不可用",
+                True,
+            )
+
+    @application.exception_handler(OperationNotFoundError)
+    async def operation_not_found(
+        _request: Request,
+        _error: OperationNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "OPERATION_NOT_FOUND", "Agent Operation 不存在", False)
+
+    @application.exception_handler(RunNotFoundError)
+    async def run_not_found(
+        _request: Request,
+        _error: RunNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "RUN_CONFLICT", "Agent Run 不存在", False)
+
+    @application.exception_handler(IdempotencyConflictError)
+    async def idempotency_conflict(
+        _request: Request,
+        _error: IdempotencyConflictError,
+    ) -> JSONResponse:
+        return safe_error(409, "RUN_CONFLICT", "幂等键已用于其他请求", False)
+
+    @application.exception_handler(RunStoreCapacityError)
+    async def run_store_capacity(
+        _request: Request,
+        _error: RunStoreCapacityError,
+    ) -> JSONResponse:
+        return safe_error(
+            429,
+            "BUDGET_EXCEEDED",
+            "Agent Run 存储容量已满",
+            True,
+        )
+
+    @application.exception_handler(ValidationError)
+    async def validation_error(
+        _request: Request,
+        _error: ValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.exception_handler(RequestValidationError)
+    async def request_validation_error(
+        _request: Request,
+        _error: RequestValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.post("/api/agent/runs", response_model=StartRunResponse)
+    async def start_run(
+        request: StartRunRequest,
+        idempotency_key: Annotated[str, Header(alias="Idempotency-Key")],
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StartRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        if not idempotency_key.strip():
+            return safe_error(400, "INVALID_INPUT", "幂等键不能为空", False)
+        record = await runtime.start(
+            request,
+            idempotency_key,
+        )
+        return StartRunResponse(
+            run_id=record.run_id,
+            status=record.status,
+            events_url=f"/api/agent/runs/{record.run_id}/events",
+        )
+
+    @application.get("/api/agent/runs/{run_id}/events", response_model=None)
+    async def get_events(
+        run_id: str,
+        after: Annotated[int | None, Query(ge=0)] = None,
+        last_event_id: Annotated[str | None, Header(alias="Last-Event-ID")] = None,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StreamingResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        await runtime.get(run_id)
+        try:
+            cursor = parse_cursor(after, last_event_id)
+        except ValueError:
+            return safe_error(400, "INVALID_INPUT", "事件游标无效", False)
+        return StreamingResponse(
+            event_stream(runtime, run_id, cursor, heartbeat_seconds),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @application.get(
+        "/api/agent/runs/{run_id}/result",
+        response_model=RunResultResponse,
+    )
+    async def get_result(
+        run_id: str,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> RunResultResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.get(run_id)
+        if record.status == "completed":
+            return RunResultResponse(
+                run_id=record.run_id,
+                status="completed",
+                output=record.output,
+            )
+        if record.status == "cancelled":
+            return safe_error(409, "RUN_CANCELLED", "Agent Run 已取消", False)
+        if record.status == "failed":
+            return safe_error(409, "RUNTIME_UNAVAILABLE", "Agent Run 执行失败", True)
+        return safe_error(409, "RUN_CONFLICT", "Agent Run 尚未完成", True)
+
+    @application.post(
+        "/api/agent/runs/{run_id}/cancel",
+        response_model=CancelRunResponse,
+    )
+    async def cancel_run(
+        run_id: str,
+        _request: CancelRunRequest,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> CancelRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.cancel(run_id)
+        return CancelRunResponse(run_id=record.run_id, status=record.status)
+
+    application.state.run_service = runtime
+    return application
+
+
+def default_engine() -> AgentEngineAdapter:
+    config = OpenAiCompatibleConfig.from_environment()
+    if config is None:
+        return AdkEngineAdapter()
+    internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
+    if not internal_token:
+        raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
+    return OpenAiCompatibleEngineAdapter(
+        OpenAiCompatibleProvider(
+            config,
+            EnvironmentSecretResolver(os.environ),
+        ),
+        ToolHostClient(internal_token),
+    )
+
+
+def default_store() -> RunStore:
+    path = os.environ.get("AGENT_RUN_STORE_PATH", "").strip()
+    return SqliteRunStore(path) if path else InMemoryRunStore()
+
+
+def authorized(provided: str | None, expected: str | None) -> bool:
+    if expected is None:
+        return True
+    if not expected or not provided or not provided.startswith("Bearer "):
+        return False
+    return hmac.compare_digest(provided.removeprefix("Bearer "), expected)
+
+
+def parse_cursor(after: int | None, last_event_id: str | None) -> int:
+    header_cursor = 0
+    if last_event_id is not None:
+        if not last_event_id.isdigit():
+            raise ValueError
+        header_cursor = int(last_event_id)
+    return max(after or 0, header_cursor)
+
+
+def safe_error(
+    status_code: int,
+    code: str,
+    message: str,
+    retryable: bool,
+) -> JSONResponse:
+    error = AgentError.model_validate(
+        {
+            "code": code,
+            "message": message,
+            "requestId": f"request_{uuid.uuid4().hex}",
+            "retryable": retryable,
+        }
+    )
+    return JSONResponse(
+        status_code=status_code,
+        content=error.model_dump(by_alias=True),
+    )
+
+
+app = create_app(internal_token=os.environ.get("AGENT_SERVER_INTERNAL_TOKEN"))

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: ...