create-windy 0.6.12 → 0.6.14

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

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .contracts import JsonValue, LongSessionContext
+
+
+@dataclass(frozen=True)
+class PreparedSource:
+    module_key: str
+    kind: str
+    id: str
+    version: str
+    sequence: int
+    digest: str
+    validity: dict[str, JsonValue]
+    content: JsonValue
+    role: str
+
+    def reference(self) -> dict[str, JsonValue]:
+        return {
+            "moduleKey": self.module_key,
+            "kind": self.kind,
+            "id": self.id,
+            "version": self.version,
+            "sequence": self.sequence,
+            "digest": self.digest,
+            "validity": self.validity,
+        }
+
+
+@dataclass(frozen=True)
+class PreparedContext:
+    preparation_id: str
+    sources: tuple[PreparedSource, ...]
+
+
+@dataclass(frozen=True)
+class CommittedContext:
+    context_version_id: str
+    digest: str
+
+
+class ContextVersionPort(Protocol):
+    async def prepare(
+        self,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+    ) -> PreparedContext: ...
+
+    async def commit(
+        self,
+        preparation: PreparedContext,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+        governed_envelope: dict[str, JsonValue],
+    ) -> CommittedContext: ...
+
+    async def abort(
+        self,
+        preparation: PreparedContext,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+    ) -> None: ...

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

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from .context_message_digest import message_content_digest
+from .context_version_contracts import (
+    CommittedContext,
+    ContextVersionPort,
+    PreparedContext,
+    PreparedSource,
+)
+from .contracts import JsonValue, LongSessionContext
+from .engine import SafeEngineError
+
+__all__ = [
+    "CommittedContext",
+    "ContextVersionPort",
+    "HttpContextVersionPort",
+    "PreparedContext",
+    "PreparedSource",
+    "UnavailableContextVersionPort",
+    "context_unavailable",
+]
+
+
+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 _Validity(_CanonicalModel):
+    status: str
+    checked_at: str
+    expires_at: str | None = None
+    reason: str | None = None
+
+
+class _ResolvedReference(_CanonicalModel):
+    module_key: str = Field(min_length=1)
+    kind: str = Field(min_length=1)
+    id: str = Field(min_length=1)
+    version: str = Field(min_length=1)
+    sequence: int = Field(ge=1)
+    digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+    validity: _Validity
+
+
+class _PreparedSource(_CanonicalModel):
+    reference: _ResolvedReference
+    content: JsonValue
+    role: Literal["system", "user", "assistant", "tool"] = "system"
+
+
+class _PrepareResponse(_CanonicalModel):
+    preparation_id: str = Field(min_length=1, max_length=160)
+    sources: list[_PreparedSource] = Field(min_length=1, max_length=128)
+
+
+class _CommitResponse(_CanonicalModel):
+    context_version_id: str = Field(min_length=1)
+    digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+    status: Literal["active"]
+    provider_request_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+class _AbortResponse(_CanonicalModel):
+    status: Literal["aborted", "absent"]
+
+
+class HttpContextVersionPort:
+    """Two-phase, fail-closed callback to the authoritative Context Builder."""
+
+    def __init__(
+        self, base_url: str, internal_token: str, *, timeout_seconds: float = 10
+    ) -> None:
+        self._url = _endpoint(base_url)
+        self._token = internal_token
+        self._timeout = timeout_seconds
+
+    async def prepare(
+        self,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+    ) -> PreparedContext:
+        request = _base_request(binding, run_id, model_attempt_id, authorization_grant)
+        request.update({"contractVersion": 2, "phase": "prepare"})
+        try:
+            response = _PrepareResponse.model_validate_json(await self._post(request))
+            return _validated_preparation(binding, response)
+        except SafeEngineError:
+            raise
+        except Exception as error:
+            raise _unavailable() from error
+
+    async def commit(
+        self,
+        preparation: PreparedContext,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+        governed_envelope: dict[str, JsonValue],
+    ) -> CommittedContext:
+        request = _base_request(binding, run_id, model_attempt_id, authorization_grant)
+        request.update(
+            {
+                "contractVersion": 2,
+                "phase": "commit",
+                "preparationId": preparation.preparation_id,
+                "governedEnvelope": governed_envelope,
+            }
+        )
+        try:
+            response = _CommitResponse.model_validate_json(await self._post(request))
+            provider = governed_envelope.get("provider")
+            expected = (
+                provider.get("requestDigest") if isinstance(provider, dict) else None
+            )
+            if response.provider_request_digest != expected:
+                raise _unavailable()
+            return CommittedContext(response.context_version_id, response.digest)
+        except SafeEngineError:
+            raise
+        except Exception as error:
+            raise _unavailable() from error
+
+    async def abort(
+        self,
+        preparation: PreparedContext,
+        binding: LongSessionContext,
+        run_id: str,
+        model_attempt_id: str,
+        authorization_grant: str,
+    ) -> None:
+        request = _base_request(binding, run_id, model_attempt_id, authorization_grant)
+        request.update(
+            {
+                "contractVersion": 2,
+                "phase": "abort",
+                "preparationId": preparation.preparation_id,
+            }
+        )
+        try:
+            _AbortResponse.model_validate_json(await self._post(request))
+        except Exception as error:
+            raise _unavailable() from error
+
+    async def _post(self, request: dict[str, object]) -> bytes:
+        content = bytearray()
+        async with httpx.AsyncClient(
+            timeout=self._timeout, follow_redirects=False
+        ) as client:
+            async with client.stream(
+                "POST",
+                self._url,
+                headers={
+                    "authorization": f"Bearer {self._token}",
+                    "content-type": "application/json",
+                },
+                json=request,
+            ) as response:
+                if response.status_code != 200:
+                    raise _unavailable()
+                async for chunk in response.aiter_bytes():
+                    content.extend(chunk)
+                    if len(content) > 2 * 1_024 * 1_024:
+                        raise _unavailable()
+        return bytes(content)
+
+
+class UnavailableContextVersionPort:
+    async def prepare(self, *args: object) -> PreparedContext:
+        del args
+        raise _unavailable()
+
+    async def commit(self, *args: object) -> CommittedContext:
+        del args
+        raise _unavailable()
+
+    async def abort(self, *args: object) -> None:
+        del args
+        raise _unavailable()
+
+
+def _base_request(
+    binding: LongSessionContext,
+    run_id: str,
+    model_attempt_id: str,
+    authorization_grant: str,
+) -> dict[str, object]:
+    return {
+        "sessionId": binding.session_id,
+        "turnId": binding.turn_id,
+        "runId": run_id,
+        "modelAttemptId": model_attempt_id,
+        "authorizationGrant": authorization_grant,
+        **({"caseId": binding.case_id} if binding.case_id else {}),
+        "sources": [source.model_dump(by_alias=True) for source in binding.sources],
+    }
+
+
+def _validated_preparation(
+    binding: LongSessionContext,
+    response: _PrepareResponse,
+) -> PreparedContext:
+    requested = {
+        (source.module_key, source.kind, source.id) for source in binding.sources
+    }
+    returned = [
+        (source.reference.module_key, source.reference.kind, source.reference.id)
+        for source in response.sources
+    ]
+    coordinates = [
+        (
+            source.reference.module_key,
+            source.reference.kind,
+            source.reference.id,
+            source.reference.version,
+            source.reference.sequence,
+        )
+        for source in response.sources
+    ]
+    if not requested.issubset(returned) or len(coordinates) != len(set(coordinates)):
+        raise _unavailable()
+    now = datetime.now(UTC)
+    sources: list[PreparedSource] = []
+    for source in response.sources:
+        reference = source.reference
+        if (
+            reference.validity.status != "valid"
+            or _invalid_timestamp(reference.validity.checked_at)
+            or _expired(reference.validity.expires_at, now)
+            or message_content_digest(source.role, source.content) != reference.digest
+        ):
+            raise _unavailable()
+        sources.append(
+            PreparedSource(
+                reference.module_key,
+                reference.kind,
+                reference.id,
+                reference.version,
+                reference.sequence,
+                reference.digest,
+                reference.validity.model_dump(by_alias=True, exclude_none=True),
+                source.content,
+                source.role,
+            )
+        )
+    return PreparedContext(response.preparation_id, tuple(sources))
+
+
+def _expired(value: str | None, now: datetime) -> bool:
+    if value is None:
+        return False
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    return parsed.tzinfo is None or parsed <= now
+
+
+def _invalid_timestamp(value: str) -> bool:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    return parsed.tzinfo is None
+
+
+def _endpoint(raw: str) -> str:
+    parts = urlsplit(raw.strip())
+    if (
+        parts.scheme not in {"http", "https"}
+        or not parts.hostname
+        or parts.username
+        or parts.password
+        or parts.query
+        or parts.fragment
+    ):
+        raise ValueError("AGENT_CONTEXT_HOST_URL 无效")
+    path = f"{parts.path.rstrip('/')}/api/internal/agent/context-versions"
+    return urlunsplit((parts.scheme, parts.netloc, path, "", ""))
+
+
+def context_unavailable() -> SafeEngineError:
+    return _unavailable()
+
+
+def _unavailable() -> SafeEngineError:
+    return SafeEngineError(
+        "RUNTIME_UNAVAILABLE",
+        "长期 Session Context 暂不可用",
+        retryable=True,
+    )

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

