create-windy 0.8.2 → 0.9.1

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

@@ -1,255 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass, field
-from typing import Protocol
-
-from .contracts import JsonValue, RunStatus
-from .engine_identity import DIRECT_ENGINE_ID
-
-CanonicalEvent = dict[str, object]
-TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
-
-
-@dataclass
-class RunRecord:
-    run_id: str
-    operation_key: str
-    input: JsonValue
-    idempotency_key: str
-    fingerprint: str
-    engine_id: str = DIRECT_ENGINE_ID
-    release: JsonValue = None
-    trace_id: str = ""
-    status: RunStatus = "accepted"
-    events: list[CanonicalEvent] = field(default_factory=list)
-    output: JsonValue = None
-
-    @property
-    def terminal(self) -> bool:
-        return self.status in TERMINAL_STATUSES
-
-
-class IdempotencyConflictError(Exception):
-    pass
-
-
-class ReleaseNotFoundError(Exception):
-    pass
-
-
-class RunStore(Protocol):
-    async def create_or_get(
-        self,
-        record: RunRecord,
-        invocation: JsonValue = None,
-    ) -> tuple[RunRecord, bool]: ...
-    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None: ...
-    async def get(self, run_id: str) -> RunRecord | None: ...
-    async def append(
-        self,
-        run_id: str,
-        event_type: str,
-        fields: dict[str, object] | None = None,
-    ) -> CanonicalEvent | None: ...
-    async def complete(self, run_id: str, output: JsonValue) -> None: ...
-    async def events_after(
-        self,
-        run_id: str,
-        after: int,
-        wait_seconds: float,
-    ) -> tuple[list[CanonicalEvent], bool]: ...
-    async def save_invocation(self, run_id: str, value: JsonValue) -> None: ...
-    async def recoverable(self) -> list[tuple[RunRecord, JsonValue]]: ...
-    async def clear_invocation(self, run_id: str) -> None: ...
-    async def record_evaluation(
-        self,
-        release_id: str,
-        evaluation_set_key: str,
-        evaluation_set_version: str,
-        metrics: dict[str, float],
-    ) -> str: ...
-    async def renew_lease(self, run_id: str) -> None: ...
-    async def release_lease(self, run_id: str) -> None: ...
-    async def probe(self) -> None: ...
-    async def close(self) -> None: ...
-
-
-class InMemoryRunStore:
-    """Non-production store for deterministic tests and local development only."""
-
-    def __init__(self) -> None:
-        self._runs: dict[str, RunRecord] = {}
-        self._idempotency: dict[str, str] = {}
-        self._condition = asyncio.Condition()
-        self._invocations: dict[str, JsonValue] = {}
-        self._evaluations: dict[tuple[str, str, str], tuple[str, dict[str, float]]] = {}
-        self._releases: dict[str, tuple[str, JsonValue]] = {}
-
-    async def create_or_get(
-        self,
-        record: RunRecord,
-        invocation: JsonValue = None,
-    ) -> tuple[RunRecord, bool]:
-        async with self._condition:
-            existing_id = self._idempotency.get(record.idempotency_key)
-            if existing_id is not None:
-                existing = self._runs[existing_id]
-                if existing.fingerprint != record.fingerprint:
-                    raise IdempotencyConflictError
-                return existing, False
-            release_id = release_id_of(record)
-            release = (record.operation_key, record.release)
-            existing_release = self._releases.get(release_id)
-            if existing_release is not None and existing_release != release:
-                raise IdempotencyConflictError
-            self._releases[release_id] = release
-            self._runs[record.run_id] = record
-            self._idempotency[record.idempotency_key] = record.run_id
-            if invocation is not None:
-                self._invocations[record.run_id] = invocation
-            self._condition.notify_all()
-            return record, True
-
-    async def get(self, run_id: str) -> RunRecord | None:
-        async with self._condition:
-            return self._runs.get(run_id)
-
-    async def get_by_idempotency(self, idempotency_key: str) -> RunRecord | None:
-        async with self._condition:
-            run_id = self._idempotency.get(idempotency_key)
-            return self._runs.get(run_id) if run_id else None
-
-    async def append(
-        self,
-        run_id: str,
-        event_type: str,
-        fields: dict[str, object] | None = None,
-    ) -> CanonicalEvent | None:
-        async with self._condition:
-            record = self._runs[run_id]
-            if record.terminal:
-                return None
-            event: CanonicalEvent = {
-                "type": event_type,
-                "runId": run_id,
-                "sequence": len(record.events) + 1,
-                **(fields or {}),
-            }
-            record.events.append(event)
-            record.status = status_for(event_type, record.status)
-            self._condition.notify_all()
-            return event
-
-    async def complete(self, run_id: str, output: JsonValue) -> None:
-        async with self._condition:
-            record = self._runs[run_id]
-            if record.terminal:
-                return
-            record.output = output
-            event: CanonicalEvent = {
-                "type": "run.completed",
-                "runId": run_id,
-                "sequence": len(record.events) + 1,
-            }
-            record.events.append(event)
-            record.status = "completed"
-            self._condition.notify_all()
-
-    async def events_after(
-        self,
-        run_id: str,
-        after: int,
-        wait_seconds: float,
-    ) -> tuple[list[CanonicalEvent], bool]:
-        async with self._condition:
-            record = self._runs[run_id]
-
-            def ready() -> bool:
-                return len(record.events) > after or record.terminal
-
-            if not ready():
-                try:
-                    await asyncio.wait_for(
-                        self._condition.wait_for(ready),
-                        wait_seconds,
-                    )
-                except TimeoutError:
-                    return [], False
-            return list(record.events[after:]), record.terminal
-
-    async def save_invocation(self, run_id: str, value: JsonValue) -> None:
-        async with self._condition:
-            if run_id not in self._runs:
-                raise KeyError(run_id)
-            self._invocations[run_id] = value
-
-    async def recoverable(self) -> list[tuple[RunRecord, JsonValue]]:
-        async with self._condition:
-            return [
-                (record, self._invocations[run_id])
-                for run_id, record in self._runs.items()
-                if not record.terminal and run_id in self._invocations
-            ]
-
-    async def clear_invocation(self, run_id: str) -> None:
-        async with self._condition:
-            self._invocations.pop(run_id, None)
-
-    async def record_evaluation(
-        self,
-        release_id: str,
-        evaluation_set_key: str,
-        evaluation_set_version: str,
-        metrics: dict[str, float],
-    ) -> str:
-        async with self._condition:
-            if release_id not in self._releases:
-                raise ReleaseNotFoundError
-            key = (release_id, evaluation_set_key, evaluation_set_version)
-            existing = self._evaluations.get(key)
-            if existing:
-                if existing[1] != metrics:
-                    raise IdempotencyConflictError
-                return existing[0]
-            evaluation_id = f"eval_{len(self._evaluations) + 1}"
-            self._evaluations[key] = (evaluation_id, metrics)
-            return evaluation_id
-
-    async def renew_lease(self, run_id: str) -> None:
-        record = self._runs.get(run_id)
-        if record is None or record.terminal:
-            raise KeyError(run_id)
-
-    async def release_lease(self, run_id: str) -> None:
-        if run_id not in self._runs:
-            raise KeyError(run_id)
-
-    async def probe(self) -> None:
-        return None
-
-    async def close(self) -> None:
-        return None
-
-
-def status_for(event_type: str, current: RunStatus) -> RunStatus:
-    if event_type == "run.started":
-        return "running"
-    if event_type == "approval.required":
-        return "awaiting-approval"
-    if event_type == "approval.resolved":
-        return "running"
-    if event_type == "run.failed":
-        return "failed"
-    if event_type == "run.cancelled":
-        return "cancelled"
-    return current
-
-
-def release_id_of(record: RunRecord) -> str:
-    if not isinstance(record.release, dict):
-        raise IdempotencyConflictError
-    release_id = record.release.get("releaseId")
-    if not isinstance(release_id, str):
-        raise IdempotencyConflictError
-    return release_id

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

