create-windy 0.3.2 → 0.3.5

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

@@ -1,6 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { DurableHandlerRegistry } from "@southwind-ai/jobs";
-import type { ModuleInitializer } from "@southwind-ai/server-sdk";
+import type {
+  ModuleInitializer,
+  ModuleSandboxToolHost,
+} from "@southwind-ai/server-sdk";
 import { initializeModuleHosts } from "./initialize.js";
 import { manifest } from "./test-fixtures.js";
 
@@ -171,6 +174,51 @@ describe("模块 Host 初始化", () => {
       }),
     ).rejects.toThrow("AI Operation Handler 未在 Manifest 声明");
   });
+
+  test("Sandbox Tool 与同进程 Handler 互斥注册", async () => {
+    const tool = {
+      key: "known.safe.echo",
+      label: "安全回显",
+      description: "回显最小输入。",
+      inputSchemaKey: "known.input.v1",
+      outputSchemaKey: "known.output.v1",
+      operation: "query" as const,
+      permissionKey: "known.safe.read",
+      featureKey: "known.safe",
+      auditAction: "known.safe.execute",
+      scopeMode: "request" as const,
+      dataClassification: "internal" as const,
+      idempotency: "supported" as const,
+      approval: "none" as const,
+      limits: {
+        maxDurationSeconds: 5,
+        maxInputBytes: 4096,
+        maxOutputBytes: 4096,
+      },
+    };
+    const known = manifest("known", { tools: [tool] });
+    const installation = {
+      manifest: known,
+      setup() {},
+      setupSandbox(host: ModuleSandboxToolHost) {
+        host.registerToolHandlers([
+          { toolKey: tool.key, execute: (input) => input },
+        ]);
+      },
+    };
+
+    const initialized = await initializeModuleHosts({
+      modules: [known],
+      installations: [installation],
+    });
+
+    expect(
+      initialized.sandboxToolHandlers.map(
+        ({ registration }) => registration.toolKey,
+      ),
+    ).toEqual([tool.key]);
+    expect(initialized.toolHandlers).toEqual([]);
+  });
 });
 
 function initializer(

package/template/apps/server/src/module-host/initialize.ts

@@ -1,7 +1,4 @@
-import {
-  DurableHandlerRegistry,
-  type DurableHandlerDefinition,
-} from "@southwind-ai/jobs";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import {
   requireModuleNamespace,
@@ -13,25 +10,32 @@ import type {
   InitializedModuleHosts,
   InitializeModuleHostsInput,
   RegisteredModuleAiOperationHandler,
+  RegisteredModuleGovernedResource,
   RegisteredModuleRolePreset,
   RegisteredModuleRoute,
   RegisteredModuleSearchProvider,
+  RegisteredModuleSandboxToolHandler,
   RegisteredModuleTaskHandler,
   RegisteredModuleToolHandler,
 } from "./initialize-contracts.js";
+import { registerModuleDurableHandler } from "./durable-handler-registration.js";
+import { registerGovernedResources } from "./governed-resources.js";
 import {
   registerResourceFileAccessPolicies,
   validateResourceFileAccessPurposes,
 } from "./resource-file-policies.js";
 import { validateRouteDeclaration } from "./route-declaration.js";
+import { createScopedSandboxHost } from "./sandbox-tool-registration.js";
 
 export type {
   InitializedModuleHosts,
   InitializeModuleHostsInput,
   RegisteredModuleAiOperationHandler,
+  RegisteredModuleGovernedResource,
   RegisteredModuleRolePreset,
   RegisteredModuleRoute,
   RegisteredModuleSearchProvider,
+  RegisteredModuleSandboxToolHandler,
   RegisteredModuleTaskHandler,
   RegisteredModuleToolHandler,
 } from "./initialize-contracts.js";
@@ -74,9 +78,12 @@ export async function initializeModuleHosts(
     taskHandlers: [],
     taskKeys: new Set<string>(),
     toolHandlers: [],
+    sandboxToolHandlers: [],
     toolKeys: new Set<string>(),
     aiOperationHandlers: [],
     aiOperationKeys: new Set<string>(),
+    governedResources: [],
+    governedResourceKeys: new Set<string>(),
     rolePresets: [],
     rolePresetKeys: new Set<string>(),
     searchProviders: [],
@@ -88,12 +95,14 @@ export async function initializeModuleHosts(
       moduleName: installation.manifest.name.trim(),
       manifest: installation.manifest,
       setup: installation.setup,
+      setupSandbox: installation.setupSandbox,
       legacy: false,
     })),
     ...(input.initializers ?? []).map((initializer) => ({
       moduleName: initializer.moduleName.trim(),
       manifest: undefined,
       setup: initializer.initialize,
+      setupSandbox: undefined,
       legacy: true,
     })),
   ];
