create-windy 0.4.0 → 0.5.0

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

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import asyncio
+import json
+
+from .contracts import JsonValue
+from .engine import EngineRunRequest, SafeEngineError
+from .openai_provider import ProviderToolCall
+from .report_types import AttemptTerminalOutcome
+
+
+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
+        ],
+    }
+
+
+def validate_provider_tool_calls(
+    calls: list[ProviderToolCall],
+    allowed: set[str],
+) -> None:
+    for call in calls:
+        if not call.call_id or not call.name or call.name not in allowed:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "模型请求了未授权 Tool",
+                retryable=False,
+            )
+        parse_arguments(call.arguments)
+
+
+def attempt_outcome(error: SafeEngineError) -> AttemptTerminalOutcome:
+    if error.code == "RUN_CANCELLED":
+        return "cancelled"
+    if error.code in {"FORBIDDEN", "INVALID_INPUT", "TOOL_DENIED"}:
+        return "blocked"
+    return "failed"

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

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+import time
+from dataclasses import dataclass, field, replace
 from typing import cast
 
 import httpx
@@ -13,6 +14,7 @@ from .config import (
 from .contracts import AgentErrorCode, JsonValue, RuntimeToolDefinition
 from .engine import SafeEngineError
 from .multimodal import response_format
+from .report_types import UsageFacts
 
 
 @dataclass
@@ -26,7 +28,8 @@ class ProviderToolCall:
 class ProviderTurn:
     text_deltas: list[str] = field(default_factory=list)
     tool_calls: list[ProviderToolCall] = field(default_factory=list)
-    usage: dict[str, JsonValue] | None = None
+    usage: UsageFacts = field(default_factory=UsageFacts)
+    reported_model: str | None = None
 
     @property
     def text(self) -> str:
@@ -69,6 +72,7 @@ class OpenAiCompatibleProvider:
             output_schema,
         )
         turn = ProviderTurn()
+        started_at = time.perf_counter()
         async with self._client() as client:
             try:
                 async with client.stream(
@@ -80,7 +84,7 @@ class OpenAiCompatibleProvider:
                     if not response.is_success:
                         await self._bounded_stream(response)
                         raise provider_status_failure(response.status_code)
-                    await self._consume_stream(response, turn)
+                    await self._consume_stream(response, turn, started_at)
             except SafeEngineError:
                 raise
             except httpx.HTTPError as error:
@@ -135,6 +139,7 @@ class OpenAiCompatibleProvider:
         self,
         response: httpx.Response,
         turn: ProviderTurn,
+        started_at: float,
     ) -> None:
         consumed = 0
         async for line in response.aiter_lines():
@@ -152,7 +157,7 @@ class OpenAiCompatibleProvider:
                 continue
             try:
                 chunk = json.loads(data)
-                consume_chunk(chunk, turn)
+                consume_chunk(chunk, turn, started_at)
             except (KeyError, TypeError, ValueError, json.JSONDecodeError):
                 raise SafeEngineError(
                     "PROVIDER_UNAVAILABLE",
@@ -179,12 +184,23 @@ class OpenAiCompatibleProvider:
         return body
 
 
-def consume_chunk(value: object, turn: ProviderTurn) -> None:
+def consume_chunk(
+    value: object,
+    turn: ProviderTurn,
+    started_at: float | None = None,
+) -> None:
     if not isinstance(value, dict):
         raise TypeError
+    reported_model = value.get("model")
+    if isinstance(reported_model, str) and reported_model:
+        turn.reported_model = reported_model
     usage = value.get("usage")
     if isinstance(usage, dict):
-        turn.usage = usage_value(usage)
+        measured = usage_value(usage)
+        turn.usage = replace(
+            measured,
+            first_token_latency_ms=turn.usage.first_token_latency_ms,
+        )
     choices = value.get("choices")
     if not isinstance(choices, list) or not choices:
         return
@@ -196,6 +212,7 @@ def consume_chunk(value: object, turn: ProviderTurn) -> None:
         return
     content = delta.get("content")
     if isinstance(content, str) and content:
+        observe_first_token(turn, started_at)
         turn.text_deltas.append(content)
     raw_calls = delta.get("tool_calls")
     if not isinstance(raw_calls, list):
@@ -208,6 +225,7 @@ def consume_chunk(value: object, turn: ProviderTurn) -> None:
             raise TypeError
         while len(turn.tool_calls) <= index:
             turn.tool_calls.append(ProviderToolCall())
+        observe_first_token(turn, started_at)
         call = turn.tool_calls[index]
         call_id = raw.get("id")
         if isinstance(call_id, str):
@@ -236,21 +254,72 @@ def tool_schema(tool: RuntimeToolDefinition) -> JsonValue:
     }
 
 
