create-windy 0.2.19 → 0.2.21

package/template/apps/server/src/agent/execution-grants.ts

@@ -0,0 +1,89 @@
+import { randomUUIDv7 } from "bun";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type { RequestGuardContext } from "../guards.js";
+
+export interface ExecutionGrant {
+  readonly token: string;
+  readonly operation: ModuleAiOperationDefinition;
+  readonly context: RequestGuardContext;
+  readonly expiresAt: number;
+  runId?: string;
+}
+
+export class ExecutionGrantStore {
+  readonly #grants = new Map<string, ExecutionGrant>();
+  readonly #runTokens = new Map<string, string>();
+
+  constructor(
+    private readonly maxActiveGrants = 1_000,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  issue(
+    operation: ModuleAiOperationDefinition,
+    context: RequestGuardContext,
+  ): ExecutionGrant {
+    this.prune();
+    if (this.#grants.size >= this.maxActiveGrants) {
+      throw new Error("Agent Execution Grant 容量已满");
+    }
+    const token = `grant_${randomUUIDv7().replaceAll("-", "")}`;
+    const expiresAt =
+      this.now() + Math.min(operation.limits.maxDurationSeconds, 300) * 1_000;
+    const grant = { token, operation, context, expiresAt };
+    this.#grants.set(token, grant);
+    return grant;
+  }
+
+  bindRun(token: string, runId: string): void {
+    const grant = this.require(token);
+    const existingToken = this.#runTokens.get(runId);
+    if (existingToken && existingToken !== token) {
+      throw new Error("Agent Run 已绑定其他 Execution Grant");
+    }
+    grant.runId = runId;
+    this.#runTokens.set(runId, token);
+  }
+
+  require(token: string, runId?: string): ExecutionGrant {
+    const grant = this.#grants.get(token);
+    if (!grant || grant.expiresAt <= this.now()) {
+      if (grant?.runId) this.#runTokens.delete(grant.runId);
+      this.#grants.delete(token);
+      throw new Error("Agent Execution Grant 无效或已过期");
+    }
+    if (runId && grant.runId !== runId) {
+      throw new Error("Agent Execution Grant 与 Run 不匹配");
+    }
+    return grant;
+  }
+
+  requireRun(runId: string, actorId: string): ExecutionGrant {
+    const token = this.#runTokens.get(runId);
+    const grant = token ? this.require(token, runId) : undefined;
+    if (!grant || grant.context.actor.id !== actorId) {
+      throw new Error("Agent Run 不属于当前 Actor");
+    }
+    return grant;
+  }
+
+  revokeRun(runId: string): void {
+    const token = this.#runTokens.get(runId);
+    if (token) this.#grants.delete(token);
+    this.#runTokens.delete(runId);
+  }
+
+  discard(token: string): void {
+    const grant = this.#grants.get(token);
+    if (grant?.runId) this.#runTokens.delete(grant.runId);
+    this.#grants.delete(token);
+  }
+
+  private prune(): void {
+    for (const [token, grant] of this.#grants) {
+      if (grant.expiresAt > this.now()) continue;
+      if (grant.runId) this.#runTokens.delete(grant.runId);
+      this.#grants.delete(token);
+    }
+  }
+}

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

@@ -0,0 +1,128 @@
+import type {
+  AgentRuntimeOperation,
+  AgentRuntimePort,
+  AgentRuntimeStartResponse,
+} from "./run-contracts.js";
+
+export interface RemoteAgentRuntimeOptions {
+  baseUrl: string;
+  internalToken: string;
+  toolHostUrl: string;
+  timeoutMs?: number;
+}
+
+export class RemoteAgentRuntime implements AgentRuntimePort {
+  readonly #baseUrl: string;
+  readonly #timeoutMs: number;
+
+  constructor(private readonly options: RemoteAgentRuntimeOptions) {
+    this.#baseUrl = normalizeInternalUrl(options.baseUrl);
+    this.#timeoutMs = options.timeoutMs ?? 10_000;
+    if (!options.internalToken.trim()) {
+      throw new Error("Agent Server 内部 Token 不能为空");
+    }
+  }
+
+  async start(
+    request: AgentRuntimeOperation,
+    idempotencyKey: string,
+  ): Promise<AgentRuntimeStartResponse> {
+    const response = await this.request("/api/agent/runs", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+      },
+      body: JSON.stringify({
+        ...request,
+        toolHostUrl: this.options.toolHostUrl,
+      }),
+    });
+    if (!response.ok) throw await remoteError(response);
+    return (await response.json()) as AgentRuntimeStartResponse;
+  }
+
+  events(runId: string, cursor: number, signal?: AbortSignal) {
+    return this.request(
+      `/api/agent/runs/${encodeURIComponent(runId)}/events?after=${cursor}`,
+      { signal },
+      false,
+    );
+  }
+
+  result(runId: string, signal?: AbortSignal) {
+    return this.request(`/api/agent/runs/${encodeURIComponent(runId)}/result`, {
+      signal,
+    });
+  }
+
+  cancel(runId: string, reason?: string, signal?: AbortSignal) {
+    return this.request(`/api/agent/runs/${encodeURIComponent(runId)}/cancel`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ reason }),
+      signal,
+    });
+  }
+
+  health(signal?: AbortSignal) {
+    return this.request("/health/ready", { signal });
+  }
+
+  private async request(
+    path: string,
+    init: RequestInit = {},
+    bounded = true,
+  ): Promise<Response> {
+    const timeout = AbortSignal.timeout(this.#timeoutMs);
+    const signal = init.signal
+      ? AbortSignal.any([init.signal, timeout])
+      : timeout;
+    const response = await fetch(`${this.#baseUrl}${path}`, {
+      ...init,
+      signal,
+      headers: {
+        authorization: `Bearer ${this.options.internalToken}`,
+        ...init.headers,
+      },
+    });
+    if (bounded) {
+      const length = Number(response.headers.get("content-length") || "0");
+      if (length > 2 * 1_024 * 1_024) {
+        throw new Error("Agent Server 响应超过上限");
+      }
+    }
+    return response;
+  }
+}
+
+function normalizeInternalUrl(raw: string): string {
+  const url = new URL(raw);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("Agent Server URL 只允许 HTTP 或 HTTPS");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent Server URL 不允许凭据、查询串或片段");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+async function remoteError(response: Response): Promise<Error> {
+  const safe = `Agent Runtime 请求失败（HTTP ${response.status}）`;
+  try {
+    const value = (await response.json()) as {
+      code?: unknown;
+      message?: unknown;
+    };
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      value.message.length <= 200
+    ) {
+      return new Error(`${value.code}: ${value.message}`);
+    }
+  } catch {
+    // Provider 或代理正文不可透传。
+  }
+  return new Error(safe);
+}

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

