create-windy 0.2.23 → 0.2.24

package/template/apps/server/src/agent/tool-registry.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleToolHandlers } from "./tool-registry.js";
+import {
+  createFoundationSnapshot,
+  loadFoundationModules,
+} from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { createSystemToolHandlers } from "./routes.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
+
+describe("Governed Tool Registry", () => {
+  test("输入 Schema 在 Handler 前校验并去除非契约字段", async () => {
+    const fixture = await createFixture();
+    await expect(
+      fixture.registry.execute(
+        "system.features.list",
+        { page: 0 },
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "TOOL_INPUT_INVALID" });
+
+    let received: unknown;
+    const handlers = new Map(fixture.handlers);
+    handlers.set("system.features.list", {
+      scopeMode: "platform",
+      execute: (input) => {
+        received = input;
+        return { items: [], total: 0, page: 1, pageSize: 10 };
+      },
+    });
+    const registry = new GovernedToolRegistry(
+      loadFoundationModules(),
+      handlers,
+      fixture.runtime,
+    );
+    await registry.execute(
+      "system.features.list",
+      { page: 1, permissionKeys: ["system.admin"] },
+      fixture.context,
+    );
+
+    expect(received).toEqual({ page: 1, pageSize: 10 });
+  });
+
+  test("输出漂移和 Handler scopeMode 漂移均 fail closed", async () => {
+    const fixture = await createFixture();
+    const invalidOutput = new Map(fixture.handlers);
+    invalidOutput.set("system.features.list", {
+      scopeMode: "platform",
+      execute: () => ({
+        items: [],
+        total: "wrong",
+        page: 1,
+        pageSize: 10,
+      }),
+    });
+    const registry = new GovernedToolRegistry(
+      loadFoundationModules(),
+      invalidOutput,
+      fixture.runtime,
+    );
+    await expect(
+      registry.execute("system.features.list", {}, fixture.context),
+    ).rejects.toMatchObject({ code: "TOOL_OUTPUT_INVALID" });
+
+    const mismatchedScope = new Map(fixture.handlers);
+    mismatchedScope.set("system.users.list", {
+      ...mismatchedScope.get("system.users.list")!,
+      scopeMode: "platform",
+    });
+    expect(
+      () =>
+        new GovernedToolRegistry(
+          loadFoundationModules(),
+          mismatchedScope,
+          fixture.runtime,
+        ),
+    ).toThrow("scopeMode 与 Manifest 不一致");
+  });
+
+  test("审计只记录受控字节计数，不记录 Tool 输入原值", async () => {
+    const fixture = await createFixture();
+    await fixture.registry.execute(
+      "system.features.list",
+      { page: 1 },
+      fixture.context,
+    );
+
+    const event = fixture.runtime.auditSink.list().at(-1);
+    expect(event?.action).toBe("agent.tool.execute");
+    expect(event?.metadata).toMatchObject({
+      inputBytes: expect.any(Number),
+      outputBytes: expect.any(Number),
+    });
+    expect(JSON.stringify(event)).not.toContain("permissionKeys");
+  });
+});
+
+async function createFixture() {
+  const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+  const handlers: ModuleToolHandlers = createSystemToolHandlers(
+    createSystemRepositories(createFoundationSnapshot()),
+    runtime,
+  );
+  const registry = new GovernedToolRegistry(
+    loadFoundationModules(),
+    handlers,
+    runtime,
+  );
+  const context = await runtime.createGuardContext(
+    new Request("http://localhost/api/agent/tools", {
+      headers: { authorization: "Bearer token_1" },
+    }),
+  );
+  return { context, handlers, registry, runtime };
+}

package/template/apps/server/src/agent/tool-registry.ts

