create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from typing import cast
+
+import httpx
+
+from .client_completion_contracts import ClientCompletionRequest, NamedToolChoice
+from .client_completion_governance import govern_client_completion
+from .contracts import JsonValue
+from .engine import SafeEngineError
+from .openai_provider import OpenAiCompatibleProvider, ProviderTurn, consume_chunk
+from .provider_governance import ProviderRequestGovernance
+
+
+@dataclass(frozen=True)
+class PreparedClientCompletion:
+    deployment_digest: str
+    model_alias: str
+    body: bytes
+    max_response_bytes: int
+
+
+class ClientCompletionRuntime:
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider,
+        governance: ProviderRequestGovernance,
+    ) -> None:
+        self._provider = provider
+        self._governance = governance
+
+    def prepare(self, request: ClientCompletionRequest) -> PreparedClientCompletion:
+        config = self._provider.config
+        if request.deployment_key != config.deployment_key:
+            raise SafeEngineError(
+                "MODEL_ROUTE_UNAVAILABLE",
+                "Client Agent Deployment 不可用",
+                retryable=False,
+            )
+        governed_messages, governed_tools = govern_client_completion(
+            self._governance,
+            deployment_key=config.deployment_key,
+            operation_key=request.operation_key,
+            run_id=request.client_run_id,
+            attempt=request.attempt,
+            messages=request.messages,
+            tools=request.tools,
+            policy=request.provider_data_policy,
+        )
+        payload: dict[str, JsonValue] = {
+            "model": config.model,
+            "messages": cast(JsonValue, governed_messages),
+            "stream": True,
+            "stream_options": {"include_usage": True},
+            "parallel_tool_calls": False,
+        }
+        if governed_tools:
+            payload["tools"] = cast(JsonValue, governed_tools)
+        if request.tool_choice is not None:
+            payload["tool_choice"] = cast(
+                JsonValue,
+                request.tool_choice.model_dump(by_alias=True)
+                if isinstance(request.tool_choice, NamedToolChoice)
+                else request.tool_choice,
+            )
+        body = json.dumps(
+            payload,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode()
+        return PreparedClientCompletion(
+            deployment_digest=self.deployment_digest(),
+            model_alias=request.model_alias,
+            body=body,
+            max_response_bytes=min(
+                request.max_response_bytes,
+                config.max_response_bytes,
+            ),
+        )
+
+    async def stream(
+        self,
+        prepared: PreparedClientCompletion,
+    ) -> AsyncGenerator[dict[str, JsonValue]]:
+        consumed = 0
+        turn = ProviderTurn()
+        async with self._provider._client() as client:
+            try:
+                async with client.stream(
+                    "POST",
+                    "/chat/completions",
+                    content=prepared.body,
+                    headers={"content-type": "application/json"},
+                ) as response:
+                    if not response.is_success:
+                        await self._provider._bounded_stream(response)
+                        raise SafeEngineError(
+                            "RATE_LIMITED"
+                            if response.status_code == 429
+                            else "PROVIDER_UNAVAILABLE",
+                            "模型服务限流"
+                            if response.status_code == 429
+                            else "模型服务暂不可用",
+                            retryable=response.status_code == 429
+                            or response.status_code >= 500,
+                        )
+                    async for line in response.aiter_lines():
+                        consumed += len(line.encode()) + 1
+                        if consumed > prepared.max_response_bytes:
+                            raise SafeEngineError(
+                                "BUDGET_EXCEEDED",
+                                "模型响应超过会话上限",
+                                retryable=False,
+                            )
+                        if not line.startswith("data:"):
+                            continue
+                        data = line.removeprefix("data:").strip()
+                        if not data or data == "[DONE]":
+                            continue
+                        chunk = json.loads(data)
+                        consume_chunk(chunk, turn)
+                        if not isinstance(chunk, dict):
+                            raise TypeError
+                        normalized = cast(dict[str, JsonValue], chunk)
+                        normalized["model"] = prepared.model_alias
+                        yield normalized
+            except SafeEngineError:
+                raise
+            except httpx.HTTPError:
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型服务暂不可用",
+                    retryable=True,
+                ) from None
+            except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型返回协议无效",
+                    retryable=True,
+                ) from None
+
+    def deployment_digest(self) -> str:
+        config = self._provider.config
+        canonical = json.dumps(
+            {
+                "deploymentKey": config.deployment_key,
+                "model": config.model,
+                "deploymentIdentity": config.readiness_deployment_identity,
+                "releaseDigest": config.readiness_release_digest,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        return f"sha256:{hashlib.sha256(canonical).hexdigest()}"

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

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .contracts import JsonValue
+
+
+def bytes_digest(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def canonical_json_digest(value: JsonValue) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    return bytes_digest(encoded)
+
+
+def message_content_digest(role: str, content: JsonValue) -> str:
+    return canonical_json_digest({"role": role, "content": content})

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"