create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/jobs/in-memory-control.ts

@@ -0,0 +1,135 @@
+import type {
+  DurableJob,
+  DurableJobLease,
+  DurableJobRecovery,
+  DurableJobStage,
+} from "@southwind-ai/jobs";
+import type {
+  CancelDurableJob,
+  ManualJobRecovery,
+} from "./execution-repository.js";
+
+interface InMemoryControlFacts {
+  jobs: Map<string, DurableJob>;
+  stages: Map<string, DurableJobStage>;
+  leases: Map<string, DurableJobLease>;
+  recoveries: Map<string, DurableJobRecovery>;
+}
+
+export function requestInMemoryCancel(
+  facts: InMemoryControlFacts,
+  input: CancelDurableJob,
+) {
+  const job = facts.jobs.get(input.jobId);
+  if (!job) return { outcome: "not-found" } as const;
+  if (job.status === "cancelled" || job.cancelRequestedAt) {
+    return { outcome: "unchanged" } as const;
+  }
+  if (
+    ["succeeded", "failed"].includes(job.status) ||
+    (input.expectedStatus && job.status !== input.expectedStatus) ||
+    (input.expectedVersion && job.updatedAt !== input.expectedVersion)
+  ) {
+    return { outcome: "conflict" } as const;
+  }
+  if (job.status === "queued") cancelInMemoryJob(facts, job, input.now);
+  else {
+    job.cancelRequestedAt = input.now.toISOString();
+    job.updatedAt = input.now.toISOString();
+  }
+  return { outcome: "changed" } as const;
+}
+
+export function recoverInMemoryJob(
+  facts: InMemoryControlFacts,
+  input: ManualJobRecovery,
+) {
+  const existing = [...facts.recoveries.values()].find(
+    (item) =>
+      item.jobId === input.jobId &&
+      item.idempotencyKey === input.idempotencyKey,
+  );
+  if (existing)
+    return { recovery: structuredClone(existing), recovered: false };
+  const job = facts.jobs.get(input.jobId);
+  if (!job) throw new Error("任务不存在");
+  const stages = jobStages(facts, job.id);
+  const currentAttempt = Math.max(
+    0,
+    ...stages.map((stage) => stage.currentAttempt),
+  );
+  if (
+    (input.expectedStatus && job.status !== input.expectedStatus) ||
+    (input.expectedVersion && job.updatedAt !== input.expectedVersion) ||
+    (input.expectedAttempt !== undefined &&
+      currentAttempt !== input.expectedAttempt)
+  )
+    throw new Error("任务状态已变化");
+  if (!["failed", "cancelled"].includes(job.status))
+    throw new Error("只有失败或已取消任务可以人工恢复");
+  if (
+    [...facts.leases.values()].some(
+      (lease) => lease.jobId === job.id && lease.status === "active",
+    )
+  )
+    throw new Error("任务仍有活跃租约，不能人工恢复");
+  const recovery: DurableJobRecovery = {
+    id: Bun.randomUUIDv7(),
+    jobId: job.id,
+    fromStatus: job.status,
+    requestedBy: input.requestedBy,
+    reason: input.reason,
+    idempotencyKey: input.idempotencyKey,
+    createdAt: input.now.toISOString(),
+  };
+  facts.recoveries.set(recovery.id, recovery);
+  for (const stage of stages) {
+    if (stage.status !== "succeeded") {
+      Object.assign(stage, {
+        status: "pending",
+        startedAt: undefined,
+        finishedAt: undefined,
+        updatedAt: input.now.toISOString(),
+      });
+    }
+  }
+  Object.assign(job, {
+    status: "queued",
+    availableAt: input.now.toISOString(),
+    cancelRequestedAt: undefined,
+    finishedAt: undefined,
+    updatedAt: input.now.toISOString(),
+  });
+  return { recovery: structuredClone(recovery), recovered: true };
+}
+
+export function cancelInMemoryJob(
+  facts: Pick<InMemoryControlFacts, "stages">,
+  job: DurableJob,
+  now: Date,
+) {
+  for (const stage of jobStages(facts, job.id)) {
+    if (stage.status !== "succeeded") {
+      Object.assign(stage, {
+        status: "cancelled",
+        finishedAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+      });
+    }
+  }
+  Object.assign(job, {
+    status: "cancelled",
+    cancelRequestedAt: job.cancelRequestedAt || now.toISOString(),
+    finishedAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  });
+}
+
+function jobStages(
+  facts: Pick<InMemoryControlFacts, "stages">,
+  jobId: string,
+) {
+  return [...facts.stages.values()]
+    .filter((stage) => stage.jobId === jobId)
+    .sort((left, right) => left.ordinal - right.ordinal);
+}