@@ -0,0 +1,43 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export interface AgentRuntimeOperation {
+  operationKey: string;
+  input: ModuleAiJsonValue;
+  instructions: string;
+  userPrompt: string;
+  allowedTools: Array<{
+    key: string;
+    label: string;
+    description: string;
+  }>;
+  limits: {
+    maxDurationSeconds: number;
+    maxOutputBytes: number;
+  };
+  executionGrant: string;
+}
+
+export interface AgentRuntimeStartResponse {
+  runId: string;
+  status: string;
+  eventsUrl: string;
+}
+
+export interface AgentRuntimePort {
+  start(
+    request: AgentRuntimeOperation,
+    idempotencyKey: string,
+  ): Promise<AgentRuntimeStartResponse>;
+  events(
+    runId: string,
+    cursor: number,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  result(runId: string, signal?: AbortSignal): Promise<Response>;
+  cancel(
+    runId: string,
+    reason?: string,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  health(signal?: AbortSignal): Promise<Response>;
+}

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

@@ -0,0 +1,257 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import type {
+  AgentRuntimeOperation,
+  AgentRuntimePort,
+} from "./run-contracts.js";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import { ExecutionGrantStore } from "./execution-grants.js";
+import { AgentRunFacade } from "./run-facade.js";
+
+describe("Guarded Agent Run facade", () => {
+  test("Guard 后由宿主 Handler 生成计划并签发短时 Grant", async () => {
+    const fixture = await createFixture();
+    const created = await fixture.facade.start(
+      "business.answer",
+      { question: "你好" },
+      "request-1",
+      fixture.context,
+    );
+
+    expect(created).toEqual({
+      runId: "run_1",
+      status: "accepted",
+      eventsUrl: "/api/agent/runs/run_1/events",
+    });
+    expect(fixture.remote.started).toHaveLength(1);
+    expect(fixture.remote.started[0]).toMatchObject({
+      operationKey: "business.answer",
+      instructions: "只回答当前业务问题。",
+      userPrompt: "你好",
+      allowedTools: [{ key: "business.records.list" }],
+    });
+    expect(fixture.remote.started[0]?.executionGrant).toMatch(/^grant_/);
+    expect(() =>
+      fixture.facade.authorizeRun("run_1", fixture.context),
+    ).not.toThrow();
+  });
+
+  test("客户端输入不能覆盖 Operation、Tool 或授权", async () => {
+    const fixture = await createFixture();
+    await fixture.facade.start(
+      "business.answer",
+      {
+        question: "正常问题",
+        allowedToolKeys: ["business.admin.delete"],
+        permissionKeys: ["business.admin"],
+        executionGrant: "forged",
+      },
+      "request-2",
+      fixture.context,
+    );
+
+    expect(
+      fixture.remote.started[0]?.allowedTools.map(({ key }) => key),
+    ).toEqual(["business.records.list"]);
+    expect(fixture.remote.started[0]?.executionGrant).not.toBe("forged");
+  });
+
+  test("缺少 Operation 权限时不调用 Handler 或 Runtime", async () => {
+    const fixture = await createFixture([]);
+    await expect(
+      fixture.facade.start(
+        "business.answer",
+        { question: "越权" },
+        "request-3",
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "FORBIDDEN", status: 403 });
+    expect(fixture.remote.started).toEqual([]);
+    expect(fixture.prepared).toEqual([]);
+  });
+});
+
+class FakeRuntime implements AgentRuntimePort {
+  readonly started: AgentRuntimeOperation[] = [];
+
+  start(request: AgentRuntimeOperation) {
+    this.started.push(request);
+    return Promise.resolve({
+      runId: "run_1",
+      status: "accepted",
+      eventsUrl: "/internal/events",
+    });
+  }
+
+  events() {
+    return Promise.resolve(new Response());
+  }
+
+  result() {
+    return Promise.resolve(new Response());
+  }
+
+  cancel() {
+    return Promise.resolve(new Response());
+  }
+
+  health() {
+    return Promise.resolve(new Response());
+  }
+}
+
+async function createFixture(
+  permissionKeys: string[] = ["business.ai.execute", "business.records.read"],
+) {
+  const module = manifest();
+  const prepared: unknown[] = [];
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            {
+              operationKey: "business.answer",
+              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 = 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" }),
+    },
+  );
+  const remote = new FakeRuntime();
+  const facade = new AgentRunFacade(
+    [module],
+    hosts,
+    runtime,
+    remote,
+    new ExecutionGrantStore(),
+  );
+  return { context, facade, prepared, remote };
+}
+
+function manifest(): 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: [],
+    tasks: [],
+    tools: [
+      {
+        key: "business.records.list",
+        label: "查询记录",
+        description: "查询当前范围记录。",
+        permissionKey: "business.records.read",
+        featureKey: "business.records",
+        auditAction: "business.records.read",
+      },
+    ],
+    aiOperations: [
+      {
+        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,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["business.ai.execute", "business.records.read"],
+  };
+}
+
+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,
+  };
+}

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

