create-windy 0.5.2 → 0.6.1

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

@@ -10,7 +10,6 @@ from .contracts import StartRunRequest
 from .engine import (
     AgentEngineAdapter,
     EngineCompleted,
-    EngineRunRequest,
     SafeEngineError,
 )
 from .fingerprint import request_fingerprint, resolved_release
@@ -22,19 +21,19 @@ from .report_lifecycle import (
     sync_terminal_from_canonical,
 )
 from .report_store import AgentRuntimeReportStore
+from .run_admission import RunAdmission
+from .run_capacity import RunCapacity, RunCapacityReservation
+from .service_errors import OperationNotFoundError, RunNotFoundError
+from .service_execution import build_engine_run_request
+from .service_tasks import complete_task, renew_lease, run_admitted
 from .signal_events import canonical_failure_fields, canonical_signal_event
 from .store import RunRecord, RunStore
 from .telemetry import AgentRunTrace
+from .vision_requirement import require_vision_readiness
 
 logger = logging.getLogger(__name__)
 
 
-class RunNotFoundError(Exception): ...
-
-
-class OperationNotFoundError(Exception): ...
-
-
 class AgentRunService:
     def __init__(
         self,
@@ -42,6 +41,8 @@ class AgentRunService:
         store: RunStore,
         report_store: AgentRuntimeReportStore,
         artifact_loader: ArtifactLoader | None = None,
+        max_concurrent_runs: int = 1,
+        max_queue_depth: int = 0,
     ) -> None:
         self.engine = engine
         self.store = store
@@ -50,6 +51,10 @@ class AgentRunService:
         self._tasks: set[asyncio.Task[None]] = set()
         self._active_run_ids: set[str] = set()
         self._recovery_task: asyncio.Task[None] | None = None
+        self._admission = RunAdmission(
+            store,
+            RunCapacity(max_concurrent_runs, max_queue_depth),
+        )
 
     async def start(
         self,
@@ -76,13 +81,14 @@ class AgentRunService:
             release=resolved_release(request),
             trace_id=request.trace_id,
         )