@@ -1,40 +0,0 @@
-from __future__ import annotations
-
-import base64
-import hashlib
-import json
-import os
-from typing import cast
-
-from cryptography.hazmat.primitives.ciphers.aead import AESGCM
-
-from .contracts import JsonValue
-
-
-class RunStoreCipher:
-    def __init__(self, secret: str) -> None:
-        if len(secret.encode()) < 32:
-            raise ValueError("AGENT_RUN_ENCRYPTION_SECRET 至少需要 32 字节")
-        self._key = hashlib.sha256(secret.encode()).digest()
-
-    def seal(self, value: JsonValue) -> str:
-        nonce = os.urandom(12)
-        body = json.dumps(
-            value,
-            ensure_ascii=False,
-            separators=(",", ":"),
-        ).encode()
-        encrypted = AESGCM(self._key).encrypt(nonce, body, b"agent-run-v1")
-        return base64.urlsafe_b64encode(nonce + encrypted).decode()
-
-    def open(self, value: str) -> JsonValue:
-        try:
-            raw = base64.urlsafe_b64decode(value.encode())
-            body = AESGCM(self._key).decrypt(
-                raw[:12],
-                raw[12:],
-                b"agent-run-v1",
-            )
-            return cast(JsonValue, json.loads(body))
-        except Exception as error:
-            raise ValueError("Agent Run 加密上下文无法解密") from error

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

