create-windy 0.2.20 → 0.2.21

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

@@ -0,0 +1,222 @@
+import { timingSafeEqual } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import type { AgentRunFacade } from "./run-facade.js";
+import { AgentRunFacadeError } from "./run-facade.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import {
+  AgentToolHostError,
+  attachExecutionGrant,
+  type RestrictedAgentToolHost,
+} from "./tool-host.js";
+
+interface RouteContext {
+  body?: unknown;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  request: Request;
+  guardContext: RequestGuardContext;
+}
+
+export function registerAgentRunRoutes(
+  app: RouteApp,
+  facade: AgentRunFacade,
+  remote: AgentRuntimePort,
+  toolHost: RestrictedAgentToolHost,
+  internalToken: string,
+) {
+  app.post("/agent/runs", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const request = parseStartRequest(context.body);
+      const idempotencyKey = context.request.headers.get("idempotency-key");
+      if (!idempotencyKey?.trim()) {
+        return errorResponse("INVALID_INPUT", "幂等键不能为空", 400);
+      }
+      return await facade.start(
+        request.operationKey,
+        request.input,
+        idempotencyKey,
+        context.guardContext,
+      );
+    } catch (error) {
+      return facadeError(error);
+    }
+  });
+
+  app.get("/agent/runs/:runId/events", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      const cursor = parseCursor(
+        context.query.after,
+        context.request.headers.get("last-event-id"),
+      );
+      return await remote.events(runId, cursor, context.request.signal);
+    } catch (error) {
+      return facadeError(error);
+    }
+  });
+
+  app.get("/agent/runs/:runId/result", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      return await remote.result(runId, context.request.signal);
+    } catch (error) {
+      return facadeError(error);
+    }
+  });
+
+  app.post("/agent/runs/:runId/cancel", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      const reason =
+        isRecord(context.body) && typeof context.body.reason === "string"
+          ? context.body.reason.slice(0, 200)
+          : undefined;
+      return await remote.cancel(runId, reason, context.request.signal);
+    } catch (error) {
+      return facadeError(error);
+    }
+  });
+
+  app.post("/internal/agent/tools/execute", async (raw) => {
+    const context = raw as RouteContext;
+    if (!validInternalToken(context.request, internalToken)) {
+      return errorResponse("FORBIDDEN", "内部调用认证失败", 403);
+    }
+    try {
+      const parsed = parseToolRequest(context.body);
+      return await toolHost.execute(
+        attachExecutionGrant(parsed.invocation, parsed.executionGrant),
+      );
+    } catch (error) {
+      if (error instanceof AgentToolHostError) {
+        return errorResponse(error.code, error.message, 403);
+      }
+      return errorResponse("TOOL_DENIED", "Agent Tool 执行失败", 403);
+    }
+  });
+
+  return app;
+}
+
+function parseStartRequest(body: unknown): {
+  operationKey: string;
+  input: ModuleAiJsonValue;
+} {
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some((key) => !["operationKey", "input"].includes(key))
+  ) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "请求格式无效", 400);
+  }
+  if (typeof body.operationKey !== "string" || !body.operationKey.trim()) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "Operation Key 无效", 400);
+  }
+  assertJson(body.input);
+  return { operationKey: body.operationKey, input: body.input };
+}
+
+function parseToolRequest(body: unknown) {
+  const allowed = [
+    "executionGrant",
+    "runId",
+    "toolCallId",
+    "toolKey",
+    "arguments",
+  ];
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some((key) => !allowed.includes(key))
+  ) {
+    throw new Error("Tool 请求格式无效");
+  }
+  if (
+    typeof body.executionGrant !== "string" ||
+    typeof body.runId !== "string" ||
+    typeof body.toolCallId !== "string" ||
+    typeof body.toolKey !== "string" ||
+    !isRecord(body.arguments)
+  ) {
+    throw new Error("Tool 请求字段无效");
+  }
+  assertJson(body.arguments);
+  return {
+    executionGrant: body.executionGrant,
+    invocation: {
+      runId: body.runId,
+      toolCallId: body.toolCallId,
+      toolKey: body.toolKey,
+      arguments: body.arguments,
+    },
+  };
+}
+
+function parseCursor(after: string | undefined, header: string | null): number {
+  const values = [after, header].filter(
+    (value): value is string => value !== undefined && value !== null,
+  );
+  if (values.some((value) => !/^\d+$/.test(value))) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "事件游标无效", 400);
+  }
+  return Math.max(0, ...values.map(Number));
+}
+
+function validInternalToken(request: Request, expected: string): boolean {
+  const provided = request.headers
+    .get("authorization")
+    ?.replace(/^Bearer /, "");
+  if (!provided || !expected) return false;
+  const left = Buffer.from(provided);
+  const right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function facadeError(error: unknown): Response {
+  if (error instanceof AgentRunFacadeError) {
+    return errorResponse(error.code, error.message, error.status);
+  }
+  return errorResponse(
+    "RUNTIME_UNAVAILABLE",
+    "Agent Runtime 暂不可用",
+    503,
+    true,
+  );
+}
+
+function errorResponse(
+  code: string,
+  message: string,
+  status: number,
+  retryable = false,
+): Response {
+  return Response.json(
+    { code, message, requestId: crypto.randomUUID(), retryable },
+    { status },
+  );
+}
+
+function required(value: string | undefined): string {
+  if (!value)
+    throw new AgentRunFacadeError("INVALID_INPUT", "Run ID 无效", 400);
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function assertJson(value: unknown): asserts value is ModuleAiJsonValue {
+  try {
+    if (JSON.stringify(value) === undefined) throw new Error();
+  } catch {
+    throw new AgentRunFacadeError("INVALID_INPUT", "请求必须是 JSON", 400);
+  }
+}

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

@@ -0,0 +1,53 @@
+import type { PlatformConfig } from "@southwind-ai/config";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InitializedModuleHosts } from "../module-host.js";
+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 { AgentRunFacade } from "./run-facade.js";
+import { registerAgentRunRoutes } from "./run-routes.js";
+import { RestrictedAgentToolHost } from "./tool-host.js";
+
+export function registerAgentPlatformRuntime(input: {
+  app: RouteApp;
+  platformConfig: PlatformConfig;
+  modules: readonly ModuleManifest[];
+  hosts: InitializedModuleHosts;
+  runtime: ReturnType<typeof createServerRuntime>;
+  toolHandlers: ModuleToolHandlers;
+}): void {
+  if (!input.platformConfig.enableAI) return;
+  const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
+  const remote = new RemoteAgentRuntime({
+    baseUrl: process.env.AGENT_SERVER_URL || "http://agent-server:8080",
+    internalToken,
+    toolHostUrl: process.env.AGENT_TOOL_HOST_URL || "http://server:9747",
+  });
+  const grants = new ExecutionGrantStore();
+  registerAgentRunRoutes(
+    input.app,
+    new AgentRunFacade(
+      input.modules,
+      input.hosts,
+      input.runtime,
+      remote,
+      grants,
+    ),
+    remote,
+    new RestrictedAgentToolHost(
+      input.modules,
+      input.toolHandlers,
+      input.runtime,
+      grants,
+    ),
+    internalToken,
+  );
+}
+
+function requiredEnvironment(key: string): string {
+  const value = process.env[key]?.trim();
+  if (!value) throw new Error(`启用 AI Runtime 时缺少 ${key}`);
+  return value;
+}

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

@@ -0,0 +1,242 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { ExecutionGrantStore } from "./execution-grants.js";
+import {
+  AgentToolHostError,
+  attachExecutionGrant,
+  RestrictedAgentToolHost,
+} from "./tool-host.js";
+
+const operation: ModuleAiOperationDefinition = {
+  key: "business.answer",
+  kind: "agent",
+  featureKey: "business.ai",
+  permissionKey: "business.ai.execute",
+  auditAction: "business.ai.execute",
+  inputSchemaKey: "business.input.v1",
+  outputSchemaKey: "business.output.v1",
+  requiredCapabilities: ["text-generation"],
+  allowedToolKeys: ["business.records.list"],
+  dataClassification: "internal",
+  execution: "streaming",
+  publicNetworkAccess: "forbidden",
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 4096,
+    maxOutputBytes: 4096,
+  },
+};
+
+describe("受限 Agent Tool Host", () => {
+  test("只接受 Grant 绑定 Operation 的 allowedToolKeys", async () => {
+    const fixture = createFixture();
+    const invocation = attachExecutionGrant(
+      {
+        runId: "run_1",
+        toolCallId: "call_1",
+        toolKey: "business.admin.delete",
+        arguments: {},
+      },
+      fixture.grant.token,
+    );
+
+    await expect(fixture.host.execute(invocation)).rejects.toMatchObject({
+      code: "TOOL_DENIED",
+      message: "Operation 未授权该 Tool",
+    });
+    expect(fixture.called).toEqual([]);
+  });
+
+  test("未知 Tool fail closed 且客户端不能提供权限事实", async () => {
+    const fixture = createFixture({
+      allowedToolKeys: ["business.unknown"],
+    });
+    const invocation = attachExecutionGrant(
+      {
+        runId: "run_1",
+        toolCallId: "call_1",
+        toolKey: "business.unknown",
+        arguments: {
+          permissionKeys: ["business.admin"],
+        },
+      },
+      fixture.grant.token,
+    );
+
+    await expect(fixture.host.execute(invocation)).rejects.toBeInstanceOf(
+      AgentToolHostError,
+    );
+    expect(fixture.called).toEqual([]);
+  });
+
+  test("使用宿主颁发 Actor 与 Scope 执行 Handler", async () => {
+    const fixture = createFixture();
+    const result = await fixture.host.execute(
+      attachExecutionGrant(
+        {
+          runId: "run_1",
+          toolCallId: "call_1",
+          toolKey: "business.records.list",
+          arguments: { page: 2 },
+        },
+        fixture.grant.token,
+      ),
+    );
+
+    expect(result.value).toEqual({
+      items: [{ id: "record-1" }],
+      total: 1,
+      page: 2,
+      pageSize: 10,
+    });
+    expect(fixture.called).toEqual([
+      {
+        query: { page: "2" },
+        actorId: "actor-1",
+        scopeKind: "self",
+      },
+    ]);
+  });
+});
+
+function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
+  const currentOperation = { ...operation, ...overrides };
+  const module = manifest(currentOperation);
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const context = createRequestGuardContext(
+    new Request("http://localhost/api/agent/runs"),
+    {
+      resolveActor: () => ({
+        id: "actor-1",
+        type: "user",
+        name: "测试用户",
+        roleCodes: ["user"],
+        permissionKeys: ["business.ai.execute", "business.records.read"],
+        scopeContext: buildScopeContext("actor-1", undefined, [
+          {
+            id: "role-user",
+            code: "user",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      }),
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+  const grants = new ExecutionGrantStore();
+  const grant = grants.issue(currentOperation, context);
+  grants.bindRun(grant.token, "run_1");
+  const called: unknown[] = [];
+  const handlers = new Map([
+    [
+      "business.records.list",
+      {
+        scopeMode: "request" as const,
+        execute: (
+          query: Record<string, string | undefined>,
+          handlerContext: typeof context,
+        ) => {
+          called.push({
+            query,
+            actorId: handlerContext.actor.id,
+            scopeKind: handlerContext.actor.scopeContext?.grants[0]?.scope,
+          });
+          return {
+            items: [{ id: "record-1" }],
+            total: 1,
+            page: Number(query.page),
+            pageSize: 10,
+          };
+        },
+      },
+    ],
+  ]);
+  return {
+    called,
+    grant,
+    grants,
+    host: new RestrictedAgentToolHost([module], handlers, runtime, grants),
+  };
+}
+
+function manifest(
+  currentOperation: ModuleAiOperationDefinition,
+): ModuleManifest {
+  return {
+    name: "business",
+    version: "0.1.0",
+    label: "业务",
+    description: "业务",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "business.ai.execute",
+        label: "AI",
+        module: "business",
+        moduleLabel: "业务",
+        resource: "ai",
+        resourceLabel: "AI",
+        action: "manage",
+      },
+      {
+        key: "business.records.read",
+        label: "记录",
+        module: "business",
+        moduleLabel: "业务",
+        resource: "records",
+        resourceLabel: "记录",
+        action: "read",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("business.ai"),
+        label: "AI",
+        module: "business",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+      {
+        key: featureKey("business.records"),
+        label: "记录",
+        module: "business",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [
+      {
+        key: "business.records.list",
+        label: "查询记录",
+        description: "查询当前范围记录。",
+        permissionKey: "business.records.read",
+        featureKey: "business.records",
+        auditAction: "business.records.read",
+      },
+    ],
+    aiOperations: [currentOperation],
+    providers: [],
+    auditActions: ["business.ai.execute", "business.records.read"],
+  };
+}

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

@@ -0,0 +1,153 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleAgentToolHostPort,
+  ModuleAgentToolInvocation,
+  ModuleAiJsonValue,
+} 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 type { ExecutionGrantStore } from "./execution-grants.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 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,
+        ),
+      ),
+    );
+  }
+
+  async execute(invocation: ModuleAgentToolInvocation) {
+    const grant = this.grants.require(
+      readGrantToken(invocation),
+      invocation.runId,
+    );
+    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,
+    );
+    const operationDecision = await evaluateAccessGuards(
+      this.runtime,
+      context,
+      {
+        permission: { permissionKey: grant.operation.permissionKey },
+        feature: findFeature(this.#features, grant.operation.featureKey),
+      },
+    );
+    if (!operationDecision.decision.allowed) {
+      throw new AgentToolHostError(
+        "TOOL_DENIED",
+        "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 数据范围无效");
+    }
+    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",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const grantTokens = new WeakMap<object, string>();
+
+export function attachExecutionGrant<T extends ModuleAgentToolInvocation>(
+  invocation: T,
+  token: string,
+): T {
+  grantTokens.set(invocation, token);
+  return invocation;
+}
+
+function readGrantToken(invocation: ModuleAgentToolInvocation): string {
+  const token = grantTokens.get(invocation);
+  if (!token) throw new AgentToolHostError("TOOL_DENIED", "缺少执行授权");
+  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;
+}