create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { randomUUIDv7 } from "bun";
+import type { DurableJobSnapshot, DurableJobs } from "@southwind-ai/jobs";
+import type {
+  ModuleJobPort,
+  ModuleJobView,
+} from "@southwind-ai/server-sdk";
+import {
+  ModuleJobControlError,
+  requireModuleNamespace,
+} from "@southwind-ai/server-sdk";
+import type { AuditEvent } from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  captureAuthorizationScope,
+  hashAuthorizationScope,
+} from "../data-access/scope-snapshot.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleJobControlRuntime {
+  readonly worker: {
+    controlCancel(input: {
+      jobId: string;
+      expectedStatus?: ModuleJobView["status"];
+      expectedVersion?: string;
+    }): Promise<{
+      outcome: "changed" | "unchanged" | "not-found" | "conflict";
+    }>;
+    recover(input: {
+      jobId: string;
+      requestedBy: string;
+      reason: string;
+      idempotencyKey: string;
+      expectedAttempt: number;
+      expectedStatus: ModuleJobView["status"];
+      expectedVersion: string;
+    }): Promise<unknown>;
+  };
+}
+
+export interface ModuleJobPortInput {
+  readonly moduleName: string;
+  readonly guardContext: RequestGuardContext;
+  readonly runtime: ServerRuntime;
+  readonly jobs?: DurableJobs;
+  readonly control?: ModuleJobControlRuntime;
+  readonly reauthorize?: () => Promise<boolean>;
+}
+
+export function createModuleJobPort(input: ModuleJobPortInput): ModuleJobPort {
+  return {
+    async submit(job) {
+      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
+      const jobs = requiredJobs(input);
+      const result = await jobs.submit({
+        ...job,
+        queue: input.moduleName,
+        requestedBy: input.guardContext.actor.id,
+        authorizationScope: currentScope(input),
+      });
+      return { jobId: result.job.id, created: result.created };
+    },
+    async get(jobId) {
+      return toAuthorizedView(input, jobId);
+    },
+    async cancel(request) {
+      const reason = sanitizeReason(request.reason);
+      const current = await requireAuthorizedSnapshot(input, request.jobId);
+      const control = requiredControl(input);
+      const result = await control.worker.controlCancel({
+        jobId: current.job.id,
+        expectedStatus: request.expectedStatus,
+        expectedVersion: request.expectedVersion,
+      });
+      if (result.outcome === "conflict" || result.outcome === "not-found") {
+        await auditControl(
+          input,
+          "cancel",
+          "failure",
+          current,
+          reason,
+          result.outcome,
+        );
+        throw conflict();
+      }
+      const updated = await requireAuthorizedSnapshot(input, request.jobId);
+      await auditControl(
+        input,
+        "cancel",
+        "success",
+        updated,
+        reason,
+        result.outcome,
+      );
+      return toView(updated);
+    },
+    async recover(request) {
+      const reason = sanitizeReason(request.reason);
+      const current = await requireAuthorizedSnapshot(input, request.jobId);
+      const control = requiredControl(input);
+      try {
+        await control.worker.recover({
+          jobId: current.job.id,
+          requestedBy: input.guardContext.actor.id,
+          reason,
+          idempotencyKey: recoveryKey(input, request),
+          expectedAttempt: request.expectedAttempt,
+          expectedStatus: request.expectedStatus,
+          expectedVersion: request.expectedVersion,
+        });
+      } catch {
+        await auditControl(
+          input,
+          "recover",
+          "failure",
+          current,
+          reason,
+          "conflict",
+        );
+        throw conflict();
+      }
+      const updated = await requireAuthorizedSnapshot(input, request.jobId);
+      await auditControl(input, "recover", "success", updated, reason, "changed");
+      return toView(updated);
+    },
+  };
+}
+
+async function toAuthorizedView(
+  input: ModuleJobPortInput,
+  jobId: string,
+): Promise<ModuleJobView | undefined> {
+  if (input.reauthorize && !(await input.reauthorize())) return undefined;
+  const snapshot = await requiredJobs(input).get(jobId);
+  return snapshot && authorized(input, snapshot) ? toView(snapshot) : undefined;
+}
+
+async function requireAuthorizedSnapshot(
+  input: ModuleJobPortInput,
+  jobId: string,
+) {
+  const snapshot = await toAuthorizedSnapshot(input, jobId);
+  if (snapshot) return snapshot;
+  await auditUnavailable(input, jobId);
+  throw new ModuleJobControlError("JOB_NOT_AVAILABLE", "任务不可用");
+}
+
+async function toAuthorizedSnapshot(
+  input: ModuleJobPortInput,
+  jobId: string,
+) {
+  if (input.reauthorize && !(await input.reauthorize())) return undefined;
+  const snapshot = await requiredJobs(input).get(jobId);
+  return snapshot && authorized(input, snapshot) ? snapshot : undefined;
+}
+
+function authorized(input: ModuleJobPortInput, snapshot: DurableJobSnapshot) {
+  const job = snapshot.job;
+  const submittedScope = job.authorizationScope;
+  return (
+    job.queue === input.moduleName &&
+    job.handlerKey.startsWith(`${input.moduleName}.`) &&
+    job.requestedBy === input.guardContext.actor.id &&
+    Boolean(submittedScope) &&
+    hashAuthorizationScope(submittedScope!) ===
+      hashAuthorizationScope(currentScope(input))
+  );
+}
+
+function toView(snapshot: DurableJobSnapshot): ModuleJobView {
+  const attempt = Math.max(
+    0,
+    ...snapshot.stages.map((stage) => stage.currentAttempt),
+  );
+  const latestProgress = snapshot.progress
+    .slice()
+    .sort(
+      (left, right) =>
+        left.recordedAt.localeCompare(right.recordedAt) ||
+        left.sequence - right.sequence,
+    )
+    .at(-1);
+  const latestFailure = snapshot.failures.at(-1);
+  const activeLease = snapshot.leases.some((lease) => lease.status === "active");
+  return {
+    jobId: snapshot.job.id,
+    handlerKey: snapshot.job.handlerKey,
+    status: snapshot.job.status,
+    progress: latestProgress
+      ? {
+          completedUnits: latestProgress.completedUnits,
+          totalUnits: latestProgress.totalUnits,
+        }
+      : undefined,
+    attempt,
+    maxAttempts: snapshot.job.maxAttempts,
+    createdAt: snapshot.job.createdAt,
+    startedAt: snapshot.job.startedAt,
+    finishedAt: snapshot.job.finishedAt,
+    failureCode: safeFailureCode(latestFailure?.code),
+    canCancel:
+      ["queued", "running"].includes(snapshot.job.status) &&
+      !snapshot.job.cancelRequestedAt,
+    canRecover:
+      ["failed", "cancelled"].includes(snapshot.job.status) && !activeLease,
+    version: snapshot.job.updatedAt,
+  };
+}
+
+function sanitizeReason(value: string) {
+  const reason = value
+    .trim()
+    .replace(/\s+/g, " ")
+    .replace(/[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/g, "[邮箱]")
+    .replace(/\b\d{7,}\b/g, "[号码]")
+    .replace(/\b[A-Za-z0-9_-]{24,}\b/g, "[敏感内容]")
+    .slice(0, 200);
+  if (reason.length < 5) {
+    throw new ModuleJobControlError(
+      "JOB_REASON_INVALID",
+      "任务控制理由至少 5 个字符",
+    );
+  }
+  return reason;
+}
+
+function safeFailureCode(code: string | undefined) {
+  if (!code) return undefined;
+  return /^[A-Z][A-Z0-9_.-]{0,79}$/.test(code) ? code : "JOB_FAILED";
+}
+
+function currentScope(input: ModuleJobPortInput) {
+  return captureAuthorizationScope(
+    input.guardContext.actor.scopeContext,
+  ).snapshot;
+}
+
+function requiredJobs(input: ModuleJobPortInput) {
+  if (input.jobs) return input.jobs;
+  throw unavailable();
+}
+
+function requiredControl(input: ModuleJobPortInput) {
+  if (input.control) return input.control;
+  throw unavailable();
+}
+
+function unavailable() {
+  return new ModuleJobControlError(
+    "JOB_CONTROL_UNAVAILABLE",
+    "Durable Jobs 运行时未挂载",
+  );
+}
+
+function conflict() {
+  return new ModuleJobControlError("JOB_STATE_CONFLICT", "任务状态已变化");
+}
+
+function recoveryKey(
+  input: ModuleJobPortInput,
+  request: {
+    jobId: string;
+    expectedAttempt: number;
+    expectedStatus: string;
+    expectedVersion: string;
+  },
+) {
+  return createHash("sha256")
+    .update(
+      [
+        input.moduleName,
+        input.guardContext.actor.id,
+        request.jobId,
+        request.expectedAttempt,
+        request.expectedStatus,
+        request.expectedVersion,
+      ].join(":"),
+    )
+    .digest("hex");
+}
+
+async function auditUnavailable(input: ModuleJobPortInput, jobId: string) {
+  await input.runtime.auditSink.recordCriticalEvent(
+    auditEvent(input, "access", "denied", jobId),
+  );
+}
+
+async function auditControl(
+  input: ModuleJobPortInput,
+  operation: "cancel" | "recover",
+  outcome: "success" | "failure",
+  snapshot: DurableJobSnapshot,
+  reason: string,
+  result: string,
+) {
+  await input.runtime.auditSink.recordCriticalEvent({
+    ...auditEvent(input, operation, outcome, snapshot.job.id),
+    metadata: {
+      handlerKey: snapshot.job.handlerKey,
+      status: snapshot.job.status,
+      attempt: Math.max(
+        0,
+        ...snapshot.stages.map((stage) => stage.currentAttempt),
+      ),
+      attemptCount: snapshot.attempts.length,
+      failureCount: snapshot.failures.length,
+      failureCode: safeFailureCode(snapshot.failures.at(-1)?.code),
+      recoveryCount: snapshot.recoveries.length,
+      version: snapshot.job.updatedAt,
+      reason,
+      result,
+    },
+  });
+}
+
+function auditEvent(
+  input: ModuleJobPortInput,
+  operation: string,
+  outcome: AuditEvent["outcome"],
+  jobId: string,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action: `module.job.${operation}`,
+    outcome,
+    actor: auditActor(input.guardContext),
+    target: { type: "durable-job", id: jobId },
+    module: input.moduleName,
+    requestId: input.guardContext.requestId,
+    occurredAt: new Date().toISOString(),
+  };
+}