@@ -1,145 +0,0 @@
-"""Agent runtime adapter for the Windy operational log contract."""
-
-from __future__ import annotations
-
-import json
-import logging
-import math
-import re
-import sys
-from datetime import UTC, datetime
-from typing import TextIO
-
-MAX_LOG_BYTES = 2048
-_CORRELATION = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
-_STABLE = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
-_EVENTS = {
-    "Agent Run 恢复轮询失败，将继续重试": (
-        "agent.run.recovery.failed",
-        "AGENT_RUN_RECOVERY_FAILED",
-    ),
-    "Agent Runtime 报表写入失败": (
-        "agent.report.write.failed",
-        "AGENT_REPORT_WRITE_FAILED",
-    ),
-}
-_ATTEMPT_EVENTS = frozenset(
-    {
-        "agent.run.attempt.started",
-        "agent.run.attempt.completed",
-    }
-)
-_ATTEMPT_ERRORS = {
-    "failed": "AGENT_RUN_FAILED",
-    "cancelled": "AGENT_RUN_CANCELLED",
-    "interrupted": "AGENT_RUN_INTERRUPTED",
-}
-
-
-def agent_log_record(record: logging.LogRecord) -> dict[str, str | bool | float]:
-    """Map known runtime failures without serializing messages, errors or extras."""
-    event, error_code = _EVENTS.get(
-        record.msg if isinstance(record.msg, str) else "",
-        ("agent.runtime.failed", "AGENT_RUNTIME_FAILED"),
-    )
-    attempt_event = getattr(record, "operational_event", None)
-    is_attempt = isinstance(attempt_event, str) and attempt_event in _ATTEMPT_EVENTS
-    result: dict[str, str | bool | float] = {
-        "timestamp": datetime.now(UTC)
-        .isoformat(timespec="milliseconds")
-        .replace("+00:00", "Z"),
-        "level": "error"
-        if record.levelno >= logging.ERROR
-        else ("warn" if record.levelno >= logging.WARNING else "info"),
-        "component": "agent-server",
-        "event": attempt_event
-        if isinstance(attempt_event, str) and is_attempt
-        else event,
-        "retentionClass": "operational",
-    }
-    if not is_attempt:
-        result.update(outcome="failure", errorCode=error_code)
-    elif attempt_event == "agent.run.attempt.completed":
-        status = getattr(record, "operational_status", "interrupted")
-        if status not in {"completed", "failed", "cancelled"}:
-            status = "interrupted"
-        result["stageKey"] = status
-        result["outcome"] = "success" if status == "completed" else "failure"
-        if status != "completed":
-            result["errorCode"] = _ATTEMPT_ERRORS[status]
-        duration = getattr(record, "operational_duration_ms", None)
-        if (
-            isinstance(duration, (int, float))
-            and not isinstance(duration, bool)
-            and math.isfinite(duration)
-            and 0 <= duration <= 3_600_000
-        ):
-            result["durationMs"] = duration
-    for source, target in (
-        ("request_id", "requestId"),
-        ("run_id", "runId"),
-        ("job_id", "jobId"),
-        ("trace_id", "traceId"),
-    ):
-        value = getattr(record, source, None)
-        if isinstance(value, str) and _CORRELATION.fullmatch(value):
-            result[target] = value
-    stage = getattr(record, "report_stage", None)
-    if isinstance(stage, str) and len(stage) <= 64 and _STABLE.fullmatch(stage):
-        result["stageKey"] = stage
-    for key in ("stageKey", "traceId", "jobId", "runId", "requestId"):
-        if len(json.dumps(result, ensure_ascii=False).encode("utf-8")) <= MAX_LOG_BYTES:
-            break
-        result.pop(key, None)
-        result["truncated"] = True
-    return result
-
-
-class AgentStructuredLogHandler(logging.Handler):
-    def __init__(self, stream: TextIO | None = None) -> None:
-        super().__init__(level=logging.INFO)
-        self.stream = stream or sys.stdout
-
-    def emit(self, record: logging.LogRecord) -> None:
-        try:
-            if (
-                record.levelno < logging.WARNING
-                and getattr(record, "operational_event", None) not in _ATTEMPT_EVENTS
-            ):
-                return
-            line = json.dumps(
-                agent_log_record(record), ensure_ascii=False, separators=(",", ":")
-            )
-            self.stream.write(f"{line}\n")
-            self.flush()
-        except Exception:
-            # 运行日志旁路失败时不能改变 Run 与报表写入的业务结果。
-            return
-
-    def flush(self) -> None:
-        try:
-            self.stream.flush()
-        except Exception:
-            return
-
-
-def configure_agent_logging() -> None:
-    """Use one package sink without closing handlers shared with Uvicorn."""
-    logger = logging.getLogger("southwind_agent_server")
-    structured = next(
-        (
-            handler
-            for handler in logger.handlers
-            if isinstance(handler, AgentStructuredLogHandler)
-        ),
-        None,
-    )
-    if structured is None:
-        structured = AgentStructuredLogHandler()
-    for handler in logger.handlers[:]:
-        if handler is not structured:
-            logger.removeHandler(handler)
-    if structured not in logger.handlers:
-        logger.addHandler(structured)
-    logger.setLevel(logging.INFO)
-    logger.propagate = False

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

