create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .attempt_context_projection import (
+    AttemptContextPreparation,
+    governed_envelope,
+)
+from .context_version_port import (
+    ContextVersionPort,
+    PreparedSource,
+    context_unavailable,
+)
+from .contracts import JsonValue, LongSessionContext
+from .engine import EngineRunRequest, PreparedArtifact
+from .openai_provider import OpenAiCompatibleProvider
+from .provider_governance import GovernedAttempt, ProviderRequestGovernance
+
+
+@dataclass(frozen=True)
+class GovernedProviderAttempt:
+    governed: GovernedAttempt
+    provider_request: bytes
+
+
+async def govern_provider_attempt(
+    port: ContextVersionPort,
+    governance: ProviderRequestGovernance,
+    provider: OpenAiCompatibleProvider,
+    request: EngineRunRequest,
+    attempt_sequence: int,
+    model_attempt_id: str | None,
+    messages: list[dict[str, JsonValue]],
+    max_output_tokens: int | None = None,
+) -> GovernedProviderAttempt:
+    preparation = await prepare_attempt_context(
+        port,
+        request.long_session,
+        request.run_id,
+        model_attempt_id,
+        request.execution_grant,
+        messages,
+    )
+    try:
+        attempt_messages = preparation.messages if preparation else messages
+        governed = governance.authorize(
+            deployment_key=provider.config.deployment_key,
+            operation_key=request.operation_key,
+            run_id=request.run_id,
+            attempt=attempt_sequence,
+            messages=attempt_messages,
+            tools=request.allowed_tools,
+            policy=request.provider_data_policy,
+            input_value=request.input,
+            artifact_bytes=sum(artifact.byte_size for artifact in request.artifacts),
+            output_schema=request.output_schema,
+            measure=lambda current_messages, tools, schema: len(
+                provider.request_body(
+                    current_messages,
+                    tools,
+                    request.output_schema_key,
+                    schema,
+                    max_output_tokens,
+                )
+            ),
+        )
+        provider_request = provider.request_body(
+            governed.messages,
+            governed.tools,
+            request.output_schema_key,
+            governed.output_schema,
+            max_output_tokens,
+        )
+        await commit_attempt_context(
+            port,
+            preparation,
+            request.long_session,
+            request.run_id,
+            model_attempt_id,
+            request.execution_grant,
+            governed.messages,
+            provider_request,
+            provider.config.deployment_key,
+            provider.config.model,
+            request.prompt_version,
+            request.artifacts,
+        )
+        return GovernedProviderAttempt(governed, provider_request)
+    except BaseException:
+        await abort_attempt_context(
+            port,
+            preparation,
+            request.long_session,
+            request.run_id,
+            model_attempt_id,
+            request.execution_grant,
+        )
+        raise
+
+
+async def prepare_attempt_context(
+    port: ContextVersionPort,
+    binding: LongSessionContext | None,
+    run_id: str,
+    model_attempt_id: str | None,
+    authorization_grant: str,
+    messages: list[dict[str, JsonValue]],
+) -> AttemptContextPreparation | None:
+    if binding is None:
+        return None
+    if model_attempt_id is None or not authorization_grant.strip():
+        raise context_unavailable()
+    context = await port.prepare(
+        binding,
+        run_id,
+        model_attempt_id,
+        authorization_grant,
+    )
+    insertion_start = 1 if messages and messages[0].get("role") == "system" else 0
+    injected = [_source_message(source) for source in context.sources]
+    return AttemptContextPreparation(
+        context,
+        [*messages[:insertion_start], *injected, *messages[insertion_start:]],
+        insertion_start,
+    )
+
+
+async def commit_attempt_context(
+    port: ContextVersionPort,
+    preparation: AttemptContextPreparation | None,
+    binding: LongSessionContext | None,
+    run_id: str,
+    model_attempt_id: str | None,
+    authorization_grant: str,
+    governed_messages: list[dict[str, JsonValue]],
+    provider_request: bytes,
+    deployment_key: str,
+    model: str,
+    prompt_version: str,
+    artifacts: tuple[PreparedArtifact, ...],
+) -> None:
+    if binding is None:
+        return
+    if preparation is None or model_attempt_id is None:
+        raise context_unavailable()
+    envelope = governed_envelope(
+        preparation,
+        run_id,
+        model_attempt_id,
+        governed_messages,
+        provider_request,
+        deployment_key,
+        model,
+        prompt_version,
+        artifacts,
+    )
+    await port.commit(
+        preparation.context,
+        binding,
+        run_id,
+        model_attempt_id,
+        authorization_grant,
+        envelope,
+    )
+
+
+async def abort_attempt_context(
+    port: ContextVersionPort,
+    preparation: AttemptContextPreparation | None,
+    binding: LongSessionContext | None,
+    run_id: str,
+    model_attempt_id: str | None,
+    authorization_grant: str,
+) -> None:
+    if binding is None or preparation is None or model_attempt_id is None:
+        return
+    try:
+        await port.abort(
+            preparation.context,
+            binding,
+            run_id,
+            model_attempt_id,
+            authorization_grant,
+        )
+    except Exception:
+        # Preparations are never active and have a bounded Server-side TTL.
+        return
+
+
+def _source_message(source: PreparedSource) -> dict[str, JsonValue]:
+    return {"role": source.role, "content": source.content}

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

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import cast
+
+from .context_message_digest import (
+    bytes_digest,
+    canonical_json_digest,
+    message_content_digest,
+)
+from .context_version_port import PreparedContext, context_unavailable
+from .contracts import JsonValue
+from .engine import PreparedArtifact
+
+
+@dataclass(frozen=True)
+class AttemptContextPreparation:
+    context: PreparedContext
+    messages: list[dict[str, JsonValue]]
+    insertion_start: int
+
+
+def governed_envelope(
+    preparation: AttemptContextPreparation,
+    run_id: str,
+    model_attempt_id: str,
+    messages: list[dict[str, JsonValue]],
+    provider_request: bytes,
+    deployment_key: str,
+    model: str,
+    prompt_version: str,
+    artifacts: tuple[PreparedArtifact, ...],
+) -> dict[str, JsonValue]:
+    payload = _provider_payload(provider_request, messages, model)
+    source_start = preparation.insertion_start
+    source_end = source_start + len(preparation.context.sources)
+    message_entries: list[JsonValue] = []
+    for ordinal, message in enumerate(messages):
+        recovery_content = _recovery_content(message, artifacts)
+        message_entries.append(
+            {
+                "ordinal": ordinal,
+                "role": cast(str, message.get("role")),
+                "content": recovery_content,
+                # digest covers actual governed Provider content; recoveryDigest
+                # covers the encrypted, ArtifactRef-only recovery projection.
+                "digest": _message_digest(message),
+                "recoveryDigest": message_content_digest(
+                    cast(str, message.get("role")), recovery_content
+                ),
+                "origins": _message_origins(
+                    preparation,
+                    run_id,
+                    model_attempt_id,
+                    prompt_version,
+                    artifacts,
+                    ordinal,
+                    message,
+                    source_start,
+                    source_end,
+                ),
+            }
+        )
+    return {
+        "provider": {
+            "deploymentKey": deployment_key,
+            "model": model,
+            "requestDigest": bytes_digest(provider_request),
+            "toolsDigest": canonical_json_digest(payload.get("tools")),
+            "outputSchemaDigest": canonical_json_digest(payload.get("response_format")),
+        },
+        "messages": message_entries,
+    }
+
+
+def _message_origins(
+    preparation: AttemptContextPreparation,
+    run_id: str,
+    model_attempt_id: str,
+    prompt_version: str,
+    artifacts: tuple[PreparedArtifact, ...],
+    ordinal: int,
+    message: dict[str, JsonValue],
+    source_start: int,
+    source_end: int,
+) -> list[JsonValue]:
+    if source_start <= ordinal < source_end:
+        source = preparation.context.sources[ordinal - source_start]
+        return [
+            {
+                "type": "context-source",
+                "sourceId": source.id,
+                "sourceVersion": source.version,
+                "digest": source.digest,
+                "source": source.reference(),
+            }
+        ]
+    role = message.get("role")
+    digest = _message_digest(message)
+    if ordinal == 0 and role == "system":
+        return [
+            {
+                "type": "instructions",
+                "sourceId": f"{run_id}:instructions",
+                "sourceVersion": prompt_version,
+                "digest": digest,
+            }
+        ]
+    if role == "user":
+        origins: list[JsonValue] = [
+            {
+                "type": "user-prompt",
+                "sourceId": f"{run_id}:user-prompt",
+                "sourceVersion": run_id,
+                "digest": digest,
+            }
+        ]
+        for artifact in artifacts:
+            origins.append(
+                {
+                    "type": "artifact",
+                    "sourceId": artifact.sha256,
+                    "sourceVersion": artifact.sha256,
+                    "digest": artifact.sha256,
+                }
+            )
+        return origins
+    if role == "assistant":
+        return [
+            {
+                "type": "provider-output",
+                "sourceId": f"{run_id}:message:{ordinal}",
+                "sourceVersion": model_attempt_id,
+                "digest": digest,
+            }
+        ]
+    if role == "tool" and isinstance(message.get("tool_call_id"), str):
+        return [
+            {
+                "type": "tool-receipt",
+                "sourceId": message["tool_call_id"],
+                "sourceVersion": model_attempt_id,
+                "digest": digest,
+            }
+        ]
+    raise context_unavailable()
+
+
+def _recovery_content(
+    message: dict[str, JsonValue],
+    artifacts: tuple[PreparedArtifact, ...],
+) -> JsonValue:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return content
+    known = {artifact.data_url: artifact for artifact in artifacts}
+    projected: list[JsonValue] = []
+    for part in content:
+        if not isinstance(part, dict):
+            raise context_unavailable()
+        if part.get("type") == "text" and isinstance(part.get("text"), str):
+            projected.append(part)
+            continue
+        image = part.get("image_url")
+        url = image.get("url") if isinstance(image, dict) else None
+        artifact = known.get(url) if isinstance(url, str) else None
+        if part.get("type") != "image_url" or artifact is None:
+            raise context_unavailable()
+        projected.append(
+            {
+                "type": "artifact_ref",
+                "sha256": artifact.sha256,
+                "mediaType": artifact.media_type,
+                "byteSize": artifact.byte_size,
+            }
+        )
+    return projected
+
+
+def _provider_payload(
+    raw: bytes,
+    messages: list[dict[str, JsonValue]],
+    model: str,
+) -> dict[str, JsonValue]:
+    try:
+        value = json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise context_unavailable() from None
+    if (
+        not isinstance(value, dict)
+        or value.get("messages") != messages
+        or value.get("model") != model
+    ):
+        raise context_unavailable()
+    return cast(dict[str, JsonValue], value)
+
+
+def _message_digest(message: dict[str, JsonValue]) -> str:
+    role = message.get("role")
+    if role not in {"system", "user", "assistant", "tool"} or "content" not in message:
+        raise context_unavailable()
+    return canonical_json_digest(cast(JsonValue, message))

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

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import Field, model_validator
+
+from .contracts import CanonicalModel, JsonValue, ProviderDataPolicy
+
+
+class NamedFunction(CanonicalModel):
+    name: str = Field(pattern=r"^[A-Za-z0-9_-]{1,64}$")
+
+
+class NamedToolChoice(CanonicalModel):
+    type: Literal["function"]
+    function: NamedFunction
+
+
+class ClientCompletionRequest(CanonicalModel):
+    client_run_id: str = Field(min_length=1, max_length=80)
+    operation_key: str = Field(min_length=1, max_length=200)
+    deployment_key: str = Field(min_length=1, max_length=200)
+    model_alias: str = Field(pattern=r"^[A-Za-z0-9._-]{1,80}$")
+    attempt: int = Field(ge=1, le=128)
+    messages: list[dict[str, JsonValue]] = Field(min_length=1, max_length=128)
+    tools: list[dict[str, JsonValue]] = Field(default_factory=list, max_length=64)
+    tool_choice: Literal["auto", "none"] | NamedToolChoice | None = None
+    parallel_tool_calls: Literal[False] = False
+    provider_data_policy: ProviderDataPolicy
+    max_response_bytes: int = Field(ge=1_024, le=16_777_216)
+
+    @model_validator(mode="after")
+    def validate_openai_envelope(self) -> Self:
+        for message in self.messages:
+            if message.get("role") not in {"system", "user", "assistant", "tool"}:
+                raise ValueError("消息角色无效")
+            content = message.get("content")
+            if content is not None and not isinstance(content, str):
+                raise ValueError("消息 content 无效")
+        names: set[str] = set()
+        for tool in self.tools:
+            function = tool.get("function")
+            if tool.get("type") != "function" or not isinstance(function, dict):
+                raise ValueError("Tool 定义无效")
+            name = function.get("name")
+            parameters = function.get("parameters")
+            if (
+                not isinstance(name, str)
+                or not name
+                or name in names
+                or not isinstance(parameters, dict)
+                or parameters.get("type") != "object"
+            ):
+                raise ValueError("Tool Function 定义无效")
+            names.add(name)
+        if (
+            isinstance(self.tool_choice, NamedToolChoice)
+            and self.tool_choice.function.name not in names
+        ):
+            raise ValueError("命名 Tool Choice 不存在")
+        return self

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

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from .contracts import JsonValue, ProviderDataPolicy
+from .engine import SafeEngineError
+from .provider_governance import (
+    GovernanceDenied,
+    ProviderRequestGovernance,
+    field_for_message,
+    govern_message,
+    govern_value,
+)
+
+
+def govern_client_completion(
+    governance: ProviderRequestGovernance,
+    *,
+    deployment_key: str,
+    operation_key: str,
+    run_id: str,
+    attempt: int,
+    messages: list[dict[str, JsonValue]],
+    tools: list[dict[str, JsonValue]],
+    policy: ProviderDataPolicy,
+) -> tuple[list[dict[str, JsonValue]], list[dict[str, JsonValue]]]:
+    rules = {rule.field: rule for rule in policy.envelope_fields}
+    classified: set[str] = set()
+    redacted = False
+    try:
+        governed_messages: list[dict[str, JsonValue]] = []
+        for message in messages:
+            field = field_for_message(message)
+            rule = rules.get(field)
+            if rule is None:
+                raise GovernanceDenied(f"Provider 未授权发送字段：{field}")
+            classified.add(rule.classification)
+            value, changed = govern_message(message, rule.dlp_action)
+            redacted = redacted or changed
+            governed_messages.append(cast(dict[str, JsonValue], value))
+        governed_tools = tools
+        if tools:
+            rule = rules.get("tool-definitions")
+            if rule is None:
+                raise GovernanceDenied("Provider 未授权发送字段：tool-definitions")
+            classified.add(rule.classification)
+            value, changed = govern_value(tools, rule.dlp_action)
+            redacted = redacted or changed
+            governed_tools = cast(list[dict[str, JsonValue]], value)
+        sent_bytes = len(
+            json.dumps(
+                {"messages": governed_messages, "tools": governed_tools},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ).encode()
+        )
+        governance.record_client(
+            deployment_key=deployment_key,
+            operation_key=operation_key,
+            run_id=run_id,
+            attempt=attempt,
+            classified=classified,
+            sent_bytes=sent_bytes,
+            decision="redact" if redacted else "allow",
+        )
+        return governed_messages, governed_tools
+    except GovernanceDenied:
+        governance.record_client(
+            deployment_key=deployment_key,
+            operation_key=operation_key,
+            run_id=run_id,
+            attempt=attempt,
+            classified=classified,
+            sent_bytes=0,
+            decision="reject",
+        )
+        raise SafeEngineError(
+            "FORBIDDEN",
+            "Provider 请求被字段治理策略拒绝",
+            retryable=False,
+        ) from None

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

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Callable
+from typing import TYPE_CHECKING, Annotated, cast
+
+from fastapi import FastAPI, Header, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from .client_completion_contracts import ClientCompletionRequest
+from .client_completion_runtime import ClientCompletionRuntime
+from .engine import AgentEngineAdapter, SafeEngineError
+from .http_helpers import authorized, safe_error
+
+if TYPE_CHECKING:
+    from .client_completion_runtime import PreparedClientCompletion
+
+
+def install_client_completion_routes(
+    application: FastAPI,
+    engine: AgentEngineAdapter,
+    internal_token: str | None,
+) -> None:
+    @application.get("/api/internal/client-agent/health", response_model=None)
+    async def client_completion_health(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, str] | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        factory = runtime_factory(engine)
+        if factory is None:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Client Agent Provider 尚未配置",
+                True,
+            )
+        try:
+            factory().deployment_digest()
+        except SafeEngineError as error:
+            return safe_error(503, error.code, error.safe_message, error.retryable)
+        return {"status": "ready"}
+
+    @application.post(
+        "/api/internal/client-agent/chat/completions",
+        response_model=None,
+    )
+    async def client_completion(
+        body: ClientCompletionRequest,
+        request: Request,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StreamingResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        factory = runtime_factory(engine)
+        if factory is None:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Client Agent Provider 尚未配置",
+                True,
+            )
+        try:
+            runtime = factory()
+            prepared = runtime.prepare(body)
+        except SafeEngineError as error:
+            return safe_error(
+                403 if error.code == "FORBIDDEN" else 503,
+                error.code,
+                error.safe_message,
+                error.retryable,
+            )
+        return StreamingResponse(
+            completion_events(runtime, prepared, request),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-store, no-transform",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+
+async def completion_events(
+    runtime: ClientCompletionRuntime,
+    prepared: object,
+    request: Request,
+) -> AsyncIterator[str]:
+    typed = cast("PreparedClientCompletion", prepared)
+    yield event(
+        "windy.meta",
+        {"deploymentDigest": typed.deployment_digest},
+    )
+    try:
+        async for chunk in runtime.stream(typed):
+            if await request.is_disconnected():
+                return
+            yield event(None, chunk)
+        yield "data: [DONE]\n\n"
+    except SafeEngineError as error:
+        yield event(
+            "windy.error",
+            {
+                "code": error.code,
+                "message": error.safe_message,
+                "retryable": error.retryable,
+            },
+        )
+
+
+def event(name: str | None, value: object) -> str:
+    prefix = f"event: {name}\n" if name else ""
+    return f"{prefix}data: {json.dumps(value, ensure_ascii=False)}\n\n"
+
+
+def runtime_factory(
+    engine: AgentEngineAdapter,
+) -> Callable[[], ClientCompletionRuntime] | None:
+    return cast(
+        Callable[[], ClientCompletionRuntime] | None,
+        getattr(engine, "client_completion_runtime", None),
+    )