create-windy 0.3.2 → 0.3.5

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

@@ -15,13 +15,26 @@ from .contracts import (
 )
 
 
+@dataclass(frozen=True)
+class PreparedArtifact:
+    media_type: str
+    data_url: str
+    byte_size: int
+    sha256: str
+
+
 @dataclass(frozen=True)
 class EngineRunRequest:
     run_id: str
     operation_key: str
     input: JsonValue
+    input_modalities: tuple[str, ...] = ("text",)
+    required_capabilities: tuple[str, ...] = ()
+    artifacts: tuple[PreparedArtifact, ...] = ()
     instructions: str = ""
     user_prompt: str = ""
+    output_schema_key: str = ""
+    output_schema: dict[str, JsonValue] | None = None
     allowed_tools: tuple[RuntimeToolDefinition, ...] = ()
     limits: RuntimeLimits = field(default_factory=RuntimeLimits)
     provider_egress: ProviderEgress = field(default_factory=ProviderEgress)
@@ -45,6 +58,14 @@ class ToolRequested:
 @dataclass(frozen=True)
 class ApprovalRequired:
     work_item_id: str
+    tool_call_id: str
+
+
+@dataclass(frozen=True)
+class ApprovalResolved:
+    work_item_id: str
+    tool_call_id: str
+    outcome: str
 
 
 @dataclass(frozen=True)
@@ -66,6 +87,7 @@ type EngineSignal = (
     OutputDelta
     | ToolRequested
     | ApprovalRequired
+    | ApprovalResolved
     | ToolCompleted
     | UsageReported
     | EngineCompleted
@@ -91,6 +113,12 @@ class AgentEngineAdapter(Protocol):
 
     def supports(self, operation_key: str) -> bool: ...
 
+    @property
+    def capabilities(self) -> tuple[str, ...]: ...
+
+    @property
+    def input_modalities(self) -> tuple[str, ...]: ...
+
     def execute(self, request: EngineRunRequest) -> AsyncIterator[EngineSignal]: ...
 
     async def cancel(self, run_id: str) -> None: ...

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

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import cast
+
+from .contracts import JsonValue, StartRunRequest
+
+
+def resolved_release(request: StartRunRequest) -> dict[str, JsonValue]:
+    release = cast(dict[str, JsonValue], request.release.model_dump(by_alias=True))
+    if release["releaseId"] == "legacy":
+        operation_digest = hashlib.sha256(request.operation_key.encode()).hexdigest()
+        release["releaseId"] = f"legacy_{operation_digest[:40]}"
+    return release
+
+
+def request_fingerprint(request: StartRunRequest) -> str:
+    encoded = json.dumps(
+        {
+            "operationKey": request.operation_key,
+            "input": request.input,
+            "artifacts": [
+                {
+                    "sha256": artifact.sha256,
+                    "mediaType": artifact.media_type,
+                    "byteSize": artifact.byte_size,
+                }
+                for artifact in request.artifacts
+            ],
+            "requiredCapabilities": sorted(request.required_capabilities),
+            "inputModalities": sorted(request.input_modalities),
+            "outputSchemaKey": request.output_schema_key,
+            "outputSchema": request.output_schema,
+            "release": resolved_release(request),
+        },
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    return hashlib.sha256(encoded).hexdigest()

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

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import hmac
+import uuid
+
+from fastapi.responses import JSONResponse
+
+from .contracts import AgentError
+
+
+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",
+    )
+    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)
+
+
+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),
+    )

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

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import asyncio
+
+
+def lease_failed(task: asyncio.Task[None]) -> bool:
+    return task.done() and not task.cancelled() and task.exception() is not None
+
+
+def cancel_on_lease_loss(
+    lease_task: asyncio.Task[None],
+    execution_task: asyncio.Task[None],
+) -> None:
+    if lease_failed(lease_task):
+        execution_task.cancel()

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

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import re
+
+from jsonschema import SchemaError, ValidationError, validate
+
+from .contracts import JsonValue
+from .engine import PreparedArtifact, SafeEngineError
+
+
+def attach_artifacts(
+    messages: list[dict[str, JsonValue]],
+    artifacts: tuple[PreparedArtifact, ...],
+) -> list[dict[str, JsonValue]]:
+    if not artifacts:
+        return messages
+    result = [dict(message) for message in messages]
+    for message in result:
+        if message.get("role") != "user":
+            continue
+        text = message.get("content")
+        if not isinstance(text, str):
+            raise invalid("Agent Vision 用户消息结构无效")
+        parts: list[JsonValue] = [{"type": "text", "text": text}]
+        parts.extend(
+            {
+                "type": "image_url",
+                "image_url": {"url": artifact.data_url, "detail": "auto"},
+            }
+            for artifact in artifacts
+        )
+        message["content"] = parts
+        return result
+    raise invalid("Agent Vision 缺少用户消息")
+
+
+def response_format(
+    output_schema_key: str,
+    output_schema: dict[str, JsonValue] | None,
+) -> JsonValue | None:
+    if output_schema is None:
+        return None
+    name = re.sub(r"[^a-zA-Z0-9_-]", "_", output_schema_key)[:64]
+    if not name:
+        raise invalid("结构化输出 Schema Key 无效")
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": name,
+            "strict": True,
+            "schema": output_schema,
+        },
+    }
+
+
+def final_output(
+    text: str,
+    output_schema: dict[str, JsonValue] | None,
+) -> JsonValue:
+    if output_schema is None:
+        return {"text": text}
+    try:
+        value: JsonValue = json.loads(text)
+        validate(instance=value, schema=output_schema)
+        return value
+    except (json.JSONDecodeError, SchemaError, ValidationError):
+        raise SafeEngineError(
+            "OUTPUT_VALIDATION_FAILED",
+            "模型结构化输出不符合 Operation Schema",
+            retryable=False,
+        ) from None
+
+
+def invalid(message: str) -> SafeEngineError:
+    return SafeEngineError("INVALID_INPUT", message, retryable=False)

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

