create-windy 0.4.0 → 0.5.0

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

@@ -14,9 +14,22 @@ from .adk_failure import AdkFailureState
 from .contracts import JsonValue
 from .engine import EngineRunRequest, SafeEngineError
 from .multimodal import attach_artifacts
-from .openai_engine import cancelled, parse_arguments
+from .openai_engine_validation import (
+    attempt_outcome,
+    cancelled,
+    parse_arguments,
+)
 from .openai_provider import OpenAiCompatibleProvider, ProviderTurn
 from .provider_governance import ProviderRequestGovernance
+from .report_lifecycle import (
+    finish_attempt_report_safely,
+    start_attempt_report_safely,
+)
+from .report_store import (
+    AgentRuntimeReportStore,
+    InMemoryAgentRuntimeReportStore,
+)
+from .report_types import UsageFacts
 
 
 class GovernedOpenAiLlm(BaseLlm):
@@ -27,6 +40,7 @@ class GovernedOpenAiLlm(BaseLlm):
     _governance: ProviderRequestGovernance = PrivateAttr()
     _cancellation: asyncio.Event = PrivateAttr()
     _failures: AdkFailureState = PrivateAttr()
+    _report_store: AgentRuntimeReportStore = PrivateAttr()
     _attempt: int = PrivateAttr(default=0)
 
     def __init__(
@@ -36,6 +50,7 @@ class GovernedOpenAiLlm(BaseLlm):
         governance: ProviderRequestGovernance,
         cancellation: asyncio.Event,
         failures: AdkFailureState,
+        report_store: AgentRuntimeReportStore | None = None,
     ) -> None:
         super().__init__(model=provider.config.model)
         self._request = request
@@ -43,6 +58,7 @@ class GovernedOpenAiLlm(BaseLlm):
         self._governance = governance
         self._cancellation = cancellation
         self._failures = failures
+        self._report_store = report_store or InMemoryAgentRuntimeReportStore()
 
     async def generate_content_async(
         self,
@@ -50,6 +66,9 @@ class GovernedOpenAiLlm(BaseLlm):
         stream: bool = False,
     ) -> AsyncGenerator[LlmResponse, None]:
         del stream
+        report_attempt = None
+        finalized = False
+        turn: ProviderTurn | None = None
         try:
             cancelled(self._cancellation)
             self._attempt += 1
@@ -59,6 +78,16 @@ class GovernedOpenAiLlm(BaseLlm):
                     "Agent Tool 调用轮次超过上限",
                     retryable=False,
                 )
+            report_attempt = await start_attempt_report_safely(
+                self._report_store,
+                self._request.run_id,
+                self._attempt,
+                self._provider.config.deployment_key,
+                self._provider.config.model,
+            )
+            attempt_sequence = (
+                report_attempt.sequence if report_attempt else self._attempt
+            )
             messages = attach_artifacts(
                 adk_messages(llm_request, self._request.instructions),
                 self._request.artifacts,
@@ -67,7 +96,7 @@ class GovernedOpenAiLlm(BaseLlm):
                 deployment_key=self._provider.config.deployment_key,
                 operation_key=self._request.operation_key,
                 run_id=self._request.run_id,
-                attempt=self._attempt,
+                attempt=attempt_sequence,
                 messages=messages,
                 tools=self._request.allowed_tools,
                 policy=self._request.provider_data_policy,
@@ -96,11 +125,42 @@ class GovernedOpenAiLlm(BaseLlm):
                 turn,
                 {tool.key for tool in self._request.allowed_tools},
             )
-            async for response in responses_for_turn(turn):
+            await finish_attempt_report_safely(
+                self._report_store,
+                report_attempt,
+                "completed",
+                turn.usage,
+                reported_model=turn.reported_model,
+            )
+            finalized = True
+            async for response in responses_for_turn(
+                turn,
+                attempt_sequence,
+            ):
                 yield response
         except SafeEngineError as error:
+            if not finalized:
+                await finish_attempt_report_safely(
+                    self._report_store,
+                    report_attempt,
+                    attempt_outcome(error),
+                    turn.usage if turn else UsageFacts(),
+                    reported_model=turn.reported_model if turn else None,
+                    safe_error_code=error.code,
+                )
             self._failures.capture(error)
             raise
