create-windy 0.3.2 → 0.3.5

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

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-import hmac
 import os
-import uuid
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from typing import Annotated, cast
 
 from fastapi import FastAPI, Header, Query, Request
@@ -10,30 +10,36 @@ 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 .artifact_input import ArtifactLoader
 from .contracts import (
-    AgentError,
     CancelRunRequest,
     CancelRunResponse,
+    EvaluationResultRequest,
+    EvaluationResultResponse,
+    JsonValue,
     RunResultResponse,
+    RunStatusResponse,
     StartRunRequest,
     StartRunResponse,
 )
-from .engine import AgentEngineAdapter
-from .openai_provider import OpenAiCompatibleProvider
-from .provider_audit import ProviderAuditStore
-from .provider_governance import ProviderRequestGovernance
+from .engine import AgentEngineAdapter, SafeEngineError
+from .http_helpers import (
+    authorized,
+    parse_cursor,
+    provider_governance_snapshot,
+    safe_error,
+)
+from .runtime_factory import default_engine, default_store
 from .service import (
     AgentRunService,
     IdempotencyConflictError,
     OperationNotFoundError,
     RunNotFoundError,
 )
-from .sqlite_store import RunStoreCapacityError, SqliteRunStore
+from .sqlite_store import RunStoreCapacityError
 from .sse import event_stream
