create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/speech/output-artifact-policy.ts

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  ModuleAiOperationReadinessPortV1,
+  ModuleAiOperationReadyV1,
+} from "@southwind-ai/server-sdk";
+import type { AiOutputArtifactScope } from "../ai-output-artifact/contracts.js";
+import type { AiOutputArtifactLimitSet } from "../ai-output-artifact/policy.js";
+import type { SpeechRuntimeOperation } from "./contracts.js";
+import { speechRequestFingerprint } from "./fingerprint.js";
+import { SpeechOutputArtifactHostError } from "./output-artifact-error.js";
+
+export const speechOutputArtifactCapabilityV1 = "speech.output-artifact.v1";
+
+export function requireSpeechOutputReady(
+  value: Awaited<ReturnType<ModuleAiOperationReadinessPortV1["inspect"]>>,
+  operationKey: string,
+  now: Date,
+): ModuleAiOperationReadyV1 {
+  if (
+    value.status !== "ready" ||
+    value.operationKey !== operationKey ||
+    value.runtimeKind !== "speech" ||
+    value.offers.length !== 1 ||
+    value.offers[0]?.variant !== "normalize" ||
+    !value.offers[0].capabilities.includes(speechOutputArtifactCapabilityV1) ||
+    Date.parse(value.validUntil) <= now.getTime()
+  ) {
+    throw new SpeechOutputArtifactHostError(
+      "CAPABILITY_UNAVAILABLE",
+      "Speech Output Artifact 暂时不可用",
+    );
+  }
+  return value;
+}
+
+export function speechOutputPolicyLimits(
+  definition: ModuleAiOperationDefinition,
+  ready: ModuleAiOperationReadyV1,
+) {
+  const operation = outputLimits(definition);
+  const runtime = offerLimits(ready);
+  return {
+    operation,
+    runtime,
+    readiness: minimumLimits(operation, runtime),
+  };
+}
+
+export function speechOutputInvocationDigest(
+  invocation: SpeechRuntimeOperation,
+  ready: ModuleAiOperationReadyV1,
+  policyDigest: string,
+) {
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        invocationFingerprint: speechRequestFingerprint(invocation),
+        deployment: ready.deployment,
+        policyDigest,
+      }),
+    )
+    .digest("hex");
+}
+
+export function validSpeechOutputScopeLimits(
+  scope: AiOutputArtifactScope,
+  definition: ModuleAiOperationDefinition,
+) {
+  return (
+    scope.allowedMediaTypes.length === 1 &&
+    scope.allowedMediaTypes[0] === "audio/wav" &&
+    scope.maxArtifacts === 1 &&
+    scope.maxArtifactBytes <= definition.limits.maxOutputBytes &&
+    scope.maxTotalBytes <= definition.limits.maxOutputBytes &&
+    scope.artifactCount === 1 &&
+    scope.completedByteSize <= scope.maxTotalBytes
+  );
+}
+
+function outputLimits(
+  definition: ModuleAiOperationDefinition,
+): AiOutputArtifactLimitSet {
+  return {
+    maxArtifactBytes: definition.limits.maxOutputBytes,
+    maxArtifacts: 1,
+    maxTotalBytes: definition.limits.maxOutputBytes,
+    maxDurationSeconds: definition.limits.maxDurationSeconds,
+  };
+}
+
+function offerLimits(
+  ready: ModuleAiOperationReadyV1,
+): AiOutputArtifactLimitSet {
+  const limits = ready.offers[0].limits;
+  return {
+    maxArtifactBytes: limits.maxOutputBytes,
+    maxArtifacts: limits.maxArtifacts ?? 1,
+    maxTotalBytes: limits.maxOutputBytes,
+    maxDurationSeconds: limits.maxDurationSeconds,
+  };
+}
+
+function minimumLimits(
+  a: AiOutputArtifactLimitSet,
+  b: AiOutputArtifactLimitSet,
+) {
+  return {
+    maxArtifactBytes: Math.min(a.maxArtifactBytes, b.maxArtifactBytes),
+    maxArtifacts: Math.min(a.maxArtifacts, b.maxArtifacts),
+    maxTotalBytes: Math.min(a.maxTotalBytes, b.maxTotalBytes),
+    maxDurationSeconds: Math.min(a.maxDurationSeconds, b.maxDurationSeconds),
+  };
+}

