create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,87 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+
+export const screenshotDeployment = {
+  key: "ai.openai-compatible",
+  identity: "windy-deployment-v1_f31e8a65-92cb-4d03-8a77-3c1b5e9d4f04",
+  releaseDigest: `sha256:${"d".repeat(64)}` as `sha256:${string}`,
+  offersDigest: `sha256:${"e".repeat(64)}` as `sha256:${string}`,
+};
+
+export function screenshotVisionManifest(): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "证据",
+    description: "证据",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "evidence.ai.execute",
+        label: "图片分析",
+        module: "evidence",
+        moduleLabel: "证据",
+        resource: "ai",
+        resourceLabel: "AI",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("evidence.ai"),
+        label: "图片分析",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+    aiOperations: [
+      {
+        key: "evidence.image.inspect",
+        kind: "agent",
+        featureKey: "evidence.ai",
+        permissionKey: "evidence.ai.execute",
+        auditAction: "evidence.ai.execute",
+        inputSchemaKey: "input",
+        outputSchemaKey: "output",
+        inputModalities: ["text", "image"],
+        requiredCapabilities: ["text-generation", "vision"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "streaming",
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: screenshotDeployment.key,
+        },
+        providerDataPolicy: { inputFields: [], envelopeFields: [] },
+        toolNetworkPolicy: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 1_024,
+          maxOutputBytes: 1_024,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+        },
+        readiness: {
+          contractVersion: 1,
+          expectedDeployment: screenshotDeployment,
+          variant: "vision",
+          inputModalities: ["text", "image"],
+          outputModalities: ["text"],
+          minConcurrentRuns: 1,
+          minQueueDepth: 0,
+        },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakeCreateV2,
+  ModuleAiScreenshotPlanV2,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+
+const MAX_BYTES = 8 * 1_024 * 1_024;
+const MAX_PIXELS = 20_000_000;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+export function assertScreenshotDeclaration(
+  input: ModuleAiScreenshotIntakeCreateV2,
+): void {
+  if (
+    !input.pageId.trim() ||
+    input.pageId.length > 256 ||
+    !DIGEST.test(input.contextDigest) ||
+    input.mediaType !== "image/png" ||
+    !Number.isSafeInteger(input.byteSize) ||
+    input.byteSize < 1 ||
+    input.byteSize > MAX_BYTES ||
+    !Number.isSafeInteger(input.pixels) ||
+    input.pixels < 1 ||
+    input.pixels > MAX_PIXELS
+  )
+    throw new Error("Screenshot declaration invalid");
+}
+
+export function assertScreenshotProducerPlan(
+  value: unknown,
+  now: Date,
+): asserts value is ModuleAiScreenshotPlanV2 & {
+  operationKey: string;
+} {
+  if (!value || typeof value !== "object")
+    throw new Error("Screenshot plan invalid");
+  const plan = value as ModuleAiScreenshotPlanV2 & {
+    operationKey: unknown;
+  };
+  if (
+    plan.contractVersion !== 2 ||
+    typeof plan.intakeToken !== "string" ||
+    !plan.intakeToken.trim() ||
+    plan.intakeToken.length > 512 ||
+    typeof plan.operationKey !== "string" ||
+    !plan.operationKey.trim() ||
+    Date.parse(plan.expiresAt) <= now.getTime()
+  )
+    throw new Error("Screenshot plan invalid");
+}
+
+export function assertScreenshotOperation(
+  operation: ModuleAiOperationDefinition,
+  input: ModuleAiScreenshotIntakeCreateV2,
+): void {
+  if (
+    !operation.readiness ||
+    !operation.inputModalities?.includes("image") ||
+    !operation.requiredCapabilities.includes("vision") ||
+    input.byteSize > operation.limits.maxInputBytes ||
+    input.pixels > (operation.limits.maxPixelsPerArtifact ?? 0)
+  )
+    throw new Error("Screenshot operation invalid");
+}
+
+export function bindingForScreenshot(context: RequestGuardContext) {
+  const scope = context.actor.scopeContext;
+  return {
+    actorId: context.actor.id,
+    actorType: context.actor.type,
+    scopeHash: createHash("sha256")
+      .update(
+        JSON.stringify(
+          scope
+            ? {
+                tenantId: scope.tenantId,
+                actorId: scope.actorId,
+                departmentId: scope.departmentId,
+                grants: scope.grants,
+                roleIds: scope.roleIds,
+              }
+            : null,
+        ),
+      )
+      .digest("hex"),
+  };
+}
+
+export function sameScreenshotBinding(
+  left: { actorId: string; actorType: string; scopeHash: string },
+  right: { actorId: string; actorType: string; scopeHash: string },
+): boolean {
+  return (
+    left.actorId === right.actorId &&
+    left.actorType === right.actorType &&
+    left.scopeHash === right.scopeHash
+  );
+}
+
+export function sameScreenshotDeployment(
+  left: AiRuntimeDeploymentV1,
+  right: AiRuntimeDeploymentV1,
+): boolean {
+  return (
+    left.key === right.key &&
+    left.identity === right.identity &&
+    left.releaseDigest === right.releaseDigest &&
+    left.offersDigest === right.offersDigest
+  );
+}
+
+export function sameScreenshotArtifact(
+  value: ModuleAiArtifactRef,
+  record: {
+    mediaType: string;
+    byteSize: number;
+    expiresAtMs: number;
+  },
+  bytes: Uint8Array,
+  now: Date,
+): boolean {
+  return (
+    value.mediaType === record.mediaType &&
+    value.byteSize === record.byteSize &&
+    value.sha256 === createHash("sha256").update(bytes).digest("hex") &&
+    Boolean(value.value) &&
+    Number.isFinite(Date.parse(value.expiresAt)) &&
+    Date.parse(value.expiresAt) > now.getTime() &&
+    Date.parse(value.expiresAt) <= record.expiresAtMs &&
+    !/^[a-z][a-z0-9+.-]*:\/\//i.test(value.value)
+  );
+}
+
+export function screenshotModuleName(
+  modules: readonly ModuleManifest[],
+  operationKey: string,
+): string {
+  const moduleName = modules.find((module) =>
+    module.aiOperations?.some((operation) => operation.key === operationKey),
+  )?.name;
+  if (!moduleName) throw new Error("Screenshot operation has no module");
+  return moduleName;
+}
+
+export function screenshotPurpose(operationKey: string): string {
+  return `agent.screenshot.${operationKey}`;
+}

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

@@ -0,0 +1,338 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import type { ModuleAiScreenshotIntakeProducerV2 } from "@southwind-ai/server-sdk";
+import type { AiRuntimeDeploymentV1 } 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";
+
+const deployment: AiRuntimeDeploymentV1 = {
+  key: "ai.openai-compatible",
+  identity: "windy-deployment-v1_f31e8a65-92cb-4d03-8a77-3c1b5e9d4f04",
+  releaseDigest: `sha256:${"d".repeat(64)}`,
+  offersDigest: `sha256:${"a".repeat(64)}`,
+};
+
+describe("Screenshot Intake V2", () => {
+  test("上传后只能按相同 scope、Operation 和 pin 消费一次", async () => {
+    const producer = fakeProducer();
+    const intake = runtime(producer);
+    const context = guard("actor-1");
+    const plan = await intake.create(
+      declaration(),
+      context,
+      AbortSignal.timeout(1_000),
+    );
+    await intake.upload(plan.intakeToken, "image/png", png(), context);
+
+    await expect(
+      intake.reserve(
+        plan.intakeToken,
+        "evidence.image.inspect",
+        {
+          ...deployment,
+          offersDigest: `sha256:${"b".repeat(64)}` as `sha256:${string}`,
+        },
+        context,
+      ),
+    ).rejects.toThrow("Screenshot Intake");
+    expect(producer.cancelled).toEqual(["producer-plan"]);
+
+    const second = await intake.create(
+      declaration(),
+      context,
+      AbortSignal.timeout(1_000),
+    );
+    await intake.upload(second.intakeToken, "image/png", png(), context);
+    const reserved = await intake.reserve(
+      second.intakeToken,
+      "evidence.image.inspect",
+      deployment,
+      context,
+    );
+    expect(reserved.artifact.value).toBe("opaque-screenshot-artifact");
+    await reserved.bind("run_canonical");
+    await expect(
+      intake.reserve(
+        second.intakeToken,
+        "evidence.image.inspect",
+        deployment,
+        context,
+      ),
+    ).rejects.toThrow("Screenshot Intake");
+  });
+
+  test("scope 漂移、上传元数据不一致与 TTL 都 fail closed 并清理 producer", async () => {
+    const producer = fakeProducer();
+    let now = new Date();
+    const intake = runtime(producer, () => now);
+    const plan = await intake.create(
+      declaration(),
+      guard("actor-1"),
+      AbortSignal.timeout(1_000),
+    );
+    await expect(
+      intake.upload(plan.intakeToken, "image/jpeg", png(), guard("actor-1")),
+    ).rejects.toThrow("Screenshot Intake");
+    expect(producer.cancelled).toEqual(["producer-plan"]);
+
+    const expiring = await intake.create(
+      declaration(),
+      guard("actor-1"),
+      AbortSignal.timeout(1_000),
+    );
+    now = new Date("2031-01-01T00:00:00.000Z");
+    await expect(
+      intake.cancelToken(expiring.intakeToken, guard("actor-2")),
+    ).rejects.toThrow("Screenshot Intake");
+    await intake.sweep();
+    expect(producer.cancelled).toEqual(["producer-plan", "producer-plan"]);
+  });
+
+  test("未安装 project factory 时不能创建 plan", async () => {
+    const runtime = new ScreenshotIntakeRuntimeV2(
+      [manifest()],
+      serverRuntime(),
+      undefined,
+      (reference) => reference,
+    );
+    await expect(
+      runtime.create(
+        declaration(),
+        guard("actor-1"),
+        AbortSignal.timeout(1_000),
+      ),
+    ).rejects.toThrow("Screenshot Intake");
+  });
+
+  test("实际上传字节的 SHA 与并发 PUT 都不能被伪造或重放", async () => {
+    const producer = fakeProducer();
+    const intake = runtime(producer);
+    const context = guard("actor-1");
+    const plan = await intake.create(
+      declaration(),
+      context,
+      AbortSignal.timeout(1_000),
+    );
+    producer.upload = async () => ({
+      value: "opaque-screenshot-artifact",
+      mediaType: "image/png",
+      byteSize: png().byteLength,
+      sha256: "a".repeat(64),
+      expiresAt: new Date(Date.now() + 20_000).toISOString(),
+    });
+    await expect(
+      intake.upload(plan.intakeToken, "image/png", png(), context),
+    ).rejects.toThrow("Screenshot Intake");
+    expect(producer.cancelled).toEqual(["producer-plan"]);
+
+    const concurrent = await intake.create(
+      declaration(),
+      context,
+      AbortSignal.timeout(1_000),
+    );
+    let started!: () => void;
+    let finish!: (value: Awaited<ReturnType<typeof producer.upload>>) => void;
+    producer.upload = async () => {
+      started();
+      return await new Promise((resolve) => {
+        finish = resolve;
+      });
+    };
+    const first = intake.upload(
+      concurrent.intakeToken,
+      "image/png",
+      png(),
+      context,
+    );
+    await new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    await expect(
+      intake.upload(concurrent.intakeToken, "image/png", png(), context),
+    ).rejects.toThrow("Screenshot Intake");
+    finish({
+      value: "opaque-screenshot-artifact",
+      mediaType: "image/png",
+      byteSize: png().byteLength,
+      sha256:
+        "b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640",
+      expiresAt: new Date(Date.now() + 20_000).toISOString(),
+    });
+    await first;
+    expect(producer.cancelled).toEqual(["producer-plan"]);
+  });
+});
+
+function runtime(producer: ReturnType<typeof fakeProducer>, now?: () => Date) {
+  return new ScreenshotIntakeRuntimeV2(
+    [manifest()],
+    serverRuntime(),
+    () => producer,
+    (reference) => reference,
+    now,
+  );
+}
+
+function fakeProducer(): ModuleAiScreenshotIntakeProducerV2 & {
+  cancelled: string[];
+} {
+  return {
+    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() {},
+    async cancel({ intakeToken }) {
+      this.cancelled.push(intakeToken);
+    },
+  };
+}
+
+function declaration() {
+  return {
+    pageId: "case-detail",
+    contextDigest: `sha256:${"c".repeat(64)}`,
+    mediaType: "image/png" as const,
+    byteSize: png().byteLength,
+    pixels: 1,
+  };
+}
+
+function png(): Uint8Array {
+  return Uint8Array.from(
+    Buffer.from(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC",
+      "base64",
+    ),
+  );
+}
+
+function serverRuntime() {
+  return createServerRuntime(
+    {},
+    {
+      featureCatalog: manifest().features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+}
+
+function guard(actorId: string) {
+  return createRequestGuardContext(
+    new Request("http://windy.test/api/agent/screenshots"),
+    {
+      resolveActor: () => ({
+        id: actorId,
+        type: "user",
+        name: "测试用户",
+        roleCodes: ["user"],
+        permissionKeys: ["evidence.ai.execute"],
+        scopeContext: buildScopeContext(actorId, undefined, [
+          {
+            id: "role-user",
+            code: "user",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      }),
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+}
+
+function manifest(): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "证据",
+    description: "证据",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "evidence.ai.execute",
+        label: "图片分析",
+        module: "evidence",
+        moduleLabel: "证据",
+        resource: "ai",
+        resourceLabel: "AI",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("evidence.ai"),
+        label: "图片分析",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+    aiOperations: [
+      {
+        key: "evidence.image.inspect",
+        kind: "agent",
+        featureKey: "evidence.ai",
+        permissionKey: "evidence.ai.execute",
+        auditAction: "evidence.ai.execute",
+        inputSchemaKey: "input",
+        outputSchemaKey: "output",
+        inputModalities: ["text", "image"],
+        requiredCapabilities: ["text-generation", "vision"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "streaming",
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: deployment.key,
+        },
+        providerDataPolicy: { inputFields: [], envelopeFields: [] },
+        toolNetworkPolicy: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 1_024,
+          maxOutputBytes: 1_024,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+        },
+        readiness: {
+          contractVersion: 1,
+          expectedDeployment: deployment,
+          variant: "vision",
+          inputModalities: ["text", "image"],
+          outputModalities: ["text"],
+          minConcurrentRuns: 1,
+          minQueueDepth: 0,
+        },
+      },
+    ],
+  };
+}