@@ -66,6 +66,18 @@ class RuntimeLimits(CanonicalModel):
     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)
+    max_model_attempts: int | None = Field(default=None, ge=1, le=500)
+    max_tool_calls: int | None = Field(default=None, ge=0, le=100_000)
+    max_subagents: int | None = Field(default=None, ge=0, le=10_000)
+    max_parallelism: int | None = Field(default=None, ge=1, le=256)
+    max_input_tokens: int | None = Field(default=None, ge=1, le=2_147_483_647)
+    max_output_tokens: int | None = Field(default=None, ge=1, le=2_147_483_647)
+    max_cost_micros: int | None = Field(default=None, ge=0, le=9_007_199_254_740_991)
+
+
+class ModelCoordinatePin(CanonicalModel):
+    deployment_key: str = Field(min_length=1, max_length=160)
+    model: str = Field(min_length=1, max_length=240)
 
 
 class ProviderEgress(CanonicalModel):
@@ -91,6 +103,18 @@ type ProviderDataField = Literal[
     "provider-output",
     "tool-results",
 ]
+type ContextSourceKind = Literal[
+    "system-instruction",
+    "operation-instruction",
+    "recent-event",
+    "skill",
+    "artifact-summary",
+    "working-context",
+    "session-summary",
+    "user-preference",
+    "case-memory-candidate",
+    "verified-fact-reference",
+]
 
 
 class ProviderFieldPolicy(CanonicalModel):
