create-windy 0.8.1 → 0.8.3

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

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from dataclasses import replace
+from pathlib import Path
+from typing import cast
+
+import httpx
+import pytest
+
+from southwind_agent_server.attempt_context import govern_provider_attempt
+from southwind_agent_server.attempt_context_projection import (
+    AttemptContextPreparation,
+    governed_envelope,
+)
+from southwind_agent_server.context_message_digest import canonical_json_digest
+from southwind_agent_server.context_version_port import (
+    PreparedContext,
+    PreparedSource,
+    UnavailableContextVersionPort,
+)
+from southwind_agent_server.contracts import JsonValue, ProviderFieldPolicy
+from southwind_agent_server.engine import (
+    EngineCompleted,
+    EngineRunRequest,
+    SafeEngineError,
+    ToolCompleted,
+)
+from southwind_agent_server.openai_engine import OpenAiCompatibleEngineAdapter
+from southwind_agent_server.tool_host import ToolHostClient
+from tests.openai_provider_test_support import (
+    create_provider,
+    governance,
+    runtime_request,
+    sse_response,
+)
+
+SCHEMA: dict[str, JsonValue] = {
+    "type": "object",
+    "properties": {"total": {"type": "integer"}},
+    "required": ["total"],
+    "additionalProperties": False,
+}
+
+
+def structured_request() -> EngineRunRequest:
+    request = runtime_request("business.records.list")
+    return replace(
+        request,
+        output_schema_key="business.answer.v1",
+        output_schema=SCHEMA,
+        provider_data_policy=request.provider_data_policy.model_copy(
+            update={
+                "envelope_fields": [
+                    *request.provider_data_policy.envelope_fields,
+                    ProviderFieldPolicy(
+                        field="output-schema",
+                        classification="internal",
+                        dlp_action="redact",
+                    ),
+                ]
+            }
+        ),
+    )
+
+
+def test_tool_payload_uses_schema_guidance_without_mutation_or_duplicate() -> None:
+    provider = create_provider(httpx.MockTransport(lambda _: httpx.Response(500)))
+    request = runtime_request("business.records.list")
+    messages: list[dict[str, JsonValue]] = [{"role": "system", "content": "原指令"}]
+    body = provider.request_body(messages, request.allowed_tools, "answer.v1", SCHEMA)
+    payload = json.loads(body)
+    assert "response_format" not in payload
+    assert payload["tools"][0]["function"]["name"] == "business.records.list"
+    assert payload["messages"][0]["content"].startswith("原指令\n\n")
+    assert (
+        json.dumps(SCHEMA, ensure_ascii=False, separators=(",", ":"))
+        in payload["messages"][0]["content"]
+    )
+    assert messages[0]["content"] == "原指令"
+    assert (
+        provider.request_body(
+            payload["messages"], request.allowed_tools, "answer.v1", SCHEMA
+        )
+        == body
+    )
+    plain = json.loads(provider.request_body(messages, (), "answer.v1", SCHEMA))
+    assert plain["messages"] == messages
+    assert plain["response_format"]["json_schema"]["strict"] is True
+
+
+@pytest.mark.parametrize("final", ['{"total":1}', '{"total":"1"}', "```json\n{}\n```"])
+async def test_real_function_round_keeps_strict_final_schema(final: str) -> None:
+    turns = 0
+    calls = 0
+
+    async def provider_handler(request: httpx.Request) -> httpx.Response:
+        nonlocal turns
+        turns += 1
+        body = json.loads(request.content)
+        assert "response_format" not in body
+        assert '"required":["total"]' in body["messages"][0]["content"]
+        if turns == 1:
+            return sse_response(
+                [
+                    {
+                        "choices": [
+                            {
+                                "delta": {
+                                    "tool_calls": [
+                                        {
+                                            "index": 0,
+                                            "id": "call_1",
+                                            "function": {
+                                                "name": "business.records.list",
+                                                "arguments": "{}",
+                                            },
+                                        }
+                                    ]
+                                }
+                            }
+                        ]
+                    }
+                ]
+            )
+        assert body["messages"][-1]["role"] == "tool"
+        return sse_response([{"choices": [{"delta": {"content": final}}]}])
+
+    async def tool_handler(request: httpx.Request) -> httpx.Response:
+        nonlocal calls
+        calls += 1
+        assert json.loads(request.content)["executionGrant"] == "grant_1"
+        return httpx.Response(200, json={"value": {"total": 1}})
+
+    engine = OpenAiCompatibleEngineAdapter(
+        create_provider(httpx.MockTransport(provider_handler)),
+        ToolHostClient("internal-token", transport=httpx.MockTransport(tool_handler)),
+        governance(),
+    )
+    request = structured_request()
+    if final == '{"total":1}':
+        signals = [signal async for signal in engine.execute(request)]
+        assert any(isinstance(signal, ToolCompleted) for signal in signals)
+        assert isinstance(signals[-1], EngineCompleted)
+        assert signals[-1].output == {"total": 1}
+    else:
+        with pytest.raises(SafeEngineError) as denied:
+            _ = [signal async for signal in engine.execute(request)]
+        assert denied.value.code == "OUTPUT_VALIDATION_FAILED"
+    assert turns == 2 and calls == 1
+
+
+async def test_text_tool_call_is_not_executable() -> None:
+    async def provider_handler(_: httpx.Request) -> httpx.Response:
+        return sse_response(
+            [
+                {
+                    "choices": [
+                        {
+                            "delta": {
+                                "content": (
+                                    '{"tool_calls":[{"name":"business.records.list",'
+                                    '"arguments":{}}]}'
+                                )
+                            }
+                        }
+                    ]
+                }
+            ]
+        )
+
+    async def tool_handler(_: httpx.Request) -> httpx.Response:
+        pytest.fail("正文中的工具调用不得执行")
+
+    engine = OpenAiCompatibleEngineAdapter(
+        create_provider(httpx.MockTransport(provider_handler)),
+        ToolHostClient("internal-token", transport=httpx.MockTransport(tool_handler)),
+        governance(),
+    )
+    with pytest.raises(SafeEngineError) as denied:
+        _ = [signal async for signal in engine.execute(structured_request())]
+    assert denied.value.code == "OUTPUT_VALIDATION_FAILED"
+
+
+async def test_governed_guidance_matches_audit_and_context_bytes(
+    tmp_path: Path,
+) -> None:
+    request = structured_request()
+    request = replace(
+        request, output_schema={**SCHEMA, "description": "password=secret"}
+    )
+    provider = create_provider(httpx.MockTransport(lambda _: httpx.Response(500)))
+    audit_path = str(tmp_path / "audit.sqlite3")
+    messages: list[dict[str, JsonValue]] = [
+        {"role": "system", "content": request.instructions},
+        {"role": "user", "content": "历史来源"},
+        {"role": "user", "content": request.user_prompt},
+    ]
+    prepared = await govern_provider_attempt(
+        UnavailableContextVersionPort(),
+        governance(audit_path),
+        provider,
+        request,
+        1,
+        None,
+        messages,
+    )
+    payload = json.loads(prepared.provider_request)
+    assert payload["messages"] == prepared.governed.messages
+    assert "password=secret" not in prepared.provider_request.decode()
+    assert "[REDACTED]" in payload["messages"][0]["content"]
+    with sqlite3.connect(audit_path) as connection:
+        assert connection.execute(
+            "select sent_bytes, decision from provider_attempt_audit"
+        ).fetchone() == (len(prepared.provider_request), "redact")
+    source = PreparedSource(
+        "business", "session", "source-1", "v1", 1, "a" * 64, {}, "历史来源", "user"
+    )
+    envelope = governed_envelope(
+        AttemptContextPreparation(
+            PreparedContext("preparation-1", (source,)), messages, 1
+        ),
+        request.run_id,
+        "attempt-1",
+        prepared.governed.messages,
+        prepared.provider_request,
+        provider.config.deployment_key,
+        provider.config.model,
+        request.prompt_version,
+        (),
+    )
+    entries = cast(list[dict[str, JsonValue]], envelope["messages"])
+    assert entries[0]["content"] == payload["messages"][0]["content"]
+    assert (
+        cast(list[dict[str, JsonValue]], entries[1]["origins"])[0]["sourceId"]
+        == "source-1"
+    )
+    provider_fields = cast(dict[str, JsonValue], envelope["provider"])
+    assert (
+        provider_fields["requestDigest"]
+        == hashlib.sha256(prepared.provider_request).hexdigest()
+    )
+    assert provider_fields["outputSchemaDigest"] == hashlib.sha256(b"null").hexdigest()
+    assert entries[0]["digest"] == canonical_json_digest(payload["messages"][0])
+    assert entries[0]["digest"] != canonical_json_digest(cast(JsonValue, messages[0]))
+
+
+async def test_schema_guidance_still_requires_output_schema_authorization() -> None:
+    request = structured_request()
+    request = replace(
+        request,
+        provider_data_policy=runtime_request(
+            "business.records.list"
+        ).provider_data_policy,
+    )
+    with pytest.raises(SafeEngineError) as denied:
+        await govern_provider_attempt(
+            UnavailableContextVersionPort(),
+            governance(),
+            create_provider(httpx.MockTransport(lambda _: httpx.Response(500))),
+            request,
+            1,
+            None,
+            [{"role": "system", "content": "指令"}],
+        )
+    assert denied.value.code == "FORBIDDEN"
+
+
+async def test_schema_guidance_counts_toward_input_token_budget() -> None:
+    calls = 0
+
+    async def handler(_: httpx.Request) -> httpx.Response:
+        nonlocal calls
+        calls += 1
+        return sse_response([])
+
+    provider = create_provider(httpx.MockTransport(handler))
+    request = structured_request()
+    messages: list[dict[str, JsonValue]] = [
+        {"role": "system", "content": request.instructions},
+        {"role": "user", "content": request.user_prompt},
+    ]
+    original_bytes = len(provider.request_body(messages, request.allowed_tools))
+    assert original_bytes < 1024
+    request = replace(
+        request,
+        output_schema={**SCHEMA, "description": "业务结果字段说明。" * 100},
+        limits=request.limits.model_copy(update={"max_input_tokens": original_bytes}),
+    )
+    engine = OpenAiCompatibleEngineAdapter(
+        provider, ToolHostClient("internal-token"), governance()
+    )
+    with pytest.raises(SafeEngineError) as denied:
+        _ = [signal async for signal in engine.execute(request)]
+    assert denied.value.code == "BUDGET_EXCEEDED"
+    assert calls == 0
+
+
+async def test_tool_schema_respects_model_attempt_limit() -> None:
+    calls = 0
+
+    async def handler(_: httpx.Request) -> httpx.Response:
+        nonlocal calls
+        calls += 1
+        return sse_response(
+            [
+                {
+                    "choices": [
+                        {
+                            "delta": {
+                                "tool_calls": [
+                                    {
+                                        "index": 0,
+                                        "id": "call_1",
+                                        "function": {
+                                            "name": "business.records.list",
+                                            "arguments": "{}",
+                                        },
+                                    }
+                                ]
+                            }
+                        }
+                    ]
+                }
+            ]
+        )
+
+    request = structured_request()
+    request = replace(
+        request, limits=request.limits.model_copy(update={"max_model_attempts": 1})
+    )
+    engine = OpenAiCompatibleEngineAdapter(
+        create_provider(httpx.MockTransport(handler)),
+        ToolHostClient(
+            "internal-token",
+            transport=httpx.MockTransport(
+                lambda _: httpx.Response(200, json={"value": {"total": 1}})
+            ),
+        ),
+        governance(),
+    )
+    with pytest.raises(SafeEngineError) as denied:
+        _ = [signal async for signal in engine.execute(request)]
+    assert denied.value.code == "BUDGET_EXCEEDED"
+    assert calls == 1