-def usage_value(raw: dict[object, object]) -> dict[str, JsonValue]:
-    values = {
-        "inputTokens": raw.get("prompt_tokens"),
-        "outputTokens": raw.get("completion_tokens"),
-        "totalTokens": raw.get("total_tokens"),
-    }
-    measurements = {
-        key: value
-        for key, value in values.items()
-        if isinstance(value, int) and value >= 0
-    }
+def usage_value(raw: dict[object, object]) -> UsageFacts:
+    input_tokens = non_negative_integer(raw.get("prompt_tokens"))
+    output_tokens = non_negative_integer(raw.get("completion_tokens"))
+    total_tokens = non_negative_integer(raw.get("total_tokens"))
+    prompt_details = raw.get("prompt_tokens_details")
+    cached_tokens = (
+        non_negative_integer(prompt_details.get("cached_tokens"))
+        if isinstance(prompt_details, dict)
+        else None
+    )
+    if (
+        cached_tokens is not None
+        and input_tokens is not None
+        and cached_tokens > input_tokens
+    ):
+        cached_tokens = None
+    completion_details = raw.get("completion_tokens_details")
+    reasoning_tokens = (
+        non_negative_integer(completion_details.get("reasoning_tokens"))
+        if isinstance(completion_details, dict)
+        else None
+    )
+    known = any(
+        value is not None
+        for value in (
+            input_tokens,
+            output_tokens,
+            cached_tokens,
+            reasoning_tokens,
+            total_tokens,
+        )
+    )
+    return UsageFacts(
+        source="provider-reported" if known else "unknown",
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_input_tokens=cached_tokens,
+        reasoning_tokens=reasoning_tokens,
+        total_tokens=total_tokens,
+        cache_status=(
+            "unknown"
+            if cached_tokens is None
+            else "hit"
+            if cached_tokens > 0
+            else "miss"
+        ),
+    )
+
+
+def non_negative_integer(value: object) -> int | None:
     return (
-        {"source": "provider-reported", **measurements}
-        if measurements
-        else {"source": "unknown"}
+        value
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 0
+        else None
+    )
+
+
+def observe_first_token(turn: ProviderTurn, started_at: float | None) -> None:
+    if started_at is None or turn.usage.first_token_latency_ms is not None:
+        return
+    turn.usage = replace(
+        turn.usage,
+        first_token_latency_ms=max(
+            0,
+            round((time.perf_counter() - started_at) * 1_000),
+        ),
     )
 
 

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

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from .contracts import StartRunRequest
+from .report_types import retention_seconds
+
+RUN_INSERT_SQL = """
+insert into agent_runtime_report_runs (
+  run_id, operation_key, release_id, trace_id,
+  actor_id, actor_type, department_id, status,
+  created_at, updated_at, expires_at
+) values (%s, %s, %s, %s, %s, %s, %s, 'accepted', %s, %s, %s)
+on conflict (run_id) do nothing
+"""
+
+
+def run_insert_values(
+    run_id: str,
+    request: StartRunRequest,
+    created_at: float,
+    retention_days: int,
+) -> tuple[object, ...]:
+    context = request.reporting
+    return (
+        run_id,
+        request.operation_key,
+        request.release.release_id,
+        request.trace_id,
+        context.actor_id if context else None,
+        context.actor_type if context else None,
+        context.department_id if context else None,
+        created_at,
+        created_at,
+        created_at + retention_seconds(retention_days),
+    )

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

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from psycopg import AsyncConnection
+from psycopg_pool import AsyncConnectionPool
+
+from .report_presenter import (
+    attempt_value,
+    attempts_for,
+    run_value,
+)
+from .report_types import (
+    AttemptOutcome,
+    AttemptReport,
+    CacheStatus,
+    ReportFilter,
+    RunReport,
+    UsageFacts,
+    UsageSource,
+)
+
+type DatabaseConnection = AsyncConnection[dict[str, Any]]
+type DatabasePool = AsyncConnectionPool[DatabaseConnection]
+
+
+async def list_runs(
+    pool: DatabasePool,
+    query: ReportFilter,
+    page: int,
+    page_size: int,
+    now: float,
+) -> dict[str, object]:
+    clause, parameters = filter_clause(query, now)
+    async with pool.connection() as connection:
+        count_cursor = await connection.execute(
+            f"select count(*) as total from agent_runtime_report_runs {clause}",
+            parameters,
+        )
+        count_row = await count_cursor.fetchone()
+        cursor = await connection.execute(
+            f"""
+            select * from agent_runtime_report_runs {clause}
+            order by created_at desc limit %s offset %s
+            """,
+            (*parameters, page_size, (page - 1) * page_size),
+        )
+        runs = [run_from_row(row) for row in await cursor.fetchall()]
+        attempts = await select_attempts(
+            connection,
+            [run.run_id for run in runs],
+        )
+    return {
+        "items": [run_value(run, attempts_for(attempts, [run])) for run in runs],
+        "total": int(count_row["total"]) if count_row else 0,
+        "page": page,
+        "pageSize": page_size,
+    }
+
+
+async def get_run(
+    pool: DatabasePool,
+    run_id: str,
+    now: float,
+) -> dict[str, object] | None:
+    async with pool.connection() as connection:
+        cursor = await connection.execute(
+            """
+            select * from agent_runtime_report_runs
+            where run_id = %s and expires_at > %s
+            """,
+            (run_id, now),
+        )
+        row = await cursor.fetchone()
+        if not row:
+            return None
+        run = run_from_row(row)
+        attempts = await select_attempts(connection, [run_id])
+    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 select_attempts(
+    connection: DatabaseConnection,
+    run_ids: list[str],
+) -> list[AttemptReport]:
+    if not run_ids:
+        return []
+    cursor = await connection.execute(
+        """
+        select * from agent_runtime_report_attempts
+        where run_id = any(%s) order by run_id, sequence
+        """,
+        (run_ids,),
+    )
+    return [attempt_from_row(row) for row in await cursor.fetchall()]
+
+
+def filter_clause(
+    query: ReportFilter,
+    now: float,
+    alias: str = "",
+) -> tuple[str, tuple[object, ...]]:
+    prefix = f"{alias}." if alias else ""
+    conditions = [
+        f"{prefix}created_at >= %s",
+        f"{prefix}created_at <= %s",
+        f"{prefix}expires_at > %s",
+    ]
+    parameters: list[object] = [
+        query.from_timestamp,
+        query.to_timestamp,
+        now,
+    ]
+    scoped_conditions, scoped_parameters = scope_conditions(
+        query,
+        prefix,
+    )
+    conditions.extend(scoped_conditions)
+    parameters.extend(scoped_parameters)
+    return f"where {' and '.join(conditions)}", tuple(parameters)
+
+
+def attempt_filter_clause(
+    query: ReportFilter,
+    now: float,
+    run_alias: str = "r",
+    attempt_alias: str = "a",
+) -> tuple[str, tuple[object, ...]]:
+    run_prefix = f"{run_alias}." if run_alias else ""
+    attempt_prefix = f"{attempt_alias}." if attempt_alias else ""
+    conditions = [
+        f"{attempt_prefix}started_at >= %s",
+        f"{attempt_prefix}started_at <= %s",
+        f"{attempt_prefix}finished_at is not null",
+        f"{run_prefix}expires_at > %s",
+    ]
+    parameters: list[object] = [
+        query.from_timestamp,
+        query.to_timestamp,
+        now,
+    ]
+    scoped_conditions, scoped_parameters = scope_conditions(
+        query,
+        run_prefix,
+    )
+    conditions.extend(scoped_conditions)
+    parameters.extend(scoped_parameters)
+    return f"where {' and '.join(conditions)}", tuple(parameters)
+
+
+def scope_conditions(
+    query: ReportFilter,
+    prefix: str,
+) -> tuple[list[str], list[object]]:
+    conditions: list[str] = []
+    parameters: list[object] = []
+    if query.selected_actor_id is not None:
+        conditions.append(f"{prefix}actor_id = %s")
+        parameters.append(query.selected_actor_id)
+    if query.scope_restricted:
+        scopes: list[str] = []
+        if query.actor_ids:
+            scopes.append(f"{prefix}actor_id = any(%s)")
+            parameters.append(list(query.actor_ids))
+        if query.department_ids:
+            scopes.append(f"{prefix}department_id = any(%s)")
+            parameters.append(list(query.department_ids))
+        conditions.append(f"({' or '.join(scopes)})" if scopes else "false")
+    return conditions, parameters
+
+
+def run_from_row(row: dict[str, Any]) -> RunReport:
+    return RunReport(
+        run_id=str(row["run_id"]),
+        operation_key=str(row["operation_key"]),
+        release_id=str(row["release_id"]),
+        trace_id=str(row["trace_id"]),
+        actor_id=optional_text(row.get("actor_id")),
+        actor_type=optional_text(row.get("actor_type")),
+        department_id=optional_text(row.get("department_id")),
+        status=cast(Any, str(row["status"])),
+        safe_error_code=optional_text(row.get("safe_error_code")),
+        started_at=optional_float(row.get("started_at")),
+        finished_at=optional_float(row.get("finished_at")),
+        duration_ms=optional_int(row.get("duration_ms")),
+        created_at=float(row["created_at"]),
+        updated_at=float(row["updated_at"]),
+        expires_at=float(row["expires_at"]),
+    )
+
+
+def attempt_from_row(row: dict[str, Any]) -> AttemptReport:
+    return AttemptReport(
+        attempt_id=str(row["attempt_id"]),
+        run_id=str(row["run_id"]),
+        sequence=int(row["sequence"]),
+        tool_round=int(row["tool_round"]),
+        deployment_key=str(row["deployment_key"]),
+        requested_model=str(row["requested_model"]),
+        reported_model=optional_text(row.get("reported_model")),
+        outcome=cast(AttemptOutcome, str(row["outcome"])),
+        usage=UsageFacts(
+            source=cast(UsageSource, str(row["usage_source"])),
+            input_tokens=optional_int(row.get("input_tokens")),
+            output_tokens=optional_int(row.get("output_tokens")),
+            cached_input_tokens=optional_int(row.get("cached_input_tokens")),
+            reasoning_tokens=optional_int(row.get("reasoning_tokens")),
+            total_tokens=optional_int(row.get("total_tokens")),
+            first_token_latency_ms=optional_int(row.get("first_token_latency_ms")),
+            cache_status=cast(CacheStatus, str(row["cache_status"])),
+        ),
+        duration_ms=optional_int(row.get("duration_ms")),
+        safe_error_code=optional_text(row.get("safe_error_code")),
+        started_at=float(row["started_at"]),
+        finished_at=optional_float(row.get("finished_at")),
+    )
+
+
+def optional_text(value: object) -> str | None:
+    return str(value) if value is not None else None
+
+
+def optional_float(value: Any) -> float | None:
+    return float(value) if value is not None else None
+
+
+def optional_int(value: Any) -> int | None:
+    return int(value) if value is not None else None

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

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .report_types import (
+    AttemptTerminalOutcome,
+    CacheStatus,
+    UsageFacts,
+    UsageSource,
+)
+
+
+def assert_attempt_terminal_replay(
+    current: dict[str, Any],
+    outcome: AttemptTerminalOutcome,
+    usage: UsageFacts,
+    reported_model: str | None,
+    safe_error_code: str | None,
+) -> None:
+    current_usage = UsageFacts(
+        source=cast(UsageSource, str(current["usage_source"])),
+        input_tokens=optional_int(current["input_tokens"]),
+        output_tokens=optional_int(current["output_tokens"]),
+        cached_input_tokens=optional_int(current["cached_input_tokens"]),
+        reasoning_tokens=optional_int(current["reasoning_tokens"]),
+        total_tokens=optional_int(current["total_tokens"]),
+        first_token_latency_ms=optional_int(current["first_token_latency_ms"]),
+        cache_status=cast(CacheStatus, str(current["cache_status"])),
+    )
+    if (
+        current["outcome"] != outcome
+        or current_usage != usage
+        or optional_text(current["reported_model"]) != reported_model
+        or optional_text(current["safe_error_code"]) != safe_error_code
+    ):
+        raise ValueError("Agent Runtime 报表 Attempt 终态冲突")
+
+
+def optional_text(value: object) -> str | None:
+    return str(value) if value is not None else None
+
+
+def optional_int(value: Any) -> int | None:
+    return int(value) if value is not None else None