@@ -7,6 +7,8 @@ from collections.abc import AsyncIterator
 from .contracts import JsonValue
 from .engine import (
     AgentEngineAdapter,
+    ApprovalRequired,
+    ApprovalResolved,
     EngineCompleted,
     EngineRunRequest,
     EngineSignal,
@@ -16,9 +18,16 @@ from .engine import (
     ToolRequested,
     UsageReported,
 )
+from .multimodal import attach_artifacts, final_output
 from .openai_provider import OpenAiCompatibleProvider, ProviderToolCall
 from .provider_governance import ProviderRequestGovernance
-from .tool_host import ToolHostClient, ToolInvocation
+from .tool_host import (
+    ToolApprovalPending,
+    ToolApprovalResolved,
+    ToolHostClient,
+    ToolInvocation,
+    canonical_tool_call_id,
+)
 
 
 class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
@@ -33,6 +42,14 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         self._governance = governance
         self._cancellations: dict[str, asyncio.Event] = {}
 
+    @property
+    def capabilities(self) -> tuple[str, ...]:
+        return self._provider.config.capabilities
+
+    @property
+    def input_modalities(self) -> tuple[str, ...]:
+        return self._provider.config.input_modalities
+
     def supports(self, operation_key: str) -> bool:
         return bool(operation_key.strip())
 
@@ -40,16 +57,24 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         self,
         request: EngineRunRequest,
     ) -> AsyncIterator[EngineSignal]:
-        validate_runtime_request(request, self._provider.config.deployment_key)
+        validate_runtime_request(
+            request,
+            self._provider.config.deployment_key,
+            self._provider.config.capabilities,
+            self._provider.config.input_modalities,
+        )
         cancellation = self._cancellations.setdefault(
             request.run_id,
             asyncio.Event(),
         )
         allowed = {tool.key for tool in request.allowed_tools}
-        messages: list[dict[str, JsonValue]] = [
-            {"role": "system", "content": request.instructions},
-            {"role": "user", "content": request.user_prompt},
-        ]
+        messages = attach_artifacts(
+            [
+                {"role": "system", "content": request.instructions},
+                {"role": "user", "content": request.user_prompt},
+            ],
+            request.artifacts,
+        )
         output_bytes = 0
         try:
             for attempt in range(1, self._provider.config.max_tool_rounds + 1):
@@ -63,13 +88,24 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
                     tools=request.allowed_tools,
                     policy=request.provider_data_policy,
                     input_value=request.input,
-                    measure=lambda messages, tools: len(
-                        self._provider.request_body(messages, tools)
+                    artifact_bytes=sum(
+                        artifact.byte_size for artifact in request.artifacts
+                    ),
+                    output_schema=request.output_schema,
+                    measure=lambda messages, tools, schema: len(
+                        self._provider.request_body(
+                            messages,
+                            tools,
+                            request.output_schema_key,
+                            schema,
+                        )
                     ),
                 )
                 turn = await self._provider.complete_turn(
                     governed.messages,
                     governed.tools,
+                    request.output_schema_key,
+                    governed.output_schema,
                 )
                 if turn.tool_calls:
                     messages.append(assistant_tool_message(turn.tool_calls))
@@ -92,7 +128,7 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
                         )
                     yield OutputDelta(delta)
                 yield UsageReported(turn.usage or {"source": "unknown"})
-                yield EngineCompleted({"text": turn.text})
+                yield EngineCompleted(final_output(turn.text, governed.output_schema))
                 return
             raise SafeEngineError(
                 "BUDGET_EXCEEDED",
@@ -119,18 +155,60 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
                     retryable=False,
                 )
             arguments = parse_arguments(call.arguments)
