create-windy 0.4.0 → 0.5.0

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

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Literal, Protocol
+
+from .contracts import StartRunRequest
+from .report_metrics import AgentRuntimeMetrics
+from .report_presenter import (
+    aggregate_summary,
+    attempt_value,
+    attempts_for,
+    filtered_attempts,
+    filtered_runs,
+    run_value,
+    scoped_runs,
+)
+from .report_types import (
+    AttemptReport,
+    AttemptTerminalOutcome,
+    NonTerminalRunStatus,
+    ReportFilter,
+    RunReport,
+    UsageFacts,
+    identity,
+    retention_seconds,
+    validate_retention,
+)
+
+
+class AgentRuntimeReportStore(Protocol):
+    retention_days: int
+    metrics: AgentRuntimeMetrics
+
+    async def ensure_run(
+        self, run_id: str, request: StartRunRequest, created_at: float
+    ) -> None: ...
+
+    async def start_run(self, run_id: str, started_at: float) -> None: ...
+
+    async def set_run_status(
+        self,
+        run_id: str,
+        status: NonTerminalRunStatus,
+        updated_at: float,
+    ) -> None: ...
+
+    async def finish_run(
+        self,
+        run_id: str,
+        status: Literal["completed", "failed", "cancelled"],
+        finished_at: float,
+        safe_error_code: str | None = None,
+    ) -> None: ...
+
+    async def start_attempt(
+        self,
+        run_id: str,
+        tool_round: int,
+        deployment_key: str,
+        requested_model: str,
+        started_at: float,
+    ) -> AttemptReport: ...
+
+    async def finish_attempt(
+        self,
+        attempt_id: str,
+        outcome: AttemptTerminalOutcome,
+        usage: UsageFacts,
+        finished_at: float,
+        reported_model: str | None = None,
+        safe_error_code: str | None = None,
+    ) -> None: ...
+
+    async def summary(self, query: ReportFilter) -> dict[str, object]: ...
+
+    async def list_runs(
+        self, query: ReportFilter, page: int, page_size: int
+    ) -> dict[str, object]: ...
+
+    async def get_run(self, run_id: str) -> dict[str, object] | None: ...
+
+    async def close(self) -> None: ...
+
+
+class InMemoryAgentRuntimeReportStore:
+    def __init__(
+        self,
+        retention_days: int = 90,
+        *,
+        now: Callable[[], float] = time.time,
+        metrics: AgentRuntimeMetrics | None = None,
+    ) -> None:
+        validate_retention(retention_days)
+        self.retention_days = retention_days
+        self._now = now
+        self.metrics = metrics or AgentRuntimeMetrics()
+        self._runs: dict[str, RunReport] = {}
+        self._attempts: dict[str, AttemptReport] = {}
+        self._lock = asyncio.Lock()
+
+    async def ensure_run(
+        self, run_id: str, request: StartRunRequest, created_at: float
+    ) -> None:
+        async with self._lock:
+            self._prune()
+            context = request.reporting
+            candidate = RunReport(
+                run_id=run_id,
+                operation_key=request.operation_key,
+                release_id=request.release.release_id,
+                trace_id=request.trace_id,
+                actor_id=context.actor_id if context else None,
+                actor_type=context.actor_type if context else None,
+                department_id=context.department_id if context else None,
+                status="accepted",
+                safe_error_code=None,
+                started_at=None,
+                finished_at=None,
+                duration_ms=None,
+                created_at=created_at,
+                updated_at=created_at,
+                expires_at=created_at + retention_seconds(self.retention_days),
+            )
+            existing = self._runs.get(run_id)
+            if existing and identity(existing) != identity(candidate):
+                raise ValueError("Agent Runtime 报表 Run 身份冲突")
+            if existing is None:
+                self._runs[run_id] = candidate
+
+    async def start_run(self, run_id: str, started_at: float) -> None:
+        async with self._lock:
+            run = self._runs[run_id]
+            if run.status in {"completed", "failed", "cancelled"}:
+                return
+            for attempt_id, attempt in self._attempts.items():
+                if attempt.run_id != run_id or attempt.outcome != "running":
+                    continue
+                usage = UsageFacts()
+                self._attempts[attempt_id] = replace(
+                    attempt,
+                    outcome="abandoned",
+                    usage=usage,
+                    duration_ms=max(
+                        0,
+                        round((started_at - attempt.started_at) * 1_000),
+                    ),
+                    finished_at=started_at,
+                )
+                self.metrics.observe_attempt("abandoned", usage)
+            self._runs[run_id] = replace(
+                run,
+                status="running",
+                started_at=run.started_at or started_at,
+                updated_at=started_at,
+            )
+
+    async def set_run_status(
+        self,
+        run_id: str,
+        status: NonTerminalRunStatus,
+        updated_at: float,
+    ) -> None:
+        async with self._lock:
+            run = self._runs[run_id]
+            if run.status in {"completed", "failed", "cancelled"}:
+                return
+            if updated_at < run.updated_at:
+                return
+            self._runs[run_id] = replace(
+                run,
+                status=status,
+                updated_at=updated_at,
+            )
+
+    async def finish_run(
+        self,
+        run_id: str,
+        status: Literal["completed", "failed", "cancelled"],
+        finished_at: float,
+        safe_error_code: str | None = None,
+    ) -> None:
+        async with self._lock:
+            run = self._runs[run_id]
+            if run.status in {"completed", "failed", "cancelled"}:
+                if run.status != status:
+                    raise ValueError("Agent Runtime 报表终态冲突")
+                return
+            started = run.started_at or run.created_at
+            self._runs[run_id] = replace(
+                run,
+                status=status,
+                safe_error_code=safe_error_code,
+                finished_at=finished_at,
+                duration_ms=max(0, round((finished_at - started) * 1_000)),
+                updated_at=finished_at,
+                expires_at=finished_at + retention_seconds(self.retention_days),
+            )
+            self.metrics.observe_run(status)
+
+    async def start_attempt(
+        self,
+        run_id: str,
+        tool_round: int,
+        deployment_key: str,
+        requested_model: str,
+        started_at: float,
+    ) -> AttemptReport:
+        async with self._lock:
+            sequence = 1 + max(
+                (
+                    attempt.sequence
+                    for attempt in self._attempts.values()
+                    if attempt.run_id == run_id
+                ),
+                default=0,
+            )
+            attempt = AttemptReport(
+                attempt_id=f"attempt_{uuid.uuid4().hex}",
+                run_id=run_id,
+                sequence=sequence,
+                tool_round=tool_round,
+                deployment_key=deployment_key,
+                requested_model=requested_model,
+                reported_model=None,
+                outcome="running",
+                usage=UsageFacts(),
+                duration_ms=None,
+                safe_error_code=None,
+                started_at=started_at,
+                finished_at=None,
+            )
+            self._attempts[attempt.attempt_id] = attempt
+            return attempt
+
+    async def finish_attempt(
+        self,
+        attempt_id: str,
+        outcome: AttemptTerminalOutcome,
+        usage: UsageFacts,
+        finished_at: float,
+        reported_model: str | None = None,
+        safe_error_code: str | None = None,
+    ) -> None:
+        async with self._lock:
+            attempt = self._attempts[attempt_id]
+            if attempt.finished_at is not None:
+                if (
+                    attempt.outcome != outcome
+                    or attempt.usage != usage
+                    or attempt.reported_model != reported_model
+                    or attempt.safe_error_code != safe_error_code
+                ):
+                    raise ValueError("Agent Runtime 报表 Attempt 终态冲突")
+                return
+            self._attempts[attempt_id] = replace(
+                attempt,
+                outcome=outcome,
+                usage=usage,
+                reported_model=reported_model,
+                safe_error_code=safe_error_code,
+                duration_ms=max(0, round((finished_at - attempt.started_at) * 1_000)),
+                finished_at=finished_at,
+            )
+            self.metrics.observe_attempt(outcome, usage)
+
+    async def summary(self, query: ReportFilter) -> dict[str, object]:
+        async with self._lock:
+            self._prune()
+            visible_runs = scoped_runs(self._runs.values(), query)
+            runs = filtered_runs(visible_runs, query)
+            attempts = filtered_attempts(
+                self._attempts.values(),
+                visible_runs,
+                query,
+            )
+            return aggregate_summary(
+                runs,
+                attempts,
+                self.retention_days,
+                min(
+                    [run.created_at for run in runs]
+                    + [attempt.started_at for attempt in attempts],
+                    default=None,
+                ),
+                self._now(),
+            )
+
+    async def list_runs(
+        self, query: ReportFilter, page: int, page_size: int
+    ) -> dict[str, object]:
+        async with self._lock:
+            self._prune()
+            runs = sorted(
+                filtered_runs(self._runs.values(), query),
+                key=lambda run: run.created_at,
+                reverse=True,
+            )
+            start = (page - 1) * page_size
+            items = [
+                run_value(run, attempts_for(self._attempts.values(), [run]))
+                for run in runs[start : start + page_size]
+            ]
+            return {
+                "items": items,
+                "total": len(runs),
+                "page": page,
+                "pageSize": page_size,
+            }
+
+    async def get_run(self, run_id: str) -> dict[str, object] | None:
+        async with self._lock:
+            self._prune()
+            run = self._runs.get(run_id)
+            if run is None:
+                return None
+            attempts = attempts_for(self._attempts.values(), [run])
+            return {
+                **run_value(run, attempts),
+                "releaseId": run.release_id,
+                "traceId": run.trace_id,
+                "safeErrorCode": run.safe_error_code,
+                "attempts": [attempt_value(item) for item in attempts],
+            }
+
+    async def close(self) -> None:
+        return None
+
+    def _prune(self) -> None:
+        expired = {
+            run_id
+            for run_id, run in self._runs.items()
+            if run.expires_at <= self._now()
+        }
+        for run_id in expired:
+            self._runs.pop(run_id, None)
+        self._attempts = {
+            key: value
+            for key, value in self._attempts.items()
+            if value.run_id not in expired
+        }

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

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Literal
+
+from .contracts import RunStatus
+
+type AttemptTerminalOutcome = Literal[
+    "completed", "failed", "cancelled", "blocked", "abandoned"
+]
+type AttemptOutcome = Literal["running"] | AttemptTerminalOutcome
+type NonTerminalRunStatus = Literal["running", "awaiting-approval"]
+type CacheStatus = Literal["hit", "miss", "unknown"]
+type UsageSource = Literal["provider-reported", "estimated", "unknown"]
+
+
+@dataclass(frozen=True)
+class UsageFacts:
+    source: UsageSource = "unknown"
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cached_input_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    total_tokens: int | None = None
+    first_token_latency_ms: int | None = None
+    cache_status: CacheStatus = "unknown"
+
+    def event_value(self) -> dict[str, str | int]:
+        result: dict[str, str | int] = {
+            "source": self.source,
+            "cacheStatus": self.cache_status,
+        }
+        for key, value in (
+            ("inputTokens", self.input_tokens),
+            ("outputTokens", self.output_tokens),
+            ("cachedInputTokens", self.cached_input_tokens),
+            ("reasoningTokens", self.reasoning_tokens),
+            ("totalTokens", self.total_tokens),
+            ("firstTokenLatencyMs", self.first_token_latency_ms),
+        ):
+            if value is not None:
+                result[key] = value
+        return result
+
+
+@dataclass(frozen=True)
+class RunReport:
+    run_id: str
+    operation_key: str
+    release_id: str
+    trace_id: str
+    actor_id: str | None
+    actor_type: str | None
+    department_id: str | None
+    status: RunStatus
+    safe_error_code: str | None
+    started_at: float | None
+    finished_at: float | None
+    duration_ms: int | None
+    created_at: float
+    updated_at: float
+    expires_at: float
+
+
+@dataclass(frozen=True)
+class AttemptReport:
+    attempt_id: str
+    run_id: str
+    sequence: int
+    tool_round: int
+    deployment_key: str
+    requested_model: str
+    reported_model: str | None
+    outcome: AttemptOutcome
+    usage: UsageFacts
+    duration_ms: int | None
+    safe_error_code: str | None
+    started_at: float
+    finished_at: float | None
+
+
+@dataclass(frozen=True)
+class ReportFilter:
+    from_timestamp: float
+    to_timestamp: float
+    selected_actor_id: str | None = None
+    scope_restricted: bool = False
+    actor_ids: tuple[str, ...] = ()
+    department_ids: tuple[str, ...] = ()
+
+
+def validate_retention(value: int) -> None:
+    if not 1 <= value <= 3650:
+        raise ValueError("AI Runtime 报表留存天数超出范围")
+
+
+def retention_seconds(days: int) -> int:
+    return days * 24 * 60 * 60
+
+
+def iso(value: float | None) -> str | None:
+    return (
+        datetime.fromtimestamp(value, tz=UTC).isoformat().replace("+00:00", "Z")
+        if value is not None
+        else None
+    )
+
+
+def identity(run: RunReport) -> tuple[str, str, str, str | None]:
+    return (run.operation_key, run.release_id, run.trace_id, run.actor_id)

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