@@ -0,0 +1,318 @@
+import type {
+  ModuleJsonSchemaDefinition,
+  ModuleManifest,
+  ModuleToolDefinition,
+} from "@southwind-ai/modules";
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+import type { AuditEvent, FeatureFlagDefinition } from "@southwind-ai/shared";
+import Ajv, { type ValidateFunction } from "ajv";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface PlatformToolExecutionContext {
+  readonly guardContext: RequestGuardContext;
+  readonly signal: AbortSignal;
+}
+
+export interface PlatformToolHandlerRegistration {
+  readonly scopeMode: "platform" | "request";
+  execute(
+    input: ModuleToolInput,
+    context: PlatformToolExecutionContext,
+  ): Promise<ModuleToolResult> | ModuleToolResult;
+}
+
+export type ModuleToolHandlers = ReadonlyMap<
+  string,
+  PlatformToolHandlerRegistration
+>;
+
+export interface RegisteredTool extends ModuleToolDefinition {
+  readonly module: string;
+  readonly feature: FeatureFlagDefinition;
+  readonly inputSchema: ModuleJsonSchemaDefinition["schema"];
+  readonly outputSchema: ModuleJsonSchemaDefinition["schema"];
+}
+
+interface CompiledTool {
+  readonly definition: RegisteredTool;
+  readonly handler: PlatformToolHandlerRegistration;
+  readonly validateInput: ValidateFunction<unknown>;
+  readonly validateOutput: ValidateFunction<unknown>;
+}
+
+export class GovernedToolRegistry {
+  readonly #tools: ReadonlyMap<string, CompiledTool>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    handlers: ModuleToolHandlers,
+    private readonly runtime: ServerRuntime,
+  ) {
+    const definitions = collectTools(modules);
+    validateHandlerContract(definitions, handlers);
+    const inputAjv = new Ajv({
+      allErrors: true,
+      coerceTypes: true,
+      removeAdditional: "all",
+      strict: true,
+      useDefaults: true,
+    });
+    const outputAjv = new Ajv({ allErrors: true, strict: true });
+    this.#tools = new Map(
+      definitions.map((definition) => {
+        const handler = handlers.get(definition.key)!;
+        if (handler.scopeMode !== definition.scopeMode) {
+          throw new Error(
+            `Agent Tool ${definition.key} 的 Handler scopeMode 与 Manifest 不一致`,
+          );
+        }
+        return [
+          definition.key,
+          {
+            definition,
+            handler,
+            validateInput: inputAjv.compile(definition.inputSchema),
+            validateOutput: outputAjv.compile(definition.outputSchema),
+          },
+        ];
+      }),
+    );
+  }
+
+  definitions(): readonly RegisteredTool[] {
+    return [...this.#tools.values()].map(({ definition }) => definition);
+  }
+
+  async allowed(key: string, context: RequestGuardContext): Promise<boolean> {
+    const tool = this.#tools.get(key);
+    if (!tool) return false;
+    return (
+      await evaluateAccessGuards(
+        this.runtime,
+        context,
+        {
+          permission: { permissionKey: tool.definition.permissionKey },
+          feature: tool.definition.feature,
+        },
+        { record: false },
+      )
+    ).decision.allowed;
+  }
+
+  async execute(
+    key: string,
+    rawInput: ModuleToolInput,
+    context: RequestGuardContext,
+  ): Promise<ModuleToolResult> {
+    const tool = this.#tools.get(key);
+    if (!tool) {
+      throw new ToolExecutionError("TOOL_NOT_FOUND", "Agent Tool 不存在");
+    }
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: tool.definition.permissionKey },
+      feature: tool.definition.feature,
+    });
+    if (!access.decision.allowed) {
+      throw new ToolExecutionError(
+        "TOOL_FORBIDDEN",
+        "Agent Tool 当前无权执行",
+        access.decision.reason,
+      );
+    }
+    if (
+      tool.definition.scopeMode === "request" &&
+      !isServerScopeContext(context.actor.scopeContext)
+    ) {
+      throw new ToolExecutionError(
+        "TOOL_FORBIDDEN",
+        "Agent Tool 数据范围无效",
+        "data-scope-denied",
+      );
+    }
+    const input = cloneJsonObject(rawInput);
+    enforceSize(
+      input,
+      tool.definition.limits.maxInputBytes,
+      "TOOL_INPUT_INVALID",
+    );
+    if (!tool.validateInput(input)) {
+      throw new ToolExecutionError(
+        "TOOL_INPUT_INVALID",
+        validationMessage(tool.validateInput),
+      );
+    }
+    const result = await executeWithTimeout(
+      tool,
+      input,
+      context,
+      tool.definition.limits.maxDurationSeconds,
+    );
+    enforceSize(
+      result,
+      tool.definition.limits.maxOutputBytes,
+      "TOOL_OUTPUT_INVALID",
+    );
+    if (!tool.validateOutput(result)) {
+      throw new ToolExecutionError(
+        "TOOL_OUTPUT_INVALID",
+        validationMessage(tool.validateOutput),
+      );
+    }
+    this.runtime.auditSink.recordEvent(
+      toolEvent(context, tool.definition, input, result),
+    );
+    return result;
+  }
+}
+
+export type ToolExecutionErrorCode =
+  | "TOOL_NOT_FOUND"
+  | "TOOL_FORBIDDEN"
+  | "TOOL_INPUT_INVALID"
+  | "TOOL_OUTPUT_INVALID"
+  | "TOOL_TIMEOUT";
+
+export class ToolExecutionError extends Error {
+  constructor(
+    readonly code: ToolExecutionErrorCode,
+    message: string,
+    readonly reason?: string,
+  ) {
+    super(message);
+  }
+}
+
+function collectTools(modules: readonly ModuleManifest[]): RegisteredTool[] {
+  const features = modules.flatMap(({ features }) => features);
+  const schemas = new Map(
+    modules.flatMap((module) =>
+      (module.jsonSchemas ?? []).map((schema) => [schema.key, schema] as const),
+    ),
+  );
+  return modules.flatMap((module) =>
+    module.tools.map((tool) => ({
+      ...tool,
+      module: module.name,
+      feature: required(
+        findFeature(features, tool.featureKey),
+        `Agent Tool ${tool.key} 缺少 Feature`,
+      ),
+      inputSchema: required(
+        schemas.get(tool.inputSchemaKey),
+        `Agent Tool ${tool.key} 缺少输入 Schema`,
+      ).schema,
+      outputSchema: required(
+        schemas.get(tool.outputSchemaKey),
+        `Agent Tool ${tool.key} 缺少输出 Schema`,
+      ).schema,
+    })),
+  );
+}
+
+function validateHandlerContract(
+  tools: readonly RegisteredTool[],
+  handlers: ModuleToolHandlers,
+): void {
+  const declared = new Set(tools.map(({ key }) => key));
+  for (const key of declared) {
+    if (!handlers.has(key)) throw new Error(`Agent Tool ${key} 缺少 Handler`);
+  }
+  for (const key of handlers.keys()) {
+    if (!declared.has(key)) {
+      throw new Error(`Agent Tool Handler 未声明：${key}`);
+    }
+  }
+}
+
+async function executeWithTimeout(
+  tool: CompiledTool,
+  input: ModuleToolInput,
+  context: RequestGuardContext,
+  seconds: number,
+): Promise<ModuleToolResult> {
+  const controller = new AbortController();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timeout = setTimeout(() => {
+      controller.abort();
+      reject(new ToolExecutionError("TOOL_TIMEOUT", "Agent Tool 执行超时"));
+    }, seconds * 1_000);
+  });
+  try {
+    return await Promise.race([
+      tool.handler.execute(input, {
+        guardContext: context,
+        signal: controller.signal,
+      }),
+      expired,
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function cloneJsonObject(value: ModuleToolInput): ModuleToolInput {
+  return structuredClone(value);
+}
+
+function enforceSize(
+  value: ModuleToolInput | ModuleToolResult,
+  maximum: number,
+  code: "TOOL_INPUT_INVALID" | "TOOL_OUTPUT_INVALID",
+): void {
+  const bytes = jsonBytes(value);
+  if (bytes > maximum) {
+    throw new ToolExecutionError(code, `Agent Tool JSON 超过 ${maximum} 字节`);
+  }
+}
+
+function validationMessage(validate: ValidateFunction<unknown>): string {
+  const detail = validate.errors
+    ?.map(({ instancePath, message }) => `${instancePath || "/"} ${message}`)
+    .join("；");
+  return `Agent Tool JSON 不符合 Schema${detail ? `：${detail}` : ""}`;
+}
+
+function toolEvent(
+  context: RequestGuardContext,
+  tool: RegisteredTool,
+  input: ModuleToolInput,
+  result: ModuleToolResult,
+): AuditEvent {
+  return {
+    id: crypto.randomUUID(),
+    action: tool.auditAction,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: { type: "agent-tool", id: tool.key, label: tool.label },
+    module: tool.module,
+    requestId: context.requestId,
+    metadata: {
+      inputBytes: jsonBytes(input),
+      outputBytes: jsonBytes(result),
+    },
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+function required<T>(value: T | undefined, message: string): T {
+  if (value === undefined) throw new Error(message);
+  return value;
+}
+
+function jsonBytes(value: ModuleToolInput | ModuleToolResult): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}

package/template/apps/server/src/http-app.test.ts

@@ -4,6 +4,92 @@ import { createPlatformObservability } from "./observability/bootstrap.js";
 import { createServerRuntime } from "./runtime.js";
 
 describe("platform HTTP app observability", () => {
+  test("未匹配路由不会因缺少请求观测而崩溃", async () => {
+    const records: Record<string, unknown>[] = [];
+    const runtime = createServerRuntime({ NODE_ENV: "test" });
+    const observability = createPlatformObservability({
+      databaseRequired: false,
+      auditStatus: () => runtime.auditSink.status(),
+      logger: {
+        info(fields) {
+          records.push(fields);
+        },
+      },
+    });
+    const app = createPlatformHttpApp(runtime, observability).get(
+      "/probe",
+      () => ({ ok: true }),
+    );
+
+    const outsidePrefix = await app.handle(
+      new Request("http://localhost/health/live"),
+    );
+    const insidePrefix = await app.handle(
+      new Request("http://localhost/api/missing"),
+    );
+    const subsequent = await app.handle(
+      new Request("http://localhost/api/probe"),
+    );
+    await Bun.sleep(0);
+
+    expect(outsidePrefix.status).toBe(404);
+    expect(insidePrefix.status).toBe(404);
+    expect(subsequent.status).toBe(200);
+    expect(outsidePrefix.headers.get("x-request-id")).toMatch(
+      /^[A-Za-z0-9._-]{1,128}$/,
+    );
+    expect(
+      records.filter(({ event }) => event === "http.request.completed"),
+    ).toHaveLength(3);
+    expect(observability.metrics.render()).toContain(
+      'windy_http_requests_total{method="GET",status_class="4xx"} 2',
+    );
+    expect(observability.metrics.render()).toContain(
+      'windy_http_requests_total{method="GET",status_class="2xx"} 1',
+    );
+    expect(observability.metrics.render()).toContain(
+      "windy_http_requests_active 0",
+    );
+  });
+
+  test("handler 异常只完成一次请求观测", async () => {
+    const records: Record<string, unknown>[] = [];
+    const runtime = createServerRuntime({ NODE_ENV: "test" });
+    const observability = createPlatformObservability({
+      databaseRequired: false,
+      auditStatus: () => runtime.auditSink.status(),
+      logger: {
+        info(fields) {
+          records.push(fields);
+        },
+      },
+    });
+    const app = createPlatformHttpApp(runtime, observability)
+      .onError(({ set }) => {
+        set.status = 500;
+        return { error: "INTERNAL_ERROR" };
+      })
+      .get("/failure", () => {
+        throw new Error("failure");
+      });
+
+    const response = await app.handle(
+      new Request("http://localhost/api/failure"),
+    );
+    await Bun.sleep(0);
+
+    expect(response.status).toBe(500);
+    expect(
+      records.filter(({ event }) => event === "http.request.completed"),
+    ).toHaveLength(1);
+    expect(observability.metrics.render()).toContain(
+      'windy_http_requests_total{method="GET",status_class="5xx"} 1',
+    );
+    expect(observability.metrics.render()).toContain(
+      "windy_http_requests_active 0",
+    );
+  });
+
   test("校验并回传 request id，日志与指标不包含 URL 和查询值", async () => {
     const records: Record<string, unknown>[] = [];
     const runtime = createServerRuntime({ NODE_ENV: "test" });
@@ -25,6 +111,7 @@ describe("platform HTTP app observability", () => {
         headers: { "x-request-id": "invalid request id" },
       }),
     );
+    await Bun.sleep(0);
 
     expect(response.status).toBe(200);
     expect(response.headers.get("x-request-id")).toMatch(

package/template/apps/server/src/http-app.ts

@@ -1,6 +1,8 @@
 import { swagger } from "@elysiajs/swagger";
 import { Elysia } from "elysia";
+import type { RequestGuardContext } from "./guards.js";
 import type { createPlatformObservability } from "./observability/bootstrap.js";
+import type { RequestObservation } from "./observability/metrics.js";
 // @windy-module system.license begin
 import { restrictedRequestResponse } from "./request-restriction.js";
 // @windy-module system.license end
@@ -8,38 +10,18 @@ import type { createServerRuntime } from "./runtime.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 type PlatformObservability = ReturnType<typeof createPlatformObservability>;
+interface HttpRequestState {
+  guardContext: RequestGuardContext;
+  requestObservation: RequestObservation;
+}
 
 export function createPlatformHttpApp(
   runtime: ServerRuntime,
   observability: PlatformObservability,
 ) {
+  const requestStates = new WeakMap<Request, HttpRequestState>();
   return (
     new Elysia({ prefix: "/api" })
-      .derive(async ({ request, server }) => ({
-        guardContext: await runtime.createGuardContext(request, {
-          clientIp: server?.requestIP(request)?.address,
-        }),
-        requestObservation: observability.http.begin(request.method),
-      }))
-      // @windy-module system.license begin
-      .onBeforeHandle(({ request, guardContext }) =>
-        restrictedRequestResponse(runtime, guardContext, request),
-      )
-      // @windy-module system.license end
-      .onAfterHandle(({ guardContext, set }) => {
-        set.headers["x-request-id"] = guardContext.requestId;
-      })
-      .onAfterResponse(
-        ({ request, guardContext, requestObservation, responseValue, set }) => {
-          observability.http.complete({
-            request,
-            guardContext,
-            observation: requestObservation,
-            responseValue,
-            status: set.status,
-          });
-        },
-      )
       .use(
         swagger({
           documentation: {
@@ -47,5 +29,41 @@ export function createPlatformHttpApp(
           },
         }),
       )
+      .onRequest(async ({ request, server, set }) => {
+        if (requestStates.has(request)) return;
+        const guardContext = await runtime.createGuardContext(request, {
+          clientIp: server?.requestIP(request)?.address,
+        });
+        requestStates.set(request, {
+          guardContext,
+          requestObservation: observability.http.begin(request.method),
+        });
+        set.headers["x-request-id"] = guardContext.requestId;
+      })
+      .derive(({ request }) => {
+        const state = requestStates.get(request);
+        if (!state) throw new Error("HTTP_REQUEST_STATE_UNAVAILABLE");
+        return {
+          guardContext: state.guardContext,
+          requestObservation: state.requestObservation,
+        };
+      })
+      // @windy-module system.license begin
+      .onBeforeHandle(({ request, guardContext }) =>
+        restrictedRequestResponse(runtime, guardContext, request),
+      )
+      // @windy-module system.license end
+      .onAfterResponse(({ request, responseValue, set }) => {
+        const state = requestStates.get(request);
+        if (!state) return;
+        requestStates.delete(request);
+        observability.http.complete({
+          request,
+          guardContext: state.guardContext,
+          observation: state.requestObservation,
+          responseValue,
+          status: set.status,
+        });
+      })
   );
 }

package/template/apps/server/src/index.ts

@@ -22,6 +22,9 @@ import {
   registerAgentRoutes,
 } from "./agent/routes.js";
 import { registerAgentPlatformRuntime } from "./agent/runtime-bootstrap.js";
+import { GovernedToolRegistry } from "./agent/tool-registry.js";
+import { PlatformMcpAdapter } from "./mcp/adapter.js";
+import { registerMcpRoutes } from "./mcp/routes.js";
 // @windy-module system.agent end
 import { registerAuthRoutes, registerAuthSessionRoute } from "./auth/routes.js";
 import { createAuthRuntime } from "./auth/runtime.js";
@@ -292,14 +295,23 @@ const toolHandlers = new Map([
   ...createSystemToolHandlers(systemRepositories, runtime),
   ...createModuleToolHandlerMap(moduleHosts),
 ]);
-registerAgentRoutes(app, foundationModules, toolHandlers, runtime);
+const toolRegistry = new GovernedToolRegistry(
+  foundationModules,
+  toolHandlers,
+  runtime,
+);
+registerAgentRoutes(app, toolRegistry);
+registerMcpRoutes(
+  app,
+  new PlatformMcpAdapter(toolRegistry, runtime, foundationSnapshot.features),
+);
 registerAgentPlatformRuntime({
   app,
   platformConfig,
   modules: foundationModules,
   hosts: moduleHosts,
   runtime,
-  toolHandlers,
+  toolRegistry,
 });
 // @windy-module system.agent end
 // @windy-module system.scheduler begin

package/template/apps/server/src/license/runtime-service.test.ts

@@ -16,6 +16,7 @@ import {
   createSystemToolHandlers,
   registerAgentRoutes,
 } from "../agent/routes.js";
+import { GovernedToolRegistry } from "../agent/tool-registry.js";
 import { runGuardedBackgroundTask } from "../background/task-guard.js";
 import {
   createFoundationSnapshot,
@@ -264,9 +265,11 @@ function createFixture(
   registerSystemRoutes(app, repositories, runtime, snapshot.features);
   registerAgentRoutes(
     app,
-    loadFoundationModules(),
-    createSystemToolHandlers(repositories, runtime),
-    runtime,
+    new GovernedToolRegistry(
+      loadFoundationModules(),
+      createSystemToolHandlers(repositories, runtime),
+      runtime,
+    ),
   );
   return { app, runtime, licenseRuntime };
 }