create-windy 0.5.1 → 0.6.0

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

@@ -0,0 +1,175 @@
+import { agentScreenshotIntakes } from "@southwind-ai/database";
+import { and, eq, gt, inArray, isNull, lte, or } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  PersistentScreenshotIntake,
+  ScreenshotIntakeRepository,
+} from "./screenshot-intake-repository.js";
+
+export class DrizzleScreenshotIntakeRepository implements ScreenshotIntakeRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async create(value: PersistentScreenshotIntake) {
+    await this.db.insert(agentScreenshotIntakes).values(values(value));
+  }
+
+  async find(tokenHash: string) {
+    const [row] = await this.db
+      .select()
+      .from(agentScreenshotIntakes)
+      .where(eq(agentScreenshotIntakes.tokenHash, tokenHash))
+      .limit(1);
+    return row ? map(row) : undefined;
+  }
+
+  async claimUpload(intakeId: string, uploadId: string, now: number) {
+    return await this.transition(intakeId, "created", "uploading", now, {
+      uploadId,
+    });
+  }
+
+  async completeUpload(intakeId: string, uploadId: string, fileId: string) {
+    const [row] = await this.db
+      .update(agentScreenshotIntakes)
+      .set({ status: "uploaded", fileId })
+      .where(
+        and(
+          eq(agentScreenshotIntakes.intakeId, intakeId),
+          eq(agentScreenshotIntakes.status, "uploading"),
+          eq(agentScreenshotIntakes.uploadId, uploadId),
+        ),
+      )
+      .returning();
+    return row ? map(row) : undefined;
+  }
+
+  reserve(intakeId: string, now: number) {
+    return this.transition(intakeId, "uploaded", "reserving", now);
+  }
+
+  async bind(intakeId: string, runId: string, now: number) {
+    const [row] = await this.db
+      .update(agentScreenshotIntakes)
+      .set({ status: "bound", runId })
+      .where(
+        and(
+          eq(agentScreenshotIntakes.intakeId, intakeId),
+          or(
+            and(
+              eq(agentScreenshotIntakes.status, "reserving"),
+              isNull(agentScreenshotIntakes.runId),
+            ),
+            and(
+              eq(agentScreenshotIntakes.status, "bound"),
+              eq(agentScreenshotIntakes.runId, runId),
+            ),
+          ),
+          gt(agentScreenshotIntakes.expiresAt, now),
+        ),
+      )
+      .returning();
+    return row ? map(row) : undefined;
+  }
+
+  async cancel(intakeId: string, _now: number) {
+    const [row] = await this.db
+      .update(agentScreenshotIntakes)
+      .set({ status: "cancelled" })
+      .where(
+        and(
+          eq(agentScreenshotIntakes.intakeId, intakeId),
+          inArray(agentScreenshotIntakes.status, [
+            "created",
+            "uploading",
+            "uploaded",
+            "reserving",
+          ]),
+        ),
+      )
+      .returning();
+    return row ? map(row) : undefined;
+  }
+
+  async listExpired(now: number, limit: number) {
+    const rows = await this.db
+      .select()
+      .from(agentScreenshotIntakes)
+      .where(
+        and(
+          lte(agentScreenshotIntakes.expiresAt, now),
+          inArray(agentScreenshotIntakes.status, [
+            "created",
+            "uploading",
+            "uploaded",
+            "reserving",
+          ]),
+        ),
+      )
+      .limit(limit);
+    return rows.map(map);
+  }
+
+  private async transition(
+    intakeId: string,
+    from: "created" | "uploaded",
+    to: "uploading" | "reserving",
+    now: number,
+    extra: { uploadId?: string } = {},
+  ) {
+    const [row] = await this.db
+      .update(agentScreenshotIntakes)
+      .set({ status: to, ...extra })
+      .where(
+        and(
+          eq(agentScreenshotIntakes.intakeId, intakeId),
+          eq(agentScreenshotIntakes.status, from),
+          gt(agentScreenshotIntakes.expiresAt, now),
+        ),
+      )
+      .returning();
+    return row ? map(row) : undefined;
+  }
+}
+
+function values(value: PersistentScreenshotIntake) {
+  return {
+    ...value,
+    deploymentPin: {
+      key: value.deployment.key,
+      identity: value.deployment.identity,
+      releaseDigest: value.deployment.releaseDigest,
+      offersDigest: value.deployment.offersDigest,
+    },
+    uploadId: value.uploadId,
+    fileId: value.fileId,
+    runId: value.runId,
+  };
+}
+
+function map(
+  row: typeof agentScreenshotIntakes.$inferSelect,
+): PersistentScreenshotIntake {
+  return {
+    intakeId: row.intakeId,
+    tokenHash: row.tokenHash,
+    actorId: row.actorId,
+    actorType: row.actorType,
+    scopeHash: row.scopeHash,
+    moduleName: row.moduleName,
+    operationKey: row.operationKey,
+    purpose: row.purpose,
+    pageId: row.pageId,
+    contextDigest: row.contextDigest,
+    deployment:
+      row.deploymentPin as unknown as PersistentScreenshotIntake["deployment"],
+    mediaType: row.mediaType,
+    byteSize: row.byteSize,
+    pixels: row.pixels,
+    status: row.status as PersistentScreenshotIntake["status"],
+    uploadId: row.uploadId ?? undefined,
+    fileId: row.fileId ?? undefined,
+    runId: row.runId ?? undefined,
+    createdAt: row.createdAt,
+    expiresAt: row.expiresAt,
+  };
+}

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

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiScreenshotIntakeCreateV2,
+} from "@southwind-ai/server-sdk";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { StorageRuntime } from "../storage/runtime.js";
+import {
+  bindingForScreenshot,
+  screenshotPurpose,
+} from "./screenshot-intake-v2-validation.js";
+import type {
+  PersistentScreenshotIntake,
+  ScreenshotIntakeRepository,
+} from "./screenshot-intake-repository.js";
+import type {
+  DurableScreenshotIntakeProducerV2,
+  DurableScreenshotIntakeSnapshotV2,
+} from "./screenshot-intake-durable.js";
+
+const STORAGE_PURPOSE = "agent-screenshot";
+
+export interface ScreenshotPageRegistryV2 {
+  resolve(input: {
+    readonly pageId: string;
+    readonly contextDigest: string;
+  }): { readonly operationKey: string } | undefined;
+}
+
+/** Platform-owned producer. The project owns only Registry resolution. */
+export class PersistentScreenshotIntakeProducer implements DurableScreenshotIntakeProducerV2 {
+  constructor(
+    private readonly registry: ScreenshotPageRegistryV2 | undefined,
+    private readonly repository: ScreenshotIntakeRepository,
+    private readonly storage: StorageRuntime,
+    private readonly artifacts: AiArtifactRuntime,
+    private readonly context: RequestGuardContext,
+    private readonly resolveModule: (
+      operationKey: string,
+    ) => string | undefined,
+    private readonly resolveDeployment: (
+      operationKey: string,
+    ) => PersistentScreenshotIntake["deployment"] | undefined,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async create(input: ModuleAiScreenshotIntakeCreateV2) {
+    const operationKey = this.registry?.resolve({
+      pageId: input.pageId,
+      contextDigest: input.contextDigest,
+    })?.operationKey;
+    const moduleName = operationKey && this.resolveModule(operationKey);
+    const deployment = operationKey && this.resolveDeployment(operationKey);
+    if (!operationKey || !moduleName || !deployment) throw unavailable();
+    const token = randomUUIDv7();
+    const expiresAt = this.now().getTime() + 60_000;
+    const binding = bindingForScreenshot(this.context);
+    await this.repository.create({
+      intakeId: randomUUIDv7(),
+      tokenHash: hash(token),
+      ...binding,
+      moduleName,
+      operationKey,
+      purpose: screenshotPurpose(operationKey),
+      pageId: input.pageId,
+      contextDigest: input.contextDigest,
+      deployment,
+      mediaType: input.mediaType,
+      byteSize: input.byteSize,
+      pixels: input.pixels,
+      status: "created",
+      createdAt: this.now().getTime(),
+      expiresAt,
+    });
+    return {
+      contractVersion: 2 as const,
+      intakeToken: token,
+      operationKey,
+      expiresAt: new Date(expiresAt).toISOString(),
+    };
+  }
+
+  async upload(input: {
+    readonly intakeToken: string;
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+  }): Promise<ModuleAiArtifactRef> {
+    const record = await this.require(
+      input.intakeToken,
+      "created",
+      "uploaded",
+      "reserving",
+      "bound",
+    );
+    if (
+      input.mediaType !== record.mediaType ||
+      input.bytes.byteLength !== record.byteSize
+    )
+      throw unavailable();
+    if (record.status !== "created") {
+      const artifact = await this.issue(record);
+      if (
+        artifact.mediaType !== record.mediaType ||
+        artifact.byteSize !== record.byteSize ||
+        artifact.sha256 !== hashBytes(input.bytes)
+      )
+        throw unavailable();
+      return artifact;
+    }
+    const upload = await this.storage.uploads.create({
+      ownerId: record.actorId,
+      purpose: STORAGE_PURPOSE,
+      authorizationBinding: {
+        moduleName: "system.agent",
+        scopeHash: record.scopeHash,
+      },
+      filename: `${record.intakeId}.png`,
+      mimeType: record.mediaType,
+      expectedByteSize: record.byteSize,
+      fileExpiresAt: new Date(record.expiresAt),
+    });
+    const claimed = await this.repository.claimUpload(
+      record.intakeId,
+      upload.id,
+      this.now().getTime(),
+    );
+    if (!claimed) {
+      await this.storage.uploads
+        .abort(upload.id, record.actorId)
+        .catch(() => undefined);
+      throw unavailable();
+    }
+    try {
+      await this.storage.uploads.appendPart({
+        sessionId: upload.id,
+        ownerId: record.actorId,
+        partNumber: 0,
+        byteOffset: 0,
+        byteSize: input.bytes.byteLength,
+        sha256: hashBytes(input.bytes),
+        body: stream(input.bytes),
+      });
+      const file = await this.storage.uploads.complete(
+        upload.id,
+        record.actorId,
+      );
+      if (
+        file.mimeType !== record.mediaType ||
+        file.byteSize !== record.byteSize ||
+        file.contentHash.value !== hashBytes(input.bytes)
+      )
+        throw unavailable();
+      const completed = await this.repository.completeUpload(
+        record.intakeId,
+        upload.id,
+        file.id,
+      );
+      if (!completed) throw unavailable();
+      return await this.issue(completed);
+    } catch {
+      await this.cancel({ intakeToken: input.intakeToken });
+      throw unavailable();
+    }
+  }
+
+  async reserve(token: string): Promise<void> {
+    const record = await this.require(token, "uploaded", "reserving", "bound");
+    if (record.status !== "uploaded") return;
+    if (await this.repository.reserve(record.intakeId, this.now().getTime()))
+      return;
+    await this.require(token, "reserving", "bound");
+  }
+
+  async bind(input: { readonly intakeToken: string; readonly runId: string }) {
+    const record = await this.require(input.intakeToken, "reserving", "bound");
+    const bound = await this.repository.bind(
+      record.intakeId,
+      input.runId,
+      this.now().getTime(),
+    );
+    if (!bound || bound.runId !== input.runId) throw unavailable();
+  }
+
+  async cancel(input: { readonly intakeToken: string }) {
+    const record = await this.repository.find(hash(input.intakeToken));
+    if (!record || !owned(record, this.context)) throw unavailable();
+    const cancelled = await this.repository.cancel(
+      record.intakeId,
+      this.now().getTime(),
+    );
+    if (!cancelled) return;
+    if (record.uploadId) {
+      await this.storage.uploads
+        .abort(record.uploadId, record.actorId)
+        .catch(() => undefined);
+    }
+  }
+
+  async recover(
+    token: string,
+  ): Promise<DurableScreenshotIntakeSnapshotV2 | undefined> {
+    const record = await this.repository.find(hash(token));
+    if (
+      !record ||
+      !owned(record, this.context) ||
+      record.expiresAt <= this.now().getTime() ||
+      !["created", "uploaded", "reserving", "bound"].includes(record.status)
+    )
+      return undefined;
+    return {
+      actorId: record.actorId,
+      actorType: record.actorType,
+      scopeHash: record.scopeHash,
+      moduleName: record.moduleName,
+      operationKey: record.operationKey,
+      purpose: record.purpose,
+      pageId: record.pageId,
+      contextDigest: record.contextDigest,
+      deployment: record.deployment,
+      expiresAtMs: record.expiresAt,
+      mediaType: record.mediaType,
+      byteSize: record.byteSize,
+      pixels: record.pixels,
+      state: durableState(record.status),
+      ...(record.status === "created"
+        ? {}
+        : { artifact: await this.issue(record) }),
+    };
+  }
+
+  private async issue(record: PersistentScreenshotIntake) {
+    if (!record.fileId) throw unavailable();
+    return await this.artifacts.issueScreenshot({
+      moduleName: record.moduleName,
+      actorId: record.actorId,
+      fileId: record.fileId,
+      purpose: record.purpose,
+      intakeId: record.intakeId,
+      expiresAt: record.expiresAt,
+    });
+  }
+
+  private async require(
+    token: string,
+    ...statuses: readonly PersistentScreenshotIntake["status"][]
+  ) {
+    const record = await this.repository.find(hash(token));
+    if (
+      !record ||
+      !owned(record, this.context) ||
+      record.expiresAt <= this.now().getTime() ||
+      !statuses.includes(record.status)
+    )
+      throw unavailable();
+    return record;
+  }
+}
+
+/** Bounded durable TTL cleanup; safe to resume after a server restart. */
+export async function cleanupPersistentScreenshotIntakes(
+  repository: ScreenshotIntakeRepository,
+  storage: StorageRuntime,
+  now = Date.now(),
+): Promise<void> {
+  const expired = await repository.listExpired(now, 64);
+  await Promise.all(
+    expired.map(async (record) => {
+      const cancelled = await repository.cancel(record.intakeId, now);
+      if (cancelled?.uploadId) {
+        await storage.uploads
+          .abort(cancelled.uploadId, cancelled.actorId)
+          .catch(() => undefined);
+      }
+    }),
+  );
+  await storage.uploads.cleanupExpired(64).catch(() => undefined);
+}
+
+function owned(
+  record: PersistentScreenshotIntake,
+  context: RequestGuardContext,
+) {
+  const binding = bindingForScreenshot(context);
+  return (
+    record.actorId === binding.actorId &&
+    record.actorType === binding.actorType &&
+    record.scopeHash === binding.scopeHash
+  );
+}
+
+function hash(value: string) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function durableState(
+  status: PersistentScreenshotIntake["status"],
+): DurableScreenshotIntakeSnapshotV2["state"] {
+  if (["created", "uploaded", "reserving", "bound"].includes(status))
+    return status as DurableScreenshotIntakeSnapshotV2["state"];
+  throw unavailable();
+}
+
+function hashBytes(value: Uint8Array) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function stream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+function unavailable() {
+  return new Error("Screenshot Intake unavailable");
+}

package/template/apps/server/src/agent/remote-runtime.ts

@@ -7,6 +7,7 @@ import type {
   AgentRuntimeTerminalEvent,
 } from "./run-contracts.js";
 import { AgentRuntimeError } from "./run-contracts.js";
+import { assertVisionReadinessPin } from "./vision-readiness-pin.js";
 
 export interface RemoteAgentRuntimeOptions {
   baseUrl: string;
@@ -31,6 +32,9 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
     request: AgentRuntimeOperation,
     idempotencyKey: string,
   ): Promise<AgentRuntimeStartResponse> {
+    if (request.readinessPin) {
+      await assertVisionReadinessPin(request.readinessPin, () => this.health());
+    }
     const remoteRequest: RemoteStartRunRequest = {
       kind: request.kind,
       operationKey: request.operationKey,
@@ -61,6 +65,9 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
       providerEgress: request.providerEgress,
       providerDataPolicy: request.providerDataPolicy,
       toolNetworkPolicy: request.toolNetworkPolicy,
+      ...(request.readinessPin === undefined
+        ? {}
+        : { readinessPin: request.readinessPin }),
       executionGrant: request.executionGrant,
       release: request.release,
       traceId: request.traceId,
@@ -112,7 +119,7 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
   }
 
   health(signal?: AbortSignal) {
-    return this.request("/health/ready", { signal });
+    return this.request("/health/vlm-ready", { signal });
   }
 
   private async request(

package/template/apps/server/src/agent/required-environment.ts

@@ -0,0 +1,5 @@
+export function requiredEnvironment(key: string): string {
+  const value = process.env[key]?.trim();
+  if (!value) throw new Error(`启用 AI Runtime 时缺少 ${key}`);
+  return value;
+}

package/template/apps/server/src/agent/run-attach.ts

@@ -0,0 +1,41 @@
+import type { RequestGuardContext } from "../guards.js";
+import { publicRunPath, runtimeErrorStatus } from "./run-definition-support.js";
+import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
+import { AgentRuntimeError, type AgentRuntimePort } from "./run-contracts.js";
+
+export async function attachAgentRun(input: {
+  readonly operationKey: string;
+  readonly runId: string;
+  readonly cursor: number;
+  readonly context: RequestGuardContext;
+  readonly signal?: AbortSignal;
+  readonly remote: AgentRuntimePort;
+  readonly authorize: () => Promise<unknown>;
+}) {
+  await input.authorize();
+  try {
+    const status = await input.remote.status(input.runId, input.signal);
+    if (status.runId !== input.runId) throw inaccessibleRun();
+    if (input.cursor > status.lastSequence) {
+      throw new AgentRunFacadeError(
+        "INVALID_INPUT",
+        "事件游标超出 Agent Run 当前序列",
+        400,
+      );
+    }
+    return {
+      ...status,
+      eventsUrl: publicRunPath(input.runId, "events", input.operationKey),
+    };
+  } catch (error) {
+    if (error instanceof AgentRuntimeError) {
+      if (error.code === "RUN_CONFLICT") throw inaccessibleRun();
+      throw new AgentRunFacadeError(
+        error.code,
+        error.message,
+        runtimeErrorStatus(error.code),
+      );
+    }
+    throw error;
+  }
+}

package/template/apps/server/src/agent/run-audit.ts

@@ -0,0 +1,49 @@
+import { randomUUIDv7 } from "bun";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type { RequestGuardContext } from "../guards.js";
+import { auditActor } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type {
+  AgentRuntimeArtifact,
+  AgentRuntimeRelease,
+} from "./run-contracts.js";
+import { debugActorAuditMetadata } from "./run-debug-authorization.js";
+
+export function auditAgentRun(input: {
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly context: RequestGuardContext;
+  readonly definition: ModuleAiOperationDefinition;
+  readonly operationKey: string;
+  readonly runId: string;
+  readonly release: AgentRuntimeRelease;
+  readonly artifacts: readonly AgentRuntimeArtifact[];
+  readonly traceId: string;
+}): void {
+  input.runtime.auditSink.recordEvent({
+    id: randomUUIDv7(),
+    action: input.definition.auditAction,
+    outcome: "success",
+    actor: auditActor(input.context),
+    target: { type: "agent-run", id: input.runId, label: input.operationKey },
+    requestId: input.context.requestId,
+    metadata: {
+      ...debugActorAuditMetadata(input.context.actor),
+      artifactCount: input.artifacts.length,
+      artifactBytes: input.artifacts.reduce(
+        (total, item) => total + item.byteSize,
+        0,
+      ),
+      requiredCapabilities: input.definition.requiredCapabilities,
+      inputModalities: input.definition.inputModalities ?? ["text"],
+      outputSchemaKey: input.definition.outputSchemaKey,
+      releaseId: input.release.releaseId,
+      operationVersion: input.release.operationVersion,
+      workflowVersion: input.release.workflowVersion,
+      promptVersion: input.release.promptVersion,
+      routeVersion: input.release.routeVersion,
+      toolSchemaVersion: input.release.toolSchemaVersion,
+      traceId: input.traceId,
+    },
+    occurredAt: new Date().toISOString(),
+  });
+}

package/template/apps/server/src/agent/run-contracts.ts

@@ -4,7 +4,10 @@ import type {
   AiProviderEgressPolicy,
   AiToolNetworkPolicy,
 } from "@southwind-ai/modules";
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
 
 export interface AgentRuntimeOperation {
   kind: "agent";
@@ -35,6 +38,8 @@ export interface AgentRuntimeOperation {
   providerEgress: AiProviderEgressPolicy;
   providerDataPolicy: AiProviderDataPolicy;
   toolNetworkPolicy: AiToolNetworkPolicy;
+  /** Host-attested VLM deployment facts; never supplied by a business Module. */
+  readinessPin?: AiRuntimeDeploymentV1;
   executionGrant: string;
   release: AgentRuntimeRelease;
   traceId: string;