package/template/apps/server/src/module-host/request-context.test.ts

@@ -1,7 +1,16 @@
 import { describe, expect, test } from "bun:test";
-import { buildScopeContext } from "../data-access/context.js";
+import {
+  buildActorScopeContexts,
+  buildScopeContext,
+} from "../data-access/context.js";
 import type { RequestActor } from "../guards.js";
-import { requestActorFromModule, toModuleActor } from "./request-context.js";
+import { createServerRuntime } from "../runtime.js";
+import { manifest } from "./test-fixtures.js";
+import {
+  buildModuleRequestContext,
+  requestActorFromModule,
+  toModuleActor,
+} from "./request-context.js";
 
 describe("模块 Actor 运行时边界", () => {
   test("只下发 SDK 白名单字段并保留宿主内部身份映射", () => {
@@ -63,4 +72,81 @@ describe("模块 Actor 运行时边界", () => {
       }),
     ).toThrow("不是由当前宿主颁发");
   });
+
+  test("模块提交任务时由宿主持久化 Actor 与 nominal Scope 快照", async () => {
+    const submissions: unknown[] = [];
+    const actor: RequestActor = {
+      id: "user-job",
+      type: "user",
+      name: "任务用户",
+      roleCodes: ["operator"],
+      permissionKeys: ["evidence.read"],
+      ...buildActorScopeContexts("user-job", "dept-evidence", [
+        {
+          id: "role-evidence",
+          code: "operator",
+          dataScope: "department",
+          departmentIds: [],
+        },
+      ]),
+    };
+    const context = buildModuleRequestContext({
+      moduleName: "evidence",
+      manifest: manifest("evidence"),
+      guardContext: {
+        requestId: "request-job",
+        actor,
+        startedAt: "2026-07-27T00:00:00.000Z",
+      },
+      params: {},
+      query: {},
+      runtime: createServerRuntime(),
+      jobs: {
+        async get() {
+          return undefined;
+        },
+        async list() {
+          return [];
+        },
+        async submit(input) {
+          submissions.push(input);
+          return {
+            job: {
+              ...input,
+              id: "job-1",
+              queue: input.queue || "default",
+              status: "queued",
+              priority: 0,
+              maxAttempts: 3,
+              timeoutSeconds: 900,
+              availableAt: "2026-07-27T00:00:00.000Z",
+              createdAt: "2026-07-27T00:00:00.000Z",
+              updatedAt: "2026-07-27T00:00:00.000Z",
+            },
+            created: true,
+          };
+        },
+      },
+    });
+
+    await context.jobs.submit({
+      handlerKey: "evidence.parse",
+      idempotencyKey: "parse-1",
+      payload: { evidenceFileId: "evidence-1" },
+    });
+
+    expect(submissions).toEqual([
+      expect.objectContaining({
+        requestedBy: "user-job",
+        queue: "evidence",
+        authorizationScope: {
+          tenantId: "single-tenant",
+          actorId: "user-job",
+          departmentId: "dept-evidence",
+          grants: [{ scope: "department", departmentId: "dept-evidence" }],
+          roleIds: ["role-evidence"],
+        },
+      }),
+    ]);
+  });
 });