package/template/apps/server/src/speech/output-artifact-replay.ts

@@ -0,0 +1,91 @@
+import type { AiOutputArtifactPolicy } from "../ai-output-artifact/policy.js";
+import type { AiOutputArtifactService } from "../ai-output-artifact/service.js";
+import { outputScopeIdentity } from "../ai-output-artifact/service-input.js";
+import {
+  outputConflict,
+  outputSinkDescriptor,
+} from "../ai-output-artifact/service-support.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+
+export async function replaySpeechOutputScope(input: {
+  service: AiOutputArtifactService;
+  runId: string;
+  moduleName: string;
+  operationKey: string;
+  idempotencyKey: string;
+  invocationDigest: string;
+  deployment: {
+    identity: string;
+    releaseDigest: string;
+    offersDigest: string;
+  };
+  policy: AiOutputArtifactPolicy;
+  context: RequestGuardContext;
+  now: Date;
+}) {
+  const scopes = (
+    await input.service.options.repository.listScopesByRun(input.runId)
+  ).filter(({ runtimeKind }) => runtimeKind === "speech");
+  if (!scopes.length) return undefined;
+  if (scopes.length !== 1) throw outputConflict();
+  const scope = scopes[0]!;
+  const grantGeneration = scope.activeGrantGeneration;
+  if (!grantGeneration || !scope.grantHash) throw outputConflict();
+  const actorScope = input.context.actor.scopeContext;
+  const identity = outputScopeIdentity({
+    runId: input.runId,
+    moduleName: input.moduleName,
+    operationKey: input.operationKey,
+    runtimeKind: "speech",
+    idempotencyKey: input.idempotencyKey,
+    invocationDigest: input.invocationDigest,
+    dataClassification: input.policy.dataClassification,
+    deploymentIdentity: input.deployment.identity,
+    releaseDigest: input.deployment.releaseDigest,
+    offersDigest: input.deployment.offersDigest,
+    policy: input.policy,
+    context: input.context,
+  });
+  const checks = {
+    context: isServerScopeContext(actorScope),
+    status: ["open", "sealed"].includes(scope.status),
+    expiry:
+      (scope.status === "open" ? scope.scopeExpiresAt : scope.refExpiresAt) >
+      input.now.toISOString(),
+    actor: scope.actorId === input.context.actor.id,
+    tenant:
+      isServerScopeContext(actorScope) &&
+      scope.tenantId === actorScope.tenantId,
+    scope:
+      isServerScopeContext(actorScope) &&
+      scope.scopeHash === captureAuthorizationScope(actorScope).hash,
+    module: scope.moduleName === input.moduleName,
+    operation: scope.operationKey === input.operationKey,
+    run: scope.runId === input.runId,
+    idempotency: scope.idempotencyHash === identity.idempotencyHash,
+    invocation: scope.fingerprint === identity.fingerprint,
+    identity: scope.deploymentIdentity === input.deployment.identity,
+    release: scope.releaseDigest === input.deployment.releaseDigest,
+    offers: scope.offersDigest === input.deployment.offersDigest,
+    policy: scope.policyDigest === input.policy.digest,
+    artifactLimit: scope.maxArtifactBytes === input.policy.maxArtifactBytes,
+    artifactCount: scope.maxArtifacts === input.policy.maxArtifacts,
+    totalLimit: scope.maxTotalBytes === input.policy.maxTotalBytes,
+  };
+  if (Object.values(checks).some((value) => !value)) {
+    const error = outputConflict();
+    throw error;
+  }
+  return {
+    runId: scope.runId,
+    scopeId: scope.scopeId,
+    grantGeneration,
+    descriptor: outputSinkDescriptor(scope, grantGeneration),
+    references:
+      scope.status === "sealed"
+        ? await input.service.claimSealedScope(scope.scopeId)
+        : undefined,
+  };
+}

package/template/apps/server/src/speech/remote-response.ts

