create-windy 0.2.23 → 0.2.25

package/template/apps/server/src/agent/routes.ts

@@ -1,51 +1,30 @@
-import { randomUUIDv7 } from "bun";
-import type { ModuleManifest, ModuleToolDefinition } from "@southwind-ai/modules";
-import type { AuditEvent, FeatureFlagDefinition } from "@southwind-ai/shared";
-import { evaluateAccessGuards } from "../access-guards.js";
-import { type RequestGuardContext } from "../guards.js";
-import { findFeature, systemFeatureKeyForPermission } from "../route-guards.js";
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
 import type { createServerRuntime } from "../runtime.js";
 import type { RouteApp } from "../system/routes.js";
 import type { SystemRepositories } from "../system/seed.js";
 import { DataScopedResourceService } from "../data-access/scoped-resource.js";
 import { departmentDescendantResolver } from "../data-access/department-tree.js";
-import { isServerScopeContext } from "../data-access/context.js";
 import { projectMaskedUser } from "../system/user-projection.js";
+import {
+  GovernedToolRegistry,
+  ToolExecutionError,
+  type ModuleToolHandlers,
+  type PlatformToolExecutionContext,
+} from "./tool-registry.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 interface RouteContext {
-  guardContext: RequestGuardContext;
+  guardContext: Parameters<GovernedToolRegistry["allowed"]>[1];
   params: Record<string, string | undefined>;
   query: Record<string, string | undefined>;
+  body?: unknown;
 }
 
