create-windy 0.5.2 → 0.6.1

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

@@ -0,0 +1,345 @@
+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}`,
+        },
+        declaration().contextDigest,
+        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,
+      declaration().contextDigest,
+      context,
+    );
+    expect(reserved.artifact.value).toBe("opaque-screenshot-artifact");
+    await reserved.bind("run_canonical");
+    await expect(
+      intake.reserve(
+        second.intakeToken,
+        "evidence.image.inspect",
+        deployment,
+        declaration().contextDigest,
+        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,
+        },
+        screenshotContext: {
+          contractVersion: 1,
+          contextInputPointer: "/uiContext",
+        },
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,348 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakeCreateV2,
+  ModuleAiScreenshotPlanV2,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import { authorizeScreenshotOperation } from "./screenshot-intake-authorization.js";
+import { pngPixels } from "./screenshot-png.js";
+import { screenshotIntakeUnavailable as unavailable } from "./screenshot-intake-errors.js";
+import {
+  durableScreenshotProducer,
+  type ProjectAiScreenshotIntakeFactoryV2,
+} from "./screenshot-intake-durable.js";
+import {
+  callBoundedScreenshotProducer,
+  cancelScreenshotProducer,
+  rejectDuplicateScreenshotProducer,
+} from "./screenshot-intake-producer.js";
+import type {
+  ScreenshotArtifactValidator,
+  ScreenshotIntakeRecordV2,
+} from "./screenshot-intake-record.js";
+import { restoreScreenshotRecord } from "./screenshot-intake-recovery.js";
+import { reserveProducerScreenshot } from "./screenshot-intake-reservation.js";
+import type { ScreenshotIntakeServerRuntime } from "./screenshot-intake-runtime-types.js";
+import { sweepScreenshotRecords } from "./screenshot-intake-sweep.js";
+import {
+  assertScreenshotDeclaration,
+  bindingForScreenshot,
+  assertScreenshotOperation,
+  assertScreenshotProducerPlan,
+  canReserveScreenshot,
+  sameScreenshotArtifact,
+  sameScreenshotBinding,
+  screenshotModuleName,
+  screenshotPurpose,
+} from "./screenshot-intake-v2-validation.js";
+
+const MAX_ENTRIES = 1_024;
+const MAX_TTL_MS = 60_000;
+const SWEEP_INTERVAL_MS = 10_000;
+
+export class ScreenshotIntakeRuntimeV2 {
+  readonly #records = new Map<string, ScreenshotIntakeRecordV2>();
+  readonly #sweeper: ReturnType<typeof setInterval>;
+
+  constructor(
+    private readonly modules: readonly ModuleManifest[],
+    private readonly runtime: ScreenshotIntakeServerRuntime,
+    private readonly factory: ProjectAiScreenshotIntakeFactoryV2 | undefined,
+    private readonly validateArtifact: ScreenshotArtifactValidator,
+    private readonly now: () => Date = () => new Date(),
+    private readonly cleanupPersistent:
+      | (() => Promise<void>)
+      | undefined = undefined,
+  ) {
+    this.#sweeper = setInterval(() => void this.sweep(), SWEEP_INTERVAL_MS);
+    (this.#sweeper as { unref?: () => void }).unref?.();
+  }
+
+  async dispose(): Promise<void> {
+    clearInterval(this.#sweeper);
+    await Promise.allSettled(
+      [...this.#records.values()]
+        .filter((record) => !record.durable)
+        .map((record) => this.cancel(record)),
+    );
+    this.#records.clear();
+  }
+
+  async create(
+    input: ModuleAiScreenshotIntakeCreateV2,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<ModuleAiScreenshotPlanV2> {
+    await this.sweep();
+    if (!this.factory || this.#records.size >= MAX_ENTRIES) throw unavailable();
+    assertScreenshotDeclaration(input);
+    const producer = this.factory(context, signal);
+    if (!producer || signal.aborted) throw unavailable();
+    let plan:
+      | (ModuleAiScreenshotPlanV2 & {
+          readonly operationKey: string;
+        })
+      | undefined;
+    let deployment: AiRuntimeDeploymentV1;
+    try {
+      plan = await callBoundedScreenshotProducer(
+        () => producer.create(input),
+        unavailable,
+        (late) =>
+          cancelScreenshotProducer(producer, late.intakeToken, unavailable),
+      );
+      assertScreenshotProducerPlan(plan, this.now());
+      const entry = await authorizeScreenshotOperation(
+        this.modules,
+        this.runtime,
+        plan.operationKey,
+        context,
+      );
+      assertScreenshotOperation(entry.operation, input);
+      if (!entry.operation.readiness) throw unavailable();
+      deployment = entry.operation.readiness.expectedDeployment;
+    } catch {
+      if (plan)
+        await cancelScreenshotProducer(producer, plan.intakeToken, unavailable);
+      throw unavailable();
+    }
+    if (!plan) throw unavailable();
+    const expiresAtMs = Math.min(
+      Date.parse(plan.expiresAt),
+      this.now().getTime() + MAX_TTL_MS,
+    );
+    const expiresAt = new Date(expiresAtMs).toISOString();
+    const token = plan.intakeToken;
+    if (this.#records.has(token))
+      await rejectDuplicateScreenshotProducer(producer, token, unavailable);
+    this.#records.set(token, {
+      ...bindingForScreenshot(context),
+      token,
+      producer,
+      producerToken: plan.intakeToken,
+      durable: durableScreenshotProducer(producer),
+      moduleName: screenshotModuleName(this.modules, plan.operationKey),
+      operationKey: plan.operationKey,
+      purpose: screenshotPurpose(plan.operationKey),
+      pageId: input.pageId,
+      contextDigest: input.contextDigest,
+      deployment,
+      expiresAtMs,
+      mediaType: input.mediaType,
+      byteSize: input.byteSize,
+      pixels: input.pixels,
+      state: "created",
+    });
+    return Object.freeze({
+      contractVersion: 2,
+      intakeToken: token,
+      expiresAt,
+    });
+  }
+
+  async upload(
+    token: string,
+    mediaType: string,
+    bytes: Uint8Array,
+    context: RequestGuardContext,
+    signal: AbortSignal = AbortSignal.timeout(10_000),
+  ): Promise<void> {
+    const record = await this.claimable(token, context, signal);
+    await authorizeScreenshotOperation(
+      this.modules,
+      this.runtime,
+      record.operationKey,
+      context,
+    );
+    if (
+      bytes.byteLength !== record.byteSize ||
+      mediaType !== record.mediaType
+    ) {
+      if (record.state === "created") await this.cancel(record);
+      throw unavailable();
+    }
+    if (mediaType !== "image/png" || pngPixels(bytes) !== record.pixels) {
+      if (record.state === "created") await this.cancel(record);
+      throw unavailable();
+    }
+    if (record.state !== "created") {
+      if (
+        record.durable &&
+        record.artifact &&
+        ["uploaded", "reserving", "bound"].includes(record.state) &&
+        sameScreenshotArtifact(record.artifact, record, bytes, this.now())
+      )
+        return;
+      throw unavailable();
+    }
+    record.state = "uploading";
+    try {
+      const artifact = await callBoundedScreenshotProducer(
+        () =>
+          record.producer.upload({
+            intakeToken: record.producerToken,
+            bytes,
+            mediaType,
+          }),
+        unavailable,
+        () => this.cancel(record),
+      );
+      const validated = this.validateArtifact(
+        artifact,
+        record.actorId,
+        record.moduleName,
+        record.purpose,
+      );
+      if (!sameScreenshotArtifact(validated, record, bytes, this.now()))
+        throw unavailable();
+      record.artifact = Object.freeze({ ...validated });
+      record.state = "uploaded";
+    } catch {
+      await this.cancel(record);
+      throw unavailable();
+    }
+  }
+
+  async reserve(
+    token: string,
+    operationKey: string,
+    deployment: AiRuntimeDeploymentV1 | undefined,
+    expectedContextDigest: string | null | undefined,
+    context: RequestGuardContext,
+    signal: AbortSignal = AbortSignal.timeout(10_000),
+  ): Promise<{
+    artifact: ModuleAiArtifactRef;
+    bind(runId: string): Promise<void>;
+    cancel(): Promise<void>;
+  }> {
+    const record = await this.claimable(token, context, signal);
+    await authorizeScreenshotOperation(
+      this.modules,
+      this.runtime,
+      record.operationKey,
+      context,
+    );
+    if (
+      !canReserveScreenshot(
+        record,
+        operationKey,
+        deployment,
+        expectedContextDigest,
+      )
+    ) {
+      await this.cancel(record);
+      throw unavailable();
+    }
+    await reserveProducerScreenshot(
+      record.producer,
+      record.producerToken,
+      unavailable,
+      () => this.cancel(record),
+    );
+    if (record.state === "uploaded") record.state = "reserving";
+    return Object.freeze({
+      artifact: record.artifact,
+      bind: async (runId: string) => {
+        if (
+          !runId.trim() ||
+          (record.state !== "reserving" && record.state !== "bound")
+        )
+          throw unavailable();
+        record.state = "binding";
+        try {
+          await callBoundedScreenshotProducer(
+            () =>
+              record.producer.bind({
+                intakeToken: record.producerToken,
+                runId,
+              }),
+            unavailable,
+            () => this.cancel(record),
+          );
+        } catch {
+          await this.cancel(record);
+          throw unavailable();
+        }
+        record.state = "bound";
+        this.#records.delete(record.token);
+      },
+      cancel: () => this.cancel(record),
+    });
+  }
+
+  async cancelToken(
+    token: string,
+    context: RequestGuardContext,
+    signal: AbortSignal = AbortSignal.timeout(10_000),
+  ): Promise<void> {
+    const record = await this.claimable(token, context, signal);
+    await authorizeScreenshotOperation(
+      this.modules,
+      this.runtime,
+      record.operationKey,
+      context,
+    );
+    if (record.state === "binding" || record.state === "bound")
+      throw unavailable();
+    await this.cancel(record);
+  }
+
+  async sweep(): Promise<void> {
+    await this.cleanupPersistent?.().catch(() => undefined);
+    await sweepScreenshotRecords(
+      this.#records,
+      this.now().getTime(),
+      (record) => this.cancel(record),
+    );
+  }
+
+  private async claimable(
+    token: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<ScreenshotIntakeRecordV2> {
+    let record = this.#records.get(token);
+    if (!record) {
+      const producer = this.factory?.(context, signal);
+      if (!producer || !durableScreenshotProducer(producer))
+        throw unavailable();
+      const snapshot = await callBoundedScreenshotProducer(
+        () => producer.recover(token),
+        unavailable,
+      );
+      if (!snapshot) throw unavailable();
+      const recovered = restoreScreenshotRecord({
+        token,
+        producer,
+        snapshot,
+        modules: this.modules,
+        context,
+        validateArtifact: this.validateArtifact,
+        now: this.now(),
+      });
+      record = this.#records.get(token) ?? recovered;
+      this.#records.set(token, record);
+    }
+    if (record.expiresAtMs <= this.now().getTime()) {
+      void this.cancel(record);
+      throw unavailable();
+    }
+    if (!sameScreenshotBinding(record, bindingForScreenshot(context)))
+      throw unavailable();
+    return record;
+  }
+
+  private async cancel(record: ScreenshotIntakeRecordV2): Promise<void> {
+    if (record.cleanup) return await record.cleanup;
+    record.state = "cleanup";
+    record.cleanup = callBoundedScreenshotProducer(
+      () => record.producer.cancel({ intakeToken: record.producerToken }),
+      unavailable,
+    )
+      .catch(() => undefined)
+      .finally(() => this.#records.delete(record.token));
+    await record.cleanup;
+  }
+}

package/template/apps/server/src/agent/screenshot-png.ts

@@ -0,0 +1,15 @@
+/** Returns decoded IHDR dimensions only for a structurally valid PNG header. */
+export function pngPixels(bytes: Uint8Array): number | undefined {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (
+    bytes.byteLength < 24 ||
+    signature.some((value, index) => bytes[index] !== value) ||
+    String.fromCharCode(...bytes.slice(12, 16)) !== "IHDR"
+  )
+    return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  const pixels = width * height;
+  return Number.isSafeInteger(pixels) && pixels > 0 ? pixels : undefined;
+}