+        except Exception:
+            if not finalized:
+                await finish_attempt_report_safely(
+                    self._report_store,
+                    report_attempt,
+                    "failed",
+                    turn.usage if turn else UsageFacts(),
+                    reported_model=turn.reported_model if turn else None,
+                    safe_error_code="RUNTIME_UNAVAILABLE",
+                )
+            raise
 
 
 def adk_messages(
@@ -179,9 +239,13 @@ def validate_tool_calls(turn: ProviderTurn, allowed: set[str]) -> None:
 
 async def responses_for_turn(
     turn: ProviderTurn,
+    attempt_sequence: int,
 ) -> AsyncGenerator[LlmResponse, None]:
-    usage = turn.usage or {"source": "unknown"}
-    metadata = {"southwindUsage": usage}
+    usage = turn.usage.event_value()
+    metadata = {
+        "southwindUsage": usage,
+        "southwindAttemptSequence": attempt_sequence,
+    }
     if turn.tool_calls:
         yield LlmResponse(
             content=types.Content(
@@ -222,7 +286,7 @@ async def responses_for_turn(
 
 
 def adk_usage(
-    usage: dict[str, JsonValue],
+    usage: dict[str, str | int],
 ) -> types.GenerateContentResponseUsageMetadata | None:
     input_tokens = usage.get("inputTokens")
     output_tokens = usage.get("outputTokens")

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

@@ -16,7 +16,7 @@ from .engine import (
     EngineSignal,
     SafeEngineError,
 )
-from .openai_engine import cancelled
+from .openai_engine_validation import cancelled
 from .tool_host import (
     ToolApprovalPending,
     ToolApprovalResolved,

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

@@ -29,16 +29,21 @@ from .http_helpers import (
     provider_governance_snapshot,
     safe_error,
 )
-from .runtime_factory import default_engine, default_store
+from .report_routes import create_report_router
+from .report_store import AgentRuntimeReportStore
+from .runtime_factory import (
+    default_engine,
+    default_report_store,
+    default_store,
+)
 from .service import (
     AgentRunService,
-    IdempotencyConflictError,
     OperationNotFoundError,
     RunNotFoundError,
 )
 from .sqlite_store import RunStoreCapacityError
 from .sse import event_stream
-from .store import ReleaseNotFoundError, RunStore
+from .store import IdempotencyConflictError, ReleaseNotFoundError, RunStore
 from .telemetry import configure_telemetry
 
 
@@ -48,12 +53,15 @@ def create_app(
     heartbeat_seconds: float = 15.0,
     internal_token: str | None = None,
     store: RunStore | None = None,
+    report_store: AgentRuntimeReportStore | None = None,
 ) -> FastAPI:
     configure_telemetry()
-    runtime_engine = engine or default_engine()
+    runtime_report_store = report_store or default_report_store()
+    runtime_engine = engine or default_engine(runtime_report_store)
     runtime = AgentRunService(
         runtime_engine,
         store or default_store(),
+        runtime_report_store,
         (
             ArtifactLoader(
                 os.environ.get(
@@ -80,6 +88,9 @@ def create_app(
         version="0.1.0",
         lifespan=lifespan,
     )
+    application.include_router(
+        create_report_router(runtime_report_store, internal_token)
+    )
 
     @application.get("/health/live")
     async def live() -> dict[str, str]:
@@ -322,6 +333,7 @@ def create_app(
         )
 
     application.state.run_service = runtime
+    application.state.report_store = runtime_report_store
     return application
 
 

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

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .store import RunRecord, RunStore
+
+
+async def resolve_pending_approval(
+    store: RunStore,
+    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 store.append(
+            record.run_id,
+            "approval.resolved",
+            {
+                "workItemId": work_item_id,
+                "toolCallId": tool_call_id,
+                "outcome": outcome,
+            },
+        )

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

@@ -139,6 +139,14 @@ class RuntimeRelease(CanonicalModel):
     manifest_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
 
 
+class RunReportingContext(CanonicalModel):
+    """Trusted platform metadata for reporting, never an authorization fact."""
+
+    actor_id: str = Field(min_length=1, max_length=64)
+    actor_type: str = Field(min_length=1, max_length=32)
+    department_id: str | None = Field(default=None, max_length=64)
+
+
 def legacy_release() -> RuntimeRelease:
     return RuntimeRelease(
         release_id="legacy",
@@ -174,6 +182,7 @@ class StartRunRequest(CanonicalModel):
     tool_host_url: str = ""
     release: RuntimeRelease = Field(default_factory=legacy_release)
     trace_id: str = Field(default="", max_length=160)
+    reporting: RunReportingContext | 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 .report_types import UsageFacts
 
 
 class DeterministicEngineAdapter:
@@ -49,7 +50,7 @@ class DeterministicEngineAdapter:
                 if isinstance(input_text, str):
                     text = input_text
             yield OutputDelta(text)
-            yield UsageReported({"source": "unknown"})
+            yield UsageReported(1, UsageFacts())
             yield EngineCompleted(request.input)
         finally:
             self._cancellations.pop(request.run_id, None)

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

@@ -13,6 +13,7 @@ from .contracts import (
     RuntimeToolDefinition,
     ToolNetworkPolicy,
 )
+from .report_types import UsageFacts
 
 
 @dataclass(frozen=True)
@@ -75,7 +76,8 @@ class ToolCompleted:
 
 @dataclass(frozen=True)
 class UsageReported:
-    usage: dict[str, JsonValue]
+    attempt_sequence: int
+    usage: UsageFacts
 
 
 @dataclass(frozen=True)

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

@@ -19,8 +19,29 @@ from .engine import (
     UsageReported,
 )
 from .multimodal import attach_artifacts, final_output
-from .openai_provider import OpenAiCompatibleProvider, ProviderToolCall
+from .openai_engine_validation import (
+    assistant_tool_message,
+    attempt_outcome,
+    cancelled,
+    parse_arguments,
+    validate_provider_tool_calls,
+    validate_runtime_request,
+)
+from .openai_provider import (
+    OpenAiCompatibleProvider,
+    ProviderToolCall,
+    ProviderTurn,
+)
 from .provider_governance import ProviderRequestGovernance
+from .report_lifecycle import (
+    finish_attempt_report_safely,
+    start_attempt_report_safely,
+)
+from .report_store import (
+    AgentRuntimeReportStore,
+    InMemoryAgentRuntimeReportStore,
+)
+from .report_types import UsageFacts
 from .tool_host import (
     ToolApprovalPending,
     ToolApprovalResolved,
@@ -36,10 +57,12 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         provider: OpenAiCompatibleProvider,
         tool_host: ToolHostClient,
         governance: ProviderRequestGovernance,
+        report_store: AgentRuntimeReportStore | None = None,
     ) -> None:
         self._provider = provider
         self._tool_host = tool_host
         self._governance = governance
+        self._report_store = report_store or InMemoryAgentRuntimeReportStore()
         self._cancellations: dict[str, asyncio.Event] = {}
 
     @property
@@ -79,34 +102,79 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         try:
             for attempt in range(1, self._provider.config.max_tool_rounds + 1):
                 cancelled(cancellation)
-                governed = self._governance.authorize(
-                    deployment_key=self._provider.config.deployment_key,
-                    operation_key=request.operation_key,
-                    run_id=request.run_id,
-                    attempt=attempt,
-                    messages=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 messages, tools, schema: len(
-                        self._provider.request_body(
-                            messages,
-                            tools,
-                            request.output_schema_key,
-                            schema,
-                        )
-                    ),
+                report_attempt = await start_attempt_report_safely(
+                    self._report_store,
+                    request.run_id,
+                    attempt,
+                    self._provider.config.deployment_key,
+                    self._provider.config.model,
                 )
-                turn = await self._provider.complete_turn(
-                    governed.messages,
-                    governed.tools,
-                    request.output_schema_key,
-                    governed.output_schema,
+                attempt_sequence = (
+                    report_attempt.sequence if report_attempt else attempt
                 )
+                finalized = False
+                turn: ProviderTurn | None = None
+                try:
+                    governed = self._governance.authorize(
+                        deployment_key=self._provider.config.deployment_key,
+                        operation_key=request.operation_key,
+                        run_id=request.run_id,
+                        attempt=attempt_sequence,
+                        messages=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 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,
+                    )
+                    validate_provider_tool_calls(turn.tool_calls, allowed)
+                    await finish_attempt_report_safely(
+                        self._report_store,
+                        report_attempt,
+                        "completed",
+                        turn.usage,
+                        reported_model=turn.reported_model,
+                    )
+                    finalized = True
+                except SafeEngineError as error:
+                    if not finalized:
+                        await finish_attempt_report_safely(
+                            self._report_store,
+                            report_attempt,
+                            attempt_outcome(error),
+                            turn.usage if turn else UsageFacts(),
+                            reported_model=(turn.reported_model if turn else None),
+                            safe_error_code=error.code,
+                        )
+                    raise
+                except Exception:
+                    if not finalized:
+                        await finish_attempt_report_safely(
+                            self._report_store,
+                            report_attempt,
+                            "failed",
+                            turn.usage if turn else UsageFacts(),
+                            reported_model=(turn.reported_model if turn else None),
+                            safe_error_code="RUNTIME_UNAVAILABLE",
+                        )
+                    raise
+                yield UsageReported(attempt_sequence, turn.usage)
                 if turn.tool_calls:
                     messages.append(assistant_tool_message(turn.tool_calls))
                     async for signal in self._execute_tools(
@@ -127,7 +195,6 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
                             retryable=False,
                         )
                     yield OutputDelta(delta)
-                yield UsageReported(turn.usage or {"source": "unknown"})
                 yield EngineCompleted(final_output(turn.text, governed.output_schema))
                 return
             raise SafeEngineError(
@@ -231,105 +298,3 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
 
     def governance_health(self) -> dict[str, int | float | str | None]:
         return self._governance.health()
-
-
-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()
-        or not request.user_prompt.strip()
-        or not request.execution_grant.strip()
-        or not request.tool_host_url.strip()
-    ):
-        raise SafeEngineError(
-            "INVALID_INPUT",
-            "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
-    ):
-        raise SafeEngineError(
-            "FORBIDDEN",
-            "Agent Operation 未授权当前模型部署出网",
-            retryable=False,
-        )
-    if request.tool_network_policy.mode != "forbidden":
-        raise SafeEngineError(
-            "TOOL_DENIED",
-            "Agent Tool 网络策略不受支持",
-            retryable=False,
-        )
-    if (
-        not request.provider_data_policy.input_fields
-        or not request.provider_data_policy.envelope_fields
-    ):
-        raise SafeEngineError(
-            "FORBIDDEN",
-            "Agent Operation 缺少 Provider 字段治理策略",
-            retryable=False,
-        )
-
-
-def cancelled(event: asyncio.Event) -> None:
-    if event.is_set():
-        raise SafeEngineError(
-            "RUN_CANCELLED",
-            "Agent Run 已取消",
-            retryable=False,
-        )
-
-
-def parse_arguments(raw: str) -> dict[str, JsonValue]:
-    try:
-        value = json.loads(raw or "{}")
-    except json.JSONDecodeError:
-        raise SafeEngineError(
-            "TOOL_DENIED",
-            "Agent Tool 参数无效",
-            retryable=False,
-        ) from None
-    if not isinstance(value, dict):
-        raise SafeEngineError(
-            "TOOL_DENIED",
-            "Agent Tool 参数必须是对象",
-            retryable=False,
-        )
-    return value
-
-
-def assistant_tool_message(
-    calls: list[ProviderToolCall],
-) -> dict[str, JsonValue]:
-    return {
-        "role": "assistant",
-        "content": None,
-        "tool_calls": [
-            {
-                "id": call.call_id,
-                "type": "function",
-                "function": {
-                    "name": call.name,
-                    "arguments": call.arguments,
-                },
-            }
-            for call in calls
-        ],
-    }