create-windy 0.5.2 → 0.6.1

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

@@ -0,0 +1,249 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { computeScreenshotContextDigestV1 } from "@southwind-ai/shared";
+import type { ModuleAiScreenshotIntakeProducerV2 } from "@southwind-ai/server-sdk";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
+import { reserveScreenshotForRun } from "./screenshot-run-binding.js";
+import {
+  screenshotDeployment,
+  screenshotVisionManifest,
+} from "./screenshot-intake-test-support.js";
+
+describe("Screenshot context Run admission", () => {
+  test("Host 重算 Manifest 指向的结构化上下文后才允许绑定", async () => {
+    const producer = fakeProducer();
+    const intake = runtime(producer);
+    const context = guard();
+    const uiContext = {
+      version: 1,
+      pageKey: "case.detail",
+      overlayStack: [{ title: "导入物证", kind: "dialog" }],
+    };
+    const plan = await intake.create(
+      declaration(await computeScreenshotContextDigestV1(uiContext)),
+      context,
+      signal(),
+    );
+    await intake.upload(plan.intakeToken, "image/png", png(), context);
+
+    const binding = await reserveScreenshotForRun(
+      intake,
+      plan.intakeToken,
+      operation(),
+      {
+        uiContext: {
+          overlayStack: [{ kind: "dialog", title: "导入物证" }],
+          pageKey: "case.detail",
+          version: 1,
+        },
+        uiContextDigest: `sha256:${"0".repeat(64)}`,
+      },
+      screenshotDeployment,
+      context,
+      signal(),
+    );
+    expect(binding?.artifact.value).toBe("opaque-screenshot-artifact");
+    await binding?.bind("run-canonical");
+    expect(producer.bound).toEqual(["run-canonical"]);
+    await intake.dispose();
+  });
+
+  test("上下文漂移或只提交自报 digest 会消费 token 并拒绝重放", async () => {
+    const producer = fakeProducer();
+    const intake = runtime(producer);
+    const context = guard();
+    const uiContext = { version: 1, pageKey: "case.detail" };
+    const first = await intake.create(
+      declaration(await computeScreenshotContextDigestV1(uiContext)),
+      context,
+      signal(),
+    );
+    await intake.upload(first.intakeToken, "image/png", png(), context);
+
+    await expect(
+      reserveScreenshotForRun(
+        intake,
+        first.intakeToken,
+        operation(),
+        { uiContext: { version: 1, pageKey: "case.list" } },
+        screenshotDeployment,
+        context,
+        signal(),
+      ),
+    ).rejects.toMatchObject({ code: "RUNTIME_UNAVAILABLE", status: 503 });
+    await expect(
+      reserveScreenshotForRun(
+        intake,
+        first.intakeToken,
+        operation(),
+        { uiContext },
+        screenshotDeployment,
+        context,
+        signal(),
+      ),
+    ).rejects.toMatchObject({ code: "RUNTIME_UNAVAILABLE", status: 503 });
+
+    const second = await intake.create(
+      declaration(await computeScreenshotContextDigestV1(uiContext)),
+      context,
+      signal(),
+    );
+    await intake.upload(second.intakeToken, "image/png", png(), context);
+    await expect(
+      reserveScreenshotForRun(
+        intake,
+        second.intakeToken,
+        operation(),
+        { uiContextDigest: await computeScreenshotContextDigestV1(uiContext) },
+        screenshotDeployment,
+        context,
+        signal(),
+      ),
+    ).rejects.toMatchObject({ code: "RUNTIME_UNAVAILABLE", status: 503 });
+    expect(producer.cancelled).toEqual(["producer-plan", "producer-plan"]);
+    await intake.dispose();
+  });
+
+  test("未 opt-in 的 0.6.0 Screenshot Operation 保留既有兼容边界", async () => {
+    const producer = fakeProducer();
+    const manifest = legacyManifest();
+    const intake = runtime(producer, manifest);
+    const context = guard();
+    const plan = await intake.create(
+      declaration(`sha256:${"f".repeat(64)}`),
+      context,
+      signal(),
+    );
+    await intake.upload(plan.intakeToken, "image/png", png(), context);
+    const binding = await reserveScreenshotForRun(
+      intake,
+      plan.intakeToken,
+      manifest.aiOperations![0]!,
+      { uiContext: { version: 1, pageKey: "legacy" } },
+      screenshotDeployment,
+      context,
+      signal(),
+    );
+    expect(binding?.artifact.value).toBe("opaque-screenshot-artifact");
+    await binding?.bind("run-legacy");
+    await intake.dispose();
+  });
+});
+
+function operation() {
+  const value = screenshotVisionManifest().aiOperations?.[0];
+  if (!value) throw new Error("测试 Manifest 缺少 Vision Operation");
+  return value;
+}
+
+function runtime(
+  producer: ReturnType<typeof fakeProducer>,
+  manifest = screenshotVisionManifest(),
+) {
+  return new ScreenshotIntakeRuntimeV2(
+    [manifest],
+    createServerRuntime(
+      {},
+      {
+        featureCatalog: manifest.features,
+        licenseResolver: { resolve: () => ({ status: "valid" }) },
+      },
+    ),
+    () => producer,
+    (reference) => reference,
+  );
+}
+
+function legacyManifest(): ModuleManifest {
+  const manifest = screenshotVisionManifest();
+  const definition = manifest.aiOperations?.[0];
+  if (!definition) throw new Error("测试 Manifest 缺少 Vision Operation");
+  return {
+    ...manifest,
+    aiOperations: [{ ...definition, screenshotContext: undefined }],
+  };
+}
+
+function fakeProducer(): ModuleAiScreenshotIntakeProducerV2 & {
+  bound: string[];
+  cancelled: string[];
+} {
+  return {
+    bound: [],
+    cancelled: [],
+    async create() {
+      return {
+        contractVersion: 2,
+        intakeToken: "producer-plan",
+        operationKey: "evidence.image.inspect",
+        expiresAt: new Date(Date.now() + 30_000).toISOString(),
+      };
+    },
+    async upload() {
+      return {
+        value: "opaque-screenshot-artifact",
+        mediaType: "image/png",
+        byteSize: png().byteLength,
+        sha256:
+          "b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640",
+        expiresAt: new Date(Date.now() + 20_000).toISOString(),
+      };
+    },
+    async bind({ runId }) {
+      this.bound.push(runId);
+    },
+    async cancel({ intakeToken }) {
+      this.cancelled.push(intakeToken);
+    },
+  };
+}
+
+function declaration(contextDigest: `sha256:${string}`) {
+  return {
+    pageId: "case-detail",
+    contextDigest,
+    mediaType: "image/png" as const,
+    byteSize: png().byteLength,
+    pixels: 1,
+  };
+}
+
+function guard() {
+  return createRequestGuardContext(
+    new Request("http://windy.test/api/agent/screenshots"),
+    {
+      resolveActor: () => ({
+        id: "actor-1",
+        type: "user",
+        name: "测试用户",
+        roleCodes: ["user"],
+        permissionKeys: ["evidence.ai.execute"],
+        scopeContext: buildScopeContext("actor-1", undefined, [
+          {
+            id: "role-user",
+            code: "user",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      }),
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+}
+
+function signal() {
+  return AbortSignal.timeout(1_000);
+}
+
+function png(): Uint8Array {
+  return Uint8Array.from(
+    Buffer.from(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC",
+      "base64",
+    ),
+  );
+}

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-authorization.ts

@@ -0,0 +1,29 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import { findFeature } from "../route-guards.js";
+import type { ScreenshotIntakeServerRuntime } from "./screenshot-intake-runtime-types.js";
+
+export async function authorizeScreenshotOperation(
+  modules: readonly ModuleManifest[],
+  runtime: ScreenshotIntakeServerRuntime,
+  operationKey: string,
+  context: RequestGuardContext,
+) {
+  const entry = modules
+    .flatMap((module) =>
+      (module.aiOperations ?? []).map((operation) => ({ module, operation })),
+    )
+    .find(({ operation }) => operation.key === operationKey);
+  const feature =
+    entry &&
+    findFeature([...entry.module.features], entry.operation.featureKey);
+  if (!entry || !feature) throw new Error("Screenshot Intake unavailable");
+  const decision = await evaluateAccessGuards(runtime, context, {
+    permission: { permissionKey: entry.operation.permissionKey },
+    feature,
+  });
+  if (!decision.decision.allowed)
+    throw new Error("Screenshot Intake unavailable");
+  return entry;
+}

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

@@ -0,0 +1,59 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { StorageRuntime } from "../storage/runtime.js";
+import { DrizzleScreenshotIntakeRepository } from "./drizzle-screenshot-intake-repository.js";
+import {
+  cleanupPersistentScreenshotIntakes,
+  PersistentScreenshotIntakeProducer,
+  type ScreenshotPageRegistryV2,
+} from "./persistent-screenshot-intake-producer.js";
+import { type ProjectAiScreenshotIntakeFactoryV2 } from "./screenshot-intake-durable.js";
+import { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
+
+export function createScreenshotIntakeRuntimeV2(input: {
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly artifacts: AiArtifactRuntime;
+  readonly storage: StorageRuntime;
+  readonly db?: NodePgDatabase;
+  readonly registry: ScreenshotPageRegistryV2 | undefined;
+}): ScreenshotIntakeRuntimeV2 | undefined {
+  if (!input.db) return undefined;
+  const modules = input.modules;
+  const factory: ProjectAiScreenshotIntakeFactoryV2 = (context) =>
+    new PersistentScreenshotIntakeProducer(
+      input.registry,
+      new DrizzleScreenshotIntakeRepository(input.db!),
+      input.storage,
+      input.artifacts,
+      context,
+      (operationKey) =>
+        modules.find((module) =>
+          module.aiOperations?.some(
+            (operation) => operation.key === operationKey,
+          ),
+        )?.name,
+      (operationKey) =>
+        modules
+          .flatMap((module) => module.aiOperations ?? [])
+          .find((operation) => operation.key === operationKey)?.readiness
+          ?.expectedDeployment,
+    );
+  const repository = new DrizzleScreenshotIntakeRepository(input.db);
+  return new ScreenshotIntakeRuntimeV2(
+    input.modules,
+    input.runtime,
+    factory,
+    (reference, actorId, moduleName, purpose) =>
+      input.artifacts.validateReference(
+        reference,
+        actorId,
+        moduleName,
+        purpose,
+      ),
+    undefined,
+    () => cleanupPersistentScreenshotIntakes(repository, input.storage),
+  );
+}

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

@@ -0,0 +1,53 @@
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakeProducerV2,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+
+export type ProjectAiScreenshotIntakeFactoryV2 = (
+  context: RequestGuardContext,
+  signal: AbortSignal,
+) => ModuleAiScreenshotIntakeProducerV2 | undefined;
+
+export type DurableScreenshotIntakeState =
+  | "created"
+  | "uploaded"
+  | "reserving"
+  | "bound";
+
+/** Safe Host recovery facts. No bytes, physical locator, upload ID or Secret. */
+export interface DurableScreenshotIntakeSnapshotV2 {
+  readonly actorId: string;
+  readonly actorType: string;
+  readonly scopeHash: string;
+  readonly moduleName: string;
+  readonly operationKey: string;
+  readonly purpose: string;
+  readonly pageId: string;
+  readonly contextDigest: string;
+  readonly deployment: AiRuntimeDeploymentV1;
+  readonly expiresAtMs: number;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly pixels: number;
+  readonly state: DurableScreenshotIntakeState;
+  readonly artifact?: ModuleAiArtifactRef;
+}
+
+export interface DurableScreenshotIntakeProducerV2 extends ModuleAiScreenshotIntakeProducerV2 {
+  recover(
+    token: string,
+  ): Promise<DurableScreenshotIntakeSnapshotV2 | undefined>;
+  reserve(token: string): Promise<void>;
+}
+
+export function durableScreenshotProducer(
+  producer: ModuleAiScreenshotIntakeProducerV2,
+): producer is DurableScreenshotIntakeProducerV2 {
+  const candidate = producer as Partial<DurableScreenshotIntakeProducerV2>;
+  return (
+    typeof candidate.recover === "function" &&
+    typeof candidate.reserve === "function"
+  );
+}

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

@@ -0,0 +1,9 @@
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export function screenshotIntakeUnavailable(): AgentRunFacadeError {
+  return new AgentRunFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "Screenshot Intake 当前不可用",
+    503,
+  );
+}

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

@@ -0,0 +1,41 @@
+/** Bounds an untrusted project producer and compensates a late completion. */
+export async function callBoundedScreenshotProducer<T>(
+  call: () => Promise<T>,
+  unavailable: () => Error,
+  late?: (value: T) => Promise<void>,
+): Promise<T> {
+  let timedOut = false;
+  const result = Promise.resolve().then(call);
+  void result
+    .then((value) => (timedOut ? late?.(value) : undefined))
+    .catch(() => undefined);
+  return await Promise.race([
+    result,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => {
+        timedOut = true;
+        reject(unavailable());
+      }, 5_000),
+    ),
+  ]);
+}
+
+export async function cancelScreenshotProducer(
+  producer: import("@southwind-ai/server-sdk").ModuleAiScreenshotIntakeProducerV2,
+  intakeToken: string,
+  unavailable: () => Error,
+): Promise<void> {
+  await callBoundedScreenshotProducer(
+    () => producer.cancel({ intakeToken }),
+    unavailable,
+  ).catch(() => undefined);
+}
+
+export async function rejectDuplicateScreenshotProducer(
+  producer: import("@southwind-ai/server-sdk").ModuleAiScreenshotIntakeProducerV2,
+  intakeToken: string,
+  unavailable: () => Error,
+): Promise<never> {
+  await cancelScreenshotProducer(producer, intakeToken, unavailable);
+  throw unavailable();
+}

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

@@ -0,0 +1,44 @@
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakeProducerV2,
+} from "@southwind-ai/server-sdk";
+
+export type ScreenshotArtifactValidator = (
+  reference: ModuleAiArtifactRef,
+  actorId: string,
+  moduleName: string,
+  purpose: string,
+) => ModuleAiArtifactRef;
+
+export type ScreenshotIntakeRecordState =
+  | "created"
+  | "uploading"
+  | "uploaded"
+  | "reserving"
+  | "binding"
+  | "bound"
+  | "cleanup";
+
+export type ScreenshotIntakeRecordV2 = {
+  actorId: string;
+  actorType: string;
+  scopeHash: string;
+  token: string;
+  producer: ModuleAiScreenshotIntakeProducerV2;
+  producerToken: string;
+  durable: boolean;
+  moduleName: string;
+  operationKey: string;
+  purpose: string;
+  pageId: string;
+  contextDigest: string;
+  deployment: AiRuntimeDeploymentV1;
+  expiresAtMs: number;
+  mediaType: string;
+  byteSize: number;
+  pixels: number;
+  state: ScreenshotIntakeRecordState;
+  artifact?: ModuleAiArtifactRef;
+  cleanup?: Promise<void>;
+};

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

@@ -0,0 +1,106 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { RequestGuardContext } from "../guards.js";
+import type {
+  DurableScreenshotIntakeProducerV2,
+  DurableScreenshotIntakeSnapshotV2,
+} from "./screenshot-intake-durable.js";
+import type {
+  ScreenshotArtifactValidator,
+  ScreenshotIntakeRecordV2,
+} from "./screenshot-intake-record.js";
+import {
+  assertScreenshotDeclaration,
+  assertScreenshotOperation,
+  bindingForScreenshot,
+  sameScreenshotBinding,
+  sameScreenshotDeployment,
+  screenshotModuleName,
+  screenshotPurpose,
+} from "./screenshot-intake-v2-validation.js";
+
+export function restoreScreenshotRecord(input: {
+  readonly token: string;
+  readonly producer: DurableScreenshotIntakeProducerV2;
+  readonly snapshot: DurableScreenshotIntakeSnapshotV2;
+  readonly modules: readonly ModuleManifest[];
+  readonly context: RequestGuardContext;
+  readonly validateArtifact: ScreenshotArtifactValidator;
+  readonly now: Date;
+}): ScreenshotIntakeRecordV2 {
+  const declaration = {
+    pageId: input.snapshot.pageId,
+    contextDigest: input.snapshot.contextDigest,
+    mediaType: input.snapshot.mediaType as "image/png",
+    byteSize: input.snapshot.byteSize,
+    pixels: input.snapshot.pixels,
+  };
+  assertScreenshotDeclaration(declaration);
+  const operation = input.modules
+    .flatMap((module) => module.aiOperations ?? [])
+    .find(({ key }) => key === input.snapshot.operationKey);
+  if (!operation?.readiness) throw new Error("Screenshot recovery unavailable");
+  assertScreenshotOperation(operation, declaration);
+  const moduleName = screenshotModuleName(
+    input.modules,
+    input.snapshot.operationKey,
+  );
+  const purpose = screenshotPurpose(input.snapshot.operationKey);
+  if (
+    input.snapshot.moduleName !== moduleName ||
+    input.snapshot.purpose !== purpose ||
+    input.snapshot.expiresAtMs <= input.now.getTime() ||
+    !sameScreenshotBinding(
+      input.snapshot,
+      bindingForScreenshot(input.context),
+    ) ||
+    !sameScreenshotDeployment(
+      input.snapshot.deployment,
+      operation.readiness.expectedDeployment,
+    )
+  )
+    throw new Error("Screenshot recovery unavailable");
+  const artifact = recoverArtifact(input, moduleName, purpose);
+  return {
+    ...input.snapshot,
+    token: input.token,
+    producer: input.producer,
+    producerToken: input.token,
+    durable: true,
+    moduleName,
+    purpose,
+    ...(artifact ? { artifact } : {}),
+  };
+}
+
+function recoverArtifact(
+  input: Parameters<typeof restoreScreenshotRecord>[0],
+  moduleName: string,
+  purpose: string,
+): ReturnType<ScreenshotArtifactValidator> | undefined {
+  if (input.snapshot.state === "created") {
+    if (input.snapshot.artifact)
+      throw new Error("Screenshot recovery unavailable");
+    return undefined;
+  }
+  if (!input.snapshot.artifact)
+    throw new Error("Screenshot recovery unavailable");
+  const artifact = input.validateArtifact(
+    input.snapshot.artifact,
+    input.snapshot.actorId,
+    moduleName,
+    purpose,
+  );
+  const artifactExpiresAt = Date.parse(artifact.expiresAt);
+  if (
+    artifact.mediaType !== input.snapshot.mediaType ||
+    artifact.byteSize !== input.snapshot.byteSize ||
+    !/^[a-f0-9]{64}$/.test(artifact.sha256) ||
+    !artifact.value ||
+    !Number.isFinite(artifactExpiresAt) ||
+    artifactExpiresAt <= input.now.getTime() ||
+    artifactExpiresAt > input.snapshot.expiresAtMs ||
+    /^[a-z][a-z0-9+.-]*:\/\//i.test(artifact.value)
+  )
+    throw new Error("Screenshot recovery unavailable");
+  return Object.freeze({ ...artifact });
+}