create-windy 0.3.17 → 0.3.19

package/template/apps/agent-server/tests/test_adk_debug_result_polling.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+
+from southwind_agent_server.adk_debug import CanonicalRunDebugClient
+
+OPERATION_KEY = "customer.copilot.global"
+
+
+async def test_client_waits_for_result_after_stream_closes() -> None:
+    result_attempts = 0
+    started_runs = 0
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal result_attempts, started_runs
+        if request.url.path == "/api/agent/runs":
+            started_runs += 1
+            return httpx.Response(200, json={"runId": "run_race"})
+        if request.url.path.endswith("/events"):
+            return httpx.Response(
+                200,
+                content=(
+                    b'event: run.started\ndata: {"sequence":1,"type":"run.started"}\n\n'
+                ),
+            )
+        if request.url.path.endswith("/result"):
+            result_attempts += 1
+            if result_attempts < 3:
+                return httpx.Response(
+                    409,
+                    json={"code": "RUN_CONFLICT", "retryable": True},
+                )
+            return httpx.Response(
+                200,
+                json={
+                    "runId": "run_race",
+                    "status": "completed",
+                    "output": {"text": "稍后可读"},
+                },
+            )
+        raise AssertionError(request.url)
+
+    client = CanonicalRunDebugClient(
+        OPERATION_KEY,
+        "https://platform.test",
+        "developer-token",
+        transport=httpx.MockTransport(handler),
+        result_poll_interval_seconds=0.001,
+    )
+
+    result = await client.run("验证竞态")
+
+    assert result["answer"] == "稍后可读"
+    events = result["events"]
+    assert isinstance(events, list) and {"type": "run.completed"} in events
+    assert started_runs == 1
+    assert result_attempts == 3
+
+
+@pytest.mark.parametrize(
+    ("payload", "timeout_seconds", "delay_seconds", "message"),
+    [
+        (
+            {
+                "code": "RUN_CANCELLED",
+                "message": "secret-upstream-body",
+                "retryable": False,
+            },
+            5,
+            0,
+            "永久失败",
+        ),
+        (
+            {
+                "code": "RUN_CONFLICT",
+                "message": "Agent Run 尚未完成",
+                "retryable": True,
+            },
+            0.01,
+            0,
+            "等待超时",
+        ),
+        (
+            {
+                "code": "RUN_CONFLICT",
+                "message": "slow-secret-upstream-body",
+                "retryable": True,
+            },
+            0.01,
+            0.05,
+            "等待超时",
+        ),
+    ],
+)
+async def test_client_bounds_result_polling_and_hides_error_content(
+    payload: dict[str, object],
+    timeout_seconds: float,
+    delay_seconds: float,
+    message: str,
+) -> None:
+    requests: list[httpx.Request] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == "/api/agent/runs":
+            return httpx.Response(200, json={"runId": "run_terminal"})
+        if request.url.path.endswith("/events"):
+            return httpx.Response(
+                200,
+                content=(
+                    b"event: run.completed\ndata: "
+                    b'{"sequence":1,"type":"run.completed"}\n\n'
+                ),
+            )
+        if request.url.path.endswith("/result"):
+            await asyncio.sleep(delay_seconds)
+            return httpx.Response(409, json=payload)
+        raise AssertionError(request.url)
+
+    client = CanonicalRunDebugClient(
+        OPERATION_KEY,
+        "https://platform.test",
+        "developer-token",
+        transport=httpx.MockTransport(handler),
+        result_poll_timeout_seconds=timeout_seconds,
+        result_poll_interval_seconds=0.001,
+    )
+
+    with pytest.raises(RuntimeError, match=message) as failure:
+        await client.run("验证结果失败")
+
+    error_message = str(failure.value)
+    assert "secret-upstream-body" not in error_message
+    assert "slow-secret-upstream-body" not in error_message
+    assert sum(request.url.path == "/api/agent/runs" for request in requests) == 1
+    assert sum(request.url.path.endswith("/result") for request in requests) >= 1