-interface RegisteredTool extends ModuleToolDefinition {
-  module: string;
-  feature?: FeatureFlagDefinition;
-}
-
-export type ModuleToolResult = {
-  items: unknown[];
-  total: number;
-  page: number;
-  pageSize: number;
-};
-
-export type ModuleToolHandler = (
-  query: RouteContext["query"],
-  context: RequestGuardContext,
-) => Promise<ModuleToolResult> | ModuleToolResult;
-
-export interface ModuleToolHandlerRegistration {
-  readonly scopeMode: "platform" | "request";
-  readonly execute: ModuleToolHandler;
-}
-
-export type ModuleToolHandlers = ReadonlyMap<
-  string,
-  ModuleToolHandlerRegistration
->;
+export type { ModuleToolHandlers } from "./tool-registry.js";
 
 export function createSystemToolHandlers(
   repositories: SystemRepositories,
@@ -55,44 +34,49 @@ export function createSystemToolHandlers(
     repositories.users,
     departmentDescendantResolver(repositories.departments),
   );
-  return new Map<string, ModuleToolHandlerRegistration>([
+  return new Map([
     [
       "system.users.list",
       {
-        scopeMode: "request",
-        execute: async (query, context) => {
-          const { page, pageSize } = paging(query);
+        scopeMode: "request" as const,
+        execute: async (
+          input: ModuleToolInput,
+          { guardContext }: PlatformToolExecutionContext,
+        ) => {
+          const { page, pageSize } = paging(input);
           const result = await userAccess.list(
             { page, pageSize },
             ["username", "displayName"],
-            context.actor,
+            guardContext.actor,
           );
-          return {
+          return jsonResult({
             ...result,
             items: result.items.map((user) => projectMaskedUser(user)),
-          };
+          });
         },
       },
     ],
     [
       "system.features.list",
       {
-        scopeMode: "platform",
-        execute: async (query) => {
-          const { page, pageSize } = paging(query);
-          return repositories.features.list({ page, pageSize }, [
-            "key",
-            "label",
-            "module",
-          ]);
+        scopeMode: "platform" as const,
+        execute: async (input: ModuleToolInput) => {
+          const { page, pageSize } = paging(input);
+          return jsonResult(
+            await repositories.features.list({ page, pageSize }, [
+              "key",
+              "label",
+              "module",
+            ]),
+          );
         },
       },
     ],
     [
       "system.audit.list",
       {
-        scopeMode: "platform",
-        execute: (query) => pagedAuditResult(query, runtime),
+        scopeMode: "platform" as const,
+        execute: (input: ModuleToolInput) => pagedAuditResult(input, runtime),
       },
     ],
   ]);
@@ -100,158 +84,108 @@ export function createSystemToolHandlers(
 
 export function registerAgentRoutes(
   app: RouteApp,
-  modules: ModuleManifest[],
-  handlers: ModuleToolHandlers,
-  runtime: ServerRuntime,
+  registry: GovernedToolRegistry,
 ) {
-  const tools = collectTools(modules);
-  validateToolHandlerContract(tools, handlers);
-
   app.get("/agent/tools", async (rawContext) => {
     const { guardContext } = rawContext as RouteContext;
     return Promise.all(
-      tools.map(async (tool) => ({
-        ...tool,
-        allowed: (
-          await evaluateToolGuards(runtime, guardContext, tool, {
-            record: false,
-          })
-        ).allowed,
+      registry.definitions().map(async (tool) => ({
+        key: tool.key,
+        label: tool.label,
+        description: tool.description,
+        operation: tool.operation,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        allowed: await registry.allowed(tool.key, guardContext),
       })),
     );
   });
 
   app.post("/agent/tools/:key/execute", async (rawContext) => {
-    const { guardContext, params, query } = rawContext as RouteContext;
-    const tool = tools.find((item) => item.key === params.key);
-    if (!tool) {
-      return Response.json(
-        { error: "TOOL_NOT_FOUND", key: params.key },
-        { status: 404 },
-      );
-    }
-
-    const decision = await evaluateToolGuards(runtime, guardContext, tool);
-    if (!decision.allowed) {
-      return Response.json(
-        { error: "FORBIDDEN", reason: decision.reason },
-        { status: 403 },
+    const context = rawContext as RouteContext;
+    try {
+      return await registry.execute(
+        context.params.key ?? "",
+        readInput(context),
+        context.guardContext,
       );
-    }
-
-    const handler = handlers.get(tool.key)!;
-    if (
-      handler.scopeMode === "request" &&
-      !isServerScopeContext(guardContext.actor.scopeContext)
-    ) {
+    } catch (error) {
+      if (!(error instanceof ToolExecutionError)) throw error;
       return Response.json(
-        { error: "FORBIDDEN", reason: "data-scope-denied" },
-        { status: 403 },
+        {
+          error: error.code === "TOOL_FORBIDDEN" ? "FORBIDDEN" : error.code,
+          reason: error.reason,
+          message: error.message,
+        },
+        { status: errorStatus(error) },
       );
     }
-    const result = await handler.execute(query, guardContext);
-    runtime.auditSink.recordEvent(toolEvent(guardContext, tool, result.total));
-    return result;
   });
 
   return app;
 }
 
-function validateToolHandlerContract(
-  tools: 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}`);
+function readInput(context: RouteContext): ModuleToolInput {
+  if (context.body !== undefined) {
+    if (
+      context.body === null ||
+      typeof context.body !== "object" ||
+      Array.isArray(context.body)
+    ) {
+      throw new ToolExecutionError(
+        "TOOL_INPUT_INVALID",
+        "Agent Tool 输入必须是 JSON object",
+      );
+    }
+    return jsonInput(context.body);
   }
+  return jsonInput(context.query);
 }
 
-function collectTools(modules: ModuleManifest[]): RegisteredTool[] {
-  const features = modules.flatMap((module) => module.features);
-  return modules.flatMap((module) =>
-    module.tools.map((tool) => ({
-      ...tool,
-      module: module.name,
-      feature: findFeature(
-        features,
-        tool.featureKey || systemFeatureKeyForPermission(tool.permissionKey),
-      ),
-    })),
-  );
-}
-
-function evaluateToolGuards(
-  runtime: ServerRuntime,
-  context: RequestGuardContext,
-  tool: RegisteredTool,
-  options: { record?: boolean } = {},
-) {
-  return evaluateAccessGuards(
-    runtime,
-    context,
-    {
-      permission: {
-        permissionKey: tool.permissionKey,
-      },
-      feature: tool.feature,
-    },
-    options,
-  ).then((result) => result.decision);
-}
-
-function paging(query: RouteContext["query"]) {
-  const page = toPositiveInt(query.page, 1);
-  const pageSize = Math.min(50, toPositiveInt(query.pageSize, 10));
-  return { page, pageSize };
+function paging(input: ModuleToolInput) {
+  return {
+    page: toPositiveInt(input.page, 1),
+    pageSize: Math.min(50, toPositiveInt(input.pageSize, 10)),
+  };
 }
 
 function pagedAuditResult(
-  query: RouteContext["query"],
+  input: ModuleToolInput,
   runtime: ServerRuntime,
 ): ModuleToolResult {
-  const { page, pageSize } = paging(query);
+  const { page, pageSize } = paging(input);
   const events = runtime.auditSink.list();
   const start = (page - 1) * pageSize;
-  return {
+  return jsonResult({
     items: events.slice(start, start + pageSize),
     total: events.length,
     page,
     pageSize,
-  };
+  });
 }
 
-function toolEvent(
-  context: RequestGuardContext,
-  tool: RegisteredTool,
-  total: number,
-): AuditEvent {
-  return {
-    id: randomUUIDv7(),
-    action: "agent.tool.execute",
-    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: { total },
-    occurredAt: new Date().toISOString(),
-  };
+function jsonInput(value: unknown): ModuleToolInput {
+  return JSON.parse(JSON.stringify(value)) as ModuleToolInput;
+}
+
+function jsonResult(value: unknown): ModuleToolResult {
+  return JSON.parse(JSON.stringify(value)) as ModuleToolResult;
+}
+
+function toPositiveInt(value: ModuleToolInput[string], fallback: number) {
+  const parsed =
+    typeof value === "number"
+      ? value
+      : typeof value === "string"
+        ? Number.parseInt(value, 10)
+        : fallback;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-function toPositiveInt(value: string | undefined, fallback: number): number {
-  const parsed = value ? Number.parseInt(value, 10) : fallback;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+function errorStatus(error: ToolExecutionError): number {
+  if (error.code === "TOOL_NOT_FOUND") return 404;
+  if (error.code === "TOOL_FORBIDDEN") return 403;
+  if (error.code === "TOOL_TIMEOUT") return 504;
+  if (error.code === "TOOL_INPUT_INVALID") return 400;
+  return 500;
 }

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

@@ -196,15 +196,45 @@ function manifest(): ModuleManifest {
     ],
     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: [

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

@@ -5,7 +5,7 @@ import type { createServerRuntime } from "../runtime.js";
 import type { RouteApp } from "../system/routes.js";
 import { ExecutionGrantStore } from "./execution-grants.js";
 import { RemoteAgentRuntime } from "./remote-runtime.js";
-import type { ModuleToolHandlers } from "./routes.js";
+import type { GovernedToolRegistry } from "./tool-registry.js";
 import { AgentRunFacade } from "./run-facade.js";
 import { registerAgentRunRoutes } from "./run-routes.js";
 import { RestrictedAgentToolHost } from "./tool-host.js";
@@ -16,7 +16,7 @@ export function registerAgentPlatformRuntime(input: {
   modules: readonly ModuleManifest[];
   hosts: InitializedModuleHosts;
   runtime: ReturnType<typeof createServerRuntime>;
-  toolHandlers: ModuleToolHandlers;
+  toolRegistry: GovernedToolRegistry;
 }): void {
   if (!input.platformConfig.enableAI) return;
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
@@ -38,7 +38,7 @@ export function registerAgentPlatformRuntime(input: {
     remote,
     new RestrictedAgentToolHost(
       input.modules,
-      input.toolHandlers,
+      input.toolRegistry,
       input.runtime,
       grants,
     ),

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

@@ -13,6 +13,7 @@ import {
   attachExecutionGrant,
   RestrictedAgentToolHost,
 } from "./tool-host.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
 
 const operation: ModuleAiOperationDefinition = {
   key: "business.answer",
@@ -98,7 +99,7 @@ describe("受限 Agent Tool Host", () => {
     });
     expect(fixture.called).toEqual([
       {
-        query: { page: "2" },
+        input: { page: 2 },
         actorId: "actor-1",
         scopeKind: "self",
       },
@@ -147,18 +148,21 @@ function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
       {
         scopeMode: "request" as const,
         execute: (
-          query: Record<string, string | undefined>,
-          handlerContext: typeof context,
+          input: { page?: number },
+          handlerContext: {
+            guardContext: typeof context;
+          },
         ) => {
           called.push({
-            query,
-            actorId: handlerContext.actor.id,
-            scopeKind: handlerContext.actor.scopeContext?.grants[0]?.scope,
+            input,
+            actorId: handlerContext.guardContext.actor.id,
+            scopeKind:
+              handlerContext.guardContext.actor.scopeContext?.grants[0]?.scope,
           });
           return {
             items: [{ id: "record-1" }],
             total: 1,
-            page: Number(query.page),
+            page: input.page ?? 1,
             pageSize: 10,
           };
         },
@@ -169,7 +173,12 @@ function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
     called,
     grant,
     grants,
-    host: new RestrictedAgentToolHost([module], handlers, runtime, grants),
+    host: new RestrictedAgentToolHost(
+      [module],
+      new GovernedToolRegistry([module], handlers, runtime),
+      runtime,
+      grants,
+    ),
   };
 }
 
@@ -224,15 +233,59 @@ function manifest(
     ],
     migrations: [],
     schemaExports: [],
+    jsonSchemas: [
+      {
+        key: "business.records.input.v1",
+        schema: {
+          type: "object",
+          properties: { page: { type: "integer", minimum: 1 } },
+          additionalProperties: false,
+        },
+      },
+      {
+        key: "business.records.output.v1",
+        schema: {
+          type: "object",
+          properties: {
+            items: { type: "array", items: { type: "object" } },
+            total: { type: "integer" },
+            page: { type: "integer" },
+            pageSize: { type: "integer" },
+          },
+          required: ["items", "total", "page", "pageSize"],
+          additionalProperties: false,
+        },
+      },
+      {
+        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: [currentOperation],

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

@@ -6,45 +6,23 @@ import type {
 } from "@southwind-ai/server-sdk";
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import { evaluateAccessGuards } from "../access-guards.js";
-import { isServerScopeContext } from "../data-access/context.js";
 import type { createServerRuntime } from "../runtime.js";
-import { findFeature, systemFeatureKeyForPermission } from "../route-guards.js";
-import type { ModuleToolHandlers } from "./routes.js";
+import { findFeature } from "../route-guards.js";
 import type { ExecutionGrantStore } from "./execution-grants.js";
+import { GovernedToolRegistry, ToolExecutionError } from "./tool-registry.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
-  readonly #tools: Map<string, ToolDefinition>;
   readonly #features: FeatureFlagDefinition[];
 
   constructor(
     modules: readonly ModuleManifest[],
-    private readonly handlers: ModuleToolHandlers,
+    private readonly tools: GovernedToolRegistry,
     private readonly runtime: ServerRuntime,
     private readonly grants: ExecutionGrantStore,
   ) {
-    const features = modules.flatMap(({ features }) => features);
-    this.#features = features;
-    this.#tools = new Map(
-      modules.flatMap((module) =>
-        module.tools.map(
-          (tool) =>
-            [
-              tool.key,
-              {
-                ...tool,
-                moduleName: module.name,
-                feature: findFeature(
-                  features,
-                  tool.featureKey ||
-                    systemFeatureKeyForPermission(tool.permissionKey),
-                ),
-              },
-            ] as const,
-        ),
-      ),
-    );
+    this.#features = modules.flatMap(({ features }) => features);
   }
 
   async execute(invocation: ModuleAgentToolInvocation) {
@@ -55,11 +33,6 @@ export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
     if (!grant.operation.allowedToolKeys.includes(invocation.toolKey)) {
       throw new AgentToolHostError("TOOL_DENIED", "Operation 未授权该 Tool");
     }
-    const tool = this.#tools.get(invocation.toolKey);
-    const handler = this.handlers.get(invocation.toolKey);
-    if (!tool || !handler) {
-      throw new AgentToolHostError("TOOL_DENIED", "Agent Tool 不存在");
-    }
     const context = await this.runtime.createGuardContextForActor(
       new Request("http://agent-tool.internal"),
       grant.context.actor,
@@ -78,34 +51,22 @@ export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
         "Agent Operation 当前无权继续执行",
       );
     }
-    const decision = await evaluateAccessGuards(this.runtime, context, {
-      permission: { permissionKey: tool.permissionKey },
-      feature: tool.feature,
-    });
-    if (!decision.decision.allowed) {
-      throw new AgentToolHostError("TOOL_DENIED", "Agent Tool 当前无权执行");
-    }
-    if (
-      handler.scopeMode === "request" &&
-      !isServerScopeContext(context.actor.scopeContext)
-    ) {
-      throw new AgentToolHostError("TOOL_DENIED", "Agent Tool 数据范围无效");
+    try {
+      const result = await this.tools.execute(
+        invocation.toolKey,
+        invocation.arguments,
+        context,
+      );
+      return { value: toJsonValue(result) };
+    } catch (error) {
+      if (error instanceof ToolExecutionError) {
+        throw new AgentToolHostError("TOOL_DENIED", error.message);
+      }
+      throw error;
     }
-    const result = await handler.execute(
-      toQuery(invocation.arguments),
-      context,
-    );
-    return { value: toJsonValue(result) };
   }
 }
 
-interface ToolDefinition {
-  key: string;
-  permissionKey: string;
-  feature?: ReturnType<typeof findFeature>;
-  moduleName: string;
-}
-
 export class AgentToolHostError extends Error {
   constructor(
     readonly code: "TOOL_DENIED",
@@ -131,23 +92,6 @@ function readGrantToken(invocation: ModuleAgentToolInvocation): string {
   return token;
 }
 
-function toQuery(
-  value: Readonly<Record<string, ModuleAiJsonValue>>,
-): Record<string, string | undefined> {
-  return Object.fromEntries(
-    Object.entries(value).map(([key, item]) => [
-      key,
-      item === null
-        ? undefined
-        : typeof item === "object"
-          ? JSON.stringify(item)
-          : String(item),
-    ]),
-  );
-}
-
 function toJsonValue(value: unknown): ModuleAiJsonValue {
-  const encoded = JSON.stringify(value);
-  if (encoded === undefined) throw new Error("Agent Tool 返回值不是 JSON");
-  return JSON.parse(encoded) as ModuleAiJsonValue;
+  return JSON.parse(JSON.stringify(value)) as ModuleAiJsonValue;
 }