create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/module-host/tool-handlers.ts

@@ -1,7 +1,14 @@
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
-import type { ModuleToolHandlers } from "../agent/tool-registry.js";
+import type {
+  ModuleToolHandlers,
+  PlatformToolHandlerRegistration,
+} from "../agent/tool-registry.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { InitializedModuleHosts } from "./initialize.js";
+import {
+  SandboxToolClientError,
+  type SandboxToolExecutor,
+} from "../agent/sandbox-client.js";
 import { toModuleActor } from "./request-context.js";
 import {
   createModuleStoragePort,
@@ -16,6 +23,7 @@ export interface ModuleToolHandlerMapContext {
   readonly runtime: ServerRuntime;
   readonly features: readonly FeatureFlagDefinition[];
   readonly storage?: ModuleStorageServices;
+  readonly sandbox?: SandboxToolExecutor;
 }
 
 /**
@@ -26,35 +34,63 @@ export function createModuleToolHandlerMap(
   hosts: InitializedModuleHosts,
   hostContext: ModuleToolHandlerMapContext,
 ): ModuleToolHandlers {
-  return new Map(
-    hosts.toolHandlers.map(({ moduleName, registration }) => [
-      registration.toolKey,
-      {
-        scopeMode: registration.scopeMode,
-        execute: (input, context) => {
-          const storage = hostContext.storage
-            ? createModuleStoragePort(
-                hostContext.storage,
-                createModuleStorageScope({
-                  moduleName,
-                  purposes: hosts.uploadPurposesOf(moduleName),
-                  resourceFileAccessPolicies:
-                    hosts.resourceFileAccessPoliciesOf(moduleName),
-                  guardContext: context.guardContext,
-                  runtime: hostContext.runtime,
-                  features: hostContext.features,
-                  signal: context.signal,
-                }),
-              )
-            : unavailableModuleStoragePort(moduleName);
-          return registration.execute(input, {
-            actor: toModuleActor(context.guardContext.actor),
-            requestId: context.guardContext.requestId,
-            signal: context.signal,
-            storage,
-          });
-        },
+  const handlers = new Map<string, PlatformToolHandlerRegistration>();
+  for (const { moduleName, registration } of hosts.toolHandlers) {
+    handlers.set(registration.toolKey, {
+      scopeMode: registration.scopeMode,
+      executionMode: "host",
+      execute: (input, context) => {
+        const storage = hostContext.storage
+          ? createModuleStoragePort(
+              hostContext.storage,
+              createModuleStorageScope({
+                moduleName,
+                purposes: hosts.uploadPurposesOf(moduleName),
+                resourceFileAccessPolicies:
+                  hosts.resourceFileAccessPoliciesOf(moduleName),
+                guardContext: context.guardContext,
+                runtime: hostContext.runtime,
+                features: hostContext.features,
+                signal: context.signal,
+              }),
+            )
+          : unavailableModuleStoragePort(moduleName);
+        return registration.execute(input, {
+          actor: toModuleActor(context.guardContext.actor),
+          requestId: context.guardContext.requestId,
+          idempotencyKey: context.toolCallId ?? context.guardContext.requestId,
+          signal: context.signal,
+          storage,
+        });
+      },
+    });
+  }
+  for (const { moduleName, registration } of hosts.sandboxToolHandlers) {
+    const definition = hosts
+      .manifestOf(moduleName)
+      .tools.find(({ key }) => key === registration.toolKey);
+    if (!definition) {
+      throw new Error(`Sandbox Agent Tool 未声明：${registration.toolKey}`);
+    }
+    handlers.set(registration.toolKey, {
+      scopeMode: definition.scopeMode,
+      executionMode: "sandbox",
+      execute: (input, context) => {
+        if (!hostContext.sandbox) {
+          throw new SandboxToolClientError(
+            "SANDBOX_UNAVAILABLE",
+            "Tool Sandbox Runtime 未挂载",
+            true,
+          );
+        }
+        return hostContext.sandbox.execute(
+          registration.toolKey,
+          input,
+          context.toolCallId ?? context.guardContext.requestId,
+          context.signal,
+        );
       },
-    ]),
-  );
+    });
+  }
+  return handlers;
 }

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

@@ -5,6 +5,7 @@ export {
   type RegisteredModuleRolePreset,
   type RegisteredModuleRoute,
   type RegisteredModuleSearchProvider,
+  type RegisteredModuleSandboxToolHandler,
   type RegisteredModuleTaskHandler,
   type RegisteredModuleToolHandler,
   type RegisteredModuleAiOperationHandler,

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

@@ -27,9 +27,13 @@ export function validateInstalledRuntime(input: {
       tasks: input.hosts.taskHandlers.map(
         ({ registration }) => registration.taskKey,
       ),
-      tools: input.hosts.toolHandlers.map(
-        ({ registration }) => registration.toolKey,
-      ),
+      tools: input.hosts.toolHandlers
+        .map(({ registration }) => registration.toolKey)
+        .concat(
+          input.hosts.sandboxToolHandlers.map(
+            ({ registration }) => registration.toolKey,
+          ),
+        ),
       aiOperations,
       providers: input.hosts.searchProviders.map(
         ({ provider }) => provider.key,

package/template/apps/server/src/speech/contracts.ts

@@ -0,0 +1,76 @@
+import type {
+  AiOperationDataClassification,
+  AiProviderDataPolicy,
+  AiProviderEgressPolicy,
+} from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export interface SpeechRuntimeArtifact {
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface SpeechRuntimeOperation {
+  readonly kind: "speech";
+  readonly operationKey: string;
+  readonly options: ModuleAiJsonValue;
+  readonly source: SpeechRuntimeArtifact;
+  readonly requiredCapabilities: readonly string[];
+  readonly dataClassification: AiOperationDataClassification;
+  readonly limits: {
+    readonly maxDurationSeconds: number;
+    readonly maxInputBytes: number;
+    readonly maxOutputBytes: number;
+    readonly maxUnits: number;
+    readonly maxMediaDurationSeconds: number;
+  };
+  readonly providerEgress: AiProviderEgressPolicy;
+  readonly providerDataPolicy?: AiProviderDataPolicy;
+}
+
+export interface SpeechRuntimeStartResponse {
+  readonly runId: string;
+  readonly status: string;
+  readonly eventsUrl: string;
+}
+
+export interface SpeechRuntimePort {
+  start(
+    request: SpeechRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<SpeechRuntimeStartResponse>;
+  events(
+    runId: string,
+    cursor: number,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  result(runId: string, signal?: AbortSignal): Promise<Response>;
+  artifact(runId: string, signal?: AbortSignal): Promise<Response>;
+  cancel(
+    runId: string,
+    reason?: string,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  health(signal?: AbortSignal): Promise<Response>;
+}
+
+export class SpeechRuntimeError extends Error {
+  constructor(
+    readonly code:
+      | "CAPABILITY_UNAVAILABLE"
+      | "RUNTIME_UNAVAILABLE"
+      | "INVALID_RESPONSE"
+      | "RUN_CONFLICT"
+      | "FORBIDDEN"
+      | "BUDGET_EXCEEDED"
+      | "INVALID_INPUT",
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = "SpeechRuntimeError";
+  }
+}

package/template/apps/server/src/speech/facade.ts

@@ -0,0 +1,316 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import { resolveProviderEgress } from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+  ModuleAiOperationHandlerRegistration,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { ExecutionGrantStore } from "../agent/execution-grants.js";
+import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
+import {
+  governProviderInput,
+  ProviderInputGovernanceError,
+} from "../agent/provider-input-governance.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { toModuleActor } from "../module-host.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  SpeechRuntimeError,
+  type SpeechRuntimePort,
+  type SpeechRuntimeStartResponse,
+} from "./contracts.js";
+
+export class SpeechRunFacade {
+  readonly #operations: Map<string, RegisteredSpeechOperation>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ReturnType<typeof createServerRuntime>,
+    private readonly remote: SpeechRuntimePort,
+    private readonly artifacts: AiArtifactRuntime,
+    private readonly grants: ExecutionGrantStore,
+  ) {
+    const handlers = new Map(
+      hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
+        registration.operationKey,
+        { registration, moduleName },
+      ]),
+    );
+    const features = modules.flatMap(({ features }) => features);
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter(({ kind }) => kind === "speech")
+          .map(
+            (definition) =>
+              [
+                definition.key,
+                {
+                  definition,
+                  feature: findFeature(features, definition.featureKey),
+                  ...handlers.get(definition.key),
+                },
+              ] as const,
+          ),
+      ),
+    );
+  }
+
+  async start(
+    operationKey: string,
+    source: ModuleAiArtifactRef,
+    input: ModuleAiJsonValue,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<SpeechRuntimeStartResponse> {
+    const operation = this.#operations.get(operationKey);
+    if (!operation?.registration?.prepareSpeech || !operation.moduleName) {
+      throw new SpeechFacadeError(
+        "OPERATION_NOT_FOUND",
+        "Speech Operation 不存在",
+        404,
+      );
+    }
+    await this.authorize(operation, context);
+    await this.requireCapabilities(
+      operation.definition.requiredCapabilities,
+      signal,
+    );
+    assertInputSize(input, operation.definition.limits.maxInputBytes);
+    if (source.byteSize > operation.definition.limits.maxInputBytes) {
+      throw new SpeechFacadeError(
+        "BUDGET_EXCEEDED",
+        "Speech Artifact 超过 Operation 输入上限",
+        400,
+      );
+    }
+    const { maxUnits, maxMediaDurationSeconds } = operation.definition.limits;
+    if (!maxUnits || !maxMediaDurationSeconds) {
+      throw new SpeechFacadeError(
+        "OPERATION_DISABLED",
+        "Speech Operation 未声明分段或媒体时长上限",
+        503,
+      );
+    }
+    const governed = governOptions(input, operation.definition);
+    const plan = await operation.registration.prepareSpeech(governed, {
+      actor: toModuleActor(context.actor),
+      requestId: context.requestId,
+    });
+    const rotated = await this.artifacts.rotate(
+      source.value,
+      context.actor.id,
+      operation.moduleName,
+      Math.min(operation.definition.limits.maxDurationSeconds + 60, 3_600),
+      signal,
+    );
+    assertArtifactMetadata(source, rotated);
+    const grant = this.grants.issue(operation.definition, context, 3_600);
+    try {
+      const created = await this.remote.start(
+        {
+          kind: "speech",
+          operationKey,
+          options: plan.options ?? governed,
+          source: {
+            value: rotated.value,
+            mediaType: rotated.mediaType,
+            byteSize: rotated.byteSize,
+            sha256: rotated.sha256,
+          },
+          requiredCapabilities: operation.definition.requiredCapabilities,
+          dataClassification: operation.definition.dataClassification,
+          limits: {
+            maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
+            maxInputBytes: operation.definition.limits.maxInputBytes,
+            maxOutputBytes: operation.definition.limits.maxOutputBytes,
+            maxUnits,
+            maxMediaDurationSeconds,
+          },
+          providerEgress: resolveProviderEgress(operation.definition),
+          providerDataPolicy: operation.definition.providerDataPolicy,
+        },
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
+        signal,
+      );
+      this.grants.bindRun(grant.token, created.runId);
+      this.runtime.auditSink.recordEvent({
+        id: randomUUIDv7(),
+        action: operation.definition.auditAction,
+        outcome: "success",
+        actor: auditActor(context),
+        target: {
+          type: "speech-run",
+          id: created.runId,
+          label: operationKey,
+        },
+        requestId: context.requestId,
+        metadata: {
+          mediaType: rotated.mediaType,
+          byteSize: rotated.byteSize,
+          sha256: rotated.sha256,
+          requiredCapabilities: operation.definition.requiredCapabilities,
+          maxMediaDurationSeconds,
+        },
+        occurredAt: new Date().toISOString(),
+      });
+      return {
+        ...created,
+        eventsUrl: `/api/speech/runs/${created.runId}/events`,
+      };
+    } catch (error) {
+      this.grants.discard(grant.token);
+      if (error instanceof SpeechRuntimeError) {
+        throw new SpeechFacadeError(
+          error.code,
+          error.message,
+          runtimeErrorStatus(error.code),
+        );
+      }
+      throw error;
+    }
+  }
+
+  authorizeRun(runId: string, context: RequestGuardContext) {
+    this.grants.requireRun(runId, context.actor.id);
+  }
+
+  private async authorize(
+    operation: RegisteredSpeechOperation,
+    context: RequestGuardContext,
+  ) {
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.feature,
+    });
+    if (!access.decision.allowed) {
+      throw new SpeechFacadeError(
+        "FORBIDDEN",
+        "无权执行 Speech Operation",
+        403,
+      );
+    }
+  }
+
+  private async requireCapabilities(
+    required: readonly string[],
+    signal: AbortSignal,
+  ) {
+    let response: Response;
+    try {
+      response = await this.remote.health(signal);
+    } catch {
+      throw capabilityUnavailable();
+    }
+    if (!response.ok) throw capabilityUnavailable();
+    try {
+      const value = (await response.json()) as Record<string, unknown>;
+      const capabilities = Array.isArray(value.capabilities)
+        ? value.capabilities.filter(
+            (item): item is string => typeof item === "string",
+          )
+        : [];
+      if (
+        value.status !== "ready" ||
+        required.some((capability) => !capabilities.includes(capability))
+      ) {
+        throw capabilityUnavailable();
+      }
+    } catch (error) {
+      if (error instanceof SpeechFacadeError) throw error;
+      throw capabilityUnavailable();
+    }
+  }
+}
+
+interface RegisteredSpeechOperation {
+  definition: ModuleAiOperationDefinition;
+  feature: ReturnType<typeof findFeature>;
+  registration?: ModuleAiOperationHandlerRegistration;
+  moduleName?: string;
+}
+
+export class SpeechFacadeError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "SpeechFacadeError";
+  }
+}
+
+function governOptions(
+  input: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+) {
+  try {
+    return definition.providerDataPolicy
+      ? governProviderInput(input, definition.providerDataPolicy)
+      : input;
+  } catch (error) {
+    if (error instanceof ProviderInputGovernanceError) {
+      throw new SpeechFacadeError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN" ? 403 : 400,
+      );
+    }
+    throw error;
+  }
+}
+
+function assertInputSize(value: ModuleAiJsonValue, maxBytes: number) {
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) {
+    throw new SpeechFacadeError("INVALID_INPUT", "Speech 输入超过上限", 400);
+  }
+}
+
+function assertArtifactMetadata(
+  submitted: ModuleAiArtifactRef,
+  resolved: ModuleAiArtifactRef,
+) {
+  if (
+    submitted.mediaType !== resolved.mediaType ||
+    submitted.byteSize !== resolved.byteSize ||
+    submitted.sha256 !== resolved.sha256
+  ) {
+    throw new SpeechFacadeError(
+      "ARTIFACT_UNAVAILABLE",
+      "Artifact 元数据不一致",
+      403,
+    );
+  }
+}
+
+function capabilityUnavailable() {
+  return new SpeechFacadeError(
+    "CAPABILITY_UNAVAILABLE",
+    "Speech Runtime 缺少 Operation 所需能力",
+    503,
+  );
+}
+
+function runtimeErrorStatus(code: SpeechRuntimeError["code"]) {
+  if (code === "FORBIDDEN") return 403;
+  if (code === "RUN_CONFLICT") return 409;
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") {
+    return 400;
+  }
+  return 503;
+}

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

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { SpeechRuntimeError } from "./contracts.js";
+import { RemoteSpeechRuntime } from "./remote-runtime.js";
+
+const request = {
+  kind: "speech" as const,
+  operationKey: "speech.transcribe.batch",
+  options: { language: "zh", timestamps: "segment" },
+  source: {
+    value: "opaque-artifact-ref",
+    mediaType: "audio/mpeg",
+    byteSize: 128,
+    sha256: "a".repeat(64),
+  },
+  requiredCapabilities: ["speech.transcribe.batch"],
+  dataClassification: "sensitive" as const,
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 1024,
+    maxOutputBytes: 4096,
+    maxUnits: 20,
+    maxMediaDurationSeconds: 600,
+  },
+  providerEgress: { mode: "forbidden" as const },
+};
+
+describe("Remote Speech Runtime", () => {
+  test("只向受信任 Runtime 发送内部认证、作用域化幂等键和有界契约", async () => {
+    const calls: Array<{ input: string; init?: RequestInit }> = [];
+    const runtime = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async (input, init) => {
+        calls.push({ input: String(input), init });
+        return Response.json({
+          runId: "speech-1",
+          status: "accepted",
+          eventsUrl: "/api/speech/runs/speech-1/events",
+        });
+      },
+    });
+
+    await expect(runtime.start(request, "scoped-key")).resolves.toEqual({
+      runId: "speech-1",
+      status: "accepted",
+      eventsUrl: "/api/speech/runs/speech-1/events",
+    });
+    expect(calls[0]?.input).toBe("http://speech.internal:8091/api/speech/runs");
+    expect(calls[0]?.init?.headers).toMatchObject({
+      authorization: "Bearer internal-token",
+      "idempotency-key": "scoped-key",
+    });
+    expect(JSON.parse(String(calls[0]?.init?.body))).toEqual(request);
+  });
+
+  test("保留可信的幂等冲突错误码并拒绝无效响应", async () => {
+    const conflict = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () =>
+        Response.json(
+          {
+            code: "RUN_CONFLICT",
+            message: "幂等键已用于不同输入",
+            retryable: false,
+          },
+          { status: 409 },
+        ),
+    });
+    await expect(conflict.start(request, "scoped-key")).rejects.toMatchObject({
+      code: "RUN_CONFLICT",
+    });
+
+    const invalid = new RemoteSpeechRuntime({
+      baseUrl: "http://speech.internal:8091",
+      internalToken: "internal-token",
+      fetch: async () =>
+        Response.json({
+          runId: "speech-1",
+          status: "unknown",
+          eventsUrl: "https://evil.example/events",
+        }),
+    });
+    await expect(invalid.start(request, "scoped-key")).rejects.toBeInstanceOf(
+      SpeechRuntimeError,
+    );
+  });
+});