create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/agent/background-operation-port.ts

@@ -0,0 +1,37 @@
+import type {
+  ModuleBackgroundAiOperationInput,
+  ModuleBackgroundAiPort,
+} from "@southwind-ai/server-sdk";
+import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { AgentBackgroundOperationExecutor } from "./background-operation.js";
+
+export class DeferredAgentBackgroundOperationPortFactory {
+  #executor?: AgentBackgroundOperationExecutor;
+
+  bind(executor: AgentBackgroundOperationExecutor): void {
+    if (this.#executor) {
+      throw new Error("后台 AI Operation Executor 已绑定");
+    }
+    this.#executor = executor;
+  }
+
+  create(
+    moduleName: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): ModuleBackgroundAiPort {
+    return {
+      enqueueOperation: (input: ModuleBackgroundAiOperationInput) => {
+        if (!this.#executor) {
+          throw new ModuleBackgroundAiError(
+            "AI_OPERATION_UNAVAILABLE",
+            "后台 AI Operation Runtime 未启用",
+            true,
+          );
+        }
+        return this.#executor.execute(moduleName, input, context, signal);
+      },
+    };
+  }
+}

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

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { AgentBackgroundOperationExecutor } from "./background-operation.js";
+
+describe("Actor-aware 后台 Agent Operation", () => {
+  test("只执行当前模块声明且不含 Tool 的 Operation", async () => {
+    const fixture = createFixture();
+
+    await expect(
+      fixture.executor.execute(
+        "other",
+        request(),
+        fixture.context,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: "AI_OPERATION_DENIED",
+      retryable: false,
+    });
+    expect(fixture.started).toEqual([]);
+  });
+
+  test("等待既有 Run 终态并读取受控结果", async () => {
+    const fixture = createFixture();
+
+    await expect(
+      fixture.executor.execute(
+        "business",
+        request(),
+        fixture.context,
+        new AbortController().signal,
+      ),
+    ).resolves.toEqual({
+      runId: "run-background",
+      output: { summary: "滚动摘要" },
+    });
+
+    expect(fixture.started).toEqual([
+      {
+        operationKey: "business.summarize",
+        idempotencyKey: "session-1-sequence-8",
+        actorId: "actor-1",
+      },
+    ]);
+    expect(fixture.attachCalls()).toBe(2);
+  });
+
+  test("Durable Job 取消会停止等待并请求取消远端 Run", async () => {
+    const controller = new AbortController();
+    const fixture = createFixture({ waitUntilAbort: true });
+    const pending = fixture.executor.execute(
+      "business",
+      request(),
+      fixture.context,
+      controller.signal,
+    );
+
+    await Promise.resolve();
+    controller.abort("cancelled");
+
+    await expect(pending).rejects.toMatchObject({
+      code: "AI_OPERATION_CANCELLED",
+      retryable: false,
+    });
+    expect(fixture.cancelled).toEqual(["run-background"]);
+  });
+});
+
+function createFixture(options: { waitUntilAbort?: boolean } = {}) {
+  const module = manifest();
+  const hosts = {
+    aiOperationHandlers: [
+      {
+        moduleName: "business",
+        registration: {
+          operationKey: "business.summarize",
+          prepare: () => ({
+            instructions: "压缩历史上下文。",
+            userPrompt: "生成滚动摘要。",
+          }),
+        },
+      },
+    ],
+  } as unknown as InitializedModuleHosts;
+  const started: unknown[] = [];
+  const cancelled: string[] = [];
+  let attaches = 0;
+  const facade = {
+    async start(
+      operationKey: string,
+      _input: unknown,
+      idempotencyKey: string,
+      context: ReturnType<typeof guardContext>,
+    ) {
+      started.push({
+        operationKey,
+        idempotencyKey,
+        actorId: context.actor.id,
+      });
+      return {
+        runId: "run-background",
+        status: "accepted" as const,
+        eventsUrl: "/events",
+      };
+    },
+    async attach(
+      _operationKey: string,
+      runId: string,
+      _cursor: number,
+      _context: ReturnType<typeof guardContext>,
+      signal?: AbortSignal,
+    ) {
+      attaches += 1;
+      if (options.waitUntilAbort) {
+        await new Promise((_, reject) => {
+          signal?.addEventListener("abort", () => reject(signal.reason), {
+            once: true,
+          });
+        });
+      }
+      return {
+        runId,
+        status: attaches === 1 ? ("running" as const) : ("completed" as const),
+        lastSequence: attaches,
+        eventsUrl: "/events",
+      };
+    },
+  };
+  const remote = {
+    result: () =>
+      Promise.resolve(
+        Response.json({
+          runId: "run-background",
+          status: "completed",
+          output: { summary: "滚动摘要" },
+        }),
+      ),
+    cancel: (runId: string) => {
+      cancelled.push(runId);
+      return Promise.resolve(new Response());
+    },
+  };
+  return {
+    executor: new AgentBackgroundOperationExecutor(
+      [module],
+      hosts,
+      facade,
+      remote,
+      0,
+    ),
+    context: guardContext(),
+    started,
+    cancelled,
+    attachCalls: () => attaches,
+  };
+}
+
+function request() {
+  return {
+    operationKey: "business.summarize",
+    input: { messages: ["a", "b"] },
+    idempotencyKey: "session-1-sequence-8",
+    timeoutSeconds: 30,
+  };
+}
+
+function guardContext() {
+  return createRequestGuardContext(new Request("http://durable.internal"), {
+    resolveActor: () => ({
+      id: "actor-1",
+      type: "user",
+      name: "测试用户",
+      roleCodes: ["user"],
+      permissionKeys: ["business.ai.execute"],
+      scopeContext: buildScopeContext("actor-1", undefined, [
+        {
+          id: "role-user",
+          code: "user",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    }),
+    resolveLicense: () => ({ status: "valid" }),
+  });
+}
+
+function manifest(): ModuleManifest {
+  return {
+    name: "business",
+    version: "1.0.0",
+    label: "业务",
+    description: "业务",
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+    aiOperations: [
+      {
+        key: "business.summarize",
+        kind: "agent",
+        featureKey: "business.ai",
+        permissionKey: "business.ai.execute",
+        auditAction: "business.ai.execute",
+        inputSchemaKey: "business.summary.input.v1",
+        outputSchemaKey: "business.summary.output.v1",
+        requiredCapabilities: ["text-generation"],
+        allowedToolKeys: [],
+        dataClassification: "internal",
+        execution: "streaming",
+        publicNetworkAccess: "forbidden",
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 16_384,
+          maxOutputBytes: 4_096,
+        },
+      },
+    ],
+  };
+}

package/template/apps/server/src/agent/background-operation.ts

@@ -0,0 +1,252 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type {
+  ModuleBackgroundAiOperationInput,
+  ModuleBackgroundAiOperationResult,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import { ModuleBackgroundAiError } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import type { AgentRunFacade } from "./run-facade.js";
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export class AgentBackgroundOperationExecutor {
+  readonly #operations: Map<string, BackgroundOperation>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly facade: Pick<AgentRunFacade, "start" | "attach">,
+    private readonly remote: Pick<AgentRuntimePort, "result" | "cancel">,
+    private readonly pollIntervalMs = 250,
+  ) {
+    const registered = new Set(
+      hosts.aiOperationHandlers.map(
+        ({ registration }) => registration.operationKey,
+      ),
+    );
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter(({ key }) => registered.has(key))
+          .map((definition) => [
+            definition.key,
+            { moduleName: module.name, definition },
+          ]),
+      ),
+    );
+  }
+
+  async execute(
+    moduleName: string,
+    input: ModuleBackgroundAiOperationInput,
+    context: RequestGuardContext,
+    outerSignal: AbortSignal,
+  ): Promise<ModuleBackgroundAiOperationResult> {
+    this.assertAllowed(moduleName, input);
+    const timeoutSeconds = validateTimeout(input.timeoutSeconds);
+    const timeout = AbortSignal.timeout(timeoutSeconds * 1_000);
+    const signal = AbortSignal.any([outerSignal, timeout]);
+    let runId: string | undefined;
+    try {
+      const created = await this.facade.start(
+        input.operationKey,
+        input.input,
+        input.idempotencyKey,
+        context,
+        [],
+        signal,
+      );
+      runId = created.runId;
+      while (true) {
+        const status = await this.facade.attach(
+          input.operationKey,
+          runId,
+          0,
+          context,
+          signal,
+        );
+        if (status.status === "completed") {
+          return {
+            runId,
+            output: await this.readResult(runId, signal),
+          };
+        }
+        if (status.status === "failed") {
+          throw new ModuleBackgroundAiError(
+            "AI_OPERATION_FAILED",
+            status.terminalEvent?.type === "run.failed"
+              ? status.terminalEvent.error.message
+              : "后台 AI Operation 执行失败",
+            status.terminalEvent?.type === "run.failed"
+              ? status.terminalEvent.error.retryable
+              : true,
+          );
+        }
+        if (status.status === "cancelled") {
+          throw new ModuleBackgroundAiError(
+            "AI_OPERATION_CANCELLED",
+            "后台 AI Operation 已取消",
+            false,
+          );
+        }
+        await wait(this.pollIntervalMs, signal);
+      }
+    } catch (error) {
+      if (signal.aborted) {
+        const timedOut = timeout.aborted || outerSignal.reason === "timeout";
+        const cancelled = outerSignal.reason === "cancelled";
+        if (runId && (timedOut || cancelled)) {
+          await this.cancel(runId);
+        }
+        throw new ModuleBackgroundAiError(
+          timedOut
+            ? "AI_OPERATION_TIMEOUT"
+            : cancelled
+              ? "AI_OPERATION_CANCELLED"
+              : "AI_OPERATION_FAILED",
+          timedOut
+            ? "后台 AI Operation 执行超时"
+            : cancelled
+              ? "后台 AI Operation 已取消"
+              : "后台 AI Operation 执行中断，可由任务重试恢复",
+          !cancelled,
+        );
+      }
+      if (error instanceof ModuleBackgroundAiError) throw error;
+      if (error instanceof AgentRunFacadeError) {
+        throw new ModuleBackgroundAiError(
+          error.status === 403 ? "AI_OPERATION_DENIED" : "AI_OPERATION_FAILED",
+          error.message,
+          error.status >= 500,
+        );
+      }
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_FAILED",
+        "后台 AI Operation 暂不可用",
+        true,
+      );
+    }
+  }
+
+  private assertAllowed(
+    moduleName: string,
+    input: ModuleBackgroundAiOperationInput,
+  ) {
+    const operation = this.#operations.get(input.operationKey);
+    if (
+      !operation ||
+      operation.moduleName !== moduleName ||
+      operation.definition.kind !== "agent"
+    ) {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_DENIED",
+        "后台 AI Operation 未在当前模块声明",
+        false,
+      );
+    }
+    if (operation.definition.allowedToolKeys.length) {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_DENIED",
+        "后台 AI Operation 禁止调用 Tool",
+        false,
+      );
+    }
+    if (!input.idempotencyKey.trim() || input.idempotencyKey.length > 200) {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_INVALID",
+        "后台 AI Operation 幂等键无效",
+        false,
+      );
+    }
+  }
+
+  private async readResult(
+    runId: string,
+    signal: AbortSignal,
+  ): Promise<ModuleAiJsonValue> {
+    const response = await this.remote.result(runId, signal);
+    if (!response.ok) {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_FAILED",
+        "后台 AI Operation 结果不可用",
+        response.status >= 500,
+      );
+    }
+    const value: unknown = await response.json();
+    if (
+      !isRecord(value) ||
+      value.runId !== runId ||
+      value.status !== "completed" ||
+      !Object.hasOwn(value, "output") ||
+      !isJson(value.output)
+    ) {
+      throw new ModuleBackgroundAiError(
+        "AI_OPERATION_FAILED",
+        "后台 AI Operation 结果格式无效",
+        false,
+      );
+    }
+    return value.output;
+  }
+
+  private async cancel(runId: string) {
+    try {
+      await this.remote.cancel(
+        runId,
+        "background-operation-aborted",
+        AbortSignal.timeout(5_000),
+      );
+    } catch {
+      // 原始 Durable Job 终止优先，远端 Run 仍受自身时长上限约束。
+    }
+  }
+}
+
+interface BackgroundOperation {
+  readonly moduleName: string;
+  readonly definition: ModuleAiOperationDefinition;
+}
+
+function validateTimeout(value: number | undefined) {
+  if (value === undefined) return 300;
+  if (!Number.isSafeInteger(value) || value < 1 || value > 900) {
+    throw new ModuleBackgroundAiError(
+      "AI_OPERATION_INVALID",
+      "后台 AI Operation 超时时间无效",
+      false,
+    );
+  }
+  return value;
+}
+
+function wait(milliseconds: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, milliseconds);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function isJson(value: unknown): value is ModuleAiJsonValue {
+  try {
+    return JSON.stringify(value) !== undefined;
+  } catch {
+    return false;
+  }
+}