package/template/apps/server/src/module-host/request-context.ts

@@ -2,16 +2,18 @@ import { randomUUIDv7 } from "bun";
 import type { DurableJobs } from "@southwind-ai/jobs";
 import type {
   ModuleActor,
+  ModuleAiArtifactPort,
+  ModuleAiOperationPort,
   ModuleAuditEmitInput,
   ModuleAuditEmitter,
-  ModuleJobSubmitter,
   ModuleRequestContext,
   ModuleStoragePort,
   ModuleUserDirectoryPort,
 } from "@southwind-ai/server-sdk";
 import {
+  ModuleAiArtifactError,
+  ModuleAiOperationError,
   ModuleUserDirectoryError,
-  requireModuleNamespace,
 } from "@southwind-ai/server-sdk";
 import type { AuditEvent } from "@southwind-ai/shared";
 import type { ModuleManifest } from "@southwind-ai/modules";
@@ -22,6 +24,10 @@ import {
 } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { unavailableModuleStoragePort } from "./storage-port.js";
+import {
+  createModuleJobPort,
+  type ModuleJobControlRuntime,
+} from "./job-port.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -66,8 +72,12 @@ export interface ModuleRequestContextInput {
   body?: unknown;
   runtime: ServerRuntime;
   jobs?: DurableJobs;