@@ -0,0 +1,190 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type {
+  ModuleAiJsonValue,
+  ModuleAiOperationHandlerRegistration,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { toModuleActor } from "../module-host.js";
+import type { createServerRuntime } from "../runtime.js";
+import { findFeature } from "../route-guards.js";
+import { ExecutionGrantStore } from "./execution-grants.js";
+import type {
+  AgentRuntimePort,
+  AgentRuntimeStartResponse,
+} from "./run-contracts.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class AgentRunFacade {
+  readonly #operations: Map<string, RegisteredOperation>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ServerRuntime,
+    private readonly remote: AgentRuntimePort,
+    private readonly grants: ExecutionGrantStore,
+  ) {
+    const handlers = new Map(
+      hosts.aiOperationHandlers.map(({ registration }) => [
+        registration.operationKey,
+        registration,
+      ]),
+    );
+    const features = modules.flatMap(({ features }) => features);
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? []).map(
+          (definition) =>
+            [
+              definition.key,
+              {
+                definition,
+                handler: handlers.get(definition.key),
+                feature: findFeature(features, definition.featureKey),
+                tools: toolDefinitions(modules, definition.allowedToolKeys),
+              },
+            ] as const,
+        ),
+      ),
+    );
+  }
+
+  async start(
+    operationKey: string,
+    input: ModuleAiJsonValue,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+  ): Promise<AgentRuntimeStartResponse> {
+    const operation = this.#operations.get(operationKey);
+    if (!operation?.handler) {
+      throw new AgentRunFacadeError(
+        "OPERATION_NOT_FOUND",
+        "Agent Operation 不存在",
+        404,
+      );
+    }
+    const decision = await evaluateAccessGuards(this.runtime, context, {
+      permission: {
+        permissionKey: operation.definition.permissionKey,
+      },
+      feature: operation.feature,
+    });
+    if (!decision.decision.allowed) {
+      throw new AgentRunFacadeError(
+        "FORBIDDEN",
+        "无权执行 Agent Operation",
+        403,
+      );
+    }
+    assertInputSize(input, operation.definition.limits.maxInputBytes);
+    const plan = await operation.handler.prepare(input, {
+      actor: toModuleActor(context.actor),
+      requestId: context.requestId,
+    });
+    if (!plan.instructions.trim() || !plan.userPrompt.trim()) {
+      throw new AgentRunFacadeError(
+        "INVALID_INPUT",
+        "Agent Operation 执行计划无效",
+        400,
+      );
+    }
+    const grant = this.grants.issue(operation.definition, context);
+    try {
+      const created = await this.remote.start(
+        {
+          operationKey,
+          input,
+          instructions: plan.instructions,
+          userPrompt: plan.userPrompt,
+          allowedTools: operation.tools,
+          limits: operation.definition.limits,
+          executionGrant: grant.token,
+        },
+        idempotencyKey,
+      );
+      this.grants.bindRun(grant.token, created.runId);
+      this.runtime.auditSink.recordEvent({
+        id: randomUUIDv7(),
+        action: operation.definition.auditAction,
+        outcome: "success",
+        actor: {
+          id: context.actor.id,
+          type:
+            context.actor.type === "anonymous" ? "user" : context.actor.type,
+          name: context.actor.name,
+        },
+        target: {
+          type: "agent-run",
+          id: created.runId,
+          label: operationKey,
+        },
+        requestId: context.requestId,
+        occurredAt: new Date().toISOString(),
+      });
+      return {
+        ...created,
+        eventsUrl: `/api/agent/runs/${created.runId}/events`,
+      };
+    } catch (error) {
+      this.grants.discard(grant.token);
+      throw error;
+    }
+  }
+
+  authorizeRun(runId: string, context: RequestGuardContext): void {
+    this.grants.requireRun(runId, context.actor.id);
+  }
+}
+
+interface RegisteredOperation {
+  definition: ModuleAiOperationDefinition;
+  handler?: ModuleAiOperationHandlerRegistration;
+  feature: ReturnType<typeof findFeature>;
+  tools: Array<{ key: string; label: string; description: string }>;
+}
+
+export class AgentRunFacadeError extends Error {
+  constructor(
+    readonly code:
+      | "OPERATION_NOT_FOUND"
+      | "INVALID_INPUT"
+      | "FORBIDDEN"
+      | "RUNTIME_UNAVAILABLE",
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+function toolDefinitions(
+  modules: readonly ModuleManifest[],
+  allowedKeys: readonly string[],
+) {
+  const tools = new Map(
+    modules.flatMap(({ tools }) => tools.map((tool) => [tool.key, tool])),
+  );
+  return allowedKeys.map((key) => {
+    const tool = tools.get(key);
+    if (!tool) throw new Error(`AI Operation 引用了未知 Tool：${key}`);
+    return {
+      key: tool.key,
+      label: tool.label,
+      description: tool.description,
+    };
+  });
+}
+
+function assertInputSize(value: ModuleAiJsonValue, maxBytes: number): void {
+  const size = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  if (size > maxBytes) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "Agent 输入超过上限", 400);
+  }
+}