@@ -160,6 +184,19 @@ class RunReportingContext(CanonicalModel):
     department_id: str | None = Field(default=None, max_length=64)
 
 
+class ContextSourceRequest(CanonicalModel):
+    module_key: str = Field(min_length=1, max_length=160)
+    kind: ContextSourceKind
+    id: str = Field(min_length=1, max_length=200)
+
+
+class LongSessionContext(CanonicalModel):
+    session_id: str = Field(pattern=r"^session_[A-Za-z0-9_-]+$", max_length=80)
+    turn_id: str = Field(pattern=r"^turn_[A-Za-z0-9_-]+$", max_length=96)
+    case_id: str | None = Field(default=None, min_length=1, max_length=160)
+    sources: list[ContextSourceRequest] = Field(min_length=1, max_length=100)
+
+
 def legacy_release() -> RuntimeRelease:
     return RuntimeRelease(
         release_id="legacy",
@@ -195,9 +232,11 @@ class StartRunRequest(CanonicalModel):
     execution_grant: str = ""
     tool_host_url: str = ""
     readiness_pin: VlmReadinessPin | None = None
+    model_pin: ModelCoordinatePin | None = None
     release: RuntimeRelease = Field(default_factory=legacy_release)
     trace_id: str = Field(default="", max_length=160)
     reporting: RunReportingContext | None = None
+    long_session: LongSessionContext | None = None
 
 
 class StartRunResponse(CanonicalModel):

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

@@ -10,6 +10,7 @@ from .engine import (
     OutputDelta,
     UsageReported,
 )
+from .engine_identity import DIRECT_ENGINE_ID
 from .report_types import UsageFacts
 
 
@@ -17,6 +18,7 @@ class DeterministicEngineAdapter:
     """Deterministic test adapter. It never calls a model or remote service."""
 
     operations = frozenset({"test.echo", "test.wait", "test.fail"})
+    engine_id = DIRECT_ENGINE_ID
 
     def __init__(self) -> None:
         self._cancellations: dict[str, asyncio.Event] = {}

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

@@ -7,6 +7,8 @@ from typing import Protocol
 from .contracts import (
     AgentErrorCode,
     JsonValue,
+    LongSessionContext,
+    ModelCoordinatePin,
     ProviderDataPolicy,
     ProviderEgress,
     RuntimeLimits,
@@ -41,8 +43,11 @@ class EngineRunRequest:
     provider_egress: ProviderEgress = field(default_factory=ProviderEgress)
     provider_data_policy: ProviderDataPolicy = field(default_factory=ProviderDataPolicy)
     tool_network_policy: ToolNetworkPolicy = field(default_factory=ToolNetworkPolicy)
+    model_pin: ModelCoordinatePin | None = None
     execution_grant: str = ""
     tool_host_url: str = ""
+    long_session: LongSessionContext | None = None
+    prompt_version: str = "legacy"
 
 
 @dataclass(frozen=True)
@@ -111,7 +116,10 @@ class SafeEngineError(Exception):
 
 
 class AgentEngineAdapter(Protocol):
-    """Internal engine seam. HTTP DTO and ADK types must not cross it."""
+    """Internal engine seam. HTTP DTO and engine-private types must not cross it."""
+
+    @property
+    def engine_id(self) -> str: ...
 
     def supports(self, operation_key: str) -> bool: ...
 

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

@@ -0,0 +1,2 @@
+DIRECT_ENGINE_ID = "windy.direct.openai-compatible.v1"
+HISTORICAL_ADK_ENGINE_ID = "google.adk.v2"

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

@@ -38,6 +38,21 @@ def request_fingerprint(request: StartRunRequest) -> str:
                 if request.readiness_pin
                 else None
             ),
+            "modelPin": (
+                request.model_pin.model_dump(by_alias=True)
+                if request.model_pin
+                else None
+            ),
+            "limits": request.limits.model_dump(by_alias=True),
+            "allowedTools": [
+                tool.model_dump(by_alias=True) for tool in request.allowed_tools
+            ],
+            "providerEgress": request.provider_egress.model_dump(by_alias=True),
+            "providerDataPolicy": request.provider_data_policy.model_dump(
+                by_alias=True
+            ),
+            "toolNetworkPolicy": request.tool_network_policy.model_dump(by_alias=True),
+            "executionGrant": request.execution_grant,
         },
         ensure_ascii=False,
         separators=(",", ":"),

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

