create-windy 0.6.0 → 0.6.2

package/template/apps/server/src/agent/screenshot-intake-v2.ts

@@ -31,9 +31,9 @@ import {
   bindingForScreenshot,
   assertScreenshotOperation,
   assertScreenshotProducerPlan,
+  canReserveScreenshot,
   sameScreenshotArtifact,
   sameScreenshotBinding,
-  sameScreenshotDeployment,
   screenshotModuleName,
   screenshotPurpose,
 } from "./screenshot-intake-v2-validation.js";
@@ -42,8 +42,6 @@ const MAX_ENTRIES = 1_024;
 const MAX_TTL_MS = 60_000;
 const SWEEP_INTERVAL_MS = 10_000;
 
-export type { ProjectAiScreenshotIntakeFactoryV2 } from "./screenshot-intake-durable.js";
-
 export class ScreenshotIntakeRuntimeV2 {
   readonly #records = new Map<string, ScreenshotIntakeRecordV2>();
   readonly #sweeper: ReturnType<typeof setInterval>;
@@ -211,6 +209,7 @@ export class ScreenshotIntakeRuntimeV2 {
     token: string,
     operationKey: string,
     deployment: AiRuntimeDeploymentV1 | undefined,
+    expectedContextDigest: string | null | undefined,
     context: RequestGuardContext,
     signal: AbortSignal = AbortSignal.timeout(10_000),
   ): Promise<{
@@ -226,13 +225,12 @@ export class ScreenshotIntakeRuntimeV2 {
       context,
     );
     if (
-      !record.artifact ||
-      (!record.durable && record.state !== "uploaded") ||
-      (record.durable &&
-        !["uploaded", "reserving", "bound"].includes(record.state)) ||
-      record.operationKey !== operationKey ||
-      !deployment ||
-      !sameScreenshotDeployment(record.deployment, deployment)
+      !canReserveScreenshot(
+        record,
+        operationKey,
+        deployment,
+        expectedContextDigest,
+      )
     ) {
       await this.cancel(record);
       throw unavailable();

package/template/apps/server/src/agent/screenshot-run-binding.ts

@@ -1,9 +1,12 @@
 import type {
   AiRuntimeDeploymentV1,
   ModuleAiArtifactRef,
+  ModuleAiJsonValue,
 } from "@southwind-ai/server-sdk";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
 import type { RequestGuardContext } from "../guards.js";
 import { AgentRunFacadeError } from "./run-errors.js";
+import { expectedScreenshotContextDigest } from "./screenshot-context-attestation.js";
 import type { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
 
 export interface ScreenshotRunBinding {
@@ -15,14 +18,26 @@ export interface ScreenshotRunBinding {
 export async function reserveScreenshotForRun(
   intake: ScreenshotIntakeRuntimeV2 | undefined,
   token: string | undefined,
-  operationKey: string,
+  definition: ModuleAiOperationDefinition,
+  input: ModuleAiJsonValue,
   deployment: AiRuntimeDeploymentV1 | undefined,
   context: RequestGuardContext,
   signal: AbortSignal,
 ): Promise<ScreenshotRunBinding | undefined> {
   if (!token) return undefined;
   if (!intake) throw unavailable();
-  return await intake.reserve(token, operationKey, deployment, context, signal);
+  const contextDigest = await expectedScreenshotContextDigest(
+    definition,
+    input,
+  );
+  return await intake.reserve(
+    token,
+    definition.key,
+    deployment,
+    contextDigest,
+    context,
+    signal,
+  );
 }
 
 function unavailable(): AgentRunFacadeError {

package/template/apps/server/src/agent/vision-readiness-pin.ts

@@ -1,19 +1,15 @@
+import type { AiRuntimeDeploymentV1 } from "@southwind-ai/server-sdk";
 import {
-  parseAiRuntimeReadinessV1,
-  type AiRuntimeDeploymentV1,
-} from "@southwind-ai/server-sdk";
+  assertAiRuntimeReadinessPin,
+  sameAiRuntimeDeployment,
+} from "../ai-runtime-readiness/deployment-pin.js";
 import { AgentRuntimeError } from "./run-contracts.js";
 
 export function sameVisionReadinessDeployment(
   actual: AiRuntimeDeploymentV1,
   expected: AiRuntimeDeploymentV1,
 ): boolean {
-  return (
-    actual.key === expected.key &&
-    actual.identity === expected.identity &&
-    actual.releaseDigest === expected.releaseDigest &&
-    actual.offersDigest === expected.offersDigest
-  );
+  return sameAiRuntimeDeployment(actual, expected);
 }
 
 export function unavailableVisionReadiness(): AgentRuntimeError {
@@ -28,47 +24,9 @@ export async function assertVisionReadinessPin(
   expected: AiRuntimeDeploymentV1,
   health: () => Promise<Response>,
 ): Promise<void> {
-  const response = await boundedHealth(health);
-  if (response.status !== 200) throw unavailableVisionReadiness();
-  if (!response.headers.get("content-type")?.includes("application/json")) {
-    throw unavailableVisionReadiness();
-  }
-  const length = Number(response.headers.get("content-length") ?? "0");
-  if (!Number.isSafeInteger(length) || length < 0 || length > 64 * 1_024) {
-    throw unavailableVisionReadiness();
-  }
-  let snapshot: unknown;
   try {
-    const text = await response.text();
-    if (new TextEncoder().encode(text).byteLength > 64 * 1_024) {
-      throw new Error("health body too large");
-    }
-    snapshot = JSON.parse(text);
+    await assertAiRuntimeReadinessPin(expected, health);
   } catch {
     throw unavailableVisionReadiness();
   }
-  const parsed = parseAiRuntimeReadinessV1(snapshot, new Date().toISOString());
-  if (
-    !parsed.ok ||
-    parsed.value.status !== "ready" ||
-    !sameVisionReadinessDeployment(parsed.value.deployment, expected)
-  ) {
-    throw unavailableVisionReadiness();
-  }
-}
-
-async function boundedHealth(
-  health: () => Promise<Response>,
-): Promise<Response> {
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      health(),
-      new Promise<Response>((_, reject) => {
-        timeout = setTimeout(() => reject(unavailableVisionReadiness()), 5_000);
-      }),
-    ]);
-  } finally {
-    if (timeout) clearTimeout(timeout);
-  }
 }

package/template/apps/server/src/ai-runtime-readiness/deployment-pin.ts

@@ -0,0 +1,69 @@
+import {
+  parseAiRuntimeReadinessV1,
+  type AiRuntimeDeploymentV1,
+} from "@southwind-ai/server-sdk";
+
+export function sameAiRuntimeDeployment(
+  actual: AiRuntimeDeploymentV1,
+  expected: AiRuntimeDeploymentV1,
+): boolean {
+  return (
+    actual.key === expected.key &&
+    actual.identity === expected.identity &&
+    actual.releaseDigest === expected.releaseDigest &&
+    actual.offersDigest === expected.offersDigest
+  );
+}
+
+export async function assertAiRuntimeReadinessPin(
+  expected: AiRuntimeDeploymentV1,
+  health: () => Promise<Response>,
+): Promise<void> {
+  const response = await boundedHealth(health);
+  if (response.status !== 200) throw unavailable();
+  if (!response.headers.get("content-type")?.includes("application/json")) {
+    throw unavailable();
+  }
+  const length = Number(response.headers.get("content-length") ?? "0");
+  if (!Number.isSafeInteger(length) || length < 0 || length > 64 * 1_024) {
+    throw unavailable();
+  }
+  let snapshot: unknown;
+  try {
+    const text = await response.text();
+    if (new TextEncoder().encode(text).byteLength > 64 * 1_024) {
+      throw new Error("health body too large");
+    }
+    snapshot = JSON.parse(text);
+  } catch {
+    throw unavailable();
+  }
+  const parsed = parseAiRuntimeReadinessV1(snapshot, new Date().toISOString());
+  if (
+    !parsed.ok ||
+    parsed.value.status !== "ready" ||
+    !sameAiRuntimeDeployment(parsed.value.deployment, expected)
+  ) {
+    throw unavailable();
+  }
+}
+
+async function boundedHealth(
+  health: () => Promise<Response>,
+): Promise<Response> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      health(),
+      new Promise<Response>((_, reject) => {
+        timeout = setTimeout(() => reject(unavailable()), 5_000);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function unavailable(): Error {
+  return new Error("AI Runtime readiness pin mismatch");
+}

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

@@ -4,7 +4,10 @@ import type {
   AiProviderDataPolicy,
   AiProviderEgressPolicy,
 } from "@southwind-ai/modules";
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
 
 export type EmbeddingRuntimeItem =
   | { readonly id: string; readonly text: string }
@@ -36,6 +39,8 @@ export interface EmbeddingRuntimeOperation {
   };
   readonly providerEgress: AiProviderEgressPolicy;
   readonly providerDataPolicy?: AiProviderDataPolicy;
+  /** Host-projected immutable deployment facts; never supplied by a Module. */
+  readonly readinessPin?: AiRuntimeDeploymentV1;
 }
 
 export interface EmbeddingBatchResponse {

package/template/apps/server/src/embedding/facade-readiness.test.ts

@@ -0,0 +1,307 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+  ModuleAiOperationReadinessV1,
+} from "@southwind-ai/server-sdk";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import type { EmbeddingRuntimeOperation } from "./contracts.js";
+import { EmbeddingFacade } from "./facade.js";
+
+const operationKey = "analysis.embedding.image";
+const deployment: AiRuntimeDeploymentV1 = {
+  key: "embedding.primary",
+  identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+  releaseDigest: `sha256:${"a".repeat(64)}`,
+  offersDigest: `sha256:${"b".repeat(64)}`,
+};
+
+describe("EmbeddingFacade readiness admission", () => {
+  test("unavailable 与 probe 异常在业务 prepare、Artifact、Run 前稳定失败关闭", async () => {
+    for (const inspect of [
+      async () => unavailableProjection(),
+      async () => {
+        throw new Error("provider secret");
+      },
+    ]) {
+      const fixture = await createFixture(true, inspect);
+
+      await expect(fixture.start()).rejects.toMatchObject({
+        code: "RUNTIME_UNAVAILABLE",
+        message: "Embedding Runtime 当前不可用",
+        status: 503,
+      });
+      expect(fixture.calls).toEqual({
+        readiness: 1,
+        prepare: 0,
+        artifact: 0,
+        run: 0,
+        remote: 0,
+      });
+    }
+  });
+
+  test("ready projection 固定 deployment pin 后才创建 Artifact 与 Run", async () => {
+    const fixture = await createFixture(true, async () => readyProjection());
+
+    await expect(fixture.start()).resolves.toMatchObject({
+      runId: "embedding_server_bound",
+      status: "accepted",
+    });
+    expect(fixture.calls).toEqual({
+      readiness: 1,
+      prepare: 1,
+      artifact: 1,
+      run: 1,
+      remote: 1,
+    });
+    expect(fixture.request?.readinessPin).toEqual(deployment);
+  });
+
+  test("未声明 readiness 的旧 Operation 保留兼容路径", async () => {
+    const fixture = await createFixture(false, async () => {
+      throw new Error("legacy operation must not inspect V1");
+    });
+
+    await expect(fixture.start()).resolves.toMatchObject({
+      runId: "embedding_server_bound",
+    });
+    expect(fixture.calls.readiness).toBe(0);
+    expect(fixture.request?.readinessPin).toBeUndefined();
+  });
+});
+
+async function createFixture(
+  withReadiness: boolean,
+  inspect: () => Promise<ModuleAiOperationReadinessV1>,
+) {
+  const module = embeddingModule(withReadiness);
+  const calls = { readiness: 0, prepare: 0, artifact: 0, run: 0, remote: 0 };
+  let request: EmbeddingRuntimeOperation | undefined;
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            {
+              operationKey,
+              prepareEmbedding: (input: ModuleAiJsonValue) => {
+                calls.prepare += 1;
+                return { options: input };
+              },
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const facade = new EmbeddingFacade(
+    [module],
+    hosts,
+    createServerRuntime({}, { featureCatalog: module.features }),
+    {
+      async start(value: EmbeddingRuntimeOperation) {
+        calls.remote += 1;
+        request = value;
+        return { runId: "embedding_server_bound" };
+      },
+    } as never,
+    {
+      async rotate() {
+        calls.artifact += 1;
+        return artifact("rotated");
+      },
+    } as never,
+    {
+      async issue() {
+        calls.run += 1;
+        return { runId: "embedding_server_bound" };
+      },
+      async bind() {},
+    } as never,
+    {
+      async inspect() {
+        calls.readiness += 1;
+        return inspect();
+      },
+    },
+  );
+  return {
+    calls,
+    get request() {
+      return request;
+    },
+    start: () =>
+      facade.start(
+        operationKey,
+        [{ id: "image", source: artifact("submitted") }],
+        {},
+        "embedding-1",
+        guardContext(),
+        AbortSignal.timeout(1_000),
+      ),
+  };
+}
+
+function embeddingModule(withReadiness: boolean): ModuleManifest {
+  return {
+    name: "analysis",
+    version: "0.1.0",
+    label: "分析",
+    description: "分析",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "analysis.embedding.execute",
+        label: "向量化",
+        module: "analysis",
+        moduleLabel: "分析",
+        resource: "embedding",
+        resourceLabel: "向量化",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("analysis.embedding"),
+        label: "向量化",
+        module: "analysis",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      { key: "analysis.embedding.input.v1", schema: { type: "object" } },
+      { key: "analysis.embedding.output.v1", schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: operationKey,
+        kind: "embedding",
+        featureKey: "analysis.embedding",
+        permissionKey: "analysis.embedding.execute",
+        auditAction: "analysis.embedding.execute",
+        inputSchemaKey: "analysis.embedding.input.v1",
+        outputSchemaKey: "analysis.embedding.output.v1",
+        inputModalities: ["image"],
+        ...(withReadiness
+          ? {
+              readiness: {
+                contractVersion: 1 as const,
+                variant: "image",
+                inputModalities: ["image"] as const,
+                outputModalities: ["embedding"] as const,
+                expectedDeployment: deployment,
+                minConcurrentRuns: 1,
+                minQueueDepth: 0,
+              },
+            }
+          : {}),
+        requiredCapabilities: ["embedding.image"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "background",
+        providerEgress: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["analysis.embedding.execute"],
+  };
+}
+
+function guardContext() {
+  return createRequestGuardContext(new Request("http://localhost"), {
+    resolveActor: () => ({
+      id: "actor-1",
+      type: "user",
+      name: "测试用户",
+      roleCodes: ["analyst"],
+      permissionKeys: ["analysis.embedding.execute"],
+      scopeContext: buildScopeContext("actor-1", undefined, [
+        {
+          id: "analyst",
+          code: "analyst",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    }),
+    resolveLicense: () => ({ status: "valid" }),
+  });
+}
+
+function artifact(value: string) {
+  return {
+    value,
+    mediaType: "image/png",
+    byteSize: 128,
+    sha256: "c".repeat(64),
+    expiresAt: "2030-01-01T00:00:00.000Z",
+  };
+}
+
+function readyProjection(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "embedding",
+    observedAt: new Date().toISOString(),
+    status: "ready",
+    validUntil: new Date(Date.now() + 60_000).toISOString(),
+    deployment,
+    offers: [
+      {
+        variant: "image",
+        capabilities: ["embedding.image"],
+        inputModalities: ["image"],
+        outputModalities: ["embedding"],
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+          maxConcurrentRuns: 1,
+          maxQueueDepth: 0,
+        },
+      },
+    ],
+    unavailableReasons: [],
+  };
+}
+
+function unavailableProjection(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "embedding",
+    observedAt: new Date().toISOString(),
+    status: "unavailable",
+    deployment: null,
+    offers: [],
+    unavailableReasons: [{ code: "DOWNSTREAM_PROBE_FAILED", retryable: true }],
+  };
+}

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

@@ -31,10 +31,10 @@ import {
   embeddingErrorStatus,
   type RegisteredEmbeddingOperation,
 } from "./facade-types.js";
+import { type ReadinessPort, requireReadiness } from "./readiness-admission.js";
 
 export class EmbeddingFacade {
   readonly #operations: Map<string, RegisteredEmbeddingOperation>;
-
   constructor(
     modules: readonly ModuleManifest[],
     hosts: InitializedModuleHosts,
@@ -42,6 +42,7 @@ export class EmbeddingFacade {
     private readonly remote: EmbeddingRuntimePort,
     private readonly artifacts: AiArtifactRuntime,
     private readonly runs: EmbeddingRunAuthorizations,
+    private readonly readiness: ReadinessPort,
   ) {
     const handlers = new Map(
       hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
@@ -68,7 +69,6 @@ export class EmbeddingFacade {
       ),
     );
   }
-
   async embed(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -113,7 +113,6 @@ export class EmbeddingFacade {
       throw error;
     }
   }
-
   async start(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -133,6 +132,7 @@ export class EmbeddingFacade {
       operationKey,
       prepared.items,
       prepared.request.options,
+      prepared.request.readinessPin,
     );
     const binding = await this.runs.issue({
       operationKey,
@@ -176,7 +176,6 @@ export class EmbeddingFacade {
       throw error;
     }
   }
-
   async authorizeRun(runId: string, context: RequestGuardContext) {
     const binding = await this.runs.require(runId, context);
     const operation = this.#operations.get(binding.operationKey);
@@ -226,7 +225,6 @@ export class EmbeddingFacade {
     await this.remote.cancel(runId, undefined, signal);
     await this.auditTerminal(binding, context, "cancelled");
   }
-
   async openRunArtifact(runId: string, itemId: string, signal: AbortSignal) {
     const initial = await this.runs.find(runId);
     if (!initial) throw unavailableArtifact();
@@ -250,7 +248,6 @@ export class EmbeddingFacade {
       signal,
     );
   }
-
   private async prepare(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -266,6 +263,10 @@ export class EmbeddingFacade {
         404,
       );
     await authorizeEmbeddingOperation(this.runtime, operation, context);
+    const readinessPin = await requireReadiness(
+      this.readiness,
+      operation.definition,
+    );
     const governed = governEmbeddingInput(items, options, operation.definition);
     const plan = await operation.registration.prepareEmbedding(governed, {
       actor: toModuleActor(context.actor),
@@ -316,6 +317,7 @@ export class EmbeddingFacade {
         },
         providerEgress: resolveProviderEgress(operation.definition),
         providerDataPolicy: operation.definition.providerDataPolicy,
+        readinessPin,
       },
     };
   }

package/template/apps/server/src/embedding/readiness-admission.ts

@@ -0,0 +1,26 @@
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiOperationReadinessPortV1,
+} from "@southwind-ai/server-sdk";
+import { EmbeddingFacadeError } from "./error.js";
+
+export type ReadinessPort = ModuleAiOperationReadinessPortV1;
+
+export async function requireReadiness(
+  readiness: ModuleAiOperationReadinessPortV1,
+  definition: ModuleAiOperationDefinition,
+): Promise<AiRuntimeDeploymentV1 | undefined> {
+  if (!definition.readiness) return undefined;
+  try {
+    const projected = await readiness.inspect({ operationKey: definition.key });
+    if (projected.status !== "ready") throw new Error("not ready");
+    return projected.deployment;
+  } catch {
+    throw new EmbeddingFacadeError(
+      "RUNTIME_UNAVAILABLE",
+      "Embedding Runtime 当前不可用",
+      503,
+    );
+  }
+}