create-windy 0.3.2 → 0.3.5

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

@@ -30,6 +30,7 @@ _REDACTED = "[REDACTED]"
 class GovernedAttempt:
     messages: list[dict[str, JsonValue]]
     tools: tuple[RuntimeToolDefinition, ...]
+    output_schema: dict[str, JsonValue] | None
 
 
 class ProviderRequestGovernance:
@@ -47,8 +48,15 @@ class ProviderRequestGovernance:
         tools: tuple[RuntimeToolDefinition, ...],
         policy: ProviderDataPolicy,
         input_value: JsonValue = None,
+        artifact_bytes: int = 0,
+        output_schema: dict[str, JsonValue] | None = None,
         measure: Callable[
-            [list[dict[str, JsonValue]], tuple[RuntimeToolDefinition, ...]], int
+            [
+                list[dict[str, JsonValue]],
+                tuple[RuntimeToolDefinition, ...],
+                dict[str, JsonValue] | None,
+            ],
+            int,
         ]
         | None = None,
     ) -> GovernedAttempt:
@@ -64,7 +72,7 @@ class ProviderRequestGovernance:
                 if rule is None:
                     raise GovernanceDenied(f"Provider 未授权发送字段：{field}")
                 classified.add(rule.classification)
-                value, changed = govern_value(message, rule.dlp_action)
+                value, changed = govern_message(message, rule.dlp_action)
                 redacted = redacted or changed
                 governed_messages.append(cast(dict[str, JsonValue], value))
             governed_tools = tools
@@ -80,9 +88,27 @@ class ProviderRequestGovernance:
                     RuntimeToolDefinition.model_validate(item)
                     for item in cast(list[object], governed)
                 )
+            governed_schema = output_schema
+            if artifact_bytes:
+                artifact_rule = rules.get("artifact-content")
+                if artifact_rule is None:
+                    raise GovernanceDenied("Provider 未授权发送字段：artifact-content")
+                classified.add(artifact_rule.classification)
+            if output_schema is not None:
+                schema_rule = rules.get("output-schema")
+                if schema_rule is None:
+                    raise GovernanceDenied("Provider 未授权发送字段：output-schema")
+                classified.add(schema_rule.classification)
+                raw_schema, changed = govern_value(
+                    output_schema,
+                    schema_rule.dlp_action,
+                )
+                redacted = redacted or changed
+                governed_schema = cast(dict[str, JsonValue], raw_schema)
             sent_bytes = (measure or payload_size)(
                 governed_messages,
                 governed_tools,
+                governed_schema,
             )
             decision = "redact" if redacted else "allow"
             self._record(
@@ -94,7 +120,11 @@ class ProviderRequestGovernance:
                 sent_bytes,
                 decision,
             )