@@ -6,19 +6,26 @@ from .adk_adapter import AdkEngineAdapter
 from .config import EnvironmentSecretResolver, OpenAiCompatibleConfig
 from .engine import AgentEngineAdapter
 from .openai_provider import OpenAiCompatibleProvider
+from .postgres_report_store import PostgresAgentRuntimeReportStore
 from .postgres_store import PostgresRunStore
 from .provider_audit import ProviderAuditStore
 from .provider_governance import ProviderRequestGovernance
+from .report_store import (
+    AgentRuntimeReportStore,
+    InMemoryAgentRuntimeReportStore,
+)
 from .sqlite_store import SqliteRunStore
 from .store import InMemoryRunStore, RunStore
 from .store_cipher import RunStoreCipher
 from .tool_host import ToolHostClient
 
 
-def default_engine() -> AgentEngineAdapter:
+def default_engine(
+    report_store: AgentRuntimeReportStore | None = None,
+) -> AgentEngineAdapter:
     config = OpenAiCompatibleConfig.from_environment()
     if config is None:
-        return AdkEngineAdapter()
+        return AdkEngineAdapter(report_store=report_store)
     internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
     if not internal_token:
         raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
@@ -34,6 +41,7 @@ def default_engine() -> AgentEngineAdapter:
                 retention_days=provider_audit_retention_days(),
             )
         ),
