create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/agent/vision-readiness.ts

@@ -0,0 +1,58 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type { AiRuntimeDeploymentV1 } from "@southwind-ai/server-sdk";
+import { createModuleAiOperationReadinessPort } from "../ai-runtime-readiness/operation-port.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import { AgentRunFacadeError } from "./run-errors.js";
+
+/** Rechecks the VLM deployment immediately before a vision Operation is admitted. */
+export async function requireVisionOperationReadiness(input: {
+  readonly definition: ModuleAiOperationDefinition;
+  readonly moduleName: string;
+  readonly modules: readonly ModuleManifest[];
+  readonly context: RequestGuardContext;
+  readonly signal: AbortSignal;
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly remote: AgentRuntimePort;
+}): Promise<AiRuntimeDeploymentV1 | undefined> {
+  if (!requiresImage(input.definition)) return undefined;
+  if (!input.definition.readiness) throw unavailable();
+  try {
+    const readiness = createModuleAiOperationReadinessPort({
+      moduleName: input.moduleName,
+      guardContext: input.context,
+      signal: input.signal,
+      modules: input.modules,
+      sources: [
+        { kind: "agent", health: (signal) => input.remote.health(signal) },
+      ],
+      runtime: input.runtime,
+    });
+    const result = await readiness.inspect({
+      operationKey: input.definition.key,
+    });
+    if (result.status !== "ready") throw unavailable();
+    return result.deployment;
+  } catch {
+    throw unavailable();
+  }
+}
+
+function unavailable(): AgentRunFacadeError {
+  return new AgentRunFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "VLM Runtime 当前不可用",
+    503,
+  );
+}
+
+function requiresImage(definition: ModuleAiOperationDefinition): boolean {
+  return Boolean(
+    definition.inputModalities?.includes("image") ||
+    definition.requiredCapabilities.includes("vision"),
+  );
+}

package/template/apps/server/src/ai-artifact/runtime-reference.test.ts

@@ -0,0 +1,135 @@
+import { expect, test } from "bun:test";
+import type { ModuleAiArtifactRef } from "@southwind-ai/server-sdk";
+import { AiArtifactCodec, type AiArtifactClaims } from "./codec.js";
+import { AiArtifactRuntime } from "./runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+
+const now = new Date("2026-08-05T00:00:00.000Z");
+
+test("AI Artifact validator 核对 codec claims 的 Module/Actor/expiry/metadata", () => {
+  const codec = new AiArtifactCodec("artifact-validator-secret".repeat(2));
+  const claims: AiArtifactClaims = {
+    version: 1,
+    moduleName: "evidence",
+    actorId: "actor-1",
+    source: {
+      fileId: "file-1",
+      purpose: "evidence-source",
+      resourceType: "case",
+      resourceId: "case-1",
+    },
+    mediaType: "image/png",
+    byteSize: 1,
+    sha256: "a".repeat(64),
+    issuedAt: now.toISOString(),
+    expiresAt: "2026-08-05T00:01:00.000Z",
+  };
+  const reference: ModuleAiArtifactRef = {
+    value: codec.encode(claims),
+    mediaType: claims.mediaType,
+    byteSize: claims.byteSize,
+    sha256: claims.sha256,
+    expiresAt: claims.expiresAt,
+  };
+  const runtime = new AiArtifactRuntime(
+    codec,
+    {} as never,
+    {} as never,
+    [],
+    {} as never,
+    async () => undefined,
+    () => now,
+  );
+
+  expect(
+    runtime.validateReference(reference, claims.actorId, claims.moduleName),
+  ).toEqual(reference);
+  expect(() =>
+    runtime.validateReference(reference, "other-actor", claims.moduleName),
+  ).toThrow("AI Artifact 当前授权已失效");
+  expect(() =>
+    runtime.validateReference(reference, claims.actorId, "other-module"),
+  ).toThrow("AI Artifact 当前授权已失效");
+  expect(() =>
+    runtime.validateReference(
+      { ...reference, byteSize: 2 },
+      claims.actorId,
+      claims.moduleName,
+    ),
+  ).toThrow("AI Artifact 当前授权已失效");
+
+  const expiredRuntime = new AiArtifactRuntime(
+    codec,
+    {} as never,
+    {} as never,
+    [],
+    {} as never,
+    async () => undefined,
+    () => new Date("2026-08-05T00:02:00.000Z"),
+  );
+  expect(() =>
+    expiredRuntime.validateReference(
+      reference,
+      claims.actorId,
+      claims.moduleName,
+    ),
+  ).toThrow("AI Artifact 当前授权已失效");
+});
+
+test("Host 签发 screenshot Artifact 时只引用受治理 Storage 文件", async () => {
+  const storage = createStorageRuntime({}, undefined, undefined, () => now);
+  const bytes = Uint8Array.from(
+    Buffer.from(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC",
+      "base64",
+    ),
+  );
+  const upload = await storage.uploads.create({
+    ownerId: "actor-1",
+    purpose: "agent-screenshot",
+    authorizationBinding: {
+      moduleName: "system.agent",
+      scopeHash: "a".repeat(64),
+    },
+    filename: "plan.png",
+    mimeType: "image/png",
+    expectedByteSize: bytes.byteLength,
+    fileExpiresAt: new Date(now.getTime() + 60_000),
+  });
+  await storage.uploads.appendPart({
+    sessionId: upload.id,
+    ownerId: "actor-1",
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: bytes.byteLength,
+    sha256: "b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640",
+    body: new Blob([bytes]).stream(),
+  });
+  const file = await storage.uploads.complete(upload.id, "actor-1");
+  const runtime = new AiArtifactRuntime(
+    new AiArtifactCodec("host-screenshot-secret".repeat(2)),
+    {} as never,
+    {} as never,
+    [],
+    storage,
+    async () => undefined,
+    () => now,
+  );
+  const reference = await runtime.issueScreenshot({
+    moduleName: "evidence",
+    actorId: "actor-1",
+    fileId: file.id,
+    purpose: "agent.screenshot.evidence.image.inspect",
+    intakeId: "intake-1",
+    expiresAt: now.getTime() + 30_000,
+  });
+  expect(reference.value).not.toContain(file.id);
+  expect(
+    runtime.validateReference(
+      reference,
+      "actor-1",
+      "evidence",
+      "agent.screenshot.evidence.image.inspect",
+    ),
+  ).toEqual(reference);
+});