@@ -1,15 +1,21 @@
 from __future__ import annotations
 
-from fastapi import FastAPI
+from collections.abc import Callable
+from typing import Annotated, cast
+
+from fastapi import FastAPI, Header
 from fastapi.responses import JSONResponse
 
-from .http_helpers import safe_error
+from .http_helpers import authorized, safe_error
 from .service import AgentRunService
 from .vlm_readiness import unavailable_vlm_snapshot
 
 
 def install_health_routes(
-    application: FastAPI, runtime: AgentRunService, engine: object
+    application: FastAPI,
+    runtime: AgentRunService,
+    engine: object,
+    internal_token: str | None,
 ) -> None:
     @application.get("/health/live")
     async def live() -> dict[str, str]:
@@ -48,3 +54,31 @@ def install_health_routes(
                 ),
                 status_code=503,
             )
+
+    @application.get("/health/model-coordinate", response_model=None)
+    async def model_coordinate(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, str] | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        coordinate = cast(
+            Callable[[], dict[str, str]] | None,
+            getattr(engine, "model_coordinate", None),
+        )
+        if coordinate is None:
+            return safe_error(
+                503,
+                "MODEL_ROUTE_UNAVAILABLE",
+                "Agent Runtime Model coordinate 不可用",
+                True,
+            )
+        try:
+            await runtime.probe()
+            return coordinate()
+        except Exception:
+            return safe_error(
+                503,
+                "MODEL_ROUTE_UNAVAILABLE",
+                "Agent Runtime Model coordinate 不可用",
+                True,
+            )