package/template/apps/server/src/jobs/in-memory-execution.ts

@@ -1,5 +1,7 @@
 import type {
+  CancelDurableJob,
   ClaimDurableJob,
+  DurableJobControlResult,
   DurableExecutionRepository,
   FailDurableJob,
   ManualJobRecovery,
@@ -17,6 +19,11 @@ import {
   publishInMemoryArtifact,
   validateInMemoryLease,
 } from "./in-memory-lease.js";
+import {
+  cancelInMemoryJob,
+  recoverInMemoryJob,
+  requestInMemoryCancel,
+} from "./in-memory-control.js";
 
 export class InMemoryDurableExecutionRepository
   extends InMemoryDurableJobRepository
@@ -160,17 +167,22 @@ export class InMemoryDurableExecutionRepository
     );
   }
 
-  async requestCancel(jobId: string, now: Date) {
-    const job = this.jobs.get(jobId);
-    if (!job || ["succeeded", "failed", "cancelled"].includes(job.status)) {
-      return false;
-    }
-    if (job.status === "queued") this.cancelJob(job, now);
-    else {
-      job.cancelRequestedAt = now.toISOString();
-      job.updatedAt = now.toISOString();
-    }
-    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 = requestInMemoryCancel(
+      this.controlFacts(),
+      legacy ? { jobId: input, now: now! } : input,
+    );
+    return legacy
+      ? ["changed", "unchanged"].includes(result.outcome)
+      : result;
   }
 
   async sweepExpired(now: Date, retryDelayMs: number) {
@@ -200,45 +212,7 @@ export class InMemoryDurableExecutionRepository
   }
 
   async recover(input: ManualJobRecovery) {
-    const existing = [...this.recoveries.values()].find(
-      (item) =>
-        item.jobId === input.jobId &&
-        item.idempotencyKey === input.idempotencyKey,
-    );
-    if (existing)
-      return { recovery: structuredClone(existing), recovered: false };
-    const job = this.jobs.get(input.jobId);
-    if (!job || !["failed", "cancelled"].includes(job.status)) {
-      throw new Error("只有失败或已取消任务可以人工恢复");
-    }
-    const recovery = {
-      id: Bun.randomUUIDv7(),
-      jobId: job.id,
-      fromStatus: job.status,
-      requestedBy: input.requestedBy,
-      reason: input.reason,
-      idempotencyKey: input.idempotencyKey,
-      createdAt: input.now.toISOString(),
-    } as const;
-    this.recoveries.set(recovery.id, recovery);
-    for (const stage of this.jobStages(job.id)) {
-      if (stage.status !== "succeeded") {
-        Object.assign(stage, {
-          status: "pending",
-          startedAt: undefined,
-          finishedAt: undefined,
-          updatedAt: input.now.toISOString(),
-        });
-      }
-    }
-    Object.assign(job, {
-      status: "queued",
-      availableAt: input.now.toISOString(),
-      cancelRequestedAt: undefined,
-      finishedAt: undefined,
-      updatedAt: input.now.toISOString(),
-    });
-    return { recovery: structuredClone(recovery), recovered: true };
+    return recoverInMemoryJob(this.controlFacts(), input);
   }
 
   private settleFailure(
@@ -317,20 +291,15 @@ export class InMemoryDurableExecutionRepository
   }
 
   private cancelJob(job: DurableJob, now: Date) {
-    for (const stage of this.jobStages(job.id)) {
-      if (stage.status !== "succeeded") {
-        Object.assign(stage, {
-          status: "cancelled",
-          finishedAt: now.toISOString(),
-          updatedAt: now.toISOString(),
-        });
-      }
-    }
-    Object.assign(job, {
-      status: "cancelled",
-      cancelRequestedAt: job.cancelRequestedAt || now.toISOString(),
-      finishedAt: now.toISOString(),
-      updatedAt: now.toISOString(),
-    });
+    cancelInMemoryJob({ stages: this.stages }, job, now);
+  }
+
+  private controlFacts() {
+    return {
+      jobs: this.jobs,
+      stages: this.stages,
+      leases: this.leases,
+      recoveries: this.recoveries,
+    };
   }
 }

package/template/apps/server/src/jobs/legacy-service-runtime.ts

@@ -17,7 +17,7 @@ import {
   LegacyDurableAdapter,
 } from "./legacy-adapter.js";
 import { DurableJobService } from "./service.js";