-            yield ToolRequested(call.call_id, call.name)
-            result = await self._tool_host.execute(
-                request.tool_host_url,
-                ToolInvocation(
-                    request.run_id,
-                    call.call_id,
-                    call.name,
-                    arguments,
-                    request.execution_grant,
-                ),
+            tool_call_id = canonical_tool_call_id(
+                request.run_id,
+                call.name,
+                arguments,
             )
-            yield ToolCompleted(call.call_id)
+            yield ToolRequested(tool_call_id, call.name)
+            invocation = ToolInvocation(
+                request.run_id,
+                tool_call_id,
+                call.name,
+                arguments,
+                request.execution_grant,
+            )
+            approval: ToolApprovalPending | None = None
+            while True:
+                cancelled(cancellation)
+                try:
+                    result = await self._tool_host.execute(
+                        request.tool_host_url,
+                        invocation,
+                    )
+                    if approval:
+                        yield ApprovalResolved(
+                            approval.work_item_id,
+                            tool_call_id,
+                            "approved",
+                        )
+                    break
+                except ToolApprovalPending as pending:
+                    if approval is None:
+                        approval = pending
+                        yield ApprovalRequired(
+                            pending.work_item_id,
+                            tool_call_id,
+                        )
+                    elif pending.work_item_id != approval.work_item_id:
+                        raise SafeEngineError(
+                            "TOOL_DENIED",
+                            "Agent Tool 审批标识漂移",
+                            retryable=False,
+                        ) from None
+                    await asyncio.sleep(2)
+                except ToolApprovalResolved as resolved:
+                    yield ApprovalResolved(
+                        resolved.work_item_id,
+                        tool_call_id,
+                        resolved.outcome,
+                    )
+                    raise SafeEngineError(
+                        "TOOL_DENIED",
+                        "Agent Tool 审批未通过",
+                        retryable=False,
+                    ) from None
+            yield ToolCompleted(tool_call_id)
             messages.append(
                 {
                     "role": "tool",
@@ -158,6 +236,8 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
 def validate_runtime_request(
     request: EngineRunRequest,
     provider_deployment_key: str,
+    provider_capabilities: tuple[str, ...],
+    provider_input_modalities: tuple[str, ...],
 ) -> None:
     if (
         not request.instructions.strip()
@@ -170,6 +250,18 @@ def validate_runtime_request(
             "Agent Operation 运行计划不完整",
             retryable=False,
         )
+    if set(request.required_capabilities) - set(provider_capabilities):
+        raise SafeEngineError(
+            "MODEL_ROUTE_UNAVAILABLE",
+            "模型 Deployment 缺少 Operation 所需能力",
+            retryable=True,
+        )
+    if set(request.input_modalities) - set(provider_input_modalities):
+        raise SafeEngineError(
+            "MODEL_ROUTE_UNAVAILABLE",
+            "模型 Deployment 不支持 Operation 输入模态",
+            retryable=True,
+        )
     if (
         request.provider_egress.mode != "configured-endpoint"
         or request.provider_egress.deployment_key != provider_deployment_key

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

@@ -12,6 +12,7 @@ from .config import (
 )
 from .contracts import AgentErrorCode, JsonValue, RuntimeToolDefinition
 from .engine import SafeEngineError
+from .multimodal import response_format
 
 
 @dataclass
@@ -58,8 +59,15 @@ class OpenAiCompatibleProvider:
         self,
         messages: list[dict[str, JsonValue]],
         tools: tuple[RuntimeToolDefinition, ...],
+        output_schema_key: str = "",
+        output_schema: dict[str, JsonValue] | None = None,
     ) -> ProviderTurn:
-        body = self.request_body(messages, tools)
+        body = self.request_body(
+            messages,
+            tools,
+            output_schema_key,
+            output_schema,
+        )
         turn = ProviderTurn()
         async with self._client() as client:
             try:
@@ -83,6 +91,8 @@ class OpenAiCompatibleProvider:
         self,
         messages: list[dict[str, JsonValue]],
         tools: tuple[RuntimeToolDefinition, ...],
+        output_schema_key: str = "",
+        output_schema: dict[str, JsonValue] | None = None,
     ) -> bytes:
         payload: dict[str, JsonValue] = {
             "model": self.config.model,
@@ -92,6 +102,9 @@ class OpenAiCompatibleProvider:
         }
         if tools:
             payload["tools"] = [tool_schema(tool) for tool in tools]
+        structured = response_format(output_schema_key, output_schema)
+        if structured is not None:
+            payload["response_format"] = structured
         return json.dumps(
             payload,
             ensure_ascii=False,