+  jobControl?: ModuleJobControlRuntime;
+  reauthorizeJobs?: () => Promise<boolean>;
   storage?: ModuleStoragePort;
   userDirectory?: ModuleUserDirectoryPort;
+  aiArtifacts?: ModuleAiArtifactPort;
+  aiOperations?: ModuleAiOperationPort;
 }
 
 export function buildModuleRequestContext(
@@ -80,13 +90,56 @@ export function buildModuleRequestContext(
     query: input.query,
     body: input.body,
     audit: createModuleAuditEmitter(input),
-    jobs: createModuleJobSubmitter(input),
+    aiArtifacts:
+      input.aiArtifacts ?? unavailableModuleAiArtifactPort(input.moduleName),
+    aiOperations:
+      input.aiOperations ?? unavailableModuleAiOperationPort(input.moduleName),
+    jobs: createModuleJobPort({
+      moduleName: input.moduleName,
+      guardContext: input.guardContext,
+      runtime: input.runtime,
+      jobs: input.jobs,
+      control: input.jobControl,
+      reauthorize: input.reauthorizeJobs,
+    }),
     storage: input.storage ?? unavailableModuleStoragePort(input.moduleName),
     userDirectory:
       input.userDirectory ?? unavailableModuleUserDirectory(input.moduleName),
   };
 }
 
+function unavailableModuleAiOperationPort(
+  moduleName: string,
+): ModuleAiOperationPort {
+  const unavailable = (): never => {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      `模块 ${moduleName} 的 AI Operation Port 未挂载`,
+    );
+  };
+  return {
+    startAgent: async () => unavailable(),
+    startDocument: async () => unavailable(),
+    startSpeech: async () => unavailable(),
+    embed: async () => unavailable(),
+    result: async () => unavailable(),
+    cancel: async () => unavailable(),
+  };
+}
+
+function unavailableModuleAiArtifactPort(
+  moduleName: string,
+): ModuleAiArtifactPort {
+  return {
+    async issue() {
+      throw new ModuleAiArtifactError(
+        "AI_ARTIFACT_UNAVAILABLE",
+        `模块 ${moduleName} 的 AI Artifact Port 未挂载`,
+      );
+    },
+  };
+}
+
 function unavailableModuleUserDirectory(
   moduleName: string,
 ): ModuleUserDirectoryPort {
@@ -141,22 +194,3 @@ function buildAuditEvent(
     occurredAt: new Date().toISOString(),
   };
 }
-
-function createModuleJobSubmitter(
-  input: ModuleRequestContextInput,
-): ModuleJobSubmitter {
-  return {
-    async submit(job) {
-      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
-      if (!input.jobs) {
-        throw new Error("Durable Jobs 运行时未挂载");
-      }
-      const result = await input.jobs.submit({
-        ...job,
-        queue: input.moduleName,
-        requestedBy: input.guardContext.actor.id,
-      });
-      return { jobId: result.job.id, created: result.created };
-    },
-  };
-}

package/template/apps/server/src/module-host/route-installer.test.ts

@@ -6,6 +6,7 @@ import type {
   ModuleRequestContext,
 } from "@southwind-ai/server-sdk";
 import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
 import type { RequestActor } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
 import { createStorageRuntime } from "../storage/runtime.js";