-import { DurableJobWorker } from "./worker.js";
+import { DurableJobWorker, type DurableWorkerOptions } from "./worker.js";
 import type { WorkflowService } from "../workflow/service.js";
 import { WorkflowTimeoutRuntime } from "../workflow/timeout-runtime.js";
 
@@ -32,6 +32,7 @@ interface LegacyServiceRuntimeInput {
   runtime: ReturnType<typeof createServerRuntime>;
   workflow: WorkflowService;
   installModuleDurableHandlers?: (registry: DurableHandlerRegistry) => void;
+  durableContextualize?: DurableWorkerOptions["contextualize"];
 }
 
 export function createLegacyServiceRuntime(input: LegacyServiceRuntimeInput) {
@@ -43,7 +44,9 @@ export function createLegacyServiceRuntime(input: LegacyServiceRuntimeInput) {
   const service = new DurableJobService(facts);
   const registry = new DurableHandlerRegistry();
   input.installModuleDurableHandlers?.(registry);
-  const worker = new DurableJobWorker(execution, registry);
+  const worker = new DurableJobWorker(execution, registry, {
+    contextualize: input.durableContextualize,
+  });
   const workflowTimeout = new WorkflowTimeoutRuntime(
     service,
     worker,

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

@@ -54,6 +54,9 @@ export class InMemoryDurableJobRepository implements DurableJobRepository {
       payload: structuredClone(input.payload),
       priority: input.priority || 0,
       requestedBy: input.requestedBy,
+      authorizationScope: input.authorizationScope
+        ? structuredClone(input.authorizationScope)
+        : undefined,
       maxAttempts: input.maxAttempts || 3,
       timeoutSeconds: input.timeoutSeconds || 900,
       availableAt: (input.availableAt || now).toISOString(),

package/template/apps/server/src/jobs/worker.ts

@@ -1,4 +1,5 @@
 import type {
+  CancelDurableJob,
   DurableExecutionRepository,
   LeaseResult,
   ManualJobRecovery,
@@ -7,6 +8,7 @@ import {
   DurableHandlerError,
   type DurableHandlerContext,
   type DurableHandlerRegistry,
+  type RegisteredDurableHandler,
   type ClaimedDurableJob,
   type DurableLeaseIdentity,
 } from "@southwind-ai/jobs";
@@ -22,12 +24,19 @@ export interface DurableWorkerOptions {
   leaseDurationMs?: number;
   retryDelayMs?: number;
   now?: () => Date;
+  contextualize?: (input: {
+    claim: ClaimedDurableJob;
+    moduleName?: string;
+    context: DurableHandlerContext;
+  }) => Promise<DurableHandlerContext>;
 }
 
 export class DurableJobWorker {
   private readonly leaseDurationMs: number;
   private readonly retryDelayMs: number;
   private readonly now: () => Date;
+  private readonly contextualize?: DurableWorkerOptions["contextualize"];
+  private readonly activeRuns = new Map<string, AbortController>();
 
   constructor(
     private readonly repository: DurableExecutionRepository,
@@ -37,6 +46,7 @@ export class DurableJobWorker {
     this.leaseDurationMs = options.leaseDurationMs || 30_000;
     this.retryDelayMs = options.retryDelayMs || 1_000;
     this.now = options.now || (() => new Date());
+    this.contextualize = options.contextualize;
   }
 
   async runNext(queue: string, workerId: string): Promise<DurableRunResult> {
@@ -61,11 +71,23 @@ export class DurableJobWorker {
       );
       return { status: "failed", jobId: claim.jobId };
     }
-    return this.execute(claim, handler.execute);
+    return this.execute(claim, handler);
   }
 
-  cancel(jobId: string) {
-    return this.repository.requestCancel(jobId, this.now());
+  async cancel(jobId: string) {
+    const result = await this.controlCancel({ jobId });
+    return ["changed", "unchanged"].includes(result.outcome);
+  }
+
+  async controlCancel(input: Omit<CancelDurableJob, "now">) {
+    const result = await this.repository.requestCancel({
+      ...input,
+      now: this.now(),
+    });
+    if (["changed", "unchanged"].includes(result.outcome)) {
+      this.activeRuns.get(input.jobId)?.abort("cancelled");
+    }
+    return result;
   }
 
   recover(input: Omit<ManualJobRecovery, "now">) {
@@ -80,12 +102,10 @@ export class DurableJobWorker {
 
   private async execute(
     claim: ClaimedDurableJob,
-    handler: (
-      payload: Record<string, unknown>,
-      context: DurableHandlerContext,
-    ) => Promise<void>,
+    handler: RegisteredDurableHandler,
   ): Promise<DurableRunResult> {
     const abort = new AbortController();
+    this.activeRuns.set(claim.jobId, abort);
     const identity = identityOf(claim);
     let rejectControl: (error: Error) => void = () => undefined;
     const control = new Promise<never>((_, reject) => {
@@ -120,40 +140,50 @@ export class DurableJobWorker {
     }, claim.job.timeoutSeconds * 1_000);
 
     try {
+      const baseContext: DurableHandlerContext = {
+        jobId: claim.jobId,
+        stageKey: claim.stage.key,
+        attemptNumber: claim.stage.currentAttempt,
+        signal: abort.signal,
+        heartbeat,
+        progress: async (progress) => {
+          validateProgress(progress.completedUnits, progress.totalUnits);
+          const result = await this.repository.recordProgress(
+            identity,
+            progress.completedUnits,
+            progress.totalUnits,
+            progress.message,
+            progress.metadata,
+            this.now(),
+          );
+          assertLease(result, abort);
+        },
+        publishArtifact: async (artifact) => {
+          const result = await this.repository.publishArtifact(
+            identity,
+            {
+              id: Bun.randomUUIDv7(),
+              jobId: identity.jobId,
+              stageId: identity.stageId,
+              ...artifact,
+              createdAt: this.now().toISOString(),
+            },
+            this.now(),
+          );
+          assertLease(result, abort);
+        },
+      };
       await Promise.race([
-        handler(claim.job.payload, {
-          jobId: claim.jobId,
-          stageKey: claim.stage.key,
-          attemptNumber: claim.stage.currentAttempt,
-          signal: abort.signal,
-          heartbeat,
-          progress: async (progress) => {
-            validateProgress(progress.completedUnits, progress.totalUnits);
-            const result = await this.repository.recordProgress(
-              identity,
-              progress.completedUnits,
-              progress.totalUnits,
-              progress.message,
-              progress.metadata,
-              this.now(),
-            );
-            assertLease(result, abort);
-          },
-          publishArtifact: async (artifact) => {
-            const result = await this.repository.publishArtifact(
-              identity,
-              {
-                id: Bun.randomUUIDv7(),
-                jobId: identity.jobId,
-                stageId: identity.stageId,
-                ...artifact,
-                createdAt: this.now().toISOString(),
-              },
-              this.now(),
-            );
-            assertLease(result, abort);
-          },
-        }),
+        (async () => {
+          const context = this.contextualize
+            ? await this.contextualize({
+                claim,
+                moduleName: handler.moduleName,
+                context: baseContext,
+              })
+            : baseContext;
+          await handler.execute(claim.job.payload, context);
+        })(),
         control,
       ]);
       const result = await this.repository.complete(identity, this.now());
@@ -166,7 +196,13 @@ export class DurableJobWorker {
       if (error instanceof LeaseLostError) {
         return { status: "lease-lost", jobId: claim.jobId };
       }
-      const failure = classifyFailure(error, this.now(), this.retryDelayMs);
+      const failure = classifyFailure(
+        abort.signal.reason === "cancelled"
+          ? new JobCancelledError("任务已请求取消")
+          : error,
+        this.now(),
+        this.retryDelayMs,
+      );
       const result = await this.repository.fail(identity, failure, this.now());
       if (!result.ok) return { status: "lease-lost", jobId: claim.jobId };
       return {
@@ -174,6 +210,9 @@ export class DurableJobWorker {
         jobId: claim.jobId,
       };
     } finally {
+      if (this.activeRuns.get(claim.jobId) === abort) {
+        this.activeRuns.delete(claim.jobId);
+      }
       clearInterval(interval);
       clearTimeout(timeout);
     }

package/template/apps/server/src/module-host/ai-operation-port.ts

@@ -0,0 +1,170 @@
+// @windy-module system.agent begin
+import type {
+  ModuleAiJsonValue,
+  ModuleAiOperationPort,
+} from "@southwind-ai/server-sdk";
+import { ModuleAiOperationError } from "@southwind-ai/server-sdk";
+import type { AgentRunFacade } from "../agent/run-facade.js";
+import type { AgentRuntimePort } from "../agent/run-contracts.js";
+import type { DocumentRuntimePort } from "../document/contracts.js";
+import type { DocumentRunFacade } from "../document/facade.js";
+import type { EmbeddingFacade } from "../embedding/facade.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { SpeechRuntimePort } from "../speech/contracts.js";
+import type { SpeechRunFacade } from "../speech/facade.js";
+
+export interface ModuleAiRuntimeServices {
+  readonly agentFacade: AgentRunFacade;
+  readonly agentRemote: AgentRuntimePort;
+  readonly documentFacade: DocumentRunFacade;
+  readonly documentRemote: DocumentRuntimePort;
+  readonly speechFacade: SpeechRunFacade;
+  readonly speechRemote: SpeechRuntimePort;
+  readonly embeddingFacade: EmbeddingFacade;
+}
+
+export function createModuleAiOperationPort(
+  moduleName: string,
+  context: RequestGuardContext,
+  signal: AbortSignal,
+  services: ModuleAiRuntimeServices,
+): ModuleAiOperationPort {
+  const own = (operationKey: string) => {
+    if (!operationKey.startsWith(`${moduleName}.`)) {
+      throw new ModuleAiOperationError(
+        "AI_OPERATION_FORBIDDEN",
+        `模块 ${moduleName} 不能执行其它模块的 AI Operation`,
+      );
+    }
+  };
+  return {
+    async startAgent(input) {
+      own(input.operationKey);
+      return services.agentFacade.start(
+        input.operationKey,
+        input.input,
+        input.idempotencyKey,
+        context,
+        input.artifacts,
+        signal,
+      );
+    },
+    async startDocument(input) {
+      own(input.operationKey);
+      return services.documentFacade.start(
+        input.operationKey,
+        input.sources,
+        input.options,
+        input.idempotencyKey,
+        context,
+        signal,
+      );
+    },
+    async startSpeech(input) {
+      own(input.operationKey);
+      return services.speechFacade.start(
+        input.operationKey,
+        input.source,
+        input.options,
+        input.idempotencyKey,
+        context,
+        signal,
+      );
+    },
+    async embed(input) {
+      own(input.operationKey);
+      return jsonValue(
+        await services.embeddingFacade.embed(
+          input.operationKey,
+          input.items,
+          input.options,
+          input.idempotencyKey,
+          context,
+          signal,
+        ),
+      );
+    },
+    async result(input) {
+      own(input.operationKey);
+      if (input.kind === "agent") {
+        await services.agentFacade.authorizeRun(
+          input.operationKey,
+          input.runId,
+          context,
+        );
+        return responseJson(
+          await services.agentRemote.result(input.runId, signal),
+        );
+      }
+      if (input.kind === "document") {
+        services.documentFacade.authorizeRun(input.runId, context);
+        return responseJson(
+          await services.documentRemote.result(input.runId, signal),
+        );
+      }
+      services.speechFacade.authorizeRun(input.runId, context);
+      return responseJson(
+        await services.speechRemote.result(input.runId, signal),
+      );
+    },
+    async cancel(input) {
+      own(input.operationKey);
+      let response: Response;
+      if (input.kind === "agent") {
+        await services.agentFacade.authorizeRun(
+          input.operationKey,
+          input.runId,
+          context,
+        );
+        response = await services.agentRemote.cancel(
+          input.runId,
+          input.reason,
+          signal,
+        );
+      } else if (input.kind === "document") {
+        services.documentFacade.authorizeRun(input.runId, context);
+        response = await services.documentRemote.cancel(
+          input.runId,
+          input.reason,
+          signal,
+        );
+      } else {
+        services.speechFacade.authorizeRun(input.runId, context);
+        response = await services.speechRemote.cancel(
+          input.runId,
+          input.reason,
+          signal,
+        );
+      }
+      if (!response.ok) throw await responseError(response);
+    },
+  };
+}
+
+async function responseJson(response: Response): Promise<ModuleAiJsonValue> {
+  if (!response.ok) throw await responseError(response);
+  return jsonValue(await response.json());
+}
+
+async function responseError(response: Response) {
+  let message = `AI Runtime 返回 ${response.status}`;
+  try {
+    const value = (await response.json()) as Record<string, unknown>;
+    if (typeof value.message === "string") message = value.message;
+  } catch {
+    // Runtime 正文不受信任；只保留稳定状态。
+  }
+  return new ModuleAiOperationError(
+    response.status === 404
+      ? "AI_OPERATION_INVALID"
+      : response.status === 409
+        ? "AI_OPERATION_PENDING"
+        : "AI_OPERATION_FAILED",
+    message,
+  );
+}
+
+function jsonValue(value: unknown): ModuleAiJsonValue {
+  return JSON.parse(JSON.stringify(value)) as ModuleAiJsonValue;
+}
+// @windy-module system.agent end