@@ -0,0 +1,158 @@
+import {
+  SpeechRuntimeError,
+  type SpeechRuntimeStartResponse,
+} from "./contracts.js";
+
+export const speechControlResponseLimit = 64 * 1024;
+export const speechStreamResponseLimit = 64 * 1024 * 1024 + 64 * 1024;
+
+export function boundSpeechResponse(response: Response, maxBytes: number) {
+  const declared = response.headers.get("content-length");
+  if (
+    declared !== null &&
+    (!/^(0|[1-9]\d*)$/.test(declared) || Number(declared) > maxBytes)
+  ) {
+    void response.body?.cancel().catch(() => undefined);
+    throw invalidSpeechResponse();
+  }
+  if (!response.body) return response;
+  const reader = response.body.getReader();
+  let total = 0;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        total += next.value.byteLength;
+        if (total > maxBytes) {
+          void reader.cancel("speech-response-limit").catch(() => undefined);
+          controller.error(invalidSpeechResponse());
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+export async function readBoundedSpeechJson(
+  response: Response,
+  maxBytes: number,
+) {
+  const contentType = response.headers.get("content-type")?.split(";", 1)[0];
+  if (
+    contentType?.trim().toLowerCase() !== "application/json" ||
+    response.headers.has("content-encoding")
+  ) {
+    void response.body?.cancel().catch(() => undefined);
+    throw invalidSpeechResponse();
+  }
+  const declared = response.headers.get("content-length");
+  const bounded = boundSpeechResponse(response, maxBytes);
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await bounded.arrayBuffer());
+  } catch {
+    throw invalidSpeechResponse();
+  }
+  if (declared !== null && Number(declared) !== bytes.byteLength) {
+    throw invalidSpeechResponse();
+  }
+  try {
+    return JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    ) as unknown;
+  } catch {
+    throw invalidSpeechResponse();
+  }
+}
+
+export async function parseSpeechStartResponse(
+  response: Response,
+): Promise<SpeechRuntimeStartResponse> {
+  const value = await readBoundedSpeechJson(
+    response,
+    speechControlResponseLimit,
+  );
+  if (!isRecord(value)) throw invalidSpeechResponse();
+  const { runId, status, eventsUrl } = value;
+  if (
+    typeof runId !== "string" ||
+    !runId.trim() ||
+    typeof status !== "string" ||
+    !["accepted", "running", "completed", "failed", "cancelled"].includes(
+      status,
+    ) ||
+    typeof eventsUrl !== "string" ||
+    !eventsUrl.startsWith("/")
+  ) {
+    throw invalidSpeechResponse();
+  }
+  return { runId, status, eventsUrl };
+}
+
+export async function safeSpeechRemoteError(response: Response) {
+  try {
+    const value = await readBoundedSpeechJson(
+      response,
+      speechControlResponseLimit,
+    );
+    return fixedRemoteError(
+      isRecord(value) && typeof value.code === "string" ? value.code : "",
+    );
+  } catch {
+    return unavailable();
+  }
+}
+
+export function invalidSpeechResponse() {
+  return new SpeechRuntimeError(
+    "INVALID_RESPONSE",
+    "Speech Runtime 响应无效",
+    false,
+  );
+}
+
+function fixedRemoteError(code: string) {
+  if (code === "CAPABILITY_UNAVAILABLE") {
+    return new SpeechRuntimeError(code, "Speech Runtime 缺少所需能力", true);
+  }
+  if (code === "RUN_CONFLICT") {
+    return new SpeechRuntimeError(code, "Speech 幂等语义冲突", false);
+  }
+  if (code === "FORBIDDEN") {
+    return new SpeechRuntimeError(code, "Speech Runtime 拒绝访问", false);
+  }
+  if (code === "BUDGET_EXCEEDED") {
+    return new SpeechRuntimeError(code, "Speech Runtime 执行预算超限", false);
+  }
+  if (code === "INVALID_INPUT") {
+    return new SpeechRuntimeError(code, "Speech Runtime 拒绝无效输入", false);
+  }
+  return unavailable();
+}
+
+function unavailable() {
+  return new SpeechRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    "Speech Runtime 暂不可用",
+    true,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/apps/server/src/speech/remote-runtime.test.ts

@@ -69,6 +69,7 @@ describe("Remote Speech Runtime", () => {
     });
     await expect(conflict.start(request, "scoped-key")).rejects.toMatchObject({
       code: "RUN_CONFLICT",
+      message: "Speech 幂等语义冲突",
     });
 
     const invalid = new RemoteSpeechRuntime({
@@ -85,4 +86,93 @@ describe("Remote Speech Runtime", () => {
       SpeechRuntimeError,
     );
   });
+
+  test("start 在无 Content-Length 时仍流式硬限制响应", async () => {
+    const valid = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () =>
+        streamedJson({
+          runId: "speech-1",
+          status: "accepted",
+          eventsUrl: "/api/speech/runs/speech-1/events",
+        }),
+    });
+    await expect(valid.start(request, "scoped-key")).resolves.toMatchObject({
+      runId: "speech-1",
+    });
+
+    const oversized = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () => streamedJson({ padding: "x".repeat(65 * 1024) }),
+    });
+    await expect(oversized.start(request, "scoped-key")).rejects.toMatchObject({
+      code: "INVALID_RESPONSE",
+    });
+  });
+
+  test("远端错误 message 中的 Secret 与 locator 不会透传", async () => {
+    const runtime = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () =>
+        streamedJson(
+          {
+            code: "CAPABILITY_UNAVAILABLE",
+            message:
+              "Bearer super-secret at /private/model and s3://customer-bucket/key",
+            retryable: false,
+          },
+          503,
+        ),
+    });
+
+    const error = await runtime
+      .start(request, "scoped-key")
+      .catch((value) =>
+        value instanceof Error ? value : new Error(String(value)),
+      );
+    expect(error).toMatchObject({
+      code: "CAPABILITY_UNAVAILABLE",
+      message: "Speech Runtime 缺少所需能力",
+    });
+    expect(String(error)).not.toContain("super-secret");
+    expect(String(error)).not.toContain("customer-bucket");
+  });
+
+  test("events 非 2xx 不会把远端错误正文直接返回给 Route", async () => {
+    const runtime = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () =>
+        streamedJson(
+          {
+            code: "FORBIDDEN",
+            message: "Bearer event-secret at /private/events.db",
+          },
+          403,
+        ),
+    });
+
+    const error = await runtime.events("speech-1", 0).catch((value) => value);
+    expect(error).toMatchObject({
+      code: "FORBIDDEN",
+      message: "Speech Runtime 拒绝访问",
+    });
+    expect(String(error)).not.toContain("event-secret");
+  });
 });