package/template/apps/agent-server/tests/test_adk_web_canonical_debug.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+from google.adk.models.llm_request import LlmRequest
+from google.genai import types
+
+from adk_web_agents.canonical_debug.agent import (
+    TOOL_NAME,
+    CanonicalDebugLlm,
+    build_root_agent,
+)
+from southwind_agent_server.adk_debug import (
+    MAX_EVENT_FRAME_BYTES,
+    CanonicalRunDebugClient,
+    TextOperationDebugConfig,
+    compact_events,
+    load_text_operation_debug_config,
+    sse_events,
+)
+
+OPERATION = TextOperationDebugConfig("customer.copilot.global")
+
+
+async def test_client_runs_project_operation_through_canonical_api() -> None:
+    requests: list[httpx.Request] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == "/api/agent/runs":
+            return httpx.Response(200, json={"runId": "run_debug"})
+        if request.url.path.endswith("/events"):
+            return httpx.Response(
+                200,
+                content=(
+                    b"event: tool.requested\ndata: "
+                    b'{"sequence":1,"type":"tool.requested",'
+                    b'"toolKey":"customer.records.search"}\n\n'
+                    b"event: run.completed\ndata: "
+                    b'{"sequence":2,"type":"run.completed"}\n\n'
+                ),
+            )
+        if request.url.path.endswith("/result"):
+            return httpx.Response(
+                200,
+                json={
+                    "runId": "run_debug",
+                    "status": "completed",
+                    "output": {"text": "真实回答"},
+                },
+            )
+        raise AssertionError(request.url)
+
+    client = CanonicalRunDebugClient(
+        OPERATION.operation_key,
+        "https://platform.test",
+        "developer-token",
+        transport=httpx.MockTransport(handler),
+    )
+
+    result = await client.run("请查询案件")
+
+    assert result == {
+        "runId": "run_debug",
+        "answer": "真实回答",
+        "events": [
+            {
+                "sequence": 1,
+                "type": "tool.requested",
+                "toolKey": "customer.records.search",
+            },
+            {"sequence": 2, "type": "run.completed"},
+        ],
+    }
+    assert requests[0].headers["authorization"] == "Bearer developer-token"
+    assert json.loads(requests[0].content) == {
+        "operationKey": "customer.copilot.global",
+        "input": {"question": "请查询案件"},
+    }
+
+
+async def test_dispatcher_sends_user_text_to_canonical_tool() -> None:
+    model = CanonicalDebugLlm(OPERATION)
+    request = LlmRequest(
+        contents=[types.Content(role="user", parts=[types.Part(text="查测试数据")])]
+    )
+
+    responses = [response async for response in model.generate_content_async(request)]
+
+    response = responses[0]
+    assert response.content and response.content.parts
+    call = response.content.parts[0].function_call
+    assert call
+    assert call.name == TOOL_NAME
+    assert call.args == {"question": "查测试数据"}
+    assert build_root_agent(OPERATION).name == "canonical_debug"
+    assert len(build_root_agent(OPERATION).tools) == 1
+
+
+async def test_dispatcher_renders_result_and_bounded_event_summary() -> None:
+    model = CanonicalDebugLlm(OPERATION)
+    request = LlmRequest(
+        contents=[
+            types.Content(
+                role="user",
+                parts=[
+                    types.Part(
+                        function_response=types.FunctionResponse(
+                            name=TOOL_NAME,
+                            response={
+                                "runId": "run_debug",
+                                "answer": "真实回答",
+                                "events": [{"type": "run.completed"}],
+                            },
+                        )
+                    )
+                ],
+            )
+        ]
+    )
+
+    responses = [response async for response in model.generate_content_async(request)]
+
+    response = responses[0]
+    assert response.content and response.content.parts
+    assert response.content.parts[0].text == (
+        '真实回答\n\n---\n调试 Run：run_debug\n事件摘要：[{"type": "run.completed"}]'
+    )
+
+
+async def test_unconfigured_project_fails_closed_without_tool() -> None:
+    model = CanonicalDebugLlm(None)
+    request = LlmRequest(
+        contents=[types.Content(role="user", parts=[types.Part(text="查测试数据")])]
+    )
+
+    responses = [response async for response in model.generate_content_async(request)]
+
+    response = responses[0]
+    assert response.content and response.content.parts
+    assert "尚未" in (response.content.parts[0].text or "")
+    assert build_root_agent(None).tools == []
+
+
+def test_project_config_selects_only_operation_key(tmp_path: Path) -> None:
+    path = tmp_path / "adk-web-debug.json"
+    path.write_text(
+        '{"schemaVersion":1,"textOperation":'
+        '{"key":"customer.copilot.global","dataActorId":"user_dev_admin"}}',
+        encoding="utf-8",
+    )
+
+    assert load_text_operation_debug_config(path) == TextOperationDebugConfig(
+        "customer.copilot.global", "user_dev_admin"
+    )
+
+
+def test_environment_selects_operation_without_mount(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("ADK_DEBUG_OPERATION_KEY", "customer.copilot.global")
+
+    assert load_text_operation_debug_config() == OPERATION
+
+
+def test_missing_project_config_is_unconfigured(tmp_path: Path) -> None:
+    assert load_text_operation_debug_config(tmp_path / "missing.json") is None
+
+
+def test_project_config_rejects_unknown_fields(tmp_path: Path) -> None:
+    path = tmp_path / "adk-web-debug.json"
+    path.write_text(
+        '{"schemaVersion":1,"textOperation":null,"token":"forbidden"}',
+        encoding="utf-8",
+    )
+
+    with pytest.raises(RuntimeError, match="格式无效"):
+        load_text_operation_debug_config(path)
+
+
+def test_client_rejects_missing_user_token(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ADK_DEBUG_PLATFORM_TOKEN", raising=False)
+
+    with pytest.raises(RuntimeError, match="ADK_DEBUG_PLATFORM_TOKEN"):
+        CanonicalRunDebugClient.from_environment(OPERATION.operation_key)
+
+
+def test_event_summary_compacts_streaming_output() -> None:
+    events = compact_events(
+        [
+            {"sequence": 1, "type": "run.started"},
+            {"sequence": 2, "type": "output.delta"},
+            {"sequence": 3, "type": "output.delta"},
+            {"sequence": 4, "type": "run.completed"},
+        ]
+    )
+
+    assert events == [
+        {"sequence": 1, "type": "run.started"},
+        {"sequence": 4, "type": "run.completed"},
+        {"type": "output.delta", "count": 2},
+    ]
+
+
+async def test_event_stream_rejects_oversized_frame() -> None:
+    response = httpx.Response(
+        200,
+        content=b"event: output.delta\ndata: " + b"x" * MAX_EVENT_FRAME_BYTES,
+    )
+
+    with pytest.raises(RuntimeError, match="超过调试上限"):
+        _ = [event async for event in sse_events(response)]
+
+
+def test_event_summary_never_exceeds_visible_limit() -> None:
+    events = compact_events(
+        [
+            *[
+                {"sequence": sequence, "type": "tool.completed"}
+                for sequence in range(100)
+            ],
+            {"sequence": 101, "type": "output.delta"},
+        ]
+    )
+
+    assert len(events) == 64
+    assert events[-2:] == [
+        {"type": "output.delta", "count": 1},
+        {"type": "events.truncated", "count": 38},
+    ]

package/template/apps/server/src/agent/run-debug-authorization.ts

@@ -0,0 +1,27 @@
+import { projectedModuleUserId, type RequestActor } from "../guards.js";
+import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
+
+interface AgentDebugOperationRuntime {
+  agentDebugOperationForActor(actorId: string): string | undefined;
+}
+
+export function assertSelectedDebugOperation(
+  runtime: AgentDebugOperationRuntime,
+  actorId: string,
+  operationKey: string,
+  disclosure: "forbidden" | "hidden",
+) {
+  const selected = runtime.agentDebugOperationForActor(actorId);
+  if (!selected || selected === operationKey) return;
+  if (disclosure === "hidden") throw inaccessibleRun();
+  throw new AgentRunFacadeError(
+    "FORBIDDEN",
+    "ADK Web 调试身份只能执行项目选定的 Agent Operation",
+    403,
+  );
+}
+
+export function debugActorAuditMetadata(actor: RequestActor) {
+  const userId = projectedModuleUserId(actor);
+  return userId ? { debugDataActorId: userId } : {};
+}

package/template/apps/server/src/agent/run-facade-adk-debug.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { AgentRunFacade } from "./run-facade.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { debugActorAuditMetadata } from "./run-debug-authorization.js";
+import { bindModuleUserProjection } from "../guards.js";
+
+describe("ADK 调试 Operation 边界", () => {
+  test("专用身份不能切换到未选定的 Agent Operation", async () => {
+    const fixture = await createRunFacadeFixture();
+    const runtime = Object.assign(fixture.runtime, {
+      agentDebugOperationForActor(actorId: string) {
+        return actorId === "actor-1" ? "business.other" : undefined;
+      },
+    });
+    const facade = new AgentRunFacade(
+      [runFacadeManifest()],
+      fixture.hosts,
+      runtime,
+      fixture.remote,
+      createTestRunAuthorizationStore(),
+    );
+
+    await expect(
+      facade.start(
+        "business.answer",
+        { question: "越权切换" },
+        "request-debug",
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "FORBIDDEN", status: 403 });
+    await expect(
+      facade.authorizeRun("business.answer", "run_1", fixture.context),
+    ).rejects.toMatchObject({ code: "RUN_CONFLICT", status: 404 });
+  });
+
+  test("审计显式记录业务数据用户但不替换核心调试主体", () => {
+    expect(
+      debugActorAuditMetadata(
+        bindModuleUserProjection(
+          {
+            id: "service_adk_debug",
+            type: "service",
+            name: "ADK 开发调试",
+            roleCodes: ["adk-debug"],
+            permissionKeys: ["business.answer.execute"],
+          },
+          "user_dev_admin",
+        ),
+      ),
+    ).toEqual({ debugDataActorId: "user_dev_admin" });
+  });
+});

package/template/apps/server/src/agent/run-facade.test-support.ts

@@ -0,0 +1,235 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeAgentRuntime } from "./fake-runtime.test-support.js";
+import { AgentRunFacade } from "./run-facade.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+
+export async function createRunFacadeFixture(
+  permissionKeys: string[] = ["business.ai.execute", "business.records.read"],
+) {
+  const module = runFacadeManifest();
+  const prepared: unknown[] = [];
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            {
+              operationKey: "business.answer",
+              release: {
+                workflowVersion: "workflow-2",
+                promptVersion: "prompt-3",
+                routeVersion: "route-4",
+              },
+              prepare(input, context) {
+                prepared.push({ input, actorId: context.actor.id });
+                const question =
+                  typeof input === "object" &&
+                  input !== null &&
+                  !Array.isArray(input) &&
+                  typeof input.question === "string"
+                    ? input.question
+                    : "";
+                return {
+                  instructions: "只回答当前业务问题。",
+                  userPrompt: question,
+                };
+              },
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const context = guardContext(permissionKeys);
+  const remote = new FakeAgentRuntime();
+  const facade = new AgentRunFacade(
+    [module],
+    hosts,
+    runtime,
+    remote,
+    createTestRunAuthorizationStore(),
+  );
+  return { context, facade, hosts, prepared, remote, runtime };
+}
+
+export function guardContext(permissionKeys: string[]) {
+  return createRequestGuardContext(
+    new Request("http://localhost/api/agent/runs"),
+    {
+      resolveActor: () => ({
+        id: "actor-1",
+        type: "user",
+        name: "测试用户",
+        roleCodes: ["user"],
+        permissionKeys,
+        scopeContext: buildScopeContext("actor-1", undefined, [
+          {
+            id: "role-user",
+            code: "user",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      }),
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+}
+
+export function runFacadeManifest(): ModuleManifest {
+  return {
+    name: "business",
+    version: "0.1.0",
+    label: "业务",
+    description: "业务",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      permission("business.ai.execute", "ai", "manage"),
+      permission("business.records.read", "records", "read"),
+    ],
+    apiPermissions: [],
+    features: [
+      enabledFeature("business.ai"),
+      enabledFeature("business.records"),
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      {
+        key: "business.records.input.v1",
+        schema: { type: "object" },
+      },
+      {
+        key: "business.records.output.v1",
+        schema: { type: "object" },
+      },
+      { key: "business.input.v1", schema: { type: "object" } },
+      { key: "business.output.v1", schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [
+      {
+        key: "business.records.list",
+        label: "查询记录",
+        description: "查询当前范围记录。",
+        inputSchemaKey: "business.records.input.v1",
+        outputSchemaKey: "business.records.output.v1",
+        operation: "query",
+        permissionKey: "business.records.read",
+        featureKey: "business.records",
+        auditAction: "business.records.read",
+        scopeMode: "request",
+        dataClassification: "internal",
+        idempotency: "none",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 10,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
+      },
+    ],
+    aiOperations: [agentOperation()],
+    providers: [],
+    auditActions: ["business.ai.execute", "business.records.read"],
+  };
+}
+
+function agentOperation() {
+  return {
+    key: "business.answer",
+    kind: "agent" as const,
+    featureKey: "business.ai",
+    permissionKey: "business.ai.execute",
+    auditAction: "business.ai.execute" as const,
+    inputSchemaKey: "business.input.v1",
+    outputSchemaKey: "business.output.v1",
+    requiredCapabilities: ["text-generation"],
+    allowedToolKeys: ["business.records.list"],
+    dataClassification: "internal" as const,
+    execution: "streaming" as const,
+    providerEgress: {
+      mode: "configured-endpoint" as const,
+      deploymentKey: "ai.openai-compatible",
+    },
+    providerDataPolicy: {
+      inputFields: [
+        {
+          jsonPointer: "/question",
+          classification: "internal" as const,
+          dlpAction: "redact" as const,
+        },
+      ],
+      envelopeFields: [
+        fieldPolicy("instructions", "reject"),
+        fieldPolicy("user-prompt", "redact"),
+        fieldPolicy("tool-definitions", "reject"),
+        fieldPolicy("provider-output", "redact"),
+        {
+          field: "tool-results" as const,
+          classification: "sensitive" as const,
+          dlpAction: "redact" as const,
+        },
+      ],
+    },
+    toolNetworkPolicy: { mode: "forbidden" as const },
+    limits: {
+      maxDurationSeconds: 60,
+      maxInputBytes: 4096,
+      maxOutputBytes: 4096,
+    },
+  };
+}
+
+function fieldPolicy(
+  field:
+    | "instructions"
+    | "user-prompt"
+    | "tool-definitions"
+    | "provider-output",
+  dlpAction: "reject" | "redact",
+) {
+  return {
+    field,
+    classification: "internal" as const,
+    dlpAction,
+  };
+}
+
+function permission(key: string, resource: string, action: "read" | "manage") {
+  return {
+    key,
+    label: key,
+    module: "business",
+    moduleLabel: "业务",
+    resource,
+    resourceLabel: resource,
+    action,
+  };
+}
+
+function enabledFeature(key: string) {
+  return {
+    key: featureKey(key),
+    label: key,
+    module: "business",
+    visible: "visible" as const,
+    enabled: true,
+    stage: "stable" as const,
+  };
+}