package/template/apps/server/src/agent/drizzle-run-binding-repository.ts

@@ -0,0 +1,114 @@
+import { agentRunBindings } from "@southwind-ai/database";
+import { and, eq, isNull, lte, or } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  AgentRunBinding,
+  AgentRunBindingRepository,
+} from "./run-binding-repository.js";
+
+export class DrizzleAgentRunBindingRepository implements AgentRunBindingRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async createOrGet(binding: AgentRunBinding) {
+    const [created] = await this.db
+      .insert(agentRunBindings)
+      .values(values(binding))
+      .onConflictDoNothing({
+        target: agentRunBindings.idempotencyHash,
+      })
+      .returning();
+    if (created) return map(created);
+    const [existing] = await this.db
+      .select()
+      .from(agentRunBindings)
+      .where(eq(agentRunBindings.idempotencyHash, binding.idempotencyHash))
+      .limit(1);
+    if (!existing) throw new Error("Agent Run Binding 幂等创建后无法读取");
+    return map(existing);
+  }
+
+  async bind(bindingId: string, runId: string, boundAt: number) {
+    const [bound] = await this.db
+      .update(agentRunBindings)
+      .set({ runId, boundAt })
+      .where(
+        and(
+          eq(agentRunBindings.bindingId, bindingId),
+          or(isNull(agentRunBindings.runId), eq(agentRunBindings.runId, runId)),
+        ),
+      )
+      .returning();
+    return bound ? map(bound) : undefined;
+  }
+
+  async findByRunId(runId: string) {
+    const [binding] = await this.db
+      .select()
+      .from(agentRunBindings)
+      .where(eq(agentRunBindings.runId, runId))
+      .limit(1);
+    return binding ? map(binding) : undefined;
+  }
+
+  async findByTokenHash(tokenHash: string) {
+    const [binding] = await this.db
+      .select()
+      .from(agentRunBindings)
+      .where(eq(agentRunBindings.tokenHash, tokenHash))
+      .limit(1);
+    return binding ? map(binding) : undefined;
+  }
+
+  async deleteUnbound(bindingId: string) {
+    await this.db
+      .delete(agentRunBindings)
+      .where(
+        and(
+          eq(agentRunBindings.bindingId, bindingId),
+          isNull(agentRunBindings.runId),
+        ),
+      );
+  }
+
+  async prune(expiredBefore: number) {
+    await this.db
+      .delete(agentRunBindings)
+      .where(lte(agentRunBindings.expiresAt, expiredBefore));
+  }
+}
+
+function values(binding: AgentRunBinding) {
+  return {
+    bindingId: binding.bindingId,
+    runId: binding.runId,
+    operationKey: binding.operationKey,
+    actorId: binding.actorId,
+    idempotencyHash: binding.idempotencyHash,
+    tokenHash: binding.tokenHash,
+    scopeHash: binding.scopeHash,
+    scopeSnapshot: binding.scopeSnapshot,
+    authorizationSnapshot: binding.authorizationSnapshot,
+    releaseId: binding.releaseId,
+    createdAt: binding.createdAt,
+    boundAt: binding.boundAt,
+    expiresAt: binding.expiresAt,
+  };
+}
+
+function map(row: typeof agentRunBindings.$inferSelect): AgentRunBinding {
+  return {
+    bindingId: row.bindingId,
+    runId: row.runId ?? undefined,
+    operationKey: row.operationKey,
+    actorId: row.actorId,
+    idempotencyHash: row.idempotencyHash,
+    tokenHash: row.tokenHash,
+    scopeHash: row.scopeHash,
+    scopeSnapshot: row.scopeSnapshot,
+    authorizationSnapshot: row.authorizationSnapshot,
+    releaseId: row.releaseId,
+    createdAt: row.createdAt,
+    boundAt: row.boundAt ?? undefined,
+    expiresAt: row.expiresAt,
+  };
+}

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

