create-windy 0.2.20 → 0.2.21

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

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import cast
+
+from .contracts import AgentError, AgentErrorCode, JsonValue, RunStatus
+from .store import (
+    CanonicalEvent,
+    IdempotencyConflictError,
+    RunRecord,
+    status_for,
+)
+
+
+class RunStoreCapacityError(Exception):
+    pass
+
+
+class SqliteRunStore:
+    """Single-replica durable Run store with bounded rows, events and output."""
+
+    def __init__(
+        self,
+        path: str,
+        *,
+        max_runs: int = 10_000,
+        max_events_per_run: int = 2_000,
+        max_output_bytes: int = 16 * 1024 * 1024,
+        terminal_ttl_seconds: int = 7 * 24 * 60 * 60,
+    ) -> None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._database = sqlite3.connect(path, check_same_thread=False)
+        self._database.row_factory = sqlite3.Row
+        self._max_runs = max_runs
+        self._max_events = max_events_per_run
+        self._max_output_bytes = max_output_bytes
+        self._terminal_ttl = terminal_ttl_seconds
+        self._condition = asyncio.Condition()
+        self._initialize()
+        self._recover_incomplete()
+
+    async def create_or_get(self, record: RunRecord) -> tuple[RunRecord, bool]:
+        async with self._condition:
+            existing = self._database.execute(
+                "select run_id from agent_runs where idempotency_key = ?",
+                (record.idempotency_key,),
+            ).fetchone()
+            if existing:
+                current = self._read(str(existing["run_id"]))
+                if current is None or current.fingerprint != record.fingerprint:
+                    raise IdempotencyConflictError
+                return current, False
+            self._prune()
+            count = int(
+                self._database.execute("select count(*) from agent_runs").fetchone()[0]
+            )
+            if count >= self._max_runs:
+                raise RunStoreCapacityError("Agent Run Store 容量已满")
+            now = time.time()
+            self._database.execute(
+                """
+                insert into agent_runs (
+                  run_id, operation_key, input_json, idempotency_key,
+                  fingerprint, status, output_json, created_at, updated_at
+                ) values (?, ?, ?, ?, ?, 'accepted', 'null', ?, ?)
+                """,
+                (
+                    record.run_id,
+                    record.operation_key,
+                    "null",
+                    record.idempotency_key,
+                    record.fingerprint,
+                    now,
+                    now,
+                ),
+            )
+            self._database.commit()
+            self._condition.notify_all()
+            return record, True
+
+    async def get(self, run_id: str) -> RunRecord | None:
+        async with self._condition:
+            return self._read(run_id)
+
+    async def append(
+        self,
+        run_id: str,
+        event_type: str,
+        fields: dict[str, object] | None = None,
+    ) -> CanonicalEvent | None:
+        async with self._condition:
+            record = self._read(run_id)
+            if record is None:
+                raise KeyError(run_id)
+            if record.terminal:
+                return None
+            sequence = len(record.events) + 1
+            if sequence >= self._max_events and not event_type.startswith("run."):
+                self._append_failure(run_id, sequence, "Agent 事件超过安全上限")
+                self._condition.notify_all()
+                raise RunStoreCapacityError("Agent 事件超过安全上限")
+            event: CanonicalEvent = {
+                "type": event_type,
+                "runId": run_id,
+                "sequence": sequence,
+                **(fields or {}),
+            }
+            self._insert_event(run_id, event, 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._read(run_id)
+            if record is None:
+                raise KeyError(run_id)
+            if record.terminal:
+                return
+            encoded = encode(output)
+            sequence = len(record.events) + 1
+            if len(encoded.encode()) > self._max_output_bytes:
+                self._append_failure(run_id, sequence, "Agent 输出超过安全上限")
+                self._condition.notify_all()
+                return
+            event: CanonicalEvent = {
+                "type": "run.completed",
+                "runId": run_id,
+                "sequence": sequence,
+            }
+            self._insert_event(run_id, event, "completed", encoded)
+            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:
+
+            def ready() -> bool:
+                record = self._read(run_id)
+                return bool(
+                    record
+                    and (
+                        any(sequence_of(event) > after for event in record.events)
+                        or record.terminal
+                    )
+                )
+
+            if not ready():
+                try:
+                    await asyncio.wait_for(
+                        self._condition.wait_for(ready),
+                        wait_seconds,
+                    )
+                except TimeoutError:
+                    return [], False
+            record = self._read(run_id)
+            if record is None:
+                raise KeyError(run_id)
+            return (
+                [event for event in record.events if sequence_of(event) > after],
+                record.terminal,
+            )
+
+    def close(self) -> None:
+        self._database.close()
+
+    def _initialize(self) -> None:
+        self._database.executescript(
+            """
+            create table if not exists agent_runs (
+              run_id text primary key,
+              operation_key text not null,
+              input_json text not null,
+              idempotency_key text not null unique,
+              fingerprint text not null,
+              status text not null,
+              output_json text not null,
+              created_at real not null,
+              updated_at real not null
+            );
+            create table if not exists agent_events (
+              run_id text not null references agent_runs(run_id) on delete cascade,
+              sequence integer not null,
+              event_json text not null,
+              primary key (run_id, sequence)
+            );
+            """
+        )
+        self._database.commit()
+
+    def _recover_incomplete(self) -> None:
+        rows = self._database.execute(
+            """
+            select run_id from agent_runs
+            where status not in ('completed', 'failed', 'cancelled')
+            """
+        ).fetchall()
+        for row in rows:
+            run_id = str(row["run_id"])
+            sequence = (
+                int(
+                    self._database.execute(
+                        "select count(*) from agent_events where run_id = ?",
+                        (run_id,),
+                    ).fetchone()[0]
+                )
+                + 1
+            )
+            self._append_failure(
+                run_id,
+                sequence,
+                "Agent Runtime 重启中断了 Run",
+                code="RUNTIME_UNAVAILABLE",
+                retryable=True,
+            )
+        self._database.commit()
+
+    def _read(self, run_id: str) -> RunRecord | None:
+        row = self._database.execute(
+            "select * from agent_runs where run_id = ?",
+            (run_id,),
+        ).fetchone()
+        if not row:
+            return None
+        events = [
+            json.loads(str(event["event_json"]))
+            for event in self._database.execute(
+                """
+                select event_json from agent_events
+                where run_id = ? order by sequence
+                """,
+                (run_id,),
+            )
+        ]
+        return RunRecord(
+            run_id=str(row["run_id"]),
+            operation_key=str(row["operation_key"]),
+            input=json.loads(str(row["input_json"])),
+            idempotency_key=str(row["idempotency_key"]),
+            fingerprint=str(row["fingerprint"]),
+            status=cast(RunStatus, str(row["status"])),
+            events=events,
+            output=json.loads(str(row["output_json"])),
+        )
+
+    def _insert_event(
+        self,
+        run_id: str,
+        event: CanonicalEvent,
+        status: RunStatus,
+        output_json: str | None = None,
+    ) -> None:
+        self._database.execute(
+            "insert into agent_events values (?, ?, ?)",
+            (run_id, event["sequence"], encode(event)),
+        )
+        self._database.execute(
+            """
+            update agent_runs
+            set status = ?, output_json = coalesce(?, output_json), updated_at = ?
+            where run_id = ?
+            """,
+            (status, output_json, time.time(), run_id),
+        )
+        self._database.commit()
+
+    def _append_failure(
+        self,
+        run_id: str,
+        sequence: int,
+        message: str,
+        *,
+        code: AgentErrorCode = "BUDGET_EXCEEDED",
+        retryable: bool = False,
+    ) -> None:
+        event: CanonicalEvent = {
+            "type": "run.failed",
+            "runId": run_id,
+            "sequence": sequence,
+            "error": AgentError(
+                code=code,
+                message=message,
+                request_id=f"request_store_{sequence}",
+                retryable=retryable,
+            ).model_dump(by_alias=True),
+        }
+        self._insert_event(run_id, event, "failed")
+
+    def _prune(self) -> None:
+        cutoff = time.time() - self._terminal_ttl
+        self._database.execute(
+            """
+            delete from agent_runs
+            where status in ('completed', 'failed', 'cancelled')
+              and updated_at < ?
+            """,
+            (cutoff,),
+        )
+        self._database.commit()
+
+
+def encode(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def sequence_of(event: CanonicalEvent) -> int:
+    value = event.get("sequence")
+    if not isinstance(value, int):
+        raise RuntimeError("Agent Event sequence 无效")
+    return value

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

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+from .service import AgentRunService
+
+
+def encode_event(event: dict[str, object]) -> str:
+    sequence = event["sequence"]
+    event_type = event["type"]
+    data = json.dumps(event, ensure_ascii=False, separators=(",", ":"))
+    return f"id: {sequence}\nevent: {event_type}\ndata: {data}\n\n"
+
+
+async def event_stream(
+    service: AgentRunService,
+    run_id: str,
+    after: int,
+    heartbeat_seconds: float,
+) -> AsyncIterator[str]:
+    cursor = after
+    while True:
+        events, terminal = await service.store.events_after(
+            run_id,
+            cursor,
+            heartbeat_seconds,
+        )
+        if not events:
+            if terminal:
+                return
+            yield ": heartbeat\n\n"
+            continue
+        for event in events:
+            sequence = event["sequence"]
+            if not isinstance(sequence, int):
+                raise RuntimeError("invalid stored sequence")
+            cursor = sequence
+            yield encode_event(event)
+        if terminal:
+            return

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

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .contracts import JsonValue, RunStatus
+
+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
+    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 RunStore(Protocol):
+    async def create_or_get(self, record: RunRecord) -> tuple[RunRecord, bool]: ...
+    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]: ...
+
+
+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()
+
+    async def create_or_get(self, record: RunRecord) -> 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
+            self._runs[record.run_id] = record
+            self._idempotency[record.idempotency_key] = record.run_id
+            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 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
+
+
+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 == "run.failed":
+        return "failed"
+    if event_type == "run.cancelled":
+        return "cancelled"
+    return current

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

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+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 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)