@@ -1,93 +0,0 @@
-from __future__ import annotations
-
-import os
-import secrets
-from contextvars import Token
-
-from opentelemetry import context, trace
-from opentelemetry.context import Context
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-from opentelemetry.trace import (
-    NonRecordingSpan,
-    Span,
-    SpanContext,
-    TraceFlags,
-)
-
-from .runtime_logging import AgentOperationalAttempt
-from .store import RunRecord
-
-_configured = False
-
-
-def configure_telemetry() -> None:
-    global _configured
-    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "").strip()
-    if _configured or not endpoint:
-        return
-    provider = TracerProvider(
-        resource=Resource.create({"service.name": "southwind-agent-server"})
-    )
-    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
-    trace.set_tracer_provider(provider)
-    _configured = True
-
-
-class AgentRunTrace:
-    """OTel span carrying metadata only; prompts, inputs and outputs stay excluded."""
-
-    def __init__(self, record: RunRecord) -> None:
-        parent = parent_context(record.trace_id)
-        self._span: Span = trace.get_tracer(__name__).start_span(
-            "agent.run",
-            context=parent,
-            attributes={
-                "agent.run.id": record.run_id,
-                "agent.operation.key": record.operation_key,
-                "agent.release.id": release_id(record),
-            },
-        )
-        self._token: Token[Context] | None = None
-        self._operational = AgentOperationalAttempt(record)
-
-    def start(self) -> None:
-        self._token = context.attach(trace.set_span_in_context(self._span))
-        self._operational.start()
-
-    def finish(self, status: str) -> None:
-        self._operational.finish(status)
-        self._span.set_attribute("agent.run.status", status)
-        if self._token is not None:
-            context.detach(self._token)
-        self._span.end()
-
-
-def parent_context(trace_id: str) -> context.Context | None:
-    if len(trace_id) != 32:
-        return None
-    try:
-        parsed = int(trace_id, 16)
-    except ValueError:
-        return None
-    if parsed == 0:
-        return None
-    parent = NonRecordingSpan(
-        SpanContext(
-            trace_id=parsed,
-            span_id=secrets.randbits(64) or 1,
-            is_remote=True,
-            trace_flags=TraceFlags(TraceFlags.SAMPLED),
-        )
-    )
-    return trace.set_span_in_context(parent)
-
-
-def release_id(record: RunRecord) -> str:
-    if isinstance(record.release, dict):
-        value = record.release.get("releaseId")
-        if isinstance(value, str):
-            return value
-    return "unknown"

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