@@ -241,6 +242,7 @@ async function createFixture(options: FixtureOptions = {}) {
     invoke(method: string, path: string, params = {}, body?: unknown) {
       return app.invoke(method, path, {
         guardContext,
+        request: new Request(`http://localhost${path}`),
         params,
         query: {},
         body,
@@ -258,6 +260,14 @@ function actor(
     name: "测试管理员",
     roleCodes: ["developer"],
     permissionKeys,
+    scopeContext: buildScopeContext("user_admin", undefined, [
+      {
+        id: "developer",
+        code: "developer",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
   };
 }
 

package/template/apps/server/src/module-host/route-installer.ts

@@ -5,6 +5,10 @@ import { forbidden, routeContext } from "../system/route-helpers.js";
 import type { RouteApp } from "../system/route-types.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { InitializedModuleHosts } from "./initialize.js";
+import type {
+  ModuleAiArtifactPort,
+  ModuleAiOperationPort,
+} from "@southwind-ai/server-sdk";
 import { buildModuleRequestContext } from "./request-context.js";
 import {
   createModuleStoragePort,
@@ -15,6 +19,7 @@ import {
   type ModuleUserDirectoryServices,
 } from "./user-directory-port.js";
 import { createModuleStorageScope } from "./storage-scope.js";
+import type { ModuleJobControlRuntime } from "./job-port.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -24,10 +29,21 @@ export interface ModuleRouteInstallContext {
   runtime: ServerRuntime;
   features: readonly FeatureFlagDefinition[];
   jobs?: DurableJobs;
+  jobControl?: ModuleJobControlRuntime;
   /** 平台存储服务；提供后模块获得受限 Upload/BlobRead Port。 */
   storage?: ModuleStorageServices;
   /** 平台身份目录；Adapter 会绑定当前请求 Actor 与服务端数据范围。 */
   userDirectory?: Omit<ModuleUserDirectoryServices, "runtime" | "features">;
+  aiArtifacts?: (
+    moduleName: string,
+    guardContext: ReturnType<typeof routeContext>["guardContext"],
+    signal: AbortSignal,
+  ) => ModuleAiArtifactPort;
+  aiOperations?: (
+    moduleName: string,
+    guardContext: ReturnType<typeof routeContext>["guardContext"],
+    signal: AbortSignal,
+  ) => ModuleAiOperationPort;
 }
 
 /**
@@ -73,7 +89,26 @@ export function installModuleRoutes(
         query: route.query,
         body: route.body,
         runtime: context.runtime,
+        aiArtifacts: context.aiArtifacts?.(
+          moduleName,
+          route.guardContext,
+          route.request.signal,
+        ),
+        aiOperations: context.aiOperations?.(
+          moduleName,
+          route.guardContext,
+          route.request.signal,
+        ),
         jobs: context.jobs,
+        jobControl: context.jobControl,
+        reauthorizeJobs: async () =>
+          (
+            await evaluateRouteGuards(
+              context.runtime,
+              route.guardContext,
+              { permission: binding, feature },
+            )
+          ).allowed,
         storage: context.storage
           ? createModuleStoragePort(context.storage, {
               ...createModuleStorageScope({
@@ -84,7 +119,7 @@ export function installModuleRoutes(
                 guardContext: route.guardContext,
                 runtime: context.runtime,
                 features: context.features,
-                signal: new AbortController().signal,
+                signal: route.request.signal,
               }),
             })
           : undefined,

package/template/apps/server/src/module-host/sandbox-tool-registration.ts

@@ -0,0 +1,42 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleNamespace,
+  type ModuleSandboxToolHost,
+} from "@southwind-ai/server-sdk";
+import type { RegisteredModuleSandboxToolHandler } from "./initialize-contracts.js";
+
+export function createScopedSandboxHost(
+  manifest: ModuleManifest,
+  state: {
+    toolKeys: Set<string>;
+    sandboxToolHandlers: RegisteredModuleSandboxToolHandler[];
+  },
+): ModuleSandboxToolHost {
+  return {
+    moduleName: manifest.name,
+    registerToolHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace(
+          "Sandbox Agent Tool",
+          registration.toolKey,
+          manifest.name,
+        );
+        if (!manifest.tools.some(({ key }) => key === registration.toolKey)) {
+          throw new Error(
+            `Sandbox Agent Tool Handler 未在 Manifest 声明：${registration.toolKey}`,
+          );
+        }
+        if (state.toolKeys.has(registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 重复注册：${registration.toolKey}`,
+          );
+        }
+        state.toolKeys.add(registration.toolKey);
+        state.sandboxToolHandlers.push({
+          moduleName: manifest.name,
+          registration,
+        });
+      }
+    },
+  };
+}