create-windy 0.8.3 → 0.10.0

package/template/apps/server/src/module-host/ai-operation-port.ts

@@ -1,15 +1,15 @@
-// @windy-module system.agent begin
+// @windy-module system.media-runtime begin
 import type {
   ModuleAiOperationDefinition,
   ModuleManifest,
 } from "@southwind-ai/modules";
 import type {
+  ModuleAiArtifactRef,
   ModuleAiJsonValue,
+  ModuleAiRunReceipt,
   ModuleAiOperationPort,
 } from "@southwind-ai/server-sdk";
 import { ModuleAiOperationError } from "@southwind-ai/server-sdk";
-import type { AgentRunFacade } from "../agent/run-facade.js";
-import type { AgentRuntimePort } from "../agent/run-contracts.js";
 import type { DocumentRuntimePort } from "../document/contracts.js";
 import type { DocumentRunFacade } from "../document/facade.js";
 import type { EmbeddingFacade } from "../embedding/facade.js";
@@ -17,14 +17,48 @@ import type { RequestGuardContext } from "../guards.js";
 import type { SpeechRuntimePort } from "../speech/contracts.js";
 import type { SpeechRunFacade } from "../speech/facade.js";
 
+interface AgentOperationService {
+  start(
+    operationKey: string,
+    input: ModuleAiJsonValue,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+    artifacts?: readonly ModuleAiArtifactRef[],
+    signal?: AbortSignal,
+  ): Promise<ModuleAiRunReceipt>;
+  verifyRunInput(
+    operationKey: string,
+    runId: string,
+    input: ModuleAiJsonValue,
+    context: RequestGuardContext,
+  ): Promise<void>;
+  authorizeRun(
+    operationKey: string,
+    runId: string,
+    context: RequestGuardContext,
+  ): Promise<unknown>;
+}
+
+interface AgentRunTransport {
+  result(runId: string, signal?: AbortSignal): Promise<Response>;
+  cancel(
+    runId: string,
+    reason?: string,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+}
+
 export interface ModuleAiRuntimeServices {
-  readonly agentFacade: AgentRunFacade;
-  readonly agentRemote: AgentRuntimePort;
-  readonly documentFacade: DocumentRunFacade;
-  readonly documentRemote: DocumentRuntimePort;
-  readonly speechFacade: SpeechRunFacade;
-  readonly speechRemote: SpeechRuntimePort;
-  readonly embeddingFacade: EmbeddingFacade;
+  readonly agentFacade?: AgentOperationService;
+  readonly agentRemote?: AgentRunTransport;
+  readonly documentFacade?: DocumentRunFacade;
+  readonly documentRemote?: DocumentRuntimePort;
+  readonly speechFacade?: SpeechRunFacade;
+  readonly speechRemote?: SpeechRuntimePort;
+  readonly embeddingFacade?: EmbeddingFacade;
+  readonly requireFeature?: (
+    kind: "agent" | "document" | "speech" | "embedding",
+  ) => Promise<void>;
   readonly modules: readonly ModuleManifest[];
 }
 
@@ -45,7 +79,8 @@ export function createModuleAiOperationPort(
   return {
     async startAgent(input) {
       own(input.operationKey);
-      return services.agentFacade.start(
+      await services.requireFeature?.("agent");
+      return requireRuntime(services.agentFacade, "Agent").start(
         input.operationKey,
         input.input,
         input.idempotencyKey,
@@ -56,7 +91,8 @@ export function createModuleAiOperationPort(
     },
     async verifyAgentRun(input) {
       own(input.operationKey);
-      await services.agentFacade.verifyRunInput(
+      await services.requireFeature?.("agent");
+      await requireRuntime(services.agentFacade, "Agent").verifyRunInput(
         input.operationKey,
         input.runId,
         input.input,
@@ -65,7 +101,8 @@ export function createModuleAiOperationPort(
     },
     async startDocument(input) {
       own(input.operationKey);
-      return services.documentFacade.start(
+      await services.requireFeature?.("document");
+      return requireRuntime(services.documentFacade, "Document").start(
         input.operationKey,
         input.sources,
         input.options,
@@ -76,12 +113,13 @@ export function createModuleAiOperationPort(
     },
     async startSpeech(input) {
       own(input.operationKey);
+      await services.requireFeature?.("speech");
       const definition = ownSpeechDefinition(
         services.modules,
         moduleName,
         input.operationKey,
       );
-      return services.speechFacade.start(
+      return requireRuntime(services.speechFacade, "Speech").start(
         input.operationKey,
         input.source,
         input.options,
@@ -93,8 +131,9 @@ export function createModuleAiOperationPort(
     },
     async embed(input) {
       own(input.operationKey);
+      await services.requireFeature?.("embedding");
       return jsonValue(
-        await services.embeddingFacade.embed(
+        await requireRuntime(services.embeddingFacade, "Embedding").embed(
           input.operationKey,
           input.items,
           input.options,
@@ -106,51 +145,69 @@ export function createModuleAiOperationPort(
     },
     async result(input) {
       own(input.operationKey);
+      await services.requireFeature?.(input.kind);
       if (input.kind === "agent") {
-        await services.agentFacade.authorizeRun(
+        await requireRuntime(services.agentFacade, "Agent").authorizeRun(
           input.operationKey,
           input.runId,
           context,
         );
         return responseJson(
-          await services.agentRemote.result(input.runId, signal),
+          await requireRuntime(services.agentRemote, "Agent").result(
+            input.runId,
+            signal,
+          ),
         );
       }
       if (input.kind === "document") {
-        await services.documentFacade.authorizeRun(input.runId, context);
+        await requireRuntime(services.documentFacade, "Document").authorizeRun(
+          input.runId,
+          context,
+        );
         return responseJson(
-          await services.documentRemote.result(input.runId, signal),
+          await requireRuntime(services.documentRemote, "Document").result(
+            input.runId,
+            signal,
+          ),
         );
       }
-      services.speechFacade.authorizeRun(input.runId, context);
+      requireRuntime(services.speechFacade, "Speech").authorizeRun(
+        input.runId,
+        context,
+      );
       return responseJson(
-        await services.speechRemote.result(input.runId, signal),
+        await requireRuntime(services.speechRemote, "Speech").result(
+          input.runId,
+          signal,
+        ),
       );
     },
     async cancel(input) {
       own(input.operationKey);
+      await services.requireFeature?.(input.kind);
       let response: Response;
       if (input.kind === "agent") {
-        await services.agentFacade.authorizeRun(
+        await requireRuntime(services.agentFacade, "Agent").authorizeRun(
           input.operationKey,
           input.runId,
           context,
         );
-        response = await services.agentRemote.cancel(
+        response = await requireRuntime(services.agentRemote, "Agent").cancel(
           input.runId,
           input.reason,
           signal,
         );
       } else if (input.kind === "document") {
-        response = await services.documentFacade.cancel(
+        response = await requireRuntime(
+          services.documentFacade,
+          "Document",
+        ).cancel(input.runId, input.reason, context, signal);
+      } else {
+        requireRuntime(services.speechFacade, "Speech").authorizeRun(
           input.runId,
-          input.reason,
           context,
-          signal,
         );
-      } else {
-        services.speechFacade.authorizeRun(input.runId, context);
-        response = await services.speechRemote.cancel(
+        response = await requireRuntime(services.speechRemote, "Speech").cancel(
           input.runId,
           input.reason,
           signal,
@@ -161,6 +218,16 @@ export function createModuleAiOperationPort(
   };
 }
 
+function requireRuntime<T>(service: T | undefined, kind: string): T {
+  if (service === undefined) {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      `${kind} Runtime 未装配`,
+    );
+  }
+  return service;
+}
+
 function ownSpeechDefinition(
   modules: readonly ModuleManifest[],
   moduleName: string,
@@ -235,4 +302,4 @@ function operationErrorCode(status: number, remoteCode: string) {
 function jsonValue(value: unknown): ModuleAiJsonValue {
   return JSON.parse(JSON.stringify(value)) as ModuleAiJsonValue;
 }
-// @windy-module system.agent end
+// @windy-module system.media-runtime end

package/template/apps/server/src/module-host/ai-operation-speech-normalize.test.ts

@@ -2,7 +2,7 @@
 import { expect, test } from "bun:test";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import type { ModuleAiOperationReadinessV1 } from "@southwind-ai/server-sdk";
-import { ExecutionGrantStore } from "../agent/execution-grants.js";
+import { ExecutionGrantStore } from "../ai-runtime-security/execution-grants.js";
 import { createRequestGuardContext } from "../guards.js";
 import { initializeModuleHosts } from "../module-host.js";
 import { createServerRuntime } from "../runtime.js";

package/template/apps/server/src/module-host/http-runtime.ts

@@ -10,11 +10,13 @@ import type { ReportStagingService } from "../report-staging/service.js";
 // @windy-module system.storage end
 import type { RouteApp } from "../system/route-types.js";
 import type { SystemRepositories } from "../system/seed.js";
-// @windy-module system.agent begin
+// @windy-module system.media-runtime begin
 import type { RequestGuardContext } from "../guards.js";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import type { ModuleAiOperationPort } from "@southwind-ai/server-sdk";
 import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+// @windy-module system.media-runtime end
+// @windy-module system.agent begin
 import type { ModuleAiScreenshotIntakePortV1 } from "@southwind-ai/server-sdk";
 import type { ModuleAgentSessionMemoryPortV1 } from "@southwind-ai/server-sdk";
 import type { ModuleAuthoritativeSourceInvalidationPortV1 } from "@southwind-ai/server-sdk";
@@ -44,7 +46,7 @@ export function installModuleHttpRuntime(
     reportStaging?: ReportStagingService;
     // @windy-module system.storage end
     systemRepositories: SystemRepositories;
-    // @windy-module system.agent begin
+    // @windy-module system.media-runtime begin
     aiArtifacts?: AiArtifactRuntime;
     aiOperations?: (
       moduleName: string,
@@ -56,6 +58,8 @@ export function installModuleHttpRuntime(
       guardContext: RequestGuardContext,
       signal: AbortSignal,
     ) => ModuleAiOperationReadinessPortV1;
+    // @windy-module system.media-runtime end
+    // @windy-module system.agent begin
     screenshots?: (
       moduleName: string,
       guardContext: RequestGuardContext,
@@ -95,7 +99,7 @@ export function installModuleHttpRuntime(
     userDirectory: {
       repositories: context.systemRepositories,
     },
-    // @windy-module system.agent begin
+    // @windy-module system.media-runtime begin
     aiArtifacts: context.aiArtifacts
       ? (moduleName, guardContext, signal) =>
           context.aiArtifacts!.createModulePort(
@@ -114,6 +118,8 @@ export function installModuleHttpRuntime(
       : undefined,
     aiOperations: context.aiOperations,
     aiReadiness: context.aiReadiness,
+    // @windy-module system.media-runtime end
+    // @windy-module system.agent begin
     screenshots: context.screenshots,
     sessionMemory: context.sessionMemory,
     sourceInvalidation: context.sourceInvalidation,

package/template/apps/server/src/module-host/static-route-authorization.test.ts

@@ -7,7 +7,7 @@ import {
 } from "./static-route-authorization.js";
 
 // @windy-module system.license begin
-test("平台静态 Route 使用 Manifest Feature 与 Permission Guard", async () => {
+test("License 基础状态免管理 Feature，安装操作仍经过 Manifest Guard", async () => {
   const modules = systemModuleManifests();
   const runtime = createServerRuntime(
     { WINDY_DEV_ADMIN_TOKEN: "token_1" },
@@ -20,10 +20,13 @@ test("平台静态 Route 使用 Manifest Feature 与 Permission Guard", async ()
     }),
   );
 
+  await expect(
+    authorizer.authorize(context, "GET", "/api/license/runtime"),
+  ).resolves.toBeUndefined();
   const denied = await authorizer.authorize(
     context,
-    "GET",
-    "/api/license/runtime",
+    "POST",
+    "/api/license/runtime/install",
   );
 
   expect(denied?.status).toBe(403);

package/template/apps/server/src/module-host/storage-authorization-binding.test.ts

@@ -8,11 +8,13 @@ import {
   type UploadPolicy,
 } from "@southwind-ai/storage";
 import type { ModuleUploadDecision } from "./storage-port.js";
+// @windy-module system.agent begin
 import { buildScopeContext } from "../data-access/context.js";
 import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import { bindModuleUserProjection } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
 import { createModuleStorageScope } from "./storage-scope.js";
+// @windy-module system.agent end
 import { createModuleStorageWritePort } from "./storage-write-port.js";
 
 const policy: UploadPolicy = {
@@ -146,6 +148,7 @@ describe("模块上传会话授权绑定", () => {
     ).toBe(true);
   });
 
+  // @windy-module system.agent begin
   test("Host 投影 service actor 时仍以业务用户 Scope 颁发绑定", async () => {
     const scopeContext = buildScopeContext("user_projected", undefined, [
       {
@@ -189,6 +192,7 @@ describe("模块上传会话授权绑定", () => {
       scopeHash: captureAuthorizationScope(scopeContext).hash,
     });
   });
+  // @windy-module system.agent end
 });
 
 interface SetupOptions {

package/template/apps/server/src/module-runtime-validation.ts

@@ -4,6 +4,7 @@ import type { InitializedModuleHosts } from "./module-host.js";
 
 export function validateInstalledRuntime(input: {
   modules: ModuleManifest[];
+  disabledFeatureKeys?: ReadonlySet<string>;
   routes: readonly { method: string; path: string }[];
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
@@ -15,6 +16,7 @@ export function validateInstalledRuntime(input: {
   );
   validateServerModuleComposition({
     modules: input.modules,
+    disabledFeatureKeys: input.disabledFeatureKeys,
     routes: input.routes,
     frameworkRoutes: ["GET /api/swagger", "GET /api/swagger/json"],
     tasks: input.tasks,

package/template/apps/server/src/observability/bootstrap.ts

@@ -1,3 +1,9 @@
+// @windy-module system.audit begin
+import {
+  createDiagnosticIndex,
+  type DiagnosticIndex,
+} from "./diagnostic-index.js";
+// @windy-module system.audit end
 import type { AuditWriteStatus } from "../audit/contracts.js";
 import type { FeatureManifestSyncResult } from "../feature/manifest-feature-repository.js";
 import type { RouteApp } from "../system/route-types.js";
@@ -12,6 +18,9 @@ import { registerObservabilityRoutes } from "./routes.js";
 export interface PlatformObservabilityOptions {
   databaseCheck?: () => Promise<void>;
   databaseRequired: boolean;
+  // @windy-module system.audit begin
+  diagnosticIndex?: DiagnosticIndex;
+  // @windy-module system.audit end
   auditStatus(): AuditWriteStatus;
   logger: StructuredRequestLogger;
 }
@@ -25,6 +34,9 @@ export function createPlatformObservability(
   return {
     http,
     metrics,
+    // @windy-module system.audit begin
+    diagnostics: options.diagnosticIndex ?? createDiagnosticIndex(),
+    // @windy-module system.audit end
     register(app: Pick<RouteApp, "get">) {
       registerObservabilityRoutes(app, readiness, metrics);
     },

package/template/apps/server/src/observability/diagnostic-failure-recorder.ts

@@ -0,0 +1,94 @@
+import { responseStatus } from "./http-observability.js";
+import {
+  diagnosticRecord,
+  newDiagnosticId,
+  safeDiagnosticCode,
+  type DiagnosticIndex,
+} from "./diagnostic-index.js";
+
+export interface DiagnosticFailureInput {
+  readonly request: Request;
+  /** 必须来自路由注册表，禁止传入请求 URL 或包含真实参数的 pathname。 */
+  readonly route?: string;
+  readonly requestId: string;
+  readonly responseValue: unknown;
+  readonly status?: number | string;
+  readonly errorCode?: unknown;
+}
+
+export interface DiagnosticFailureReceipt {
+  readonly diagnosticId: string;
+  readonly errorCode: string;
+  readonly persisted: boolean;
+}
+
+export function createDiagnosticFailureRecorder(index: DiagnosticIndex) {
+  const captured = new WeakMap<
+    Request,
+    Promise<DiagnosticFailureReceipt | undefined>
+  >();
+  let nextPurge = 0;
+  return {
+    capture(
+      input: DiagnosticFailureInput,
+    ): Promise<DiagnosticFailureReceipt | undefined> {
+      const previous = captured.get(input.request);
+      if (previous) return previous;
+      const pending = record(input);
+      captured.set(input.request, pending);
+      return pending;
+    },
+  };
+
+  async function record(
+    input: DiagnosticFailureInput,
+  ): Promise<DiagnosticFailureReceipt | undefined> {
+    const statusCode = responseStatus(input.responseValue, input.status);
+    if (statusCode < 400) return;
+    const diagnosticId = newDiagnosticId();
+    const suppliedCode = input.errorCode ?? objectError(input.responseValue);
+    const errorCode = safeDiagnosticCode(suppliedCode, statusCode);
+    const record = diagnosticRecord({
+      diagnosticId,
+      requestId: /^[A-Za-z0-9._:-]{1,160}$/.test(input.requestId)
+        ? input.requestId
+        : "(unavailable)",
+      service: "server",
+      stage: "http",
+      method: /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(
+        input.request.method,
+      )
+        ? input.request.method
+        : "OTHER",
+      route: safeDiagnosticRoute(input.route),
+      statusCode,
+      errorCode,
+    });
+    try {
+      await index.record(record);
+      if (Date.now() >= nextPurge) {
+        nextPurge = Date.now() + 60_000;
+        // 有界批量清理不影响失败响应和原始错误处理。
+        void index.purgeExpired().catch(() => {});
+      }
+      return { diagnosticId, errorCode, persisted: true };
+    } catch {
+      return { diagnosticId, errorCode, persisted: false };
+    }
+  }
+}
+
+export function safeDiagnosticRoute(route: unknown): string {
+  return typeof route === "string" && /^\/[A-Za-z0-9_./:*-]{0,255}$/.test(route)
+    ? route
+    : "(unmatched)";
+}
+
+function objectError(value: unknown): unknown {
+  return value &&
+    typeof value === "object" &&
+    !(value instanceof Response) &&
+    "error" in value
+    ? value.error
+    : undefined;
+}

package/template/apps/server/src/observability/diagnostic-http-contract.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { createPlatformHttpApp } from "../http-app.js";
+import { createServerRuntime } from "../runtime.js";
+import { createPlatformObservability } from "./bootstrap.js";
+
+test("实际 HTTP 失败响应带诊断编号并只持久化模板与脱敏摘要", async () => {
+  const observability = createPlatformObservability({
+    databaseRequired: false,
+    auditStatus: () => ({
+      queued: 0,
+      dropped: 0,
+      state: "healthy",
+      attempted: 0,
+      persisted: 0,
+      failedAttempts: 0,
+      retries: 0,
+    }),
+    logger: { info() {} },
+  });
+  const app = createPlatformHttpApp(createServerRuntime(), observability).get(
+    "/synthetic/:privateId",
+    () =>
+      Response.json(
+        { error: "SAFE_FAILURE", privateBody: "private-note" },
+        { status: 503 },
+      ),
+  );
+  const response = await app.handle(
+    new Request("http://localhost/api/synthetic/secret-id?secret=query"),
+  );
+  expect(response.status).toBe(503);
+  const id = response.headers.get("x-diagnostic-id");
+  expect(id).toMatch(/^diag-/);
+  const record = await observability.diagnostics.find(id!);
+  expect(record).toMatchObject({
+    route: "/api/synthetic/:privateId",
+    statusCode: 503,
+  });
+  const serialized = JSON.stringify(record);
+  for (const secret of ["secret-id", "private-note", "secret=query"])
+    expect(serialized).not.toContain(secret);
+});

package/template/apps/server/src/observability/diagnostic-index.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { createDiagnosticFailureRecorder } from "./diagnostic-failure-recorder.js";
+import {
+  InMemoryDiagnosticIndex,
+  newDiagnosticId,
+  validDiagnosticId,
+} from "./diagnostic-index.js";
+
+describe("受控失败索引", () => {
+  test("同一请求只记录一次，不持久化 URL 查询、正文或错误内容", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    const request = new Request(
+      "https://example.test/api/people/private-id?token=secret",
+      { method: "POST", body: "private material" },
+    );
+    const input = {
+      request,
+      route: "/api/people/:id",
+      requestId: "safe-request",
+      status: 500,
+      responseValue: { error: "Provider returned secret body" },
+    };
+    const [first, second] = await Promise.all([
+      recorder.capture(input),
+      recorder.capture(input),
+    ]);
+    expect(first).toEqual(second);
+    expect(validDiagnosticId(first!.diagnosticId)).toBe(true);
+    const stored = await index.find(first!.diagnosticId);
+    expect(stored).toMatchObject({
+      route: "/api/people/:id",
+      errorCode: "UNEXPECTED_FAILURE",
+      requestId: "safe-request",
+      statusCode: 500,
+    });
+    const serialized = JSON.stringify(stored);
+    for (const secret of [
+      "private-id",
+      "token",
+      "secret",
+      "private material",
+      "Provider",
+    ])
+      expect(serialized).not.toContain(secret);
+  });
+
+  test("成功请求不产生索引，失效清理使用相同30天边界", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    expect(
+      await recorder.capture({
+        request: new Request("https://test.invalid/"),
+        requestId: "ok",
+        responseValue: new Response(null, { status: 200 }),
+      }),
+    ).toBeUndefined();
+    const receipt = await recorder.capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: new Response(null, { status: 503 }),
+    });
+    const stored = await index.find(receipt!.diagnosticId);
+    const expiry = new Date(stored!.expiresAt);
+    expect(
+      await index.find(receipt!.diagnosticId, new Date(expiry.getTime() - 1)),
+    ).toBeDefined();
+    expect(await index.find(receipt!.diagnosticId, expiry)).toBeUndefined();
+    expect(await index.purgeExpired(expiry)).toBe(1);
+  });
+
+  test("索引失败不掩盖原请求失败，返回受控关联回执", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    index.record = async () => {
+      throw new Error("storage secret");
+    };
+    const receipt = await createDiagnosticFailureRecorder(index).capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: { error: "OPERATION_DENIED" },
+      status: 403,
+    });
+    expect(receipt).toMatchObject({
+      errorCode: "OPERATION_DENIED",
+      persisted: false,
+    });
+    expect(validDiagnosticId(newDiagnosticId())).toBe(true);
+  });
+});