+        report_store,
     )
 
 
@@ -50,6 +58,16 @@ def default_store() -> RunStore:
     )
 
 
+def default_report_store() -> AgentRuntimeReportStore:
+    database_url = os.environ.get("AGENT_DATABASE_URL", "").strip()
+    retention_days = report_retention_days()
+    return (
+        PostgresAgentRuntimeReportStore(database_url, retention_days)
+        if database_url
+        else InMemoryAgentRuntimeReportStore(retention_days)
+    )
+
+
 def required_environment(key: str) -> str:
     value = os.environ.get(key, "").strip()
     if not value:
@@ -66,3 +84,14 @@ def provider_audit_retention_days() -> int:
     if not 1 <= value <= 3650:
         raise ValueError("AI_PROVIDER_AUDIT_RETENTION_DAYS 超出允许范围")
     return value
+
+
+def report_retention_days() -> int:
+    raw = os.environ.get("AI_RUNTIME_REPORT_RETENTION_DAYS", "90")
+    try:
+        value = int(raw)
+    except ValueError as error:
+        raise ValueError("AI_RUNTIME_REPORT_RETENTION_DAYS 必须是整数") from error
+    if not 1 <= value <= 3650:
+        raise ValueError("AI_RUNTIME_REPORT_RETENTION_DAYS 超出允许范围")
+    return value