package/template/apps/server/src/agent/admin-catalog-bootstrap.ts

@@ -0,0 +1,25 @@
+import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
+import type { composeAgentToolRuntime } from "./runtime-tool-composition.js";
+import { registerAgentAdminCatalogRoutes } from "./tool-catalog-routes.js";
+
+export interface AgentAdminReadinessRef {
+  current?: ModuleAiOperationReadinessPortV1;
+}
+
+export function registerAgentAdminCatalogRuntime(
+  input: AgentPlatformRuntimeInput,
+  tools: ReturnType<typeof composeAgentToolRuntime>,
+  readiness: AgentAdminReadinessRef,
+) {
+  registerAgentAdminCatalogRoutes(input.app, {
+    modules: input.modules,
+    hosts: input.hosts,
+    runtime: input.runtime,
+    registry: tools.toolRegistry,
+    authorizer: tools.routeAuthorizer,
+    runtimeAvailable: () => input.platformConfig.enableAI,
+    operationReadiness: async (operationKey) =>
+      (await readiness.current?.inspect({ operationKey }))?.status === "ready",
+  });
+}

package/template/apps/server/src/agent/agent-session-bootstrap.ts

@@ -11,13 +11,12 @@ export function registerAgentSessions(input: {
   runtime: ReturnType<typeof createServerRuntime>;
   secret: string;
 }) {
-  if (!input.hosts.agentSessionProviders.length) return;
-  registerAgentSessionRoutesV1(
-    input.app,
-    new AgentSessionFacadeV1(
-      input.hosts,
-      input.runtime,
-      new AgentSessionIdCodecV1(input.secret),
-    ),
+  const facade = new AgentSessionFacadeV1(
+    input.hosts,
+    input.runtime,
+    new AgentSessionIdCodecV1(input.secret),
   );
+  if (!input.hosts.agentSessionProviders.length) return facade;
+  registerAgentSessionRoutesV1(input.app, facade);
+  return facade;
 }

package/template/apps/server/src/agent/agent-session-facade.ts

@@ -2,6 +2,8 @@ import { randomUUIDv7 } from "bun";
 import {
   MODULE_AGENT_SESSION_SCHEMA_VERSION,
   type ModuleAgentSessionSummaryV1,
+  type ModuleAgentSessionRunReferenceV1,
+  type ModuleAgentSessionWorkflowReferenceV1,
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
@@ -33,12 +35,15 @@ export interface AgentSessionSummaryDtoV1 {
 }
 
 export interface AgentSessionDetailDtoV1 extends AgentSessionSummaryDtoV1 {
+  readonly truncated?: boolean;
   readonly messages: readonly {
     sequence: number;
     role: "user" | "assistant";
     content: string;
     createdAt: string;
   }[];
+  readonly runRefs?: readonly ModuleAgentSessionRunReferenceV1[];
+  readonly workflowRefs?: readonly ModuleAgentSessionWorkflowReferenceV1[];
 }
 
 export class AgentSessionFacadeError extends Error {
@@ -156,6 +161,13 @@ export class AgentSessionFacadeV1 {
             session: {
               ...this.project(entry, actor.id, validated),
               messages: validated.messages,
+              ...(validated.truncated !== undefined
+                ? { truncated: validated.truncated }
+                : {}),
+              ...(validated.runRefs ? { runRefs: validated.runRefs } : {}),
+              ...(validated.workflowRefs
+                ? { workflowRefs: validated.workflowRefs }
+                : {}),
             } satisfies AgentSessionDetailDtoV1,
           };
         } catch (error) {

package/template/apps/server/src/agent/agent-session-validation.ts

@@ -66,6 +66,49 @@ export function validateAgentSessionDetail(
     previousSequence = message.sequence;
   }
   if (totalChars > MAX_TOTAL_MESSAGE_CHARS) invalidProvider();
+  if (value.truncated !== undefined && typeof value.truncated !== "boolean")
+    invalidProvider();
+  const messageSequences = new Set(
+    value.messages.map(({ sequence }) => sequence),
+  );
+  if (value.runRefs !== undefined) {
+    if (!Array.isArray(value.runRefs) || value.runRefs.length > 200)
+      invalidProvider();
+    const ids = new Set<string>();
+    for (const ref of value.runRefs) {
+      if (
+        !ref ||
+        !validText(ref.runId, 200) ||
+        !validText(ref.operationKey, 200) ||
+        !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(ref.operationKey) ||
+        ids.has(ref.runId) ||
+        (ref.sessionId !== undefined && !validText(ref.sessionId, 200)) ||
+        (ref.turnId !== undefined && !validText(ref.turnId, 200)) ||
+        (ref.workflowRunId !== undefined &&
+          !validText(ref.workflowRunId, 200)) ||
+        (ref.messageSequence !== undefined &&
+          !messageSequences.has(ref.messageSequence))
+      )
+        invalidProvider();
+      ids.add(ref.runId);
+    }
+  }
+  if (value.workflowRefs !== undefined) {
+    if (!Array.isArray(value.workflowRefs) || value.workflowRefs.length > 100)
+      invalidProvider();
+    const ids = new Set<string>();
+    for (const ref of value.workflowRefs) {
+      if (
+        !ref ||
+        !validText(ref.workflowRunId, 200) ||
+        ids.has(ref.workflowRunId) ||
+        (ref.messageSequence !== undefined &&
+          !messageSequences.has(ref.messageSequence))
+      )
+        invalidProvider();
+      ids.add(ref.workflowRunId);
+    }
+  }
   return value;
 }
 

package/template/apps/server/src/agent/operation-catalog.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from "bun:test";
+import { createServerRuntime } from "../runtime.js";
+import { AgentAdminOperationCatalog } from "./operation-catalog.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+
+async function fixture(
+  options: { workflowOnly?: boolean; runtimeAvailable?: boolean } = {},
+) {
+  const run = await createRunFacadeFixture(undefined, {
+    workflowOnly: options.workflowOnly,
+  });
+  const module = runFacadeManifest(options.workflowOnly);
+  const catalog = new AgentAdminOperationCatalog({
+    modules: [module],
+    hosts: run.hosts,
+    runtime: run.runtime,
+    runtimeAvailable: () => options.runtimeAvailable ?? true,
+  });
+  return { ...run, catalog, module };
+}
+
+describe("Admin Operation catalogue uses production registration", () => {
+  test("Registered and governed agent exposes real Schema/limits/tools, without preparing or running", async () => {
+    const { catalog, context, prepared, module, remote } = await fixture();
+    const [operation] = await catalog.list(context);
+    expect(operation).toMatchObject({
+      key: "business.answer",
+      module: "business",
+      inputSchemaKey: "business.input.v1",
+      inputSchema: module.jsonSchemas!.find(
+        ({ key }) => key === "business.input.v1",
+      )!.schema,
+      outputSchemaKey: "business.output.v1",
+      allowedToolKeys: ["business.records.list"],
+      limits: module.aiOperations![0]!.limits,
+      selectable: true,
+      availabilityReason: "allowed",
+    });
+    expect(prepared).toHaveLength(0);
+    expect(remote.started).toHaveLength(0);
+  });
+
+  test("Catalog read capability cannot start an unauthorized operation", async () => {
+    const { catalog, context, facade } = await fixture();
+    context.actor.permissionKeys = ["system.agent-debug.read"];
+    const [operation] = await catalog.list(context);
+    expect(operation).toMatchObject({
+      selectable: false,
+      availabilityReason: "permission-denied",
+    });
+    await expect(
+      facade.start(
+        "business.answer",
+        { question: "测试" },
+        "catalog-no-grant",
+        context,
+      ),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+
+  test("Workflow-only operation and unavailable Runtime are unselectable", async () => {
+    const workflow = await fixture({ workflowOnly: true });
+    expect((await workflow.catalog.list(workflow.context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "workflow-only",
+      launchAuthority: "workflow-artifact",
+    });
+    const unavailable = await fixture({ runtimeAvailable: false });
+    expect(
+      (await unavailable.catalog.list(unavailable.context))[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+  });
+
+  test("Declared readiness needs a current successful projection", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    module.aiOperations![0]!.readiness = {
+      contractVersion: 1,
+      variant: "test",
+      inputModalities: ["text"],
+      outputModalities: ["text"],
+      expectedDeployment: {
+        key: "test",
+        identity: "test",
+        releaseDigest: `sha256:${"a".repeat(64)}`,
+        offersDigest: `sha256:${"b".repeat(64)}`,
+      },
+      minConcurrentRuns: 1,
+      minQueueDepth: 1,
+    };
+    const input = {
+      modules: [module],
+      hosts,
+      runtime,
+      runtimeAvailable: () => true,
+    };
+    expect(
+      (await new AgentAdminOperationCatalog(input).list(context))[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+    expect(
+      (
+        await new AgentAdminOperationCatalog({
+          ...input,
+          operationReadiness: async () => false,
+        }).list(context)
+      )[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+    expect(
+      (
+        await new AgentAdminOperationCatalog({
+          ...input,
+          operationReadiness: async () => true,
+        }).list(context)
+      )[0],
+    ).toMatchObject({ selectable: true });
+  });
+
+  test("Unregistered handler, unsupported kind, invalid scope fail closed", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    const catalog = (current = module, currentHosts = hosts) =>
+      new AgentAdminOperationCatalog({
+        modules: [current],
+        hosts: currentHosts,
+        runtime,
+        runtimeAvailable: () => true,
+      });
+    expect(
+      (
+        await catalog(module, { ...hosts, aiOperationHandlers: [] }).list(
+          context,
+        )
+      )[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "handler-unavailable",
+    });
+    const speech = structuredClone(module);
+    speech.aiOperations![0]!.kind = "speech";
+    expect((await catalog(speech).list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "unsupported-operation",
+    });
+    delete context.actor.scopeContext;
+    expect((await catalog().list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "scope-unavailable",
+    });
+  });
+
+  test("Feature closure and missing registered output Schema fail closed", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    const missingSchema = structuredClone(module);
+    missingSchema.jsonSchemas = missingSchema.jsonSchemas!.filter(
+      ({ key }) => key !== "business.output.v1",
+    );
+    expect(
+      () =>
+        new AgentAdminOperationCatalog({
+          modules: [missingSchema],
+          hosts,
+          runtime,
+          runtimeAvailable: () => true,
+        }),
+    ).toThrow();
+    const disabledModule = structuredClone(module);
+    disabledModule.features = disabledModule.features.map((feature) => ({
+      ...feature,
+      enabled: false,
+    }));
+    const disabledRuntime = createServerRuntime(
+      {},
+      { featureCatalog: disabledModule.features },
+    );
+    const missing = new AgentAdminOperationCatalog({
+      modules: [disabledModule],
+      hosts,
+      runtime: disabledRuntime,
+      runtimeAvailable: () => true,
+    });
+    expect((await missing.list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "feature-unavailable",
+    });
+    context.license = { status: "expired", restricted: true };
+    context.licenseEnforced = true;
+    expect((await missing.list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "license-unavailable",
+    });
+  });
+});