-        record, created = await self.store.create_or_get(
+        admission = await self._admission.admit(
             candidate,
             request.model_dump(by_alias=True),
         )
+        record = admission.record
         await ensure_run_report_safely(self.report_store, record.run_id, request)
-        if created:
-            self._spawn(record, request)
+        if admission.reservation:
+            await self._spawn(record, request, admission.reservation)
         return record
 
     async def recover(self) -> None:
@@ -108,14 +114,18 @@ class AgentRunService:
             if record.run_id in self._active_run_ids:
                 continue
             request = StartRunRequest.model_validate(raw)
+            reservation = await self._admission.reserve_recovery()
+            if not reservation:
+                return
             await ensure_run_report_safely(
                 self.report_store,
                 record.run_id,
                 request,
             )
-            self._spawn(
+            await self._spawn(
                 record,
                 request,
+                reservation,
                 resumed=True,
             )
 
@@ -175,7 +185,7 @@ class AgentRunService:
         execution_task = asyncio.current_task()
         if execution_task is None:
             raise RuntimeError("Agent Run 缺少执行任务")
-        lease_task = asyncio.create_task(self._renew_lease(record.run_id))
+        lease_task = asyncio.create_task(renew_lease(self.store, record.run_id))
         run_trace = AgentRunTrace(record)
         run_trace.start()
         final_status = "unknown"
@@ -183,6 +193,10 @@ class AgentRunService:
             lambda completed: cancel_on_lease_loss(completed, execution_task)
         )
         try:
+            await asyncio.wait_for(
+                require_vision_readiness(self.engine, invocation),
+                timeout=invocation.limits.max_duration_seconds,
+            )
             await start_run_report_safely(self.report_store, record.run_id)
             if await append_and_sync_canonical_event(
                 self.report_store,
@@ -206,25 +220,7 @@ class AgentRunService:
                 if self.artifact_loader
                 else ()
             )
-            request = EngineRunRequest(
-                run_id=record.run_id,
-                operation_key=record.operation_key,
-                input=invocation.input,
-                input_modalities=tuple(invocation.input_modalities),
-                required_capabilities=tuple(invocation.required_capabilities),
-                artifacts=prepared,
-                instructions=invocation.instructions,
-                user_prompt=invocation.user_prompt,
-                output_schema_key=invocation.output_schema_key,
-                output_schema=invocation.output_schema,
-                allowed_tools=tuple(invocation.allowed_tools),
-                limits=invocation.limits,
-                provider_egress=invocation.provider_egress,
-                provider_data_policy=invocation.provider_data_policy,
-                tool_network_policy=invocation.tool_network_policy,
-                execution_grant=invocation.execution_grant,
-                tool_host_url=invocation.tool_host_url,
-            )
+            request = build_engine_run_request(record, invocation, prepared)
             approval_timeout = max(
                 (
                     tool.approval_timeout_seconds or 0
@@ -315,30 +311,33 @@ class AgentRunService:
             finally:
                 run_trace.finish(final_status)
 
-    def _spawn(
+    async def _spawn(
         self,
         record: RunRecord,
         request: StartRunRequest,
+        reservation: RunCapacityReservation,
         resumed: bool = False,
     ) -> None:
         if record.run_id in self._active_run_ids:
+            await reservation.release()
             return
         self._active_run_ids.add(record.run_id)
-        task = asyncio.create_task(self._execute(record, request, resumed))
+        task = asyncio.create_task(
+            run_admitted(
+                reservation,
+                lambda: self._execute(record, request, resumed),
+            )
+        )
         self._tasks.add(task)
         task.add_done_callback(
-            lambda completed: self._completed(record.run_id, completed)
+            lambda completed: complete_task(
+                self._tasks,
+                self._active_run_ids,
+                record.run_id,
+                completed,
+            )
         )
 
-    async def _renew_lease(self, run_id: str) -> None:
-        while True:
-            await asyncio.sleep(10)
-            await self.store.renew_lease(run_id)
-
-    def _completed(self, run_id: str, task: asyncio.Task[None]) -> None:
-        self._tasks.discard(task)
-        self._active_run_ids.discard(run_id)
-
     async def _fail(self, run_id: str, failure: SafeEngineError) -> None:
         await append_and_sync_canonical_event(
             self.report_store,

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

@@ -0,0 +1,4 @@
+class RunNotFoundError(Exception): ...
+
+
+class OperationNotFoundError(Exception): ...

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

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .contracts import StartRunRequest
+from .engine import EngineRunRequest, PreparedArtifact
+from .store import RunRecord
+
+
+def build_engine_run_request(
+    record: RunRecord,
+    invocation: StartRunRequest,
+    artifacts: tuple[PreparedArtifact, ...],
+) -> EngineRunRequest:
+    return EngineRunRequest(
+        run_id=record.run_id,
+        operation_key=record.operation_key,
+        input=invocation.input,
+        input_modalities=tuple(invocation.input_modalities),
+        required_capabilities=tuple(invocation.required_capabilities),
+        artifacts=artifacts,
+        instructions=invocation.instructions,
+        user_prompt=invocation.user_prompt,
+        output_schema_key=invocation.output_schema_key,
+        output_schema=invocation.output_schema,
+        allowed_tools=tuple(invocation.allowed_tools),
+        limits=invocation.limits,
+        provider_egress=invocation.provider_egress,
+        provider_data_policy=invocation.provider_data_policy,
+        tool_network_policy=invocation.tool_network_policy,
+        execution_grant=invocation.execution_grant,
+        tool_host_url=invocation.tool_host_url,
+    )

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

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from .run_capacity import RunCapacityReservation
+from .store import RunStore
+
+
+async def renew_lease(store: RunStore, run_id: str) -> None:
+    while True:
+        await asyncio.sleep(10)
+        await store.renew_lease(run_id)
+
+
+def complete_task(
+    tasks: set[asyncio.Task[None]],
+    active_run_ids: set[str],
+    run_id: str,
+    task: asyncio.Task[None],
+) -> None:
+    tasks.discard(task)
+    active_run_ids.discard(run_id)
+
+
+async def run_admitted(
+    reservation: RunCapacityReservation,
+    execute: Callable[[], Awaitable[None]],
+) -> None:
+    try:
+        await reservation.enter()
+        await execute()
+    finally:
+        await reservation.release()

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

@@ -16,6 +16,14 @@ class SqliteCatalogMixin:
     _condition: asyncio.Condition
     _cipher: RunStoreCipher
 
+    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None:
+        async with self._condition:
+            row = self._database.execute(
+                "select run_id from agent_runs where idempotency_key = ?",
+                (idempotency_key,),
+            ).fetchone()
+            return self._read(str(row["run_id"])) if row else None
+
     async def save_invocation(self, run_id: str, value: JsonValue) -> None:
         async with self._condition:
             updated = self._database.execute(
@@ -105,3 +113,6 @@ class SqliteCatalogMixin:
             """,
             (release_id, record.operation_key, encoded, time.time()),
         )
+
+    def _read(self, run_id: str) -> RunRecord | None:
+        raise NotImplementedError

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

@@ -42,6 +42,7 @@ class RunStore(Protocol):
         record: RunRecord,
         invocation: JsonValue = None,
     ) -> tuple[RunRecord, bool]: ...
+    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None: ...
     async def get(self, run_id: str) -> RunRecord | None: ...
     async def append(
         self,
@@ -112,6 +113,11 @@ class InMemoryRunStore:
         async with self._condition:
             return self._runs.get(run_id)
 
+    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None:
+        async with self._condition:
+            run_id = self._idempotency.get(idempotency_key)
+            return self._runs.get(run_id) if run_id else None
+
     async def append(
         self,
         run_id: str,

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

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Protocol
+
+from .config import OpenAiCompatibleConfig
+from .contracts import JsonValue, RuntimeToolDefinition
+from .engine import SafeEngineError
+
+_PROBE_IMAGE = (
+    "data:image/png;base64,"
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/"
+    "pLvAAAAAElFTkSuQmCC"
+)
+_PROBE_PROMPT = '观察图片的主色。只返回 JSON：{\\"color\\":\\"red\\"}。'
+
+
+class ProbeTurn(Protocol):
+    @property
+    def text(self) -> str: ...
+
+    @property
+    def reported_model(self) -> str | None: ...
+
+
+class VisionProbeClient(Protocol):
+    config: OpenAiCompatibleConfig
+
+    def complete_turn(
+        self,
+        messages: list[dict[str, JsonValue]],
+        tools: tuple[RuntimeToolDefinition, ...],
+        output_schema_key: str = "",
+        output_schema: dict[str, JsonValue] | None = None,
+    ) -> Awaitable[ProbeTurn]: ...
+
+
+async def probe_vision(client: VisionProbeClient) -> None:
+    """Exercises the configured VLM with a bounded synthetic image."""
+    if not {"text-generation", "vision"}.issubset(client.config.capabilities) or not {
+        "text",
+        "image",
+    }.issubset(client.config.input_modalities):
+        raise SafeEngineError(
+            "RUNTIME_UNAVAILABLE",
+            "VLM 输入能力尚未配置",
+            retryable=False,
+        )
+    turn = await client.complete_turn(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": _PROBE_PROMPT},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": _PROBE_IMAGE, "detail": "low"},
+                    },
+                ],
+            }
+        ],
+        (),
+        "windy.vlm-readiness.v1",
+        {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {"color": {"type": "string", "const": "red"}},
+            "required": ["color"],
+        },
+    )
+    try:
+        value = json.loads(turn.text)
+    except (TypeError, json.JSONDecodeError):
+        value = None
+    if value != {"color": "red"}:
+        raise SafeEngineError(
+            "PROVIDER_UNAVAILABLE",
+            "VLM 合成图片探测未通过",
+            retryable=False,
+        )
+    if turn.reported_model != client.config.model:
+        raise SafeEngineError(
+            "PROVIDER_UNAVAILABLE",
+            "VLM 合成图片探测的模型版本不匹配",
+            retryable=False,
+        )

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

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from .contracts import StartRunRequest
+from .engine import SafeEngineError
+from .readiness_pin import readiness_pin_matches
+
+
+def requires_vision_readiness(request: StartRunRequest) -> bool:
+    return (
+        "vision" in request.required_capabilities or "image" in request.input_modalities
+    )
+
+
+async def require_vision_readiness(
+    engine: object,
+    request: StartRunRequest,
+) -> None:
+    """Fail closed immediately before every vision provider execution."""
+    if not requires_vision_readiness(request):
+        return
+    if not request.readiness_pin or not await readiness_pin_matches(
+        engine, request.readiness_pin.model_dump(by_alias=True)
+    ):
+        raise SafeEngineError(
+            "RUNTIME_UNAVAILABLE",
+            "VLM Runtime 当前不可用",
+            retryable=True,
+        )

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

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime, timedelta
+from typing import Protocol, cast
+
+from .config import OpenAiCompatibleConfig
+from .engine import SafeEngineError
+
+_DEPLOYMENT_IDENTITY = re.compile(
+    r"^windy-deployment-v1_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-"
+    r"[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
+
+
+class VisionProbeProvider(Protocol):
+    def probe_vision(self) -> Awaitable[None]: ...
+
+
+class VlmReadinessProbe:
+    """Produces a V1 Agent/VLM snapshot only after bounded image inference."""
+
+    def __init__(
+        self,
+        config: OpenAiCompatibleConfig,
+        provider: VisionProbeProvider,
+        *,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.config = config
+        self.provider = provider
+        self.wall_clock = wall_clock
+        self.monotonic_clock = monotonic_clock
+
+    async def inspect(self) -> dict[str, object]:
+        checked_at = self._now()
+        if not self._configured():
+            return self._not_configured(checked_at)
+        started = self.monotonic_clock()
+        try:
+            await self.provider.probe_vision()
+        except SafeEngineError as error:
+            return self._failed(
+                checked_at,
+                started,
+                "RESOURCE_UNAVAILABLE" if error.retryable else "UNHEALTHY",
+                error.retryable,
+            )
+        except Exception:
+            return self._failed(checked_at, started, "CONNECTION_FAILED", True)
+        observed_at = self._now()
+        valid_until = checked_at + timedelta(seconds=self.config.readiness_ttl_seconds)
+        if observed_at >= valid_until:
+            return self._failed(checked_at, started, "TIMEOUT", True)
+        offers = self._offers()
+        deployment = self._deployment(offers)
+        return {
+            "schemaVersion": 1,
+            "status": "ready",
+            "configured": True,
+            "runtimeKind": "agent",
+            "observedAt": _time(observed_at),
+            "downstreamProbe": {
+                "status": "passed",
+                "checkedAt": _time(checked_at),
+                "validUntil": _time(valid_until),
+                "latencyMs": _latency(started, self.monotonic_clock),
+                "deploymentIdentity": deployment["identity"],
+                "releaseDigest": deployment["releaseDigest"],
+                "offersDigest": deployment["offersDigest"],
+            },
+            "deployment": deployment,
+            "offers": offers,
+            "unavailableReasons": [],
+        }
+
+    def _configured(self) -> bool:
+        return (
+            {"text-generation", "vision"}.issubset(self.config.capabilities)
+            and {"text", "image"}.issubset(self.config.input_modalities)
+            and bool(
+                self.config.readiness_deployment_identity
+                and _DEPLOYMENT_IDENTITY.fullmatch(
+                    self.config.readiness_deployment_identity
+                )
+            )
+            and _valid_digest(self.config.readiness_release_digest)
+        )
+
+    def _offers(self) -> list[dict[str, object]]:
+        return [
+            {
+                "variant": "vision",
+                "capabilities": ["text-generation", "vision"],
+                "inputModalities": ["text", "image"],
+                "outputModalities": ["text"],
+                "limits": {
+                    "maxDurationSeconds": self.config.max_duration_seconds,
+                    "maxInputBytes": self.config.max_input_bytes,
+                    "maxOutputBytes": self.config.max_response_bytes,
+                    "maxArtifacts": self.config.max_artifacts,
+                    "maxPixelsPerArtifact": self.config.max_pixels_per_artifact,
+                    "maxConcurrentRuns": self.config.max_concurrent_runs,
+                    "maxQueueDepth": self.config.max_queue_depth,
+                },
+            }
+        ]
+
+    def _deployment(self, offers: list[dict[str, object]]) -> dict[str, str]:
+        return {
+            "key": self.config.deployment_key,
+            "identity": self.config.readiness_deployment_identity or "",
+            "releaseDigest": self.config.readiness_release_digest or "",
+            "offersDigest": offers_digest(offers),
+        }
+
+    def _not_configured(self, observed_at: datetime) -> dict[str, object]:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": False,
+            "runtimeKind": "agent",
+            "observedAt": _time(observed_at),
+            "downstreamProbe": {"status": "not-run", "reason": "NOT_CONFIGURED"},
+            "deployment": None,
+            "offers": [],
+            "unavailableReasons": [
+                {"code": "RUNTIME_NOT_CONFIGURED", "retryable": False}
+            ],
+        }
+
+    def _failed(
+        self, checked_at: datetime, started: float, code: str, retryable: bool
+    ) -> dict[str, object]:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": True,
+            "runtimeKind": "agent",
+            "observedAt": _time(self._now()),
+            "downstreamProbe": {
+                "status": "failed",
+                "checkedAt": _time(checked_at),
+                "latencyMs": _latency(started, self.monotonic_clock),
+                "failureCode": code,
+                "retryable": retryable,
+            },
+            "deployment": self._deployment(self._offers()),
+            "offers": [],
+            "unavailableReasons": [
+                {
+                    "code": "DOWNSTREAM_PROBE_FAILED",
+                    "retryable": retryable,
+                    "subject": code,
+                }
+            ],
+        }
+
+    def _now(self) -> datetime:
+        return self.wall_clock().astimezone(UTC)
+
+
+def _valid_digest(value: str | None) -> bool:
+    return bool(value and len(value) == 71 and value.startswith("sha256:")) and all(
+        char in "0123456789abcdef" for char in (value or "")[7:]
+    )
+
+
+def offers_digest(offers: list[dict[str, object]]) -> str:
+    canonical = sorted(
+        (
+            {
+                "variant": offer["variant"],
+                "capabilities": sorted(cast(list[str], offer["capabilities"])),
+                "inputModalities": sorted(cast(list[str], offer["inputModalities"])),
+                "outputModalities": sorted(cast(list[str], offer["outputModalities"])),
+                "limits": offer["limits"],
+            }
+            for offer in offers
+        ),
+        key=lambda offer: str(offer["variant"]),
+    )
+    body = json.dumps(canonical, ensure_ascii=False, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(body.encode()).hexdigest()
+
+
+def unavailable_vlm_snapshot(
+    *,
+    configured: bool,
+    failure_code: str | None = None,
+    retryable: bool = True,
+) -> dict[str, object]:
+    """Build the public V1 fallback used when the VLM adapter itself faults."""
+    observed_at = _time(datetime.now(UTC))
+    if not configured:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": False,
+            "runtimeKind": "agent",
+            "observedAt": observed_at,
+            "downstreamProbe": {"status": "not-run", "reason": "NOT_CONFIGURED"},
+            "deployment": None,
+            "offers": [],
+            "unavailableReasons": [
+                {"code": "RUNTIME_NOT_CONFIGURED", "retryable": False}
+            ],
+        }
+    code = failure_code or "CONNECTION_FAILED"
+    return {
+        "schemaVersion": 1,
+        "status": "unavailable",
+        "configured": True,
+        "runtimeKind": "agent",
+        "observedAt": observed_at,
+        "downstreamProbe": {
+            "status": "failed",
+            "checkedAt": observed_at,
+            "latencyMs": 0,
+            "failureCode": code,
+            "retryable": retryable,
+        },
+        "deployment": None,
+        "offers": [],
+        "unavailableReasons": [
+            {
+                "code": "DOWNSTREAM_PROBE_FAILED",
+                "retryable": retryable,
+                "subject": code,
+            }
+        ],
+    }
+
+
+def _time(value: datetime) -> str:
+    return (
+        value.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    )
+
+
+def _latency(started: float, clock: Callable[[], float]) -> int:
+    return max(0, int((clock() - started) * 1_000))