create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,152 @@
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/route-types.js";
+import { EmbeddingFacadeError } from "./error.js";
+import type { EmbeddingFacade } from "./facade.js";
+import type { EmbeddingFacadeItem } from "./input.js";
+
+interface RouteContext {
+  readonly body?: unknown;
+  readonly request: Request;
+  readonly guardContext: RequestGuardContext;
+}
+
+export function registerEmbeddingRoutes(
+  app: RouteApp,
+  facade: EmbeddingFacade,
+) {
+  app.post("/embeddings", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const request = parseRequest(context.body);
+      const idempotencyKey = context.request.headers.get("idempotency-key");
+      if (!idempotencyKey?.trim()) throw invalid("幂等键不能为空");
+      return Response.json(
+        await facade.embed(
+          request.operationKey,
+          request.items,
+          request.options,
+          idempotencyKey,
+          context.guardContext,
+          context.request.signal,
+        ),
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+}
+
+function parseRequest(value: unknown): {
+  operationKey: string;
+  items: readonly EmbeddingFacadeItem[];
+  options: ModuleAiJsonValue;
+} {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).some(
+      (key) => !["operationKey", "items", "options"].includes(key),
+    ) ||
+    typeof value.operationKey !== "string" ||
+    !value.operationKey.trim() ||
+    !Array.isArray(value.items) ||
+    !value.items.length ||
+    value.items.length > 256
+  ) {
+    throw invalid("Embedding 请求格式无效");
+  }
+  const ids = new Set<string>();
+  const items = value.items.map((item): EmbeddingFacadeItem => {
+    if (
+      !isRecord(item) ||
+      typeof item.id !== "string" ||
+      !item.id.trim() ||
+      ids.has(item.id)
+    ) {
+      throw invalid("Embedding 输入 ID 无效或重复");
+    }
+    ids.add(item.id);
+    if (
+      "text" in item &&
+      !("source" in item) &&
+      typeof item.text === "string" &&
+      item.text.trim()
+    ) {
+      return { id: item.id, text: item.text };
+    }
+    if (!("text" in item) && isRecord(item.source)) {
+      return { id: item.id, source: artifact(item.source) };
+    }
+    throw invalid("Embedding 输入必须且只能包含文本或 Artifact");
+  });
+  assertJson(value.options ?? {});
+  return {
+    operationKey: value.operationKey,
+    items,
+    options: (value.options ?? {}) as ModuleAiJsonValue,
+  };
+}
+
+function artifact(value: Record<string, unknown>): ModuleAiArtifactRef {
+  if (
+    typeof value.value !== "string" ||
+    !value.value ||
+    /^[a-z][a-z0-9+.-]*:\/\//i.test(value.value) ||
+    typeof value.mediaType !== "string" ||
+    !Number.isSafeInteger(value.byteSize) ||
+    Number(value.byteSize) < 1 ||
+    typeof value.sha256 !== "string" ||
+    !/^[a-f0-9]{64}$/.test(value.sha256)
+  ) {
+    throw invalid("Embedding ArtifactRef 无效");
+  }
+  return {
+    value: value.value,
+    mediaType: value.mediaType,
+    byteSize: Number(value.byteSize),
+    sha256: value.sha256,
+    expiresAt: typeof value.expiresAt === "string" ? value.expiresAt : "",
+  };
+}
+
+function assertJson(value: unknown) {
+  try {
+    if (JSON.stringify(value) === undefined) throw new Error();
+  } catch {
+    throw invalid("Embedding options 必须是 JSON");
+  }
+}
+
+function knownError(error: unknown) {
+  if (error instanceof EmbeddingFacadeError) {
+    return Response.json(
+      {
+        code: error.code,
+        message: error.message,
+        requestId: crypto.randomUUID(),
+        retryable: error.status >= 500,
+      },
+      { status: error.status },
+    );
+  }
+  return Response.json(
+    {
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Embedding Runtime 暂不可用",
+      requestId: crypto.randomUUID(),
+      retryable: true,
+    },
+    { status: 503 },
+  );
+}
+
+function invalid(message: string) {
+  return new EmbeddingFacadeError("INVALID_INPUT", message, 400);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -17,14 +17,8 @@ import { createServerRuntime } from "./runtime.js";
 import { readPositiveInt } from "./runtime-config.js";
 // @windy-module system.scheduler end
 // @windy-module system.agent begin
-import {
-  createSystemToolHandlers,
-  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";
+import { DeferredAgentBackgroundOperationPortFactory } from "./agent/background-operation-port.js";
 // @windy-module system.agent end
 import { createAuthRuntime } from "./auth/runtime.js";
 import { createServerPersistence } from "./persistence.js";
@@ -56,16 +50,13 @@ import { createStorageRuntime } from "./storage/runtime.js";
 import { registerStorageRoutes } from "./storage/routes.js";
 // @windy-module system.storage end
 import { validateInstalledRuntime } from "./module-runtime-validation.js";
-import { installModuleRoutes } from "./module-host.js";
+import { installModuleHttpRuntime } from "./module-host/http-runtime.js";
 // @windy-module system.search begin
 import { adaptModuleSearchProviders } from "./module-host.js";
 // @windy-module system.search end
 // @windy-module system.scheduler begin
 import { createModuleTaskDefinitions } from "./module-host.js";
 // @windy-module system.scheduler end
-// @windy-module system.agent begin
-import { createModuleToolHandlerMap } from "./module-host.js";
-// @windy-module system.agent end
 // @windy-module system.search begin
 import { createSearchHost } from "./search/host.js";
 // @windy-module system.search end
@@ -130,7 +121,13 @@ const observability = createHttpObservability(runtime, persistence, logger);
 // @windy-module system.license begin
 platformLicenseRuntime.setAuditSink(runtime.auditSink);
 // @windy-module system.license end
-const { authRepository, authService } = createAuthRuntime({
+const {
+  authRepository,
+  authService,
+  // @windy-module system.data-governance begin
+  reauthentication,
+  // @windy-module system.data-governance end
+} = createAuthRuntime({
   repository: persistence?.authRepository,
   sessionTtlSeconds: () => platformConfig.security.sessionTtlSeconds,
   passwordPolicy: () => ({
@@ -172,6 +169,9 @@ const moduleTaskDefinitions = createModuleTaskDefinitions(
   moduleHosts,
   features,
 );
+// @windy-module system.agent begin
+const moduleBackgroundAi = new DeferredAgentBackgroundOperationPortFactory();
+// @windy-module system.agent end
 const {
   bulkDataService,
   scheduler,
@@ -190,7 +190,11 @@ const {
   moduleTasks: moduleTaskDefinitions,
   bulkRetentionDays: readPositiveInt(process.env.BULK_DATA_RETENTION_DAYS, 7),
   mailConfig: platformConfig.mail,
+  moduleHosts,
   installModuleDurableHandlers: moduleHosts.installDurableHandlers,
+  // @windy-module system.agent begin
+  backgroundAi: moduleBackgroundAi,
+  // @windy-module system.agent end
 });
 const schedulerWorker = new SchedulerWorker(
   scheduler,
@@ -278,31 +282,19 @@ registerSystemOperationRoutes(app, runtime, features, {
 });
 // @windy-module system.operations end
 // @windy-module system.agent begin
-const toolHandlers = new Map([
-  ...createSystemToolHandlers(systemRepositories, runtime),
-  ...createModuleToolHandlerMap(moduleHosts, {
+const { toolHandlers, aiArtifacts, aiOperations } =
+  registerAgentPlatformRuntime({
+    app,
+    platformConfig,
+    modules: foundationModules,
+    hosts: moduleHosts,
     runtime,
-    features: foundationSnapshot.features,
-    // @windy-module system.storage begin
+    systemRepositories,
     storage: storageRuntime,
-    // @windy-module system.storage end
-  }),
-]);
-const toolRegistry = new GovernedToolRegistry(
-  foundationModules,
-  toolHandlers,
-  runtime,
-);
-registerAgentRoutes(app, toolRegistry);
-registerMcpRoutes(app, new PlatformMcpAdapter(toolRegistry, runtime, features));
-registerAgentPlatformRuntime({
-  app,
-  platformConfig,
-  modules: foundationModules,
-  hosts: moduleHosts,
-  runtime,
-  toolRegistry,
-});
+    workflow: workflowService,
+    db: persistence?.db,
+    backgroundAi: moduleBackgroundAi,
+  });
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
 registerSchedulerRoutes(app, scheduler, runtime, features);
@@ -310,21 +302,26 @@ registerSchedulerRoutes(app, scheduler, runtime, features);
 // @windy-module system.bulk-data begin
 registerBulkDataRoutes(app, bulkDataService, runtime, features);
 // @windy-module system.bulk-data end
-installModuleRoutes(moduleHosts, app, {
+installModuleHttpRuntime(moduleHosts, app, {
   runtime,
   features,
   // @windy-module system.scheduler begin
   jobs: durableJobRuntime.service,
+  jobWorker: durableJobRuntime.worker,
   // @windy-module system.scheduler end
   // @windy-module system.storage begin
-  storage: {
-    uploads: storageRuntime.uploads,
-    files: storageRuntime.files,
-  },
+  storage: storageRuntime,
   // @windy-module system.storage end
-  userDirectory: {
-    repositories: systemRepositories,
-  },
+  systemRepositories,
+  // @windy-module system.agent begin
+  aiArtifacts,
+  aiOperations,
+  // @windy-module system.agent end
+  // @windy-module system.data-governance begin
+  reauthenticate: (actorId, password) =>
+    reauthentication.verify(actorId, password),
+  governedExportService,
+  // @windy-module system.data-governance end
 });
 
 validateInstalledRuntime({

package/template/apps/server/src/jobs/artifact-service.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import { MemoryBlobStore } from "@southwind-ai/storage";
 import { DurableArtifactService } from "./artifact-service.js";
-import { InMemoryDurableJobRepository } from "./repository.js";
+import { InMemoryDurableExecutionRepository } from "./in-memory-execution.js";
 import { DurableJobService } from "./service.js";
 
 describe("DurableArtifactService", () => {
   test("只有 Owner 或 manage 权限可读取且过期后统一拒绝", async () => {
     let now = new Date("2026-07-16T00:00:00.000Z");
-    const repository = new InMemoryDurableJobRepository();
+    const repository = new InMemoryDurableExecutionRepository();
     const jobs = new DurableJobService(repository, () => now);
     const submitted = await jobs.submit({
       handlerKey: "test.artifact",
@@ -70,6 +70,18 @@ describe("DurableArtifactService", () => {
     ).rejects.toMatchObject({
       code: "ARTIFACT_EXPIRED",
     });
+
+    now = new Date("2026-07-16T12:00:00.000Z");
+    await repository.requestCancel({
+      jobId: submitted.job.id,
+      expectedStatus: "queued",
+      now,
+    });
+    await expect(
+      service.open(submitted.job.id, "result", "owner-1"),
+    ).rejects.toMatchObject({
+      code: "ARTIFACT_JOB_CANCELLED",
+    });
   });
 });
 

package/template/apps/server/src/jobs/artifact-service.ts

@@ -5,6 +5,7 @@ import type { DurableJobRepository } from "./repository.js";
 export type DurableArtifactErrorCode =
   | "ARTIFACT_NOT_FOUND"
   | "ARTIFACT_FORBIDDEN"
+  | "ARTIFACT_JOB_CANCELLED"
   | "ARTIFACT_EXPIRED"
   | "ARTIFACT_CONTENT_MISSING";
 
@@ -54,6 +55,15 @@ export class DurableArtifactService {
     if (artifact.ownerId !== actorId && !allowManage) {
       throw new DurableArtifactError("ARTIFACT_FORBIDDEN", "无权访问任务产物");
     }
+    if (
+      snapshot?.job.status === "cancelled" ||
+      snapshot?.job.cancelRequestedAt
+    ) {
+      throw new DurableArtifactError(
+        "ARTIFACT_JOB_CANCELLED",
+        "已取消任务的产物不可访问",
+      );
+    }
     if (artifact.expiresAt && artifact.expiresAt <= this.now().toISOString()) {
       throw new DurableArtifactError("ARTIFACT_EXPIRED", "任务产物已过期");
     }

package/template/apps/server/src/jobs/drizzle-execution-repository.ts

@@ -11,6 +11,8 @@ import { and, eq, max, notInArray } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type {
   ClaimDurableJob,
+  CancelDurableJob,
+  DurableJobControlResult,
   DurableExecutionRepository,
   FailDurableJob,
   LeaseResult,
@@ -220,24 +222,21 @@ export class DrizzleDurableExecutionRepository implements DurableExecutionReposi
     });
   }
 
-  async requestCancel(jobId: string, now: Date) {
-    return this.db.transaction(async (tx) => {
-      const [job] = await tx
-        .select()
-        .from(durableJobs)
-        .where(eq(durableJobs.id, jobId))
-        .for("update")
-        .limit(1);
-      if (!job || !["queued", "running"].includes(job.status)) return false;
-      if (job.status === "queued") await cancelRemaining(tx, job.id, now);
-      else {
-        await tx
-          .update(durableJobs)
-          .set({ cancelRequestedAt: now, updatedAt: now })
-          .where(eq(durableJobs.id, job.id));
-      }
-      return true;
-    });
+  requestCancel(
+    input: CancelDurableJob,
+  ): Promise<DurableJobControlResult>;
+  requestCancel(jobId: string, now: Date): Promise<boolean>;
+  async requestCancel(
+    input: CancelDurableJob | string,
+    now?: Date,
+  ) {
+    const legacy = typeof input === "string";
+    const result = await this.recovery.requestCancel(
+      legacy ? { jobId: input, now: now! } : input,
+    );
+    return legacy
+      ? ["changed", "unchanged"].includes(result.outcome)
+      : result;
   }
 
   sweepExpired(now: Date, retryDelayMs: number) {

package/template/apps/server/src/jobs/drizzle-execution.integration.test.ts

@@ -180,7 +180,20 @@ describePostgres("PostgreSQL durable execution", () => {
     const execution = new DrizzleDurableExecutionRepository(drizzle(pool));
     const claim = await execution.claim(claimInput("worker-a", base, 10_000));
     if (!claim) throw new Error("任务未领取");
-    expect(await execution.requestCancel(submitted.job.id, base)).toBe(true);
+    const running = await service.get(submitted.job.id);
+    if (!running) throw new Error("运行任务不存在");
+    const cancelInput = {
+      jobId: submitted.job.id,
+      expectedStatus: running.job.status,
+      expectedVersion: running.job.updatedAt,
+      now: base,
+    } as const;
+    expect(await execution.requestCancel(cancelInput)).toEqual({
+      outcome: "changed",
+    });
+    expect(await execution.requestCancel(cancelInput)).toEqual({
+      outcome: "unchanged",
+    });
     expect(await execution.heartbeat(claim, base, 10_000)).toMatchObject({
       ok: true,
       cancelRequested: true,
@@ -190,11 +203,16 @@ describePostgres("PostgreSQL durable execution", () => {
     ).toBe(1);
     expect((await service.get(submitted.job.id))?.job.status).toBe("cancelled");
 
+    const cancelled = await service.get(submitted.job.id);
+    if (!cancelled) throw new Error("取消任务不存在");
     const recovery = {
       jobId: submitted.job.id,
       requestedBy: "ops_user",
       reason: "确认下游依赖已经恢复",
       idempotencyKey: "pg-recovery-1",
+      expectedAttempt: 1,
+      expectedStatus: "cancelled" as const,
+      expectedVersion: cancelled.job.updatedAt,
       now: new Date(base.getTime() + 2_000),
     };
     const results = await Promise.all([

package/template/apps/server/src/jobs/drizzle-mappers.ts

@@ -26,6 +26,7 @@ export function mapJob(row: typeof durableJobs.$inferSelect): DurableJob {
   return {
     ...row,
     status: row.status as DurableJob["status"],
+    authorizationScope: row.authorizationScope ?? undefined,
     availableAt: row.availableAt.toISOString(),
     cancelRequestedAt: iso(row.cancelRequestedAt),
     startedAt: iso(row.startedAt),
@@ -89,10 +90,12 @@ export function mapProgress(
 export function mapArtifact(
   row: typeof durableJobArtifacts.$inferSelect,
 ): DurableJobArtifact {
+  const { metadata, ...artifact } = row;
   return {
-    ...row,
+    ...artifact,
     stageId: row.stageId ?? undefined,
     artifactRef: artifactRef(row.artifactRef),
+    ...(metadata ? { metadata } : {}),
     expiresAt: iso(row.expiresAt),
     createdAt: row.createdAt.toISOString(),
   };

package/template/apps/server/src/jobs/drizzle-recovery-repository.ts

@@ -6,14 +6,48 @@ import {
   durableJobStages,
   durableJobs,
 } from "@southwind-ai/database";
-import { and, eq, lte, notInArray, or } from "drizzle-orm";
+import { and, eq, lte, max, notInArray, or } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
-import type { ManualJobRecovery } from "./execution-repository.js";
+import type {
+  CancelDurableJob,
+  ManualJobRecovery,
+} from "./execution-repository.js";
 import { mapRecovery } from "./drizzle-mappers.js";
 
 export class DrizzleDurableRecoveryRepository {
   constructor(private readonly db: NodePgDatabase) {}
 
+  async requestCancel(input: CancelDurableJob) {
+    return this.db.transaction(async (tx) => {
+      const [job] = await tx
+        .select()
+        .from(durableJobs)
+        .where(eq(durableJobs.id, input.jobId))
+        .for("update")
+        .limit(1);
+      if (!job) return { outcome: "not-found" } as const;
+      if (job.status === "cancelled" || job.cancelRequestedAt) {
+        return { outcome: "unchanged" } as const;
+      }
+      if (
+        !["queued", "running"].includes(job.status) ||
+        (input.expectedStatus && job.status !== input.expectedStatus) ||
+        (input.expectedVersion &&
+          job.updatedAt.toISOString() !== input.expectedVersion)
+      ) {
+        return { outcome: "conflict" } as const;
+      }
+      if (job.status === "queued") await cancelRemaining(tx, job.id, input.now);
+      else {
+        await tx
+          .update(durableJobs)
+          .set({ cancelRequestedAt: input.now, updatedAt: input.now })
+          .where(eq(durableJobs.id, job.id));
+      }
+      return { outcome: "changed" } as const;
+    });
+  }
+
   async sweepExpired(now: Date, retryDelayMs: number) {
     return this.db.transaction(async (tx) => {
       const rows = await tx
@@ -139,6 +173,19 @@ export class DrizzleDurableRecoveryRepository {
       if (!["failed", "cancelled"].includes(job.status)) {
         throw new Error("只有失败或已取消任务可以人工恢复");
       }
+      const [{ attempt = 0 } = { attempt: 0 }] = await tx
+        .select({ attempt: max(durableJobStages.currentAttempt) })
+        .from(durableJobStages)
+        .where(eq(durableJobStages.jobId, job.id));
+      if (
+        (input.expectedStatus && job.status !== input.expectedStatus) ||
+        (input.expectedVersion &&
+          job.updatedAt.toISOString() !== input.expectedVersion) ||
+        (input.expectedAttempt !== undefined &&
+          (attempt || 0) !== input.expectedAttempt)
+      ) {
+        throw new Error("任务状态已变化");
+      }
       const [activeLease] = await tx
         .select({ id: durableJobLeases.id })
         .from(durableJobLeases)

package/template/apps/server/src/jobs/drizzle-repository.ts

@@ -49,6 +49,7 @@ export class DrizzleDurableJobRepository implements DurableJobRepository {
           payload: input.payload,
           priority: input.priority || 0,
           requestedBy: input.requestedBy,
+          authorizationScope: input.authorizationScope,
           maxAttempts: input.maxAttempts || 3,
           timeoutSeconds: input.timeoutSeconds || 900,
           availableAt: input.availableAt || now,

package/template/apps/server/src/jobs/execution-repository.ts

@@ -2,6 +2,7 @@ import type {
   ClaimedDurableJob,
   DurableJobArtifact,
   DurableJobRecovery,
+  DurableJobStatus,
   DurableLeaseIdentity,
 } from "@southwind-ai/jobs";
 
@@ -32,6 +33,9 @@ export interface ManualJobRecovery {
   requestedBy: string;
   reason: string;
   idempotencyKey: string;
+  expectedAttempt?: number;
+  expectedStatus?: DurableJobStatus;
+  expectedVersion?: string;
   now: Date;
 }
 
@@ -40,6 +44,17 @@ export interface ManualJobRecoveryResult {
   recovered: boolean;
 }
 
+export interface CancelDurableJob {
+  jobId: string;
+  expectedStatus?: DurableJobStatus;
+  expectedVersion?: string;
+  now: Date;
+}
+
+export type DurableJobControlResult =
+  | { outcome: "changed" | "unchanged" }
+  | { outcome: "not-found" | "conflict" };
+
 export interface DurableExecutionRepository {
   claim(input: ClaimDurableJob): Promise<ClaimedDurableJob | undefined>;
   heartbeat(
@@ -66,7 +81,9 @@ export interface DurableExecutionRepository {
     failure: FailDurableJob,
     now: Date,
   ): Promise<LeaseResult>;
+  /** @deprecated 兼容平台内部旧调用；模块 Port 必须使用 CAS 输入。 */
   requestCancel(jobId: string, now: Date): Promise<boolean>;
+  requestCancel(input: CancelDurableJob): Promise<DurableJobControlResult>;
   sweepExpired(now: Date, retryDelayMs: number): Promise<number>;
   recover(input: ManualJobRecovery): Promise<ManualJobRecoveryResult>;
 }

package/template/apps/server/src/jobs/execution.test.ts

@@ -287,6 +287,40 @@ describe("durable job execution", () => {
     expect(observed).toEqual(["prepare:2", "apply:2"]);
     expect((await service.get(submitted.job.id))?.job.status).toBe("succeeded");
   });
+
+  test("模块 Handler 每次尝试都通过 contextualizer 重建执行上下文", async () => {
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    await service.submit(jobInput("module-context"));
+    const observed: string[] = [];
+    const handlers = new DurableHandlerRegistry().register(
+      {
+        key: "test.handler",
+        payload: { parse: () => ({}) },
+        execute: (_payload, context) => {
+          observed.push(
+            `${(context as { requestId?: string }).requestId}:${context.attemptNumber}`,
+          );
+        },
+      },
+      { moduleName: "test" },
+    );
+    let rebuilds = 0;
+    const worker = new DurableJobWorker(repository, handlers, {
+      now: () => base,
+      contextualize: async ({ moduleName, context }) => {
+        rebuilds += 1;
+        expect(moduleName).toBe("test");
+        return { ...context, requestId: `request-${rebuilds}` };
+      },
+    });
+
+    expect(await worker.runNext("default", "worker-a")).toMatchObject({
+      status: "succeeded",
+    });
+    expect(observed).toEqual(["request-1:1"]);
+    expect(rebuilds).toBe(1);
+  });
 });
 
 function jobInput(idempotencyKey: string) {