@@ -1,152 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import json
-from dataclasses import dataclass
-
-import httpx
-
-from .config import normalize_base_url
-from .contracts import JsonValue
-from .engine import SafeEngineError
-
-
-@dataclass(frozen=True)
-class ToolInvocation:
-    run_id: str
-    tool_call_id: str
-    tool_key: str
-    arguments: dict[str, JsonValue]
-    execution_grant: str
-
-
-class ToolHostClient:
-    def __init__(
-        self,
-        internal_token: str,
-        *,
-        transport: httpx.AsyncBaseTransport | None = None,
-        timeout_seconds: float = 15.0,
-        max_response_bytes: int = 1024 * 1024,
-    ) -> None:
-        self._internal_token = internal_token
-        self._transport = transport
-        self._timeout_seconds = timeout_seconds
-        self._max_response_bytes = max_response_bytes
-
-    async def execute(
-        self,
-        base_url: str,
-        invocation: ToolInvocation,
-    ) -> JsonValue:
-        endpoint = normalize_base_url(base_url)
-        headers = {
-            "authorization": f"Bearer {self._internal_token}",
-            "content-type": "application/json",
-        }
-        try:
-            async with httpx.AsyncClient(
-                base_url=f"{endpoint}/",
-                headers=headers,
-                timeout=self._timeout_seconds,
-                transport=self._transport,
-            ) as client:
-                response = await client.post(
-                    "api/internal/agent/tools/execute",
-                    json={
-                        "executionGrant": invocation.execution_grant,
-                        "runId": invocation.run_id,
-                        "toolCallId": invocation.tool_call_id,
-                        "toolKey": invocation.tool_key,
-                        "arguments": invocation.arguments,
-                    },
-                )
-                body = await response.aread()
-        except httpx.HTTPError:
-            raise denied("Agent Tool Host 暂不可用", retryable=True) from None
-        if len(body) > self._max_response_bytes:
-            raise denied("Agent Tool 响应超过安全上限")
-        if response.status_code == 202:
-            raise approval_pending(body)
-        if response.status_code == 409:
-            raise approval_resolved(body)
-        if not response.is_success:
-            raise denied("Agent Tool 执行被拒绝")
-        try:
-            value = json.loads(body)
-        except json.JSONDecodeError:
-            raise denied("Agent Tool 响应无效") from None
-        if not isinstance(value, dict) or "value" not in value:
-            raise denied("Agent Tool 响应无效")
-        return value["value"]  # type: ignore[no-any-return]
-
-
-def denied(message: str, *, retryable: bool = False) -> SafeEngineError:
-    return SafeEngineError("TOOL_DENIED", message, retryable=retryable)
-
-
-def canonical_tool_call_id(
-    run_id: str,
-    tool_key: str,
-    arguments: dict[str, JsonValue],
-) -> str:
-    encoded = json.dumps(
-        {
-            "runId": run_id,
-            "toolKey": tool_key,
-            "arguments": arguments,
-        },
-        ensure_ascii=False,
-        separators=(",", ":"),
-        sort_keys=True,
-    ).encode()
-    return f"tool_{hashlib.sha256(encoded).hexdigest()[:40]}"
-
-
-class ToolApprovalPending(Exception):
-    def __init__(self, work_item_id: str) -> None:
-        super().__init__("Agent Tool 等待人工审批")
-        self.work_item_id = work_item_id
-
-
-class ToolApprovalResolved(Exception):
-    def __init__(self, work_item_id: str, outcome: str) -> None:
-        super().__init__("Agent Tool 审批未通过")
-        self.work_item_id = work_item_id
-        self.outcome = outcome
-
-
-def approval_pending(body: bytes) -> ToolApprovalPending:
-    value = safe_object(body)
-    if value.get("code") != "APPROVAL_REQUIRED" or not isinstance(
-        value.get("workItemId"), str
-    ):
-        raise denied("Agent Tool 审批响应无效")
-    work_item_id = value["workItemId"]
-    if not isinstance(work_item_id, str):
-        raise denied("Agent Tool 审批响应无效")
-    return ToolApprovalPending(work_item_id)
-
-
-def approval_resolved(body: bytes) -> ToolApprovalResolved:
-    value = safe_object(body)
-    code = value.get("code")
-    work_item_id = value.get("workItemId")
-    outcomes = {
-        "APPROVAL_REJECTED": "rejected",
-        "APPROVAL_CANCELLED": "cancelled",
-        "APPROVAL_TIMED_OUT": "timed-out",
-    }
-    if code not in outcomes or not isinstance(work_item_id, str):
-        raise denied("Agent Tool 审批响应无效")
-    return ToolApprovalResolved(work_item_id, outcomes[code])
-
-
-def safe_object(body: bytes) -> dict[str, JsonValue]:
-    try:
-        value = json.loads(body)
-    except json.JSONDecodeError:
-        raise denied("Agent Tool 审批响应无效") from None
-    if not isinstance(value, dict):
-        raise denied("Agent Tool 审批响应无效")
-    return value