create-windy 0.6.0 → 0.6.1

package/template/apps/server/src/agent/screenshot-context-attestation.ts

@@ -0,0 +1,60 @@
+import { timingSafeEqual } from "node:crypto";
+import {
+  parseAiScreenshotContextInputPointer,
+  type ModuleAiOperationDefinition,
+} from "@southwind-ai/modules";
+import {
+  computeScreenshotContextDigestV1,
+  isScreenshotContextDigestV1,
+  type JsonValue,
+  type ScreenshotContextDigestV1,
+} from "@southwind-ai/shared";
+
+/** null 表示 legacy 未 opt-in；undefined 表示已 opt-in 但上下文不能形成证明。 */
+export async function expectedScreenshotContextDigest(
+  definition: ModuleAiOperationDefinition,
+  input: JsonValue,
+): Promise<ScreenshotContextDigestV1 | null | undefined> {
+  const binding = definition.screenshotContext;
+  if (!binding) return null;
+  try {
+    const context = readPointer(
+      input,
+      parseAiScreenshotContextInputPointer(binding.contextInputPointer),
+    );
+    if (!isRecord(context)) return undefined;
+    return await computeScreenshotContextDigestV1(context);
+  } catch {
+    return undefined;
+  }
+}
+
+export function sameScreenshotContextDigest(
+  actual: string,
+  expected: string | undefined,
+): boolean {
+  if (
+    !isScreenshotContextDigestV1(actual) ||
+    !isScreenshotContextDigestV1(expected)
+  ) {
+    return false;
+  }
+  const actualBytes = Buffer.from(actual.slice("sha256:".length), "hex");
+  const expectedBytes = Buffer.from(expected.slice("sha256:".length), "hex");
+  return timingSafeEqual(actualBytes, expectedBytes);
+}
+
+function readPointer(value: JsonValue, segments: readonly string[]): JsonValue {
+  let current = value;
+  for (const segment of segments) {
+    if (!isRecord(current) || !Object.hasOwn(current, segment)) {
+      throw new Error("Screenshot context input 缺失");
+    }
+    current = current[segment] as JsonValue;
+  }
+  return current;
+}
+
+function isRecord(value: JsonValue): value is Record<string, JsonValue> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -9,10 +9,8 @@ import {
   PersistentScreenshotIntakeProducer,
   type ScreenshotPageRegistryV2,
 } from "./persistent-screenshot-intake-producer.js";
-import {
-  ScreenshotIntakeRuntimeV2,
-  type ProjectAiScreenshotIntakeFactoryV2,
-} from "./screenshot-intake-v2.js";
+import { type ProjectAiScreenshotIntakeFactoryV2 } from "./screenshot-intake-durable.js";
+import { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
 
 export function createScreenshotIntakeRuntimeV2(input: {
   readonly modules: readonly ModuleManifest[];

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

@@ -81,6 +81,10 @@ export function screenshotVisionManifest(): ModuleManifest {
           minConcurrentRuns: 1,
           minQueueDepth: 0,
         },
+        screenshotContext: {
+          contractVersion: 1,
+          contextInputPointer: "/uiContext",
+        },
       },
     ],
   };

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

@@ -8,6 +8,8 @@ import type {
   ModuleAiScreenshotPlanV2,
 } from "@southwind-ai/server-sdk";
 import type { RequestGuardContext } from "../guards.js";
+import { sameScreenshotContextDigest } from "./screenshot-context-attestation.js";
+import type { ScreenshotIntakeRecordV2 } from "./screenshot-intake-record.js";
 
 const MAX_BYTES = 8 * 1_024 * 1_024;
 const MAX_PIXELS = 20_000_000;
@@ -114,6 +116,28 @@ export function sameScreenshotDeployment(
   );
 }
 
+export function canReserveScreenshot(
+  record: ScreenshotIntakeRecordV2,
+  operationKey: string,
+  deployment: AiRuntimeDeploymentV1 | undefined,
+  expectedContextDigest: string | null | undefined,
+): record is ScreenshotIntakeRecordV2 & { artifact: ModuleAiArtifactRef } {
+  return Boolean(
+    record.artifact &&
+    (record.durable
+      ? ["uploaded", "reserving", "bound"].includes(record.state)
+      : record.state === "uploaded") &&
+    record.operationKey === operationKey &&
+    (expectedContextDigest === null ||
+      sameScreenshotContextDigest(
+        record.contextDigest,
+        expectedContextDigest,
+      )) &&
+    deployment &&
+    sameScreenshotDeployment(record.deployment, deployment),
+  );
+}
+
 export function sameScreenshotArtifact(
   value: ModuleAiArtifactRef,
   record: {

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

@@ -35,6 +35,7 @@ describe("Screenshot Intake V2", () => {
           ...deployment,
           offersDigest: `sha256:${"b".repeat(64)}` as `sha256:${string}`,
         },
+        declaration().contextDigest,
         context,
       ),
     ).rejects.toThrow("Screenshot Intake");
@@ -50,6 +51,7 @@ describe("Screenshot Intake V2", () => {
       second.intakeToken,
       "evidence.image.inspect",
       deployment,
+      declaration().contextDigest,
       context,
     );
     expect(reserved.artifact.value).toBe("opaque-screenshot-artifact");
@@ -59,6 +61,7 @@ describe("Screenshot Intake V2", () => {
         second.intakeToken,
         "evidence.image.inspect",
         deployment,
+        declaration().contextDigest,
         context,
       ),
     ).rejects.toThrow("Screenshot Intake");
@@ -332,6 +335,10 @@ function manifest(): ModuleManifest {
           minConcurrentRuns: 1,
           minQueueDepth: 0,
         },
+        screenshotContext: {
+          contractVersion: 1,
+          contextInputPointer: "/uiContext",
+        },
       },
     ],
   };

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 {