@@ -117,6 +126,9 @@ export async function initializeModuleHosts(
       );
     }
     await installation.setup(createScopedHost(manifest, state));
+    if (installation.setupSandbox) {
+      await installation.setupSandbox(createScopedSandboxHost(manifest, state));
+    }
   }
   validateResourceFileAccessPurposes(state);
 
@@ -127,7 +139,9 @@ export async function initializeModuleHosts(
     routes: [...state.routes],
     taskHandlers: [...state.taskHandlers],
     toolHandlers: [...state.toolHandlers],
+    sandboxToolHandlers: [...state.sandboxToolHandlers],
     aiOperationHandlers: [...state.aiOperationHandlers],
+    governedResources: [...state.governedResources],
     rolePresets: [...state.rolePresets],
     searchProviders: [...state.searchProviders],
     manifestOf(moduleName) {
@@ -165,9 +179,12 @@ interface HostCollections {
   taskHandlers: RegisteredModuleTaskHandler[];
   taskKeys: Set<string>;
   toolHandlers: RegisteredModuleToolHandler[];
+  sandboxToolHandlers: RegisteredModuleSandboxToolHandler[];
   toolKeys: Set<string>;
   aiOperationHandlers: RegisteredModuleAiOperationHandler[];
   aiOperationKeys: Set<string>;
+  governedResources: RegisteredModuleGovernedResource[];
+  governedResourceKeys: Set<string>;
   rolePresets: RegisteredModuleRolePreset[];
   rolePresetKeys: Set<string>;
   searchProviders: RegisteredModuleSearchProvider[];
@@ -196,15 +213,12 @@ function createScopedHost(
     registerResourceFileAccessPolicies(policies) {
       registerResourceFileAccessPolicies(manifest, state, policies);
     },
-    registerDurableHandler<T>(definition: DurableHandlerDefinition<T>) {
+    registerDurableHandler(definition) {
       requireModuleNamespace("任务 handler", definition.key, moduleName);
-      if (state.handlerKeys.has(definition.key)) {
-        throw new Error(`任务 handler 重复注册：${definition.key}`);
-      }
-      state.handlerKeys.add(definition.key);
-      state.handlerInstallers.push((registry) => {
-        registry.register(definition);
-      });
+      registerModuleDurableHandler(moduleName, state, definition);
+    },
+    registerGovernedResources(registrations) {
+      registerGovernedResources(manifest, state, registrations);
     },
     registerRoutes(routes) {
       for (const definition of routes) {
@@ -261,13 +275,22 @@ function createScopedHost(
           registration.operationKey,
           moduleName,
         );
+        const operation = manifest.aiOperations?.find(
+          ({ key }) => key === registration.operationKey,
+        );
+        if (!operation) {
+          throw new Error(
+            `AI Operation Handler 未在 Manifest 声明：${registration.operationKey}`,
+          );
+        }
         if (
-          !manifest.aiOperations?.some(
-            ({ key }) => key === registration.operationKey,
-          )
+          (operation.kind === "agent" && !registration.prepare) ||
+          (operation.kind === "document" && !registration.prepareDocument) ||
+          (operation.kind === "speech" && !registration.prepareSpeech) ||
+          (operation.kind === "embedding" && !registration.prepareEmbedding)
         ) {
           throw new Error(
-            `AI Operation Handler 未在 Manifest 声明：${registration.operationKey}`,
+            `AI Operation Handler 与 kind 不匹配：${registration.operationKey}`,
           );
         }
         if (state.aiOperationKeys.has(registration.operationKey)) {

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

@@ -0,0 +1,262 @@
+import { describe, expect, test } from "bun:test";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { InMemoryDurableExecutionRepository } from "../jobs/in-memory-execution.js";
+import { DurableJobService } from "../jobs/service.js";
+import { DurableJobWorker } from "../jobs/worker.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleJobPort } from "./job-port.js";
+
+const now = new Date("2026-07-27T08:00:00.000Z");
+
+describe("Module Durable Job 受限控制 Port", () => {
+  test("最小投影限制在当前 Module、Actor、Scope 与当前授权", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "analysis-1",
+      payload: { privateTranscript: "不得返回" },
+    });
+
+    expect(await fixture.port.get(submitted.jobId)).toEqual(
+      expect.objectContaining({
+        jobId: submitted.jobId,
+        handlerKey: "evidence.analyze",
+        status: "queued",
+        attempt: 0,
+        canCancel: true,
+      }),
+    );
+    expect(
+      JSON.stringify(await fixture.port.get(submitted.jobId)),
+    ).not.toContain("privateTranscript");
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        moduleName: "other",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        actorId: "actor-b",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    await expect(
+      createFixture({
+        facts: fixture.repository,
+        actorId: "actor-b",
+      }).port.cancel({
+        jobId: submitted.jobId,
+        reason: "尝试取消其他操作者任务",
+      }),
+    ).rejects.toMatchObject({ code: "JOB_NOT_AVAILABLE" });
+    await expect(
+      fixture.port.cancel({
+        jobId: "missing-job",
+        reason: "尝试取消不存在的任务",
+      }),
+    ).rejects.toMatchObject({ code: "JOB_NOT_AVAILABLE" });
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        departmentId: "dept-b",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    fixture.authorized.value = false;
+    expect(await fixture.port.get(submitted.jobId)).toBeUndefined();
+  });
+
+  test("取消使用 CAS、重复调用幂等并将脱敏原因写入关键审计", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "cancel-1",
+      payload: {},
+    });
+    const view = await fixture.port.get(submitted.jobId);
+    if (!view) throw new Error("任务未创建");
+
+    const cancelled = await fixture.port.cancel({
+      jobId: view.jobId,
+      reason: "申请人 test@example.com 要求停止 13800138000",
+      expectedStatus: view.status,
+      expectedVersion: view.version,
+    });
+    expect(cancelled.status).toBe("cancelled");
+    expect(
+      await fixture.port.cancel({
+        jobId: view.jobId,
+        reason: "申请人 test@example.com 要求停止 13800138000",
+        expectedStatus: view.status,
+        expectedVersion: view.version,
+      }),
+    ).toMatchObject({ status: "cancelled" });
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "module.job.cancel",
+        outcome: "success",
+        metadata: expect.objectContaining({
+          reason: "申请人 [邮箱] 要求停止 [号码]",
+        }),
+      }),
+    );
+  });
+
+  test("运行中取消立即传播 AbortSignal 并阻止成功完成", async () => {
+    const registry = new DurableHandlerRegistry();
+    let started: () => void = () => {};
+    const startedPromise = new Promise<void>((resolve) => {
+      started = () => resolve();
+    });
+    let observedReason: unknown;
+    registry.register(
+      {
+        key: "evidence.analyze",
+        payload: { parse: (value) => value as Record<string, unknown> },
+        execute: async (_, context) => {
+          started();
+          await new Promise<void>((_, reject) => {
+            context.signal.addEventListener(
+              "abort",
+              () => {
+                observedReason = context.signal.reason;
+                reject(new Error("aborted"));
+              },
+              { once: true },
+            );
+          });
+        },
+      },
+      { moduleName: "evidence" },
+    );
+    const fixture = createFixture({ registry });
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "running-cancel-1",
+      payload: {},
+      maxAttempts: 1,
+    });
+    const running = fixture.worker.runNext("evidence", "worker-1");
+    await startedPromise;
+    const view = await fixture.port.get(submitted.jobId);
+    if (!view) throw new Error("运行中任务不可见");
+    await fixture.port.cancel({
+      jobId: view.jobId,
+      reason: "人工确认停止后台研判",
+      expectedStatus: view.status,
+      expectedVersion: view.version,
+    });
+
+    expect(await running).toEqual({
+      status: "cancelled",
+      jobId: submitted.jobId,
+    });
+    expect(observedReason).toBe("cancelled");
+    expect((await fixture.facts.get(submitted.jobId))?.job.status).toBe(
+      "cancelled",
+    );
+  });
+
+  test("人工恢复以 attempt/status/version CAS 保留失败与恢复事实", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "recover-1",
+      payload: {},
+      maxAttempts: 1,
+    });
+    const claim = await fixture.repository.claim({
+      queue: "evidence",
+      workerId: "worker-1",
+      now,
+      leaseDurationMs: 30_000,
+    });
+    if (!claim) throw new Error("任务未领取");
+    await fixture.repository.fail(
+      claim,
+      { code: "MODEL_UNAVAILABLE", message: "模型不可用", retryable: false },
+      now,
+    );
+    const failed = await fixture.port.get(submitted.jobId);
+    if (!failed) throw new Error("失败任务不可见");
+    const request = {
+      jobId: failed.jobId,
+      reason: "人工确认依赖已经恢复",
+      expectedAttempt: failed.attempt,
+      expectedStatus: failed.status,
+      expectedVersion: failed.version,
+    } as const;
+
+    const recovered = await Promise.all([
+      fixture.port.recover(request),
+      fixture.port.recover(request),
+    ]);
+    expect(recovered).toEqual([
+      expect.objectContaining({ status: "queued", attempt: 1 }),
+      expect.objectContaining({ status: "queued", attempt: 1 }),
+    ]);
+    expect(await fixture.facts.get(submitted.jobId)).toMatchObject({
+      attempts: [{ status: "failed" }],
+      failures: [{ code: "MODEL_UNAVAILABLE" }],
+      recoveries: [
+        expect.objectContaining({
+          fromStatus: "failed",
+          reason: "人工确认依赖已经恢复",
+        }),
+      ],
+    });
+  });
+});
+
+function createFixture(
+  options: {
+    facts?: InMemoryDurableExecutionRepository;
+    registry?: DurableHandlerRegistry;
+    moduleName?: string;
+    actorId?: string;
+    departmentId?: string;
+  } = {},
+) {
+  const moduleName = options.moduleName || "evidence";
+  const actorId = options.actorId || "actor-a";
+  const departmentId = options.departmentId || "dept-a";
+  const repository = options.facts || new InMemoryDurableExecutionRepository();
+  const facts = new DurableJobService(repository, () => now);
+  const worker = new DurableJobWorker(
+    repository,
+    options.registry || new DurableHandlerRegistry(),
+    { now: () => now, leaseDurationMs: 60_000 },
+  );
+  const actor: RequestActor = {
+    id: actorId,
+    type: "user",
+    name: actorId,
+    roleCodes: ["analyst"],
+    permissionKeys: [`${moduleName}.analysis.manage`],
+    ...buildActorScopeContexts(actorId, departmentId, [
+      {
+        id: "role-analyst",
+        code: "analyst",
+        dataScope: "department",
+        departmentIds: [],
+      },
+    ]),
+  };
+  const runtime = createServerRuntime();
+  const authorized = { value: true };
+  const port = createModuleJobPort({
+    moduleName,
+    guardContext: {
+      requestId: `request-${actorId}`,
+      actor,
+      startedAt: now.toISOString(),
+    },
+    runtime,
+    jobs: facts,
+    control: { worker },
+    reauthorize: async () => authorized.value,
+  });
+  return { port, facts, repository, worker, runtime, authorized };
+}