+
+function streamedJson(value: unknown, status = 200) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  return new Response(
+    new ReadableStream({
+      start(controller) {
+        controller.enqueue(bytes);
+        controller.close();
+      },
+    }),
+    { status, headers: { "content-type": "application/json" } },
+  );
+}

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

@@ -4,6 +4,13 @@ import {
   type SpeechRuntimePort,
   type SpeechRuntimeStartResponse,
 } from "./contracts.js";
+import {
+  boundSpeechResponse,
+  parseSpeechStartResponse,
+  safeSpeechRemoteError,
+  speechControlResponseLimit,
+  speechStreamResponseLimit,
+} from "./remote-response.js";
 
 export class RemoteSpeechRuntime implements SpeechRuntimePort {
   readonly #baseUrl: string;
@@ -31,26 +38,32 @@ export class RemoteSpeechRuntime implements SpeechRuntimePort {
     request: SpeechRuntimeOperation,
     idempotencyKey: string,
     signal?: AbortSignal,
+    outputArtifactGrant?: string,
   ): Promise<SpeechRuntimeStartResponse> {
     const response = await this.request("/api/speech/runs", {
       method: "POST",
       headers: {
         "content-type": "application/json",
         "idempotency-key": idempotencyKey,
+        ...(outputArtifactGrant
+          ? { "x-ai-output-artifact-grant": outputArtifactGrant }
+          : {}),
       },
       body: JSON.stringify(request),
       signal,
     });
-    if (!response.ok) throw await remoteError(response);
-    return parseStartResponse(await response.json());
+    if (!response.ok) throw await safeSpeechRemoteError(response);
+    return parseSpeechStartResponse(response);
   }
 
-  events(runId: string, cursor: number, signal?: AbortSignal) {
-    return this.request(
+  async events(runId: string, cursor: number, signal?: AbortSignal) {
+    const response = await this.request(
       `/api/speech/runs/${encodeURIComponent(runId)}/events?after=${cursor}`,
       { signal },
-      false,
+      speechStreamResponseLimit,
     );
+    if (!response.ok) throw await safeSpeechRemoteError(response);
+    return response;
   }
 
   result(runId: string, signal?: AbortSignal) {
@@ -59,6 +72,7 @@ export class RemoteSpeechRuntime implements SpeechRuntimePort {
       {
         signal,
       },
+      speechStreamResponseLimit,
     );
   }
 
@@ -66,6 +80,7 @@ export class RemoteSpeechRuntime implements SpeechRuntimePort {
     return this.request(
       `/api/speech/runs/${encodeURIComponent(runId)}/artifact`,
       { signal },
+      speechStreamResponseLimit,
     );
   }
 
@@ -88,7 +103,7 @@ export class RemoteSpeechRuntime implements SpeechRuntimePort {
   private request(
     path: string,
     init: RequestInit = {},
-    bounded = true,
+    maxBytes = speechControlResponseLimit,
   ): Promise<Response> {
     const timeout = AbortSignal.timeout(this.#timeoutMs);
     const signal = init.signal
@@ -97,21 +112,13 @@ export class RemoteSpeechRuntime implements SpeechRuntimePort {
     const requestFetch = this.options.fetch ?? fetch;
     return requestFetch(`${this.#baseUrl}${path}`, {
       ...init,
+      redirect: "error",
       signal,
       headers: {
         authorization: `Bearer ${this.options.internalToken}`,
         ...init.headers,
       },
-    }).then((response) => {
-      if (
-        bounded &&
-        Number(response.headers.get("content-length") || "0") >
-          64 * 1_024 * 1_024
-      ) {
-        throw invalidResponse("Speech Runtime 响应超过上限");
-      }
-      return response;
-    });
+    }).then((response) => boundSpeechResponse(response, maxBytes));
   }
 }
 
@@ -137,30 +144,24 @@ export const unavailableSpeechRuntime: SpeechRuntimePort = {
   },
   async health() {
     return Response.json(
-      { status: "unavailable", capabilities: [] },
+      {
+        schemaVersion: 1,
+        status: "unavailable",
+        configured: false,
+        runtimeKind: "speech",
+        observedAt: new Date().toISOString(),
+        downstreamProbe: { status: "not-run", reason: "NOT_CONFIGURED" },
+        deployment: null,
+        offers: [],
+        unavailableReasons: [
+          { code: "RUNTIME_NOT_CONFIGURED", retryable: true },
+        ],
+      },
       { status: 503 },
     );
   },
 };
 
-function parseStartResponse(value: unknown): SpeechRuntimeStartResponse {
-  if (!isRecord(value)) throw invalidResponse();
-  const { runId, status, eventsUrl } = value;
-  if (
-    typeof runId !== "string" ||
-    !runId.trim() ||
-    typeof status !== "string" ||
-    !["accepted", "running", "completed", "failed", "cancelled"].includes(
-      status,
-    ) ||
-    typeof eventsUrl !== "string" ||
-    !eventsUrl.startsWith("/")
-  ) {
-    throw invalidResponse();
-  }
-  return { runId, status, eventsUrl };
-}
-
 function unavailable() {
   return new SpeechRuntimeError(
     "RUNTIME_UNAVAILABLE",
@@ -169,10 +170,6 @@ function unavailable() {
   );
 }
 
-function invalidResponse(message = "Speech Runtime 响应无效") {
-  return new SpeechRuntimeError("INVALID_RESPONSE", message, false);
-}
-
 function normalizeUrl(raw: string) {
   const url = new URL(raw);
   if (
@@ -186,42 +183,3 @@ function normalizeUrl(raw: string) {
   }
   return url.toString().replace(/\/$/, "");
 }
-
-async function remoteError(response: Response) {
-  try {
-    const value = (await response.json()) as Record<string, unknown>;
-    if (
-      typeof value.code === "string" &&
-      typeof value.message === "string" &&
-      typeof value.retryable === "boolean" &&
-      value.message.length <= 200
-    ) {
-      return new SpeechRuntimeError(
-        knownRemoteCode(value.code),
-        value.message,
-        value.retryable,
-      );
-    }
-  } catch {
-    // 不透传远端正文。
-  }
-  return unavailable();
-}
-
-function knownRemoteCode(
-  code: string,
-): ConstructorParameters<typeof SpeechRuntimeError>[0] {
-  return [
-    "CAPABILITY_UNAVAILABLE",
-    "RUN_CONFLICT",
-    "FORBIDDEN",
-    "BUDGET_EXCEEDED",
-    "INVALID_INPUT",
-  ].includes(code)
-    ? (code as ConstructorParameters<typeof SpeechRuntimeError>[0])
-    : "RUNTIME_UNAVAILABLE";
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}