package/template/apps/server/src/ai-artifact/runtime.ts

@@ -45,6 +45,58 @@ export class AiArtifactRuntime {
     };
   }
 
+  /**
+   * Screenshot bytes are stored by the Host, never by a business Module.  The
+   * opaque reference retains the module Operation binding only for Run policy.
+   */
+  async issueScreenshot(input: {
+    readonly moduleName: string;
+    readonly actorId: string;
+    readonly fileId: string;
+    readonly purpose: string;
+    readonly intakeId: string;
+    readonly expiresAt: number;
+  }): Promise<ModuleAiArtifactRef> {
+    if (
+      !input.purpose.startsWith("agent.screenshot.") ||
+      !Number.isFinite(input.expiresAt) ||
+      input.expiresAt <= this.now().getTime()
+    )
+      throw forbidden();
+    const file = await this.storage.files.open(input.fileId, input.actorId);
+    const opened = {
+      ...file,
+      sha256: file.contentHash.value,
+    };
+    try {
+      return this.reference(
+        {
+          version: 1,
+          moduleName: input.moduleName,
+          actorId: input.actorId,
+          source: {
+            fileId: input.fileId,
+            purpose: input.purpose,
+            resourceType: "agent-screenshot",
+            resourceId: input.intakeId,
+          },
+          mediaType: opened.mimeType,
+          byteSize: opened.byteSize,
+          sha256: opened.sha256,
+          issuedAt: this.now().toISOString(),
+          expiresAt: new Date(input.expiresAt).toISOString(),
+        },
+        opened,
+        Math.max(
+          1,
+          Math.floor((input.expiresAt - this.now().getTime()) / 1_000),
+        ),
+      );
+    } finally {
+      await opened.body.cancel().catch(() => undefined);
+    }
+  }
+
   async rotate(
     token: string,
     actorId: string,
@@ -62,6 +114,55 @@ export class AiArtifactRuntime {
     return this.open(this.requireClaims(token), signal);
   }
 
+  async currentGuardContext(actorId: string, signal: AbortSignal) {
+    const actor = await this.resolveActor(actorId);
+    if (!actor) throw forbidden();
+    return this.runtime.createGuardContextForActor(
+      new Request("http://ai-artifact.internal/run-bound", { signal }),
+      actor,
+    );
+  }
+
+  async openRunBound(
+    reference: ModuleAiArtifactRef,
+    actorId: string,
+    moduleName: string,
+    signal: AbortSignal,
+  ) {
+    const claims = this.codec.decode(reference.value);
+    if (
+      claims.actorId !== actorId ||
+      claims.moduleName !== moduleName ||
+      !sameMetadata(reference, claims)
+    ) {
+      throw forbidden();
+    }
+    const opened = await this.open(claims, signal);
+    return {
+      opened,
+      refreshed: this.reference(claims, opened, 900),
+    };
+  }
+
+  validateReference(
+    reference: ModuleAiArtifactRef,
+    actorId: string,
+    moduleName: string,
+    purpose?: string,
+  ): ModuleAiArtifactRef {
+    try {
+      const claims = this.requireClaims(reference.value, actorId, moduleName);
+      if (
+        !sameMetadata(reference, claims) ||
+        (purpose !== undefined && claims.source.purpose !== purpose)
+      )
+        throw new Error("AI Artifact metadata mismatch");
+      return Object.freeze({ ...reference });
+    } catch {
+      throw forbidden();
+    }
+  }
+
   private async issue(
     moduleName: string,
     guardContext: RequestGuardContext,
@@ -150,11 +251,18 @@ export class AiArtifactRuntime {
       request,
       actor,
     );
-    const opened = await this.storagePort(
-      claims.moduleName,
-      guardContext,
-      signal,
-    ).openResourceFile(claims.source);
+    const opened =
+      claims.source.resourceType === "agent-screenshot"
+        ? await openedScreenshot(
+            this.storage,
+            claims.source.fileId,
+            claims.actorId,
+          )
+        : await this.storagePort(
+            claims.moduleName,
+            guardContext,
+            signal,
+          ).openResourceFile(claims.source);
     if (
       opened.mimeType !== claims.mediaType ||
       opened.byteSize !== claims.byteSize ||
@@ -187,6 +295,27 @@ export class AiArtifactRuntime {
   }
 }
 
+async function openedScreenshot(
+  storage: ModuleStorageServices,
+  fileId: string,
+  actorId: string,
+) {
+  const file = await storage.files.open(fileId, actorId);
+  return { ...file, sha256: file.contentHash.value };
+}
+
+function sameMetadata(
+  reference: ModuleAiArtifactRef,
+  claims: AiArtifactClaims,
+) {
+  return (
+    reference.mediaType === claims.mediaType &&
+    reference.byteSize === claims.byteSize &&
+    reference.sha256 === claims.sha256 &&
+    (!reference.expiresAt || reference.expiresAt === claims.expiresAt)
+  );
+}
+
 function boundedTtl(value: number, minimum: number, maximum: number) {
   if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
     throw new ModuleAiArtifactError(

package/template/apps/server/src/ai-output-artifact/cleanup.ts

@@ -0,0 +1,214 @@
+import type { StorageRuntime } from "../storage/runtime.js";
+import type {
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+} from "./contracts.js";
+import type { AiOutputArtifactRepository } from "./repository.js";
+import type { AiOutputArtifactService } from "./service.js";
+import type { AiOutputArtifactStorageWriterFactory } from "./storage-writer.js";
+import { purgeCompletedOutputUpload } from "./storage-recovery.js";
+
+export class AiOutputArtifactCleanupService {
+  readonly #now: () => Date;
+
+  constructor(
+    private readonly repository: AiOutputArtifactRepository,
+    private readonly storage: StorageRuntime,
+    private readonly writers: AiOutputArtifactStorageWriterFactory,
+    now: () => Date = () => new Date(),
+  ) {
+    this.#now = now;
+  }
+
+  async abortAuthorized(
+    service: AiOutputArtifactService,
+    scopeId: string,
+    grant: string,
+    signal: AbortSignal = new AbortController().signal,
+  ) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      signal.throwIfAborted();
+      const scope = await service.requireRevocable(scopeId, grant);
+      if (scope.status === "aborted") return true;
+      if (
+        await this.abortScope(scopeId, "aborted", true, scope.revision, signal)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async abortOpenAuthorized(
+    service: AiOutputArtifactService,
+    scopeId: string,
+    grant: string,
+    signal: AbortSignal = new AbortController().signal,
+  ) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      signal.throwIfAborted();
+      const scope = await service.requireRevocable(scopeId, grant);
+      if (["sealed", "aborted", "cleaned"].includes(scope.status)) return true;
+      if (
+        await this.abortScope(scopeId, "aborted", false, scope.revision, signal)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async abortRun(runId: string) {
+    const scopes = await this.repository.listScopesByRun(runId);
+    if (!scopes.length) return false;
+    const results: boolean[] = [];
+    for (const scope of scopes) {
+      results.push(await this.abortScope(scope.scopeId, "aborted"));
+    }
+    return results.every(Boolean);
+  }
+
+  /**
+   * 远端结果未知时只撤销仍可写的 scope。并发 seal 代表 Runtime 已完成提交，
+   * 必须保留，由调用方返回不确定状态而不是删除成功产物。
+   */
+  async abortOpenRun(runId: string) {
+    const scopes = await this.repository.listScopesByRun(runId);
+    if (!scopes.length) return false;
+    const results: boolean[] = [];
+    for (const scope of scopes) {
+      if (["sealed", "aborted", "cleaned"].includes(scope.status)) {
+        results.push(true);
+        continue;
+      }
+      const aborted = await this.abortScope(scope.scopeId, "aborted", false);
+      if (aborted) {
+        results.push(true);
+        continue;
+      }
+      const current = await this.repository.getScope(scope.scopeId);
+      results.push(
+        Boolean(
+          current && ["sealed", "aborted", "cleaned"].includes(current.status),
+        ),
+      );
+    }
+    return results.every(Boolean);
+  }
+
+  async cleanupExpired(limit = 100) {
+    await this.repository.clearExpiredGrantHashes(
+      this.#now().toISOString(),
+      limit,
+    );
+    const scopes = await this.repository.listCleanupScopes(
+      this.#now().toISOString(),
+      limit,
+    );
+    let cleaned = 0;
+    let pending = 0;
+    for (const scope of scopes) {
+      if (await this.abortScope(scope.scopeId, "cleaned")) cleaned += 1;
+      else pending += 1;
+    }
+    return { inspected: scopes.length, cleaned, pending };
+  }
+
+  private async abortScope(
+    scopeId: string,
+    terminal: "aborted" | "cleaned",
+    includeSealed = true,
+    expectedRevision?: number,
+    signal: AbortSignal = new AbortController().signal,
+  ): Promise<boolean> {
+    signal.throwIfAborted();
+    const current = await this.repository.getScope(scopeId);
+    if (!current) return true;
+    if (current.status === "cleaned") return true;
+    if (terminal === "aborted" && current.status === "aborted") return true;
+    if (
+      expectedRevision !== undefined &&
+      current.revision !== expectedRevision
+    ) {
+      return false;
+    }
+    if (
+      current.status === "aborting" &&
+      Date.parse(current.updatedAt) > this.#now().getTime() - 60_000
+    ) {
+      return false;
+    }
+    const claimed = await this.repository.transitionScope(
+      scopeId,
+      current.revision,
+      includeSealed
+        ? ["open", "sealed", "cleanup-pending", "aborted", "aborting"]
+        : ["open", "cleanup-pending", "aborted", "aborting"],
+      "aborting",
+      this.#now().toISOString(),
+    );
+    if (!claimed) return false;
+    const artifacts = await this.repository.listArtifacts(scopeId);
+    let failed = false;
+    for (const artifact of artifacts) {
+      signal.throwIfAborted();
+      if (!(await this.cleanupArtifact(claimed, artifact, signal)))
+        failed = true;
+    }
+    const next = failed ? "cleanup-pending" : terminal;
+    const finalized = await this.repository.transitionScope(
+      scopeId,
+      claimed.revision,
+      ["aborting"],
+      next,
+      this.#now().toISOString(),
+    );
+    return !failed && Boolean(finalized);
+  }
+
+  private async cleanupArtifact(
+    scope: AiOutputArtifactScope,
+    artifact: AiOutputArtifactRecord,
+    signal: AbortSignal,
+  ) {
+    if (artifact.status === "aborted") return true;
+    const claimed = await this.repository.transitionArtifact(
+      artifact.artifactId,
+      artifact.generation,
+      ["creating", "uploading", "completed", "cleanup-pending", "aborting"],
+      "aborting",
+      this.#now().toISOString(),
+    );
+    if (!claimed) return false;
+    try {
+      const purged = await purgeCompletedOutputUpload(
+        this.storage,
+        scope,
+        claimed,
+        signal,
+      );
+      if (!purged && claimed.uploadSessionId) {
+        await this.writers
+          .create(scope, signal)
+          .abortUpload(claimed.uploadSessionId);
+      }
+      const finalized = await this.repository.transitionArtifact(
+        claimed.artifactId,
+        claimed.generation,
+        ["aborting"],
+        "aborted",
+        this.#now().toISOString(),
+      );
+      return Boolean(finalized);
+    } catch {
+      await this.repository.transitionArtifact(
+        claimed.artifactId,
+        claimed.generation,
+        ["aborting"],
+        "cleanup-pending",
+        this.#now().toISOString(),
+      );
+      return false;
+    }
+  }
+}