create-windy 0.5.2 → 0.6.1

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;