@@ -22,6 +22,7 @@ export class ExecutionGrantStore {
   issue(
     operation: ModuleAiOperationDefinition,
     context: RequestGuardContext,
+    maximumLifetimeSeconds = 300,
   ): ExecutionGrant {
     this.prune();
     if (this.#grants.size >= this.maxActiveGrants) {
@@ -29,7 +30,12 @@ export class ExecutionGrantStore {
     }
     const token = `grant_${randomUUIDv7().replaceAll("-", "")}`;
     const expiresAt =
-      this.now() + Math.min(operation.limits.maxDurationSeconds, 300) * 1_000;
+      this.now() +
+      Math.min(
+        Math.max(operation.limits.maxDurationSeconds, maximumLifetimeSeconds),
+        7 * 24 * 60 * 60,
+      ) *
+        1_000;
     const grant = { token, operation, context, expiresAt };
     this.#grants.set(token, grant);
     return grant;

package/template/apps/server/src/agent/fake-runtime.test-support.ts

@@ -0,0 +1,43 @@
+import type {
+  AgentRuntimeOperation,
+  AgentRuntimePort,
+} from "./run-contracts.js";
+
+export class FakeAgentRuntime implements AgentRuntimePort {
+  readonly started: AgentRuntimeOperation[] = [];
+  readonly startedIdempotencyKeys: string[] = [];
+
+  start(request: AgentRuntimeOperation, idempotencyKey: string) {
+    this.started.push(request);
+    this.startedIdempotencyKeys.push(idempotencyKey);
+    return Promise.resolve({
+      runId: "run_1",
+      status: "accepted" as const,
+      eventsUrl: "/internal/events",
+    });
+  }
+
+  status(runId: string) {
+    return Promise.resolve({
+      runId,
+      status: "running" as const,
+      lastSequence: 0,
+    });
+  }
+
+  events() {
+    return Promise.resolve(new Response());
+  }
+
+  result() {
+    return Promise.resolve(new Response());
+  }
+
+  cancel() {
+    return Promise.resolve(new Response());
+  }
+
+  health() {
+    return Promise.resolve(new Response());
+  }
+}