-from .store import InMemoryRunStore, RunStore
-from .tool_host import ToolHostClient
+from .store import ReleaseNotFoundError, RunStore
+from .telemetry import configure_telemetry
 
 
 def create_app(
@@ -43,16 +49,44 @@ def create_app(
     internal_token: str | None = None,
     store: RunStore | None = None,
 ) -> FastAPI:
+    configure_telemetry()
     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")
+    runtime = AgentRunService(
+        runtime_engine,
+        store or default_store(),
+        (
+            ArtifactLoader(
+                os.environ.get(
+                    "AI_ARTIFACT_URL",
+                    "http://server:9747/api/internal/ai/artifacts",
+                ),
+                internal_token,
+            )
+            if internal_token
+            else None
+        ),
+    )
+
+    @asynccontextmanager
+    async def lifespan(_application: FastAPI) -> AsyncIterator[None]:
+        await runtime.recover()
+        try:
+            yield
+        finally:
+            await runtime.close()
+
+    application = FastAPI(
+        title="Southwind AI Agent Server",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
 
     @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:
+    async def ready() -> dict[str, object] | JSONResponse:
         health = getattr(runtime_engine, "health", None)
         if not health:
             return safe_error(
@@ -62,8 +96,13 @@ def create_app(
                 True,
             )
         try:
+            await runtime.probe()
             await health()
-            return {"status": "ready"}
+            return {
+                "status": "ready",
+                "capabilities": list(runtime_engine.capabilities),
+                "inputModalities": list(runtime_engine.input_modalities),
+            }
         except Exception:
             return safe_error(
                 503,
@@ -111,6 +150,13 @@ def create_app(
     ) -> JSONResponse:
         return safe_error(409, "RUN_CONFLICT", "幂等键已用于其他请求", False)
 
+    @application.exception_handler(ReleaseNotFoundError)
+    async def release_not_found(
+        _request: Request,
+        _error: ReleaseNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "RUN_CONFLICT", "Agent Release 不存在", False)
+
     @application.exception_handler(RunStoreCapacityError)
     async def run_store_capacity(
         _request: Request,
@@ -123,6 +169,21 @@ def create_app(
             True,
         )
 
+    @application.exception_handler(SafeEngineError)
+    async def safe_engine_error(
+        _request: Request,
+        error: SafeEngineError,
+    ) -> JSONResponse:
+        status = 403 if error.code == "FORBIDDEN" else 503
+        if error.code in {"INVALID_INPUT", "BUDGET_EXCEEDED"}:
+            status = 400
+        return safe_error(
+            status,
+            error.code,
+            error.safe_message,
+            error.retryable,
+        )
+
     @application.exception_handler(ValidationError)
     async def validation_error(
         _request: Request,
@@ -157,6 +218,28 @@ def create_app(
             events_url=f"/api/agent/runs/{record.run_id}/events",
         )
 
+    @application.get(
+        "/api/agent/runs/{run_id}",
+        response_model=RunStatusResponse,
+    )
+    async def get_run_status(
+        run_id: str,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> RunStatusResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.get(run_id)
+        terminal_event = cast(
+            dict[str, JsonValue] | None,
+            record.events[-1] if record.terminal and record.events else None,
+        )
+        return RunStatusResponse(
+            run_id=record.run_id,
+            status=record.status,
+            last_sequence=len(record.events),
+            terminal_event=terminal_event,
+        )
+
     @application.get("/api/agent/runs/{run_id}/events", response_model=None)
     async def get_events(
         run_id: str,
@@ -217,107 +300,29 @@ def create_app(
         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 AdkEngineAdapter(
-        OpenAiCompatibleProvider(
-            config,
-            EnvironmentSecretResolver(os.environ),
-        ),
-        ToolHostClient(internal_token),
-        ProviderRequestGovernance(
-            ProviderAuditStore(
-                required_environment("AI_PROVIDER_AUDIT_STORE_PATH"),
-                retention_days=provider_audit_retention_days(),
-            )
-        ),
-    )
-
-
-def default_store() -> RunStore:
-    path = os.environ.get("AGENT_RUN_STORE_PATH", "").strip()
-    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",
+    @application.post(
+        "/api/agent/evaluations",
+        response_model=EvaluationResultResponse,
     )
-    return {key: value.get(key) for key in allowed}
-
-
-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)
-
+    async def record_evaluation(
+        request: EvaluationResultRequest,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> EvaluationResultResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        evaluation_id = await runtime.record_evaluation(
+            request.release_id,
+            request.evaluation_set_key,
+            request.evaluation_set_version,
+            request.metrics,
+        )
+        return EvaluationResultResponse(
+            evaluation_id=evaluation_id,
+            release_id=request.release_id,
+        )
 
-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),
-    )
+    application.state.run_service = runtime
+    return application
 
 
 app = create_app(internal_token=os.environ.get("AGENT_SERVER_INTERNAL_TOKEN"))

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

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+from collections.abc import Sequence
+from io import BytesIO
+from urllib.parse import urlsplit
+
+import httpx
+from PIL import Image, UnidentifiedImageError
+
+from .config import private_hostname
+from .contracts import RuntimeArtifact, RuntimeLimits
+from .engine import PreparedArtifact, SafeEngineError
+
+_IMAGE_TYPES = frozenset({"image/jpeg", "image/png", "image/webp"})
+
+
+class ArtifactLoader:
+    def __init__(
+        self,
+        artifact_url: str,
+        internal_token: str,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.artifact_url = validate_artifact_url(artifact_url)
+        self.internal_token = internal_token
+        self.transport = transport
+
+    async def prepare(
+        self,
+        artifacts: list[RuntimeArtifact],
+        modalities: Sequence[str],
+        limits: RuntimeLimits,
+    ) -> tuple[PreparedArtifact, ...]:
+        if not artifacts:
+            return ()
+        if (
+            "image" not in modalities
+            or limits.max_artifacts is None
+            or limits.max_pixels_per_artifact is None
+        ):
+            raise invalid("Agent Operation 未授权图片输入")
+        if len(artifacts) > limits.max_artifacts:
+            raise budget("图片数量超过 Operation 上限")
+        declared = sum(item.byte_size for item in artifacts)
+        if declared > limits.max_input_bytes:
+            raise budget("图片总大小超过 Operation 上限")
+        prepared: list[PreparedArtifact] = []
+        total = 0
+        for artifact in artifacts:
+            if artifact.media_type.lower() not in _IMAGE_TYPES:
+                raise invalid("Agent Vision 仅接受 JPEG、PNG 或 WebP")
+            raw = await self._download(artifact, limits.max_input_bytes - total)
+            item = await asyncio.to_thread(
+                sanitize_image,
+                raw,
+                limits.max_pixels_per_artifact,
+            )
+            total += item.byte_size
+            if total > limits.max_input_bytes:
+                raise budget("归一化图片总大小超过 Operation 上限")
+            prepared.append(item)
+        return tuple(prepared)
+
+    async def _download(self, artifact: RuntimeArtifact, remaining: int) -> bytes:
+        body = bytearray()
+        digest = hashlib.sha256()
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(60, connect=5),
+                transport=self.transport,
+            ) as client:
+                async with client.stream(
+                    "GET",
+                    self.artifact_url,
+                    headers={
+                        "authorization": f"Bearer {self.internal_token}",
+                        "x-ai-artifact-ref": artifact.value,
+                    },
+                ) as response:
+                    response.raise_for_status()
+                    if response.headers.get("content-type", "").split(";")[0] != (
+                        artifact.media_type
+                    ):
+                        raise invalid("Artifact MIME 不一致")
+                    async for chunk in response.aiter_bytes():
+                        body.extend(chunk)
+                        digest.update(chunk)
+                        if len(body) > min(artifact.byte_size, remaining):
+                            raise budget("Artifact 内容超过声明上限")
+        except SafeEngineError:
+            raise
+        except Exception as error:
+            raise SafeEngineError(
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 无法读取图片 Artifact",
+                retryable=True,
+            ) from error
+        if len(body) != artifact.byte_size or digest.hexdigest() != artifact.sha256:
+            raise invalid("Artifact 完整性校验失败")
+        return bytes(body)
+
+
+def sanitize_image(raw: bytes, max_pixels: int) -> PreparedArtifact:
+    try:
+        with Image.open(BytesIO(raw)) as source:
+            width, height = source.size
+            if width <= 0 or height <= 0 or width * height > max_pixels:
+                raise budget("图片像素超过 Operation 上限")
+            source.load()
+            normalized = source.convert(
+                "RGBA" if source.has_transparency_data else "RGB"
+            )
+            target = BytesIO()
+            normalized.save(target, format="PNG", optimize=False)
+    except SafeEngineError:
+        raise
+    except (Image.DecompressionBombError, UnidentifiedImageError, OSError):
+        raise invalid("图片内容损坏或格式不受支持") from None
+    body = target.getvalue()
+    digest = hashlib.sha256(body).hexdigest()
+    return PreparedArtifact(
+        media_type="image/png",
+        data_url=f"data:image/png;base64,{base64.b64encode(body).decode()}",
+        byte_size=len(body),
+        sha256=digest,
+    )
+
+
+def validate_artifact_url(raw: str) -> str:
+    parsed = urlsplit(raw.strip())
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+        or not private_hostname(parsed.hostname.lower())
+    ):
+        raise ValueError("Agent Artifact URL 必须是固定本地或内网地址")
+    return raw.rstrip("/")
+
+
+def invalid(message: str) -> SafeEngineError:
+    return SafeEngineError("INVALID_INPUT", message, retryable=False)
+
+
+def budget(message: str) -> SafeEngineError:
+    return SafeEngineError("BUDGET_EXCEEDED", message, retryable=False)

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

@@ -38,6 +38,8 @@ class OpenAiCompatibleConfig:
     max_tool_rounds: int = 8
     https_host_allowlist: tuple[str, ...] = ()
     deployment_key: str = "ai.openai-compatible"
+    capabilities: tuple[str, ...] = ("text-generation",)
+    input_modalities: tuple[str, ...] = ("text",)
 
     def __post_init__(self) -> None:
         normalized = normalize_base_url(self.base_url)
@@ -89,6 +91,16 @@ class OpenAiCompatibleConfig:
                 1_024,
                 16 * 1024 * 1024,
             ),
+            capabilities=read_csv(
+                environment,
+                "AI_PROVIDER_CAPABILITIES",
+                ("text-generation",),
+            ),
+            input_modalities=read_csv(
+                environment,
+                "AI_PROVIDER_INPUT_MODALITIES",
+                ("text",),
+            ),
         )
 
 
@@ -187,3 +199,20 @@ def read_integer(
     if not minimum <= value <= maximum:
         raise ValueError(f"{key} 超出允许范围")
     return value
+
+
+def read_csv(
+    environment: Mapping[str, str],
+    key: str,
+    default: tuple[str, ...],
+) -> tuple[str, ...]:
+    values = tuple(
+        dict.fromkeys(
+            item.strip()
+            for item in environment.get(key, ",".join(default)).split(",")
+            if item.strip()
+        )
+    )
+    if not values or len(values) > 32:
+        raise ValueError(f"{key} 无效")
+    return values

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

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+from math import isfinite
 from typing import Literal, Self
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 type JsonValue = (
     str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
@@ -15,6 +16,7 @@ type RunStatus = Literal[
     "failed",
     "cancelled",
 ]
+type InputModality = Literal["text", "image", "audio", "video", "document"]
 type AgentErrorCode = Literal[
     "OPERATION_NOT_FOUND",
     "OPERATION_DISABLED",
@@ -53,11 +55,17 @@ class RuntimeToolDefinition(CanonicalModel):
     key: str = Field(min_length=1)
     label: str = Field(min_length=1)
     description: str = Field(min_length=1)
+    approval: Literal["none", "required"] = "none"
+    idempotency: Literal["none", "supported", "required"] = "supported"
+    approval_timeout_seconds: int | None = Field(default=None, ge=1, le=604_800)
 
 
 class RuntimeLimits(CanonicalModel):
     max_duration_seconds: int = Field(default=60, ge=1, le=300)
+    max_input_bytes: int = Field(default=1_048_576, ge=1_024, le=67_108_864)
     max_output_bytes: int = Field(default=1_048_576, ge=1_024, le=16_777_216)
+    max_artifacts: int | None = Field(default=None, ge=1, le=16)
+    max_pixels_per_artifact: int | None = Field(default=None, ge=1, le=100_000_000)
 
 
 class ProviderEgress(CanonicalModel):
@@ -78,6 +86,8 @@ type ProviderDataField = Literal[
     "instructions",
     "user-prompt",
     "tool-definitions",
+    "artifact-content",
+    "output-schema",
     "provider-output",
     "tool-results",
 ]
@@ -112,11 +122,49 @@ class ToolNetworkPolicy(CanonicalModel):
     mode: Literal["forbidden"] = "forbidden"
 
 
+class RuntimeArtifact(CanonicalModel):
+    value: str = Field(min_length=1)
+    media_type: str = Field(min_length=1)
+    byte_size: int = Field(ge=1)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+class RuntimeRelease(CanonicalModel):
+    release_id: str = Field(min_length=1, max_length=80)
+    operation_version: str = Field(min_length=1, max_length=80)
+    workflow_version: str = Field(min_length=1, max_length=80)
+    prompt_version: str = Field(min_length=1, max_length=80)
+    route_version: str = Field(min_length=1, max_length=80)
+    tool_schema_version: str = Field(min_length=1, max_length=80)
+    manifest_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+def legacy_release() -> RuntimeRelease:
+    return RuntimeRelease(
+        release_id="legacy",
+        operation_version="legacy",
+        workflow_version="legacy",
+        prompt_version="legacy",
+        route_version="legacy",
+        tool_schema_version="legacy",
+        manifest_digest="0" * 64,
+    )
+
+
 class StartRunRequest(CanonicalModel):
+    kind: Literal["agent"] = "agent"
     operation_key: str = Field(min_length=1)
     input: JsonValue
+    input_modalities: list[InputModality] = Field(
+        default_factory=lambda: default_modalities(),
+        min_length=1,
+    )
+    required_capabilities: list[str] = Field(default_factory=list, max_length=32)
+    artifacts: list[RuntimeArtifact] = Field(default_factory=list, max_length=16)
     instructions: str = ""
     user_prompt: str = ""
+    output_schema_key: str = ""
+    output_schema: dict[str, JsonValue] | None = None
     allowed_tools: list[RuntimeToolDefinition] = Field(default_factory=list)
     limits: RuntimeLimits = Field(default_factory=RuntimeLimits)
     provider_egress: ProviderEgress = Field(default_factory=ProviderEgress)
@@ -124,6 +172,8 @@ class StartRunRequest(CanonicalModel):
     tool_network_policy: ToolNetworkPolicy = Field(default_factory=ToolNetworkPolicy)
     execution_grant: str = ""
     tool_host_url: str = ""
+    release: RuntimeRelease = Field(default_factory=legacy_release)
+    trace_id: str = Field(default="", max_length=160)
 
 
 class StartRunResponse(CanonicalModel):
@@ -132,6 +182,13 @@ class StartRunResponse(CanonicalModel):
     events_url: str
 
 
+class RunStatusResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+    last_sequence: int = Field(ge=0)
+    terminal_event: dict[str, JsonValue] | None = None
+
+
 class RunResultResponse(CanonicalModel):
     run_id: str
     status: Literal["completed"]
@@ -152,3 +209,26 @@ class AgentError(CanonicalModel):
     message: str
     request_id: str
     retryable: bool
+
+
+class EvaluationResultRequest(CanonicalModel):
+    release_id: str = Field(min_length=1, max_length=80)
+    evaluation_set_key: str = Field(min_length=1, max_length=160)
+    evaluation_set_version: str = Field(min_length=1, max_length=80)
+    metrics: dict[str, float] = Field(min_length=1, max_length=100)
+
+    @field_validator("metrics")
+    @classmethod
+    def validate_metrics(cls, metrics: dict[str, float]) -> dict[str, float]:
+        if not all(isfinite(value) for value in metrics.values()):
+            raise ValueError("评估指标必须是有限数值")
+        return metrics
+
+
+class EvaluationResultResponse(CanonicalModel):
+    evaluation_id: str
+    release_id: str
+
+
+def default_modalities() -> list[InputModality]:
+    return ["text"]

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

@@ -20,6 +20,14 @@ class DeterministicEngineAdapter:
     def __init__(self) -> None:
         self._cancellations: dict[str, asyncio.Event] = {}
 
+    @property
+    def capabilities(self) -> tuple[str, ...]:
+        return ("text-generation",)
+
+    @property
+    def input_modalities(self) -> tuple[str, ...]:
+        return ("text",)
+
     def supports(self, operation_key: str) -> bool:
         return operation_key in self.operations