-            return GovernedAttempt(governed_messages, governed_tools)
+            return GovernedAttempt(
+                governed_messages,
+                governed_tools,
+                governed_schema,
+            )
         except GovernanceDenied:
             self._record(
                 deployment_key,
@@ -210,13 +240,44 @@ def govern_value(value: object, action: str) -> tuple[object, bool]:
     return value, False
 
 
+def govern_message(
+    message: dict[str, JsonValue],
+    action: str,
+) -> tuple[object, bool]:
+    content = message.get("content")
+    if message.get("role") != "user" or not isinstance(content, list):
+        return govern_value(message, action)
+    changed = False
+    governed_parts: list[object] = []
+    for part in content:
+        if not isinstance(part, dict):
+            raise GovernanceDenied("Provider 多模态消息结构无效")
+        if part.get("type") == "text":
+            governed, item_changed = govern_value(part, action)
+            governed_parts.append(governed)
+            changed = changed or item_changed
+            continue
+        image = part.get("image_url")
+        url = image.get("url") if isinstance(image, dict) else None
+        if (
+            part.get("type") != "image_url"
+            or not isinstance(url, str)
+            or not url.startswith("data:image/png;base64,")
+        ):
+            raise GovernanceDenied("Provider 图片输入结构无效")
+        governed_parts.append(part)
+    return {**message, "content": governed_parts}, changed
+
+
 def payload_size(
     messages: list[dict[str, JsonValue]],
     tools: tuple[RuntimeToolDefinition, ...],
+    output_schema: dict[str, JsonValue] | None = None,
 ) -> int:
     payload = {
         "messages": messages,
         "tools": [tool.model_dump(by_alias=True) for tool in tools],
+        "outputSchema": output_schema,
     }
     return len(
         json.dumps(

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

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+
+from .adk_adapter import AdkEngineAdapter
+from .config import EnvironmentSecretResolver, OpenAiCompatibleConfig
+from .engine import AgentEngineAdapter
+from .openai_provider import OpenAiCompatibleProvider
+from .postgres_store import PostgresRunStore
+from .provider_audit import ProviderAuditStore
+from .provider_governance import ProviderRequestGovernance
+from .sqlite_store import SqliteRunStore
+from .store import InMemoryRunStore, RunStore
+from .store_cipher import RunStoreCipher
+from .tool_host import ToolHostClient
+
+
+def default_engine() -> AgentEngineAdapter:
+    config = OpenAiCompatibleConfig.from_environment()
+    if config is None:
+        return AdkEngineAdapter()
+    internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
+    if not internal_token:
+        raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
+    return AdkEngineAdapter(
+        OpenAiCompatibleProvider(
+            config,
+            EnvironmentSecretResolver(os.environ),
+        ),
+        ToolHostClient(internal_token),
+        ProviderRequestGovernance(
+            ProviderAuditStore(
+                required_environment("AI_PROVIDER_AUDIT_STORE_PATH"),
+                retention_days=provider_audit_retention_days(),
+            )
+        ),
+    )
+
+
+def default_store() -> RunStore:
+    database_url = os.environ.get("AGENT_DATABASE_URL", "").strip()
+    path = os.environ.get("AGENT_RUN_STORE_PATH", "").strip()
+    if not database_url and not path:
+        return InMemoryRunStore()
+    cipher = RunStoreCipher(required_environment("AGENT_RUN_ENCRYPTION_SECRET"))
+    return (
+        PostgresRunStore(database_url, cipher)
+        if database_url
+        else SqliteRunStore(path, cipher)
+    )
+
+
+def required_environment(key: str) -> str:
+    value = os.environ.get(key, "").strip()
+    if not value:
+        raise ValueError(f"Provider 已配置但缺少 {key}")
+    return value
+
+
+def provider_audit_retention_days() -> int:
+    raw = os.environ.get("AI_PROVIDER_AUDIT_RETENTION_DAYS", "90")
+    try:
+        value = int(raw)
+    except ValueError as error:
+        raise ValueError("AI_PROVIDER_AUDIT_RETENTION_DAYS 必须是整数") from error
+    if not 1 <= value <= 3650:
+        raise ValueError("AI_PROVIDER_AUDIT_RETENTION_DAYS 超出允许范围")
+    return value

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

@@ -1,23 +1,24 @@
 from __future__ import annotations
 
 import asyncio
-import hashlib
-import json
+import logging
 import uuid
 
-from .contracts import AgentError, JsonValue, StartRunRequest
+from .artifact_input import ArtifactLoader
+from .contracts import AgentError, StartRunRequest
 from .engine import (
     AgentEngineAdapter,
-    ApprovalRequired,
     EngineCompleted,
     EngineRunRequest,
-    OutputDelta,
     SafeEngineError,
-    ToolCompleted,
-    ToolRequested,
-    UsageReported,
 )
+from .fingerprint import request_fingerprint, resolved_release
+from .lease import cancel_on_lease_loss, lease_failed
+from .signal_events import canonical_signal_event
 from .store import IdempotencyConflictError, RunRecord, RunStore
+from .telemetry import AgentRunTrace
+
+logger = logging.getLogger(__name__)
 
 
 class RunNotFoundError(Exception):
@@ -29,10 +30,18 @@ class OperationNotFoundError(Exception):
 
 
 class AgentRunService:
-    def __init__(self, engine: AgentEngineAdapter, store: RunStore) -> None:
+    def __init__(
+        self,
+        engine: AgentEngineAdapter,
+        store: RunStore,
+        artifact_loader: ArtifactLoader | None = None,
+    ) -> None:
         self.engine = engine
         self.store = store
+        self.artifact_loader = artifact_loader
         self._tasks: set[asyncio.Task[None]] = set()
+        self._active_run_ids: set[str] = set()
+        self._recovery_task: asyncio.Task[None] | None = None
 
     async def start(
         self,
@@ -41,48 +50,148 @@ class AgentRunService:
     ) -> RunRecord:
         if not self.engine.supports(request.operation_key):
             raise OperationNotFoundError
-        fingerprint = request_fingerprint(request.operation_key, request.input)
+        missing = set(request.required_capabilities) - set(self.engine.capabilities)
+        unsupported = set(request.input_modalities) - set(self.engine.input_modalities)
+        if missing or unsupported:
+            raise SafeEngineError(
+                "MODEL_ROUTE_UNAVAILABLE",
+                "模型 Deployment 缺少 Operation 所需能力或输入模态",
+                retryable=True,
+            )
+        fingerprint = request_fingerprint(request)
         candidate = RunRecord(
             run_id=f"run_{uuid.uuid4().hex}",
             operation_key=request.operation_key,
             input=request.input,
             idempotency_key=idempotency_key,
             fingerprint=fingerprint,
+            release=resolved_release(request),
+            trace_id=request.trace_id,
+        )
+        record, created = await self.store.create_or_get(
+            candidate,
+            request.model_dump(by_alias=True),
         )
-        record, created = await self.store.create_or_get(candidate)
         if created:
-            task = asyncio.create_task(self._execute(record, request))
-            self._tasks.add(task)
-            task.add_done_callback(self._tasks.discard)
+            self._spawn(record, request)
         return record
 
+    async def recover(self) -> None:
+        await self._recover_once()
+        if self._recovery_task is None:
+            self._recovery_task = asyncio.create_task(self._recovery_loop())
+
+    async def close(self) -> None:
+        if self._recovery_task:
+            self._recovery_task.cancel()
+        for task in list(self._tasks):
+            task.cancel()
+        await asyncio.gather(
+            *([self._recovery_task] if self._recovery_task else []),
+            *self._tasks,
+            return_exceptions=True,
+        )
+        await self.store.close()
+
+    async def _recover_once(self) -> None:
+        for record, raw in await self.store.recoverable():
+            if record.run_id in self._active_run_ids:
+                continue
+            self._spawn(
+                record,
+                StartRunRequest.model_validate(raw),
+                resumed=True,
+            )
+
+    async def _recovery_loop(self) -> None:
+        while True:
+            await asyncio.sleep(10)
+            try:
+                await self._recover_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("Agent Run 恢复轮询失败，将继续重试")
+
+    async def record_evaluation(
+        self,
+        release_id: str,
+        evaluation_set_key: str,
+        evaluation_set_version: str,
+        metrics: dict[str, float],
+    ) -> str:
+        return await self.store.record_evaluation(
+            release_id,
+            evaluation_set_key,
+            evaluation_set_version,
+            metrics,
+        )
+
     async def get(self, run_id: str) -> RunRecord:
         record = await self.store.get(run_id)
         if record is None:
             raise RunNotFoundError
         return record
 
+    async def probe(self) -> None:
+        await self.store.probe()
+
     async def cancel(self, run_id: str) -> RunRecord:
         record = await self.get(run_id)
         if record.terminal:
             return record
         await self.engine.cancel(run_id)
+        await self._resolve_pending_approval(record, "cancelled")
         await self.store.append(run_id, "run.cancelled")
-        return record
+        return await self.get(run_id)
 
     async def _execute(
         self,
         record: RunRecord,
         invocation: StartRunRequest,
+        resumed: bool = False,
     ) -> None:
-        await self.store.append(record.run_id, "run.started")
+        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))
+        run_trace = AgentRunTrace(record)
+        run_trace.start()
+        final_status = "unknown"
+        lease_task.add_done_callback(
+            lambda completed: cancel_on_lease_loss(completed, execution_task)
+        )
         try:
+            await self.store.append(
+                record.run_id,
+                "run.resumed" if resumed else "run.started",
+            )
+            if invocation.artifacts and not self.artifact_loader:
+                raise SafeEngineError(
+                    "RUNTIME_UNAVAILABLE",
+                    "Agent Artifact Runtime 未配置",
+                    retryable=True,
+                )
+            prepared = (
+                await self.artifact_loader.prepare(
+                    invocation.artifacts,
+                    invocation.input_modalities,
+                    invocation.limits,
+                )
+                if self.artifact_loader
+                else ()
+            )
             request = EngineRunRequest(
                 run_id=record.run_id,
                 operation_key=record.operation_key,
-                input=record.input,
+                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,
@@ -91,12 +200,26 @@ class AgentRunService:
                 execution_grant=invocation.execution_grant,
                 tool_host_url=invocation.tool_host_url,
             )
-            async with asyncio.timeout(invocation.limits.max_duration_seconds):
+            approval_timeout = max(
+                (
+                    tool.approval_timeout_seconds or 0
+                    for tool in invocation.allowed_tools
+                    if tool.approval == "required"
+                ),
+                default=0,
+            )
+            async with asyncio.timeout(
+                max(
+                    invocation.limits.max_duration_seconds,
+                    approval_timeout + (5 if approval_timeout else 0),
+                )
+            ):
                 async for signal in self.engine.execute(request):
                     if isinstance(signal, EngineCompleted):
                         await self.store.complete(record.run_id, signal.output)
                         return
-                    await self._append_signal(record.run_id, signal)
+                    event_type, fields = canonical_signal_event(signal)
+                    await self.store.append(record.run_id, event_type, fields)
             await self._fail(
                 record.run_id,
                 SafeEngineError(
@@ -108,6 +231,8 @@ class AgentRunService:
         except SafeEngineError as error:
             await self._fail(record.run_id, error)
         except TimeoutError:
+            current = await self.get(record.run_id)
+            await self._resolve_pending_approval(current, "timed-out")
             await self._fail(
                 record.run_id,
                 SafeEngineError(
@@ -116,6 +241,18 @@ class AgentRunService:
                     retryable=True,
                 ),
             )
+        except asyncio.CancelledError:
+            if lease_failed(lease_task):
+                await self._fail(
+                    record.run_id,
+                    SafeEngineError(
+                        "RUNTIME_UNAVAILABLE",
+                        "Agent Run 租约已丢失",
+                        retryable=True,
+                    ),
+                )
+                return
+            raise
         except Exception:
             await self._fail(
                 record.run_id,
@@ -125,36 +262,71 @@ class AgentRunService:
                     retryable=True,
                 ),
             )
+        finally:
+            try:
+                lease_task.cancel()
+                await asyncio.gather(lease_task, return_exceptions=True)
+                final_record = await self.store.get(record.run_id)
+                if final_record and final_record.terminal:
+                    await self.store.clear_invocation(record.run_id)
+                if final_record:
+                    final_status = final_record.status
+                try:
+                    await self.store.release_lease(record.run_id)
+                except KeyError:
+                    pass
+            finally:
+                run_trace.finish(final_status)
 
-    async def _append_signal(self, run_id: str, signal: object) -> None:
-        if isinstance(signal, OutputDelta):
-            await self.store.append(run_id, "output.delta", {"text": signal.text})
-        elif isinstance(signal, ToolRequested):
-            await self.store.append(
-                run_id,
-                "tool.requested",
-                {"toolCallId": signal.tool_call_id, "toolKey": signal.tool_key},
-            )
-        elif isinstance(signal, ApprovalRequired):
-            await self.store.append(
-                run_id,
-                "approval.required",
-                {"workItemId": signal.work_item_id},
-            )
-        elif isinstance(signal, ToolCompleted):
-            await self.store.append(
-                run_id,
-                "tool.completed",
-                {"toolCallId": signal.tool_call_id},
-            )
-        elif isinstance(signal, UsageReported):
+    def _spawn(
+        self,
+        record: RunRecord,
+        request: StartRunRequest,
+        resumed: bool = False,
+    ) -> None:
+        if record.run_id in self._active_run_ids:
+            return
+        self._active_run_ids.add(record.run_id)
+        task = asyncio.create_task(self._execute(record, request, resumed))
+        self._tasks.add(task)
+        task.add_done_callback(
+            lambda completed: self._completed(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 _resolve_pending_approval(
+        self,
+        record: RunRecord,
+        outcome: str,
+    ) -> None:
+        pending: dict[str, object] | None = None
+        for event in record.events:
+            if event.get("type") == "approval.required":
+                pending = event
+            elif event.get("type") == "approval.resolved":
+                pending = None
+        if not pending:
+            return
+        work_item_id = pending.get("workItemId")
+        tool_call_id = pending.get("toolCallId")
+        if isinstance(work_item_id, str) and isinstance(tool_call_id, str):
             await self.store.append(
-                run_id,
-                "usage.reported",
-                {"usage": signal.usage},
+                record.run_id,
+                "approval.resolved",
+                {
+                    "workItemId": work_item_id,
+                    "toolCallId": tool_call_id,
+                    "outcome": outcome,
+                },
             )
-        else:
-            raise TypeError("unsupported engine signal")
 
     async def _fail(self, run_id: str, failure: SafeEngineError) -> None:
         error = AgentError(
@@ -170,14 +342,4 @@ class AgentRunService:
         )
 
 
-def request_fingerprint(operation_key: str, input_value: JsonValue) -> str:
-    encoded = json.dumps(
-        {"operationKey": operation_key, "input": input_value},
-        ensure_ascii=False,
-        separators=(",", ":"),
-        sort_keys=True,
-    ).encode()
-    return hashlib.sha256(encoded).hexdigest()
-
-
 __all__ = ["AgentRunService", "IdempotencyConflictError"]

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

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from .engine import (
+    ApprovalRequired,
+    ApprovalResolved,
+    OutputDelta,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
+)
+
+
+def canonical_signal_event(signal: object) -> tuple[str, dict[str, object]]:
+    if isinstance(signal, OutputDelta):
+        return "output.delta", {"text": signal.text}
+    if isinstance(signal, ToolRequested):
+        return "tool.requested", {
+            "toolCallId": signal.tool_call_id,
+            "toolKey": signal.tool_key,
+        }
+    if isinstance(signal, ApprovalRequired):
+        return "approval.required", {
+            "workItemId": signal.work_item_id,
+            "toolCallId": signal.tool_call_id,
+        }
+    if isinstance(signal, ApprovalResolved):
+        return "approval.resolved", {
+            "workItemId": signal.work_item_id,
+            "toolCallId": signal.tool_call_id,
+            "outcome": signal.outcome,
+        }
+    if isinstance(signal, ToolCompleted):
+        return "tool.completed", {"toolCallId": signal.tool_call_id}
+    if isinstance(signal, UsageReported):
+        return "usage.reported", {"usage": signal.usage}
+    raise TypeError("unsupported engine signal")