create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/embedding/run-fingerprint.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from "bun:test";
+import { embeddingRunFingerprint } from "./run-fingerprint.js";
+
+test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与 options", async () => {
+  const pin = {
+    key: "embedding.primary",
+    identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+    releaseDigest: `sha256:${"a".repeat(64)}` as const,
+    offersDigest: `sha256:${"b".repeat(64)}` as const,
+  };
+  const first = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-one",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    pin,
+  );
+  const retry = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-two",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    pin,
+  );
+  const changed = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-three",
+          mediaType: "image/png",
+          byteSize: 13,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
+  );
+  const deploymentChanged = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-four",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
+  );
+  expect(retry).toBe(first);
+  expect(changed).not.toBe(first);
+  expect(deploymentChanged).not.toBe(first);
+});

package/template/apps/server/src/embedding/run-fingerprint.ts

@@ -0,0 +1,48 @@
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { EmbeddingRuntimeItem } from "./contracts.js";
+
+export async function embeddingRunFingerprint(
+  operationKey: string,
+  items: readonly EmbeddingRuntimeItem[],
+  options: ModuleAiJsonValue,
+  readinessPin?: AiRuntimeDeploymentV1,
+) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(
+      stableJson({
+        operationKey,
+        items: items.map(stableItem),
+        options,
+        ...(readinessPin ? { readinessPin } : {}),
+      }),
+    ),
+  );
+  return [...new Uint8Array(digest)]
+    .map((item) => item.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function stableItem(item: EmbeddingRuntimeItem) {
+  if ("text" in item) return { id: item.id, text: item.text };
+  return {
+    id: item.id,
+    mediaType: item.source.mediaType,
+    byteSize: item.source.byteSize,
+    sha256: item.source.sha256,
+  };
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/template/apps/server/src/embedding/terminal-observer.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { observeEmbeddingTerminal } from "./terminal-observer.js";
+
+test("终态 events 在失败时触发受信审计，不请求结果向量", async () => {
+  const audited: string[] = [];
+  let resultCalls = 0;
+  await observeEmbeddingTerminal({
+    response: new Response(
+      'data: {"type":"run.started"}\n\ndata: {"type":"run.failed"}\n\n',
+    ),
+    binding: { runId: "embedding_1" } as never,
+    context: {} as never,
+    signal: new AbortController().signal,
+    remote: {
+      async result() {
+        resultCalls += 1;
+        throw new Error("failed run must not fetch result");
+      },
+    } as never,
+    async audit(status) {
+      audited.push(status);
+    },
+  });
+  expect(audited).toEqual(["failed"]);
+  expect(resultCalls).toBe(0);
+});

package/template/apps/server/src/embedding/terminal-observer.ts

@@ -0,0 +1,44 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { EmbeddingRuntimePort } from "./contracts.js";
+import type { EmbeddingRunBinding } from "./run-binding-repository.js";
+
+export async function observeEmbeddingTerminal(input: {
+  response: Response;
+  binding: EmbeddingRunBinding;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  remote: EmbeddingRuntimePort;
+  audit: (
+    status: "completed" | "failed" | "cancelled",
+    result?: Awaited<ReturnType<EmbeddingRuntimePort["result"]>>,
+  ) => Promise<void>;
+}) {
+  try {
+    const terminal = terminalEvent(await input.response.text());
+    if (terminal === "completed") {
+      await input.audit(
+        terminal,
+        await input.remote.result(input.binding.runId!, input.signal),
+      );
+    } else if (terminal) await input.audit(terminal);
+  } catch {
+    // 事件读取或审计不可影响 SSE；下次可信观察会重试未完成的 claim。
+  }
+}
+
+function terminalEvent(
+  value: string,
+): "completed" | "failed" | "cancelled" | undefined {
+  for (const line of value.split("\n")) {
+    if (!line.startsWith("data: ")) continue;
+    try {
+      const event = JSON.parse(line.slice(6)) as { type?: string };
+      if (event.type === "run.completed") return "completed";
+      if (event.type === "run.failed") return "failed";
+      if (event.type === "run.cancelled") return "cancelled";
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}

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

@@ -16,6 +16,10 @@ import { readPositiveInt } from "./runtime-config.js";
 // @windy-module system.agent begin
 import { registerAgentPlatformRuntime } from "./agent/runtime-bootstrap.js";
 import { DeferredAgentBackgroundOperationPortFactory } from "./agent/background-operation-port.js";
+import {
+  projectAiScreenshotIntakeFactoryV1,
+  projectAiScreenshotPageRegistryV2,
+} from "./app/ai-screenshot-intake-binding.js";
 import { resolveCurrentSystemActor } from "./system/actor.js";
 // @windy-module system.agent end
 import { createAuthRuntime } from "./auth/runtime.js";
@@ -38,10 +42,9 @@ import { createPlatformSettingsRuntime } from "./settings/runtime.js";
 import { registerNotificationRoutes } from "./notification/routes.js";
 // @windy-module system.notification end
 // @windy-module system.storage begin
-import { createStorageRuntime } from "./storage/runtime.js";
+import { createStorageHostRuntime } from "./storage/host-runtime.js";
 import { registerStorageRoutes } from "./storage/routes.js";
 // @windy-module system.storage end
-import { validateInstalledRuntime } from "./module-runtime-validation.js";
 import { installModuleHttpRuntime } from "./module-host/http-runtime.js";
 // @windy-module system.search begin
 import { adaptModuleSearchProviders } from "./module-host.js";
@@ -56,15 +59,10 @@ import { createSearchHost } from "./search/host.js";
 import { registerWorkflowRoutes } from "./workflow/routes.js";
 // @windy-module system.workflow end
 import { bootstrapServerModules } from "./module-bootstrap.js";
-import {
-  createHttpObservability,
-  listenPlatformServer,
-  logServerStartup,
-} from "./platform-http-runtime.js";
+import { createHttpObservability } from "./platform-http-runtime.js";
 import { bootstrapPlatformApp } from "./platform-app-bootstrap.js";
 import { createPreparedPlatformBootstrap } from "./startup-preflight.js";
-import { validateCompositionBeforeStartup } from "./startup-composition-validation.js";
-validateCompositionBeforeStartup();
+import { finalizePlatformStartup } from "./startup-finalization.js";
 const { logger, persistence, platformConfig, preparedModules } =
   await createPreparedPlatformBootstrap();
 const {
@@ -126,7 +124,7 @@ const {
   // @windy-module system.audit end
 });
 // @windy-module system.storage begin
-const storageRuntime = createStorageRuntime(
+const { storageRuntime, reportStagingRuntime } = createStorageHostRuntime(
   process.env,
   persistence?.db,
   moduleHosts.uploadPolicies,
@@ -184,6 +182,7 @@ const {
   runtime,
   // @windy-module system.storage begin
   storage: storageRuntime,
+  reportStaging: reportStagingRuntime,
   // @windy-module system.storage end
   moduleTasks: moduleTaskDefinitions,
   // @windy-module system.bulk-data begin
@@ -279,19 +278,22 @@ registerSystemOperationRoutes(app, runtime, features, {
 });
 // @windy-module system.operations end
 // @windy-module system.agent begin
-const { toolHandlers, aiArtifacts, aiOperations } =
-  registerAgentPlatformRuntime({
-    app,
-    platformConfig,
-    modules: foundationModules,
-    hosts: moduleHosts,
-    runtime,
-    systemRepositories,
-    storage: storageRuntime,
-    workflow: workflowService,
-    db: persistence?.db,
-    backgroundAi: moduleBackgroundAi,
-  });
+const agentRuntime = registerAgentPlatformRuntime({
+  app,
+  platformConfig,
+  modules: foundationModules,
+  hosts: moduleHosts,
+  runtime,
+  systemRepositories,
+  storage: storageRuntime,
+  workflow: workflowService,
+  db: persistence?.db,
+  backgroundAi: moduleBackgroundAi,
+  screenshotPageRegistry: platformConfig.enableAI
+    ? projectAiScreenshotPageRegistryV2
+    : undefined,
+});
+const { toolHandlers, aiArtifacts, aiOperations, aiReadiness } = agentRuntime;
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
 registerSchedulerRoutes(app, scheduler, runtime, features);
@@ -308,11 +310,16 @@ installModuleHttpRuntime(moduleHosts, app, {
   // @windy-module system.scheduler end
   // @windy-module system.storage begin
   storage: storageRuntime,
+  reportStaging: reportStagingRuntime,
   // @windy-module system.storage end
   systemRepositories,
   // @windy-module system.agent begin
   aiArtifacts,
   aiOperations,
+  aiReadiness,
+  screenshots: platformConfig.enableAI
+    ? projectAiScreenshotIntakeFactoryV1
+    : undefined,
   // @windy-module system.agent end
   // @windy-module system.data-governance begin
   reauthenticate: (actorId, password) =>
@@ -320,24 +327,24 @@ installModuleHttpRuntime(moduleHosts, app, {
   governedExportService,
   // @windy-module system.data-governance end
 });
-validateInstalledRuntime({
+finalizePlatformStartup({
+  app,
   modules: foundationModules,
-  routes: app.routes,
   // @windy-module system.scheduler begin
   tasks: scheduledTaskDefinitions,
   // @windy-module system.scheduler end
   // @windy-module system.agent begin
   tools: toolHandlers,
+  disposeAgentRuntime: agentRuntime.disposeAgentRuntime,
   // @windy-module system.agent end
   // @windy-module system.search begin
   providers: searchHost.providerKeys,
   // @windy-module system.search end
   hosts: moduleHosts,
-});
-if (!process.argv.includes("--validate-module-composition")) {
-  const port = listenPlatformServer(app);
   // @windy-module system.scheduler begin
-  schedulerWorker.start();
+  schedulerWorker,
   // @windy-module system.scheduler end
-  logServerStartup(logger, featureSync, Boolean(persistence), port);
-}
+  logger,
+  featureSync,
+  persistenceEnabled: Boolean(persistence),
+});

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

@@ -2,6 +2,65 @@ import { describe, expect, test } from "bun:test";
 import { createModuleAiOperationPort } from "./ai-operation-port.js";
 
 describe("Module AI Operation canonical result", () => {
+  test("Speech contract 只从 Manifest 重建 normalize 变体", async () => {
+    let received: unknown;
+    const port = createModuleAiOperationPort(
+      "analysis",
+      {} as never,
+      AbortSignal.timeout(1_000),
+      {
+        modules: [speechModule("normalize")],
+        speechFacade: {
+          async start(...args: unknown[]) {
+            received = args.at(-1);
+            return {
+              runId: "speech-1",
+              status: "accepted",
+              eventsUrl: "/events",
+            };
+          },
+        },
+      } as never,
+    );
+
+    await port.startSpeech({
+      operationKey: "analysis.audio.normalize",
+      source: {} as never,
+      options: { contractVersion: 2, variant: "translate" },
+      idempotencyKey: "speech-1",
+    });
+
+    expect(received).toEqual({ contractVersion: 2, variant: "normalize" });
+  });
+
+  test("Manifest Speech 变体未知时不触达 facade", async () => {
+    let called = false;
+    const port = createModuleAiOperationPort(
+      "analysis",
+      {} as never,
+      AbortSignal.timeout(1_000),
+      {
+        modules: [speechModule("forged")],
+        speechFacade: {
+          async start() {
+            called = true;
+            throw new Error("unreachable");
+          },
+        },
+      } as never,
+    );
+
+    await expect(
+      port.startSpeech({
+        operationKey: "analysis.audio.normalize",
+        source: {} as never,
+        options: {},
+        idempotencyKey: "speech-1",
+      }),
+    ).rejects.toMatchObject({ code: "AI_OPERATION_UNAVAILABLE" });
+    expect(called).toBe(false);
+  });
+
   test("只把尚未完成的 RUN_CONFLICT 映射为 pending", async () => {
     const port = agentPort(() =>
       Response.json(
@@ -50,6 +109,19 @@ describe("Module AI Operation canonical result", () => {
   });
 });
 
+function speechModule(variant: string) {
+  return {
+    name: "analysis",
+    aiOperations: [
+      {
+        key: "analysis.audio.normalize",
+        kind: "speech",
+        readiness: { contractVersion: 1, variant },
+      },
+    ],
+  } as never;
+}
+
 function agentPort(result: () => Response) {
   return createModuleAiOperationPort(
     "analysis",

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

@@ -1,4 +1,8 @@
 // @windy-module system.agent begin
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
 import type {
   ModuleAiJsonValue,
   ModuleAiOperationPort,
@@ -21,6 +25,7 @@ export interface ModuleAiRuntimeServices {
   readonly speechFacade: SpeechRunFacade;
   readonly speechRemote: SpeechRuntimePort;
   readonly embeddingFacade: EmbeddingFacade;
+  readonly modules: readonly ModuleManifest[];
 }
 
 export function createModuleAiOperationPort(
@@ -71,6 +76,11 @@ export function createModuleAiOperationPort(
     },
     async startSpeech(input) {
       own(input.operationKey);
+      const definition = ownSpeechDefinition(
+        services.modules,
+        moduleName,
+        input.operationKey,
+      );
       return services.speechFacade.start(
         input.operationKey,
         input.source,
@@ -78,6 +88,7 @@ export function createModuleAiOperationPort(
         input.idempotencyKey,
         context,
         signal,
+        speechContract(definition),
       );
     },
     async embed(input) {
@@ -106,7 +117,7 @@ export function createModuleAiOperationPort(
         );
       }
       if (input.kind === "document") {
-        services.documentFacade.authorizeRun(input.runId, context);
+        await services.documentFacade.authorizeRun(input.runId, context);
         return responseJson(
           await services.documentRemote.result(input.runId, signal),
         );
@@ -131,10 +142,10 @@ export function createModuleAiOperationPort(
           signal,
         );
       } else if (input.kind === "document") {
-        services.documentFacade.authorizeRun(input.runId, context);
-        response = await services.documentRemote.cancel(
+        response = await services.documentFacade.cancel(
           input.runId,
           input.reason,
+          context,
           signal,
         );
       } else {
@@ -150,6 +161,38 @@ export function createModuleAiOperationPort(
   };
 }
 
+function ownSpeechDefinition(
+  modules: readonly ModuleManifest[],
+  moduleName: string,
+  operationKey: string,
+): ModuleAiOperationDefinition {
+  const definition = modules
+    .find((module) => module.name === moduleName)
+    ?.aiOperations?.find((operation) => operation.key === operationKey);
+  if (!definition || definition.kind !== "speech") {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      "Speech Operation 当前不可用",
+    );
+  }
+  return definition;
+}
+
+function speechContract(definition: ModuleAiOperationDefinition) {
+  const variant = definition.readiness?.variant;
+  if (!variant) return {};
+  if (!["normalize", "transcribe", "translate"].includes(variant)) {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      "Speech Operation contract 当前不可用",
+    );
+  }
+  return {
+    contractVersion: 2 as const,
+    variant: variant as "normalize" | "transcribe" | "translate",
+  };
+}
+
 async function responseJson(response: Response): Promise<ModuleAiJsonValue> {
   if (!response.ok) throw await responseError(response);
   return jsonValue(await response.json());