create-windy 0.5.1 → 0.6.0

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,61 @@
+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 {
+  ScreenshotIntakeRuntimeV2,
+  type ProjectAiScreenshotIntakeFactoryV2,
+} 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 });
+}

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

@@ -0,0 +1,64 @@
+import type { AiRuntimeDeploymentV1 } from "@southwind-ai/server-sdk";
+
+export type ScreenshotIntakeStatus =
+  | "created"
+  | "uploading"
+  | "uploaded"
+  | "reserving"
+  | "bound"
+  | "cancelled";
+
+export interface PersistentScreenshotIntake {
+  readonly intakeId: string;
+  readonly tokenHash: string;
+  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 mediaType: string;
+  readonly byteSize: number;
+  readonly pixels: number;
+  readonly status: ScreenshotIntakeStatus;
+  readonly uploadId?: string;
+  readonly fileId?: string;
+  readonly runId?: string;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+}
+
+export interface ScreenshotIntakeRepository {
+  create(value: PersistentScreenshotIntake): Promise<void>;
+  find(tokenHash: string): Promise<PersistentScreenshotIntake | undefined>;
+  claimUpload(
+    intakeId: string,
+    uploadId: string,
+    now: number,
+  ): Promise<PersistentScreenshotIntake | undefined>;
+  completeUpload(
+    intakeId: string,
+    uploadId: string,
+    fileId: string,
+  ): Promise<PersistentScreenshotIntake | undefined>;
+  reserve(
+    intakeId: string,
+    now: number,
+  ): Promise<PersistentScreenshotIntake | undefined>;
+  bind(
+    intakeId: string,
+    runId: string,
+    now: number,
+  ): Promise<PersistentScreenshotIntake | undefined>;
+  cancel(
+    intakeId: string,
+    now: number,
+  ): Promise<PersistentScreenshotIntake | undefined>;
+  listExpired(
+    now: number,
+    limit: number,
+  ): Promise<readonly PersistentScreenshotIntake[]>;
+}

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

@@ -0,0 +1,24 @@
+import type { ModuleAiScreenshotIntakeProducerV2 } from "@southwind-ai/server-sdk";
+import { callBoundedScreenshotProducer } from "./screenshot-intake-producer.js";
+
+export async function reserveProducerScreenshot(
+  producer: ModuleAiScreenshotIntakeProducerV2,
+  intakeToken: string,
+  unavailable: () => Error,
+  cleanup: () => Promise<void>,
+): Promise<void> {
+  const candidate = producer as ModuleAiScreenshotIntakeProducerV2 & {
+    reserve?: (token: string) => Promise<void>;
+  };
+  if (!candidate.reserve) return;
+  try {
+    await callBoundedScreenshotProducer(
+      () => candidate.reserve!(intakeToken),
+      unavailable,
+      cleanup,
+    );
+  } catch {
+    await cleanup();
+    throw unavailable();
+  }
+}

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

@@ -0,0 +1,171 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/route-types.js";
+import type { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
+
+interface Context {
+  readonly guardContext: RequestGuardContext;
+  readonly params: Record<string, string | undefined>;
+  readonly request: Request;
+}
+
+export function registerScreenshotIntakeRoutes(
+  app: RouteApp,
+  intake: ScreenshotIntakeRuntimeV2 | undefined,
+): void {
+  app.post(
+    "/agent/screenshots",
+    async (raw) => {
+      const context = raw as Context;
+      if (!intake) return unavailable(context.guardContext.requestId);
+      try {
+        return await intake.create(
+          await readCreate(context.request),
+          context.guardContext,
+          context.request.signal,
+        );
+      } catch {
+        return unavailable(context.guardContext.requestId);
+      }
+    },
+    { parse: "none" },
+  );
+  app.put(
+    "/agent/screenshots/:token",
+    async (raw) => {
+      const context = raw as Context;
+      if (!intake) return unavailable(context.guardContext.requestId);
+      try {
+        const bytes = await readImage(context.request);
+        await intake.upload(
+          required(context.params.token),
+          requiredMime(context.request),
+          bytes,
+          context.guardContext,
+          context.request.signal,
+        );
+        return new Response(null, { status: 204 });
+      } catch {
+        return unavailable(context.guardContext.requestId);
+      }
+    },
+    { parse: "none" },
+  );
+  app.post("/agent/screenshots/:token/cancel", async (raw) => {
+    const context = raw as Context;
+    if (!intake) return unavailable(context.guardContext.requestId);
+    try {
+      await intake.cancelToken(
+        required(context.params.token),
+        context.guardContext,
+        context.request.signal,
+      );
+      return new Response(null, { status: 204 });
+    } catch {
+      return unavailable(context.guardContext.requestId);
+    }
+  });
+}
+
+async function readCreate(request: Request) {
+  const declared = request.headers.get("content-length");
+  const length = declared === null ? undefined : Number(declared);
+  if (
+    length !== undefined &&
+    (!Number.isSafeInteger(length) || length < 1 || length > 8 * 1_024)
+  )
+    throw new Error();
+  const bytes = await readBounded(request, 8 * 1_024);
+  return parseCreate(JSON.parse(new TextDecoder().decode(bytes)));
+}
+
+function parseCreate(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error();
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some(
+      (key) =>
+        ![
+          "pageId",
+          "contextDigest",
+          "mediaType",
+          "byteSize",
+          "pixels",
+        ].includes(key),
+    )
+  )
+    throw new Error();
+  if (
+    typeof body.pageId !== "string" ||
+    typeof body.contextDigest !== "string" ||
+    typeof body.mediaType !== "string" ||
+    !Number.isSafeInteger(body.byteSize) ||
+    !Number.isSafeInteger(body.pixels)
+  )
+    throw new Error();
+  return {
+    pageId: body.pageId,
+    contextDigest: body.contextDigest,
+    mediaType: body.mediaType as "image/png",
+    byteSize: Number(body.byteSize),
+    pixels: Number(body.pixels),
+  };
+}
+
+async function readImage(request: Request): Promise<Uint8Array> {
+  return await readBounded(request, 8 * 1_024 * 1_024);
+}
+
+async function readBounded(
+  request: Request,
+  maximum: number,
+): Promise<Uint8Array> {
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      size += next.value.byteLength;
+      if (size > maximum) throw new Error();
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (size < 1) throw new Error();
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function required(value: string | undefined): string {
+  if (!value || !/^[0-9a-f-]{36}$/i.test(value)) throw new Error();
+  return value;
+}
+function requiredMime(request: Request): string {
+  const value = request.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (!value) throw new Error();
+  return value;
+}
+function unavailable(requestId: string): Response {
+  return Response.json(
+    {
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Screenshot Intake 当前不可用",
+      retryable: true,
+      requestId,
+    },
+    { status: 503 },
+  );
+}

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

@@ -0,0 +1,6 @@
+import type { createServerRuntime } from "../runtime.js";
+
+export type ScreenshotIntakeServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;

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

@@ -0,0 +1,26 @@
+import type { ScreenshotIntakeRecordV2 } from "./screenshot-intake-record.js";
+
+const SWEEP_CONCURRENCY = 8;
+
+export async function sweepScreenshotRecords(
+  records: ReadonlyMap<string, ScreenshotIntakeRecordV2>,
+  now: number,
+  cancel: (record: ScreenshotIntakeRecordV2) => Promise<void>,
+): Promise<void> {
+  const expired = [...records.values()].filter(
+    (record) => record.expiresAtMs <= now,
+  );
+  let cursor = 0;
+  await Promise.all(
+    Array.from(
+      { length: Math.min(SWEEP_CONCURRENCY, expired.length) },
+      async () => {
+        while (true) {
+          const record = expired[cursor++];
+          if (!record) return;
+          await cancel(record);
+        }
+      },
+    ),
+  );
+}