create-windy 0.2.20 → 0.2.21

package/README.md

@@ -68,7 +68,7 @@ npx create-windy@latest my-dashboard \
 
 选择 `system.license` 时，Server 与 Web 通过 npm 依赖
 `@southwind-ai/license@^0.1.1` 使用运行时能力；生成项目及 `create-windy` 模板快照都不包含
-`packages/license-sdk` 源码。公网 npm 已发布兼容的 `@southwind-ai/license@0.1.1`；
+`packages/license-sdk` 源码。公网 npm 已发布兼容的 `@southwind-ai/license@0.1.2`；
 发布包含该模块的新版创建器前，必须先确认目标 registry 中存在兼容版本，并完成真实
 安装回归。
 

package/dist/cli.js

@@ -228,10 +228,15 @@ var optionalModuleManifests = [
       "system.audit"
     ]),
     fileRoots: [
+      "apps/agent-server",
       "apps/server/src/agent",
       "packages/modules/src/system-agent-tools.ts"
     ],
-    documentation: ["docs/platform/agent-tools.md"]
+    documentation: [
+      "docs/architecture/ai-runtime.md",
+      "docs/platform/agent-runtime.md",
+      "docs/platform/agent-tools.md"
+    ]
   },
   {
     ...module("system.scheduler", "任务调度", "任务、重试、历史和恢复。", [
@@ -881,7 +886,10 @@ async function initializeLocalEnvironment(projectRoot, generateSecret = defaultS
   if (!gitignore.split(/\r?\n/).some((line) => line.trim() === ".env")) {
     throw new Error("生成项目的 .gitignore 未排除 .env，拒绝写入本地密码");
   }
-  const content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  let content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  if (/^AGENT_SERVER_INTERNAL_TOKEN=[ \t\r]*$/m.test(content)) {
+    content = setEmptyVariable(content, "AGENT_SERVER_INTERNAL_TOKEN", generateSecret());
+  }
   let handle;
   try {
     handle = await open(target, "wx", 384);
@@ -1441,8 +1449,8 @@ function isMissing2(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-// src/project-files.ts
-var starterCompose = `services:
+// src/runtime-profile-files.ts
+var starterComposeBase = `services:
   postgres:
     image: postgres:17-alpine
     environment:
@@ -1486,6 +1494,10 @@ var starterCompose = `services:
       WINDY_CONTAINERIZED: "1"
       BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD: "true"
       WINDY_SYSTEM_USAGE_PATHS: /app/data/audit
+      PLATFORM_ENABLE_AI: \${PLATFORM_ENABLE_AI:-false}
+      AGENT_SERVER_URL: http://agent-server:8080
+      AGENT_TOOL_HOST_URL: http://server:9747
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
     ports:
       - "9747:9747"
     volumes:
@@ -1529,11 +1541,50 @@ var starterCompose = `services:
 volumes:
   postgres-data:
   server-audit-data:
+__AGENT_VOLUME__
+`;
+var agentComposeService = `  agent-server:
+    profiles: ["agent"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    environment:
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
+      AGENT_RUN_STORE_PATH: /app/data/agent/runs.sqlite3
+      QWEN_API_URL: \${QWEN_API_URL:-}
+      QWEN_API_KEY: \${QWEN_API_KEY:-}
+      QWEN_MODEL: \${QWEN_MODEL:-}
+      AI_PROVIDER_CONNECT_TIMEOUT_MS: \${AI_PROVIDER_CONNECT_TIMEOUT_MS:-5000}
+      AI_PROVIDER_REQUEST_TIMEOUT_MS: \${AI_PROVIDER_REQUEST_TIMEOUT_MS:-60000}
+      AI_PROVIDER_MAX_RESPONSE_BYTES: \${AI_PROVIDER_MAX_RESPONSE_BYTES:-2097152}
+    volumes:
+      - agent-run-data:/app/data/agent
+    depends_on:
+      server:
+        condition: service_started
+
 `;
-function environmentExample(includeExample) {
+function starterComposeFor(includeAgent) {
+  return starterComposeBase.replace(`  web:
+`, `${includeAgent ? agentComposeService : ""}  web:
+`).replace("__AGENT_VOLUME__", includeAgent ? "  agent-run-data:" : "");
+}
+var starterCompose = starterComposeFor(true);
+function environmentExample(includeExample, includeAgent = true) {
   return `# 复制为 .env 后填写。不要提交真实密码。
 POSTGRES_PASSWORD=
 WINDY_BOOTSTRAP_ADMIN_PASSWORD=
+${includeAgent ? `
+# Agent profile 仅由 Server 读取；不要使用 VITE_ 前缀。
+PLATFORM_ENABLE_AI=false
+AGENT_SERVER_INTERNAL_TOKEN=
+QWEN_API_URL=
+QWEN_API_KEY=
+QWEN_MODEL=
+# AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
+# AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
+# AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
+` : ""}
 
 # 可选搜索配置；不配置时启用 Manifest 中默认开启的 Provider。${includeExample ? `
 # SEARCH_PROVIDER_KEYS=work-order.ticket.search` : `
@@ -1543,7 +1594,8 @@ WINDY_BOOTSTRAP_ADMIN_PASSWORD=
 # SEARCH_MAX_REQUESTS_PER_MINUTE=30
 `;
 }
-function starterDocsReadme(includeOfflineLicense = true) {
+// src/project-files.ts
+function starterDocsReadme(includeOfflineLicense = true, includeAgent = true) {
   return `# Windy Starter 文档
 
 本目录只包含客户运行项目需要的平台架构、开发接入和运维可观测性文档。
@@ -1554,11 +1606,13 @@ License 签发中心、独立签名服务、Vault、发布治理、内部任务
 - 平台开发：从 [系统 CRUD API](./platform/system-crud-api.md) 和 [CRUD 生成器](./development/crud-generator.md) 开始。
 ${includeOfflineLicense ? "- License 消费端：[离线激活与安装协议](./license/license-offline-activation-code.md)；运行时能力由 npm 依赖 `@southwind-ai/license` 提供。" : ""}
 - 运维：[可观测性](./operations/observability.md) 与 [运维总览](./platform/operations-overview.md)。
+${includeAgent ? "- Agent：[Agent Runtime 接入](./platform/agent-runtime.md) 与 [受控工具](./platform/agent-tools.md)。" : ""}
 - 兼容：[RuoYi-Vue Adapter](./adapters/ruoyi-vue-compatibility.md)。
 `;
 }
 function starterReadme(projectName, includeExample = true, includeOxc = true, projectLicense = "UNLICENSED", selectedModules = []) {
   const selected = new Set(selectedModules);
+  const includeAgent = selected.has("system.agent");
   const moduleRows = moduleDistributionCatalog.map(({ name, description, selection }) => `| \`${name}\` | ${selected.has(name) ? "已包含" : "未包含"} | ${selection === "required" ? "H0" : "H2"} | ${description} |`).join(`
 `);
   return `# ${projectName}
@@ -1614,6 +1668,21 @@ bun run dev:server
 直接输出已有地址，其它服务占用时会自动使用后续端口，最多检查 100 个。实际地址始终
 以终端输出为准。\`dev:server\` 不会自动启动 PostgreSQL 或执行 migration；未配置
 \`DATABASE_URL\` 时使用内存模式。
+${includeAgent ? `
+## OpenAI-compatible Agent profile
+
+Agent Runtime 默认不启动。先在仅供本机使用的 \`.env\` 中设置
+\`PLATFORM_ENABLE_AI=true\`、\`AGENT_SERVER_INTERNAL_TOKEN\`、\`QWEN_API_URL\`、
+\`QWEN_API_KEY\` 与 \`QWEN_MODEL\`，再运行：
+
+\`\`\`bash
+bun run dev:agent
+\`\`\`
+
+公网 Provider URL 必须使用 HTTPS；本机、容器服务名和内网地址允许 HTTP。
+\`QWEN_API_KEY\` 只进入 Agent Server，不会进入 Web 环境或返回给客户端。运行与模块
+接入细节见 [Agent Runtime 接入](./docs/platform/agent-runtime.md)。
+` : ""}
 
 ## 页面与登录
 
@@ -1738,6 +1807,7 @@ function createStarterPackage(source, projectName, includeOxc = true, projectLic
       dev: "docker compose up",
       "docker:sync": "create-windy sync-docker",
       "dev:build": "bun run docker:sync && docker compose up --build",
+      ...selectedModules.includes("system.agent") ? { "dev:agent": "docker compose --profile agent up --build" } : {},
       ...generatorVersion ? { windy: "create-windy" } : {},
       "dev:web": "bun run --cwd apps/web dev",
       "dev:server": "bun run --cwd apps/server dev",
@@ -1785,6 +1855,7 @@ var templateRootFiles = [
 ];
 var templateDirectories = [
   "apps/server",
+  "apps/agent-server",
   "apps/web",
   "examples",
   "packages/ai-client",
@@ -1801,6 +1872,7 @@ var templateDirectories = [
 var templateDocumentationFiles = [
   "docs/adapters/ruoyi-vue-compatibility.md",
   "docs/architecture/admin-surface-boundary.md",
+  "docs/architecture/ai-runtime.md",
   "docs/architecture/data-scope-query-enforcement.md",
   "docs/architecture/durable-jobs.md",
   "docs/architecture/minimal-approval-workflow.md",
@@ -1811,6 +1883,7 @@ var templateDocumentationFiles = [
   "docs/license/license-offline-activation-code.md",
   "docs/operations/observability.md",
   "docs/platform/agent-tools.md",
+  "docs/platform/agent-runtime.md",
   "docs/platform/audit-reliability.md",
   "docs/platform/bulk-data-jobs.md",
   "docs/platform/data-access-control.md",
@@ -2025,10 +2098,10 @@ async function generateProject(input) {
   const packageJson = JSON.parse(await readFile10(packagePath, "utf8"));
   await writeFile9(packagePath, `${JSON.stringify(createStarterPackage(packageJson, input.projectName, includeOxc, projectLicense, selectedModules, templateMetadata.generatorVersion), null, 2)}
 `);
-  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterCompose);
-  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample));
+  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterComposeFor(selectedModules.includes("system.agent")));
+  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample, selectedModules.includes("system.agent")));
   await writeFile9(join10(input.targetDirectory, "README.md"), starterReadme(input.projectName, includeExample, includeOxc, projectLicense, selectedModules));
-  await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license")));
+  await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license"), selectedModules.includes("system.agent")));
   await reflectCodeQualityChoice(input.targetDirectory, includeOxc);
   await applyWindyBaseLicense(input.targetDirectory);
   await applyProjectLicense(input.targetDirectory, projectLicense, input.licenseHolder);
@@ -4205,7 +4278,8 @@ var recipes = [
   { id: "starter-0.2.16-to-0.2.17", from: "0.2.16", to: "0.2.17" },
   { id: "starter-0.2.17-to-0.2.18", from: "0.2.17", to: "0.2.18" },
   { id: "starter-0.2.18-to-0.2.19", from: "0.2.18", to: "0.2.19" },
-  { id: "starter-0.2.19-to-0.2.20", from: "0.2.19", to: "0.2.20" }
+  { id: "starter-0.2.19-to-0.2.20", from: "0.2.19", to: "0.2.20" },
+  { id: "starter-0.2.20-to-0.2.21", from: "0.2.20", to: "0.2.21" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "0219ad152473b48f39df25b3ea261dcef52171c7",
-  "generatorVersion": "0.2.20",
+  "templateCommit": "3b9b26fdc1160543df838b4d198a36c6ac3308d0",
+  "generatorVersion": "0.2.21",
   "modules": [
     {
       "name": "system",

package/template/README.md

@@ -52,6 +52,7 @@ bun run dev:server
 以终端输出为准。`dev:server` 不会自动启动 PostgreSQL 或执行 migration；未配置
 `DATABASE_URL` 时使用内存模式。
 
+
 ## 页面与登录
 
 全新数据库的初始平台账号为 `admin`。初始密码不是所有项目共用的固定值，而是

package/template/apps/agent-server/Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim AS runtime
+WORKDIR /app/apps/agent-server
+
+RUN pip install --no-cache-dir uv==0.9.27 \
+  && useradd --create-home --uid 10001 windy
+COPY apps/agent-server/pyproject.toml apps/agent-server/uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY apps/agent-server/src ./src
+RUN uv sync --frozen --no-dev
+
+ENV PATH="/app/apps/agent-server/.venv/bin:${PATH}"
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8080
+RUN mkdir -p /app/data/agent && chown -R windy:windy /app/data
+USER windy
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=4 \
+  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3)"]
+CMD ["uvicorn", "southwind_agent_server.app:app", "--host", "0.0.0.0", "--port", "8080"]

package/template/apps/agent-server/README.md

@@ -0,0 +1,46 @@
+# Southwind AI Agent Server
+
+Python 3.12 Agent Runtime。HTTP 层只公开 Southwind AI canonical Agent
+contracts。当前可用 Adapter 连接 OpenAI-compatible `/chat/completions`；Google ADK
+仍只是未配置 Provider 时安全拒绝的内部 Adapter。
+
+```bash
+uv sync --frozen
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+HTTP Interface：
+
+- `POST /api/agent/runs`
+- `GET /api/agent/runs/:runId/events`
+- `GET /api/agent/runs/:runId/result`
+- `POST /api/agent/runs/:runId/cancel`
+
+Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-ID` 和 `after`
+断线重放，并周期发送 comment heartbeat。Provider 或框架异常只会映射为 canonical
+安全错误，不会把原始异常正文暴露给调用方。
+
+配置以下仅服务端可见的环境变量后，默认运行 OpenAI-compatible Adapter：
+
+```bash
+export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
+export QWEN_API_URL='https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
+export QWEN_API_KEY='<server-secret>'
+export QWEN_MODEL='qwen-plus'
+export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
+uv run uvicorn southwind_agent_server.app:app
+```
+
+公网 URL 必须使用 HTTPS，本机、容器服务名和内网地址允许 HTTP。Provider 请求包含连接
+和总超时、响应大小限制、错误脱敏与 `/models` readiness。缺少 URL/Model 时回退
+`AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
+`DeterministicEngineAdapter`。
+
+未设置 `AGENT_RUN_STORE_PATH` 时使用的 `InMemoryRunStore` **仅用于 deterministic
+测试**。配置路径后使用有界 SQLite Store，可在单副本重启后保留 Run/Event/Result 和
+cursor；多副本部署仍必须替换为共享 Store。Execution Grant 与 Tool 授权由
+Southwind AI Server 签发和复核，Agent Server 不能自行扩大 Operation 的
+`allowedToolKeys`。

package/template/apps/agent-server/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "southwind-agent-server"
+version = "0.1.0"
+description = "Southwind AI canonical Agent Runtime server"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+  "fastapi==0.139.2",
+  "google-adk==2.5.0",
+  "httpx==0.28.1",
+  "pydantic==2.13.4",
+  "uvicorn==0.51.0",
+]
+
+[dependency-groups]
+dev = [
+  "mypy==2.3.0",
+  "pytest==9.1.1",
+  "pytest-asyncio==1.4.0",
+  "ruff==0.15.22",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/southwind_agent_server"]

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

@@ -0,0 +1,5 @@
+"""Southwind AI Agent Server."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

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

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+
+from .engine import (
+    AgentEngineAdapter,
+    EngineRunRequest,
+    EngineSignal,
+    SafeEngineError,
+)
+
+
+class AdkEngineAdapter(AgentEngineAdapter):
+    """Google ADK implementation skeleton.
+
+    Agent objects remain opaque and internal. A later slice will create ADK Runners,
+    consume ADK Events, and translate them into EngineSignal values at this seam.
+    """
+
+    def __init__(self, agents: Mapping[str, object] | None = None) -> None:
+        self._agents = dict(agents or {})
+
+    def supports(self, operation_key: str) -> bool:
+        return operation_key in self._agents
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        del request
+        raise SafeEngineError(
+            "RUNTIME_UNAVAILABLE",
+            "Agent Runtime 尚未配置",
+            retryable=True,
+        )
+        yield  # pragma: no cover - keeps this method an async generator
+
+    async def cancel(self, run_id: str) -> None:
+        del run_id

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

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hmac
+import os
+import uuid
+from typing import Annotated
+
+from fastapi import FastAPI, Header, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import ValidationError
+
+from .adk_adapter import AdkEngineAdapter
+from .config import EnvironmentSecretResolver, OpenAiCompatibleConfig
+from .contracts import (
+    AgentError,
+    CancelRunRequest,
+    CancelRunResponse,
+    RunResultResponse,
+    StartRunRequest,
+    StartRunResponse,
+)
+from .engine import AgentEngineAdapter
+from .openai_engine import OpenAiCompatibleEngineAdapter
+from .openai_provider import OpenAiCompatibleProvider
+from .service import (
+    AgentRunService,
+    IdempotencyConflictError,
+    OperationNotFoundError,
+    RunNotFoundError,
+)
+from .sqlite_store import RunStoreCapacityError, SqliteRunStore
+from .sse import event_stream
+from .store import InMemoryRunStore, RunStore
+from .tool_host import ToolHostClient
+
+
+def create_app(
+    engine: AgentEngineAdapter | None = None,
+    *,
+    heartbeat_seconds: float = 15.0,
+    internal_token: str | None = None,
+    store: RunStore | None = None,
+) -> FastAPI:
+    runtime_engine = engine or default_engine()
+    runtime = AgentRunService(runtime_engine, store or default_store())
+    application = FastAPI(title="Southwind AI Agent Server", version="0.1.0")
+
+    @application.get("/health/live")
+    async def live() -> dict[str, str]:
+        return {"status": "live"}
+
+    @application.get("/health/ready", response_model=None)
+    async def ready() -> dict[str, str] | JSONResponse:
+        health = getattr(runtime_engine, "health", None)
+        if not health:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime 尚未配置",
+                True,
+            )
+        try:
+            await health()
+            return {"status": "ready"}
+        except Exception:
+            return safe_error(
+                503,
+                "PROVIDER_UNAVAILABLE",
+                "模型服务暂不可用",
+                True,
+            )
+
+    @application.exception_handler(OperationNotFoundError)
+    async def operation_not_found(
+        _request: Request,
+        _error: OperationNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "OPERATION_NOT_FOUND", "Agent Operation 不存在", False)
+
+    @application.exception_handler(RunNotFoundError)
+    async def run_not_found(
+        _request: Request,
+        _error: RunNotFoundError,
+    ) -> JSONResponse:
+        return safe_error(404, "RUN_CONFLICT", "Agent Run 不存在", False)
+
+    @application.exception_handler(IdempotencyConflictError)
+    async def idempotency_conflict(
+        _request: Request,
+        _error: IdempotencyConflictError,
+    ) -> JSONResponse:
+        return safe_error(409, "RUN_CONFLICT", "幂等键已用于其他请求", False)
+
+    @application.exception_handler(RunStoreCapacityError)
+    async def run_store_capacity(
+        _request: Request,
+        _error: RunStoreCapacityError,
+    ) -> JSONResponse:
+        return safe_error(
+            429,
+            "BUDGET_EXCEEDED",
+            "Agent Run 存储容量已满",
+            True,
+        )
+
+    @application.exception_handler(ValidationError)
+    async def validation_error(
+        _request: Request,
+        _error: ValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.exception_handler(RequestValidationError)
+    async def request_validation_error(
+        _request: Request,
+        _error: RequestValidationError,
+    ) -> JSONResponse:
+        return safe_error(400, "INVALID_INPUT", "请求格式无效", False)
+
+    @application.post("/api/agent/runs", response_model=StartRunResponse)
+    async def start_run(
+        request: StartRunRequest,
+        idempotency_key: Annotated[str, Header(alias="Idempotency-Key")],
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StartRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        if not idempotency_key.strip():
+            return safe_error(400, "INVALID_INPUT", "幂等键不能为空", False)
+        record = await runtime.start(
+            request,
+            idempotency_key,
+        )
+        return StartRunResponse(
+            run_id=record.run_id,
+            status=record.status,
+            events_url=f"/api/agent/runs/{record.run_id}/events",
+        )
+
+    @application.get("/api/agent/runs/{run_id}/events", response_model=None)
+    async def get_events(
+        run_id: str,
+        after: Annotated[int | None, Query(ge=0)] = None,
+        last_event_id: Annotated[str | None, Header(alias="Last-Event-ID")] = None,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StreamingResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        await runtime.get(run_id)
+        try:
+            cursor = parse_cursor(after, last_event_id)
+        except ValueError:
+            return safe_error(400, "INVALID_INPUT", "事件游标无效", False)
+        return StreamingResponse(
+            event_stream(runtime, run_id, cursor, heartbeat_seconds),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @application.get(
+        "/api/agent/runs/{run_id}/result",
+        response_model=RunResultResponse,
+    )
+    async def get_result(
+        run_id: str,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> RunResultResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.get(run_id)
+        if record.status == "completed":
+            return RunResultResponse(
+                run_id=record.run_id,
+                status="completed",
+                output=record.output,
+            )
+        if record.status == "cancelled":
+            return safe_error(409, "RUN_CANCELLED", "Agent Run 已取消", False)
+        if record.status == "failed":
+            return safe_error(409, "RUNTIME_UNAVAILABLE", "Agent Run 执行失败", True)
+        return safe_error(409, "RUN_CONFLICT", "Agent Run 尚未完成", True)
+
+    @application.post(
+        "/api/agent/runs/{run_id}/cancel",
+        response_model=CancelRunResponse,
+    )
+    async def cancel_run(
+        run_id: str,
+        _request: CancelRunRequest,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> CancelRunResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        record = await runtime.cancel(run_id)
+        return CancelRunResponse(run_id=record.run_id, status=record.status)
+
+    application.state.run_service = runtime
+    return application
+
+
+def default_engine() -> AgentEngineAdapter:
+    config = OpenAiCompatibleConfig.from_environment()
+    if config is None:
+        return AdkEngineAdapter()
+    internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
+    if not internal_token:
+        raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
+    return OpenAiCompatibleEngineAdapter(
+        OpenAiCompatibleProvider(
+            config,
+            EnvironmentSecretResolver(os.environ),
+        ),
+        ToolHostClient(internal_token),
+    )
+
+
+def default_store() -> RunStore:
+    path = os.environ.get("AGENT_RUN_STORE_PATH", "").strip()
+    return SqliteRunStore(path) if path else InMemoryRunStore()
+
+
+def authorized(provided: str | None, expected: str | None) -> bool:
+    if expected is None:
+        return True
+    if not expected or not provided or not provided.startswith("Bearer "):
+        return False
+    return hmac.compare_digest(provided.removeprefix("Bearer "), expected)
+
+
+def parse_cursor(after: int | None, last_event_id: str | None) -> int:
+    header_cursor = 0
+    if last_event_id is not None:
+        if not last_event_id.isdigit():
+            raise ValueError
+        header_cursor = int(last_event_id)
+    return max(after or 0, header_cursor)
+
+
+def safe_error(
+    status_code: int,
+    code: str,
+    message: str,
+    retryable: bool,
+) -> JSONResponse:
+    error = AgentError.model_validate(
+        {
+            "code": code,
+            "message": message,
+            "requestId": f"request_{uuid.uuid4().hex}",
+            "retryable": retryable,
+        }
+    )
+    return JSONResponse(
+        status_code=status_code,
+        content=error.model_dump(by_alias=True),
+    )
+
+
+app = create_app(internal_token=os.environ.get("AGENT_SERVER_INTERNAL_TOKEN"))