create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/agent/tool-registry.ts

@@ -7,23 +7,26 @@ import type {
   ModuleToolInput,
   ModuleToolResult,
 } from "@southwind-ai/server-sdk";
-import type { AuditEvent, FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import Ajv, { type ValidateFunction } from "ajv";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { isServerScopeContext } from "../data-access/context.js";
-import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { RequestGuardContext } from "../guards.js";
 import { findFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
+import { sandboxFailureEvent, toolEvent, toolJsonBytes } from "./tool-audit.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 export interface PlatformToolExecutionContext {
   readonly guardContext: RequestGuardContext;
+  readonly toolCallId?: string;
   readonly signal: AbortSignal;
 }
 
 export interface PlatformToolHandlerRegistration {
   readonly scopeMode: "platform" | "request";
+  readonly executionMode?: "host" | "sandbox";
   execute(
     input: ModuleToolInput,
     context: PlatformToolExecutionContext,
@@ -92,6 +95,10 @@ export class GovernedToolRegistry {
     return [...this.#tools.values()].map(({ definition }) => definition);
   }
 
+  definition(key: string): RegisteredTool | undefined {
+    return this.#tools.get(key)?.definition;
+  }
+
   async allowed(key: string, context: RequestGuardContext): Promise<boolean> {
     const tool = this.#tools.get(key);
     if (!tool) return false;
@@ -112,6 +119,7 @@ export class GovernedToolRegistry {
     key: string,
     rawInput: ModuleToolInput,
     context: RequestGuardContext,
+    toolCallId = context.requestId,
   ): Promise<ModuleToolResult> {
     const tool = this.#tools.get(key);
     if (!tool) {
@@ -150,25 +158,47 @@ export class GovernedToolRegistry {
         validationMessage(tool.validateInput),
       );
     }
-    const result = await executeWithTimeout(
-      tool,
-      input,
-      context,
-      tool.definition.limits.maxDurationSeconds,
-    );
-    enforceSize(
-      result,
-      tool.definition.limits.maxOutputBytes,
-      "TOOL_OUTPUT_INVALID",
-    );
-    if (!tool.validateOutput(result)) {
-      throw new ToolExecutionError(
+    let result: ModuleToolResult;
+    try {
+      result = await executeWithTimeout(
+        tool,
+        input,
+        {
+          guardContext: context,
+          toolCallId,
+          signal: AbortSignal.timeout(
+            tool.definition.limits.maxDurationSeconds * 1_000,
+          ),
+        },
+        tool.definition.limits.maxDurationSeconds,
+      );
+      enforceSize(
+        result,
+        tool.definition.limits.maxOutputBytes,
         "TOOL_OUTPUT_INVALID",
-        validationMessage(tool.validateOutput),
       );
+      if (!tool.validateOutput(result)) {
+        throw new ToolExecutionError(
+          "TOOL_OUTPUT_INVALID",
+          validationMessage(tool.validateOutput),
+        );
+      }
+    } catch (error) {
+      if (tool.handler.executionMode === "sandbox") {
+        this.runtime.auditSink.recordEvent(
+          sandboxFailureEvent(context, tool.definition, input, error),
+        );
+      }
+      throw error;
     }
     this.runtime.auditSink.recordEvent(
-      toolEvent(context, tool.definition, input, result),
+      toolEvent(
+        context,
+        tool.definition,
+        input,
+        result,
+        tool.handler.executionMode ?? "host",
+      ),
     );
     return result;
   }
@@ -236,7 +266,7 @@ function validateHandlerContract(
 async function executeWithTimeout(
   tool: CompiledTool,
   input: ModuleToolInput,
-  context: RequestGuardContext,
+  context: PlatformToolExecutionContext,
   seconds: number,
 ): Promise<ModuleToolResult> {
   const controller = new AbortController();
@@ -250,8 +280,9 @@ async function executeWithTimeout(
   try {
     return await Promise.race([
       tool.handler.execute(input, {
-        guardContext: context,
-        signal: controller.signal,
+        guardContext: context.guardContext,
+        toolCallId: context.toolCallId,
+        signal: AbortSignal.any([context.signal, controller.signal]),
       }),
       expired,
     ]);
@@ -269,7 +300,7 @@ function enforceSize(
   maximum: number,
   code: "TOOL_INPUT_INVALID" | "TOOL_OUTPUT_INVALID",
 ): void {
-  const bytes = jsonBytes(value);
+  const bytes = toolJsonBytes(value);
   if (bytes > maximum) {
     throw new ToolExecutionError(code, `Agent Tool JSON 超过 ${maximum} 字节`);
   }
@@ -282,33 +313,7 @@ function validationMessage(validate: ValidateFunction<unknown>): string {
   return `Agent Tool JSON 不符合 Schema${detail ? `：${detail}` : ""}`;
 }
 
-function toolEvent(
-  context: RequestGuardContext,
-  tool: RegisteredTool,
-  input: ModuleToolInput,
-  result: ModuleToolResult,
-): AuditEvent {
-  return {
-    id: crypto.randomUUID(),
-    action: tool.auditAction,
-    outcome: "success",
-    actor: auditActor(context),
-    target: { type: "agent-tool", id: tool.key, label: tool.label },
-    module: tool.module,
-    requestId: context.requestId,
-    metadata: {
-      inputBytes: jsonBytes(input),
-      outputBytes: jsonBytes(result),
-    },
-    occurredAt: new Date().toISOString(),
-  };
-}
-
 function required<T>(value: T | undefined, message: string): T {
   if (value === undefined) throw new Error(message);
   return value;
 }
-
-function jsonBytes(value: ModuleToolInput | ModuleToolResult): number {
-  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
-}

package/template/apps/server/src/agent/vision-facade.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import type {
+  AgentRuntimeOperation,
+  AgentRuntimePort,
+} from "./run-contracts.js";
+import { AgentRunFacade } from "./run-facade.js";
+
+describe("Agent Vision facade", () => {
+  test("轮换 Artifact 并传递能力、模态和结构化输出 Schema", async () => {
+    const module = visionManifest();
+    const remote = new FakeRuntime();
+    const runtime = createServerRuntime(
+      {},
+      {
+        featureCatalog: module.features,
+        licenseResolver: { resolve: () => ({ status: "valid" }) },
+      },
+    );
+    const facade = new AgentRunFacade(
+      [module],
+      {
+        aiOperationHandlers: [
+          {
+            moduleName: "business",
+            registration: {
+              operationKey: "business.vision",
+              prepare() {
+                return {
+                  instructions: "只提取图片可见内容。",
+                  userPrompt: "提取字段。",
+                  outputSchema: { type: "object" },
+                };
+              },
+            },
+          },
+        ],
+      } as unknown as InitializedModuleHosts,
+      runtime,
+      remote,
+      createTestRunAuthorizationStore(),
+      artifactRuntime(),
+    );
+    await facade.start(
+      "business.vision",
+      { question: "提取字段" },
+      "vision-1",
+      guardContext(),
+      [
+        {
+          value: "opaque-original",
+          mediaType: "image/png",
+          byteSize: 128,
+          sha256: "a".repeat(64),
+          expiresAt: "2030-01-01T00:00:00.000Z",
+        },
+      ],
+    );
+
+    expect(remote.started[0]).toMatchObject({
+      kind: "agent",
+      operationKey: "business.vision",
+      inputModalities: ["text", "image"],
+      requiredCapabilities: ["text-generation", "vision"],
+      artifacts: [{ value: "opaque-rotated", mediaType: "image/png" }],
+      outputSchemaKey: "business.output.v1",
+      outputSchema: { type: "object" },
+      limits: {
+        maxArtifacts: 4,
+        maxPixelsPerArtifact: 20_000_000,
+      },
+    });
+  });
+});
+
+class FakeRuntime implements AgentRuntimePort {
+  readonly started: AgentRuntimeOperation[] = [];
+
+  start(request: AgentRuntimeOperation) {
+    this.started.push(request);
+    return Promise.resolve({
+      runId: "run_vision",
+      status: "accepted" as const,
+      eventsUrl: "/internal/events",
+    });
+  }
+
+  status(runId: string) {
+    return Promise.resolve({
+      runId,
+      status: "running" as const,
+      lastSequence: 0,
+    });
+  }
+
+  events() {
+    return Promise.resolve(new Response());
+  }
+
+  result() {
+    return Promise.resolve(new Response());
+  }
+
+  cancel() {
+    return Promise.resolve(new Response());
+  }
+
+  health() {
+    return Promise.resolve(new Response());
+  }
+}
+
+function artifactRuntime() {
+  return {
+    rotate: async () => ({
+      value: "opaque-rotated",
+      mediaType: "image/png",
+      byteSize: 128,
+      sha256: "a".repeat(64),
+      expiresAt: "2030-01-01T00:00:00.000Z",
+    }),
+  } as unknown as AiArtifactRuntime;
+}
+
+function guardContext() {
+  return createRequestGuardContext(
+    new Request("http://localhost/api/agent/runs"),
+    {
+      resolveActor: () => ({
+        id: "actor-1",
+        type: "user",
+        name: "测试用户",
+        roleCodes: ["user"],
+        permissionKeys: ["business.ai.execute"],
+        scopeContext: buildScopeContext("actor-1", undefined, [
+          {
+            id: "role-user",
+            code: "user",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      }),
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+}
+
+function visionManifest(): ModuleManifest {
+  return {
+    name: "business",
+    version: "0.1.0",
+    label: "业务",
+    description: "业务",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "business.ai.execute",
+        label: "视觉分析",
+        module: "business",
+        moduleLabel: "业务",
+        resource: "ai",
+        resourceLabel: "AI",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("business.ai"),
+        label: "视觉分析",
+        module: "business",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      { key: "business.input.v1", schema: { type: "object" } },
+      { key: "business.output.v1", schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: "business.vision",
+        kind: "agent",
+        featureKey: "business.ai",
+        permissionKey: "business.ai.execute",
+        auditAction: "business.ai.execute",
+        inputSchemaKey: "business.input.v1",
+        outputSchemaKey: "business.output.v1",
+        inputModalities: ["text", "image"],
+        requiredCapabilities: ["text-generation", "vision"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "streaming",
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: "ai.openai-compatible",
+        },
+        providerDataPolicy: {
+          inputFields: [
+            {
+              jsonPointer: "/question",
+              classification: "internal",
+              dlpAction: "redact",
+            },
+          ],
+          envelopeFields: [
+            {
+              field: "instructions",
+              classification: "internal",
+              dlpAction: "reject",
+            },
+            {
+              field: "user-prompt",
+              classification: "internal",
+              dlpAction: "redact",
+            },
+            {
+              field: "artifact-content",
+              classification: "sensitive",
+              dlpAction: "reject",
+            },
+            {
+              field: "output-schema",
+              classification: "internal",
+              dlpAction: "reject",
+            },
+          ],
+        },
+        toolNetworkPolicy: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+          maxArtifacts: 4,
+          maxPixelsPerArtifact: 20_000_000,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["business.ai.execute"],
+  };
+}

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

@@ -0,0 +1,120 @@
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import type { RequestGuardContext } from "../guards.js";
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export async function rotateVisionArtifacts(
+  artifacts: readonly ModuleAiArtifactRef[],
+  definition: ModuleAiOperationDefinition,
+  moduleName: string,
+  runtime: AiArtifactRuntime | undefined,
+  context: RequestGuardContext,
+  signal: AbortSignal,
+) {
+  validateVisionArtifacts(artifacts, definition);
+  return Promise.all(
+    artifacts.map(async (artifact) => {
+      const rotated = await runtime?.rotate(
+        artifact.value,
+        context.actor.id,
+        moduleName,
+        Math.min(definition.limits.maxDurationSeconds + 60, 3_600),
+        signal,
+      );
+      if (!rotated) {
+        throw new AgentRunFacadeError(
+          "RUNTIME_UNAVAILABLE",
+          "AI Artifact Runtime 未配置",
+          503,
+        );
+      }
+      if (
+        artifact.mediaType !== rotated.mediaType ||
+        artifact.byteSize !== rotated.byteSize ||
+        artifact.sha256 !== rotated.sha256
+      ) {
+        throw new AgentRunFacadeError(
+          "FORBIDDEN",
+          "Agent Artifact 元数据不一致",
+          403,
+        );
+      }
+      return {
+        value: rotated.value,
+        mediaType: rotated.mediaType,
+        byteSize: rotated.byteSize,
+        sha256: rotated.sha256,
+      };
+    }),
+  );
+}
+
+export function validateOutputSchema(
+  schema: ModuleAiJsonValue | undefined,
+  definition: ModuleAiOperationDefinition,
+) {
+  if (schema === undefined) return;
+  if (
+    !schema ||
+    typeof schema !== "object" ||
+    Array.isArray(schema) ||
+    new TextEncoder().encode(JSON.stringify(schema)).byteLength > 256 * 1024
+  ) {
+    throw new AgentRunFacadeError(
+      "INVALID_INPUT",
+      "Agent 结构化输出 Schema 无效",
+      400,
+    );
+  }
+  if (
+    definition.providerEgress?.mode === "configured-endpoint" &&
+    !definition.providerDataPolicy?.envelopeFields.some(
+      ({ field }) => field === "output-schema",
+    )
+  ) {
+    throw new AgentRunFacadeError(
+      "FORBIDDEN",
+      "Provider 未获授权接收输出 Schema",
+      403,
+    );
+  }
+}
+
+function validateVisionArtifacts(
+  artifacts: readonly ModuleAiArtifactRef[],
+  definition: ModuleAiOperationDefinition,
+) {
+  if (!artifacts.length) return;
+  if (!definition.inputModalities?.includes("image")) {
+    throw invalid("该 Agent Operation 未声明图片输入");
+  }
+  if (
+    !definition.limits.maxArtifacts ||
+    artifacts.length > definition.limits.maxArtifacts
+  ) {
+    throw invalid("Agent Artifact 数量超过上限");
+  }
+  const total = artifacts.reduce((sum, artifact) => sum + artifact.byteSize, 0);
+  if (total > definition.limits.maxInputBytes) {
+    throw invalid("Agent Artifact 总大小超过上限");
+  }
+  if (
+    artifacts.some(
+      ({ mediaType, byteSize }) =>
+        byteSize < 1 ||
+        !["image/jpeg", "image/png", "image/webp"].includes(
+          mediaType.toLowerCase(),
+        ),
+    )
+  ) {
+    throw invalid("Agent Vision 仅接受 JPEG、PNG 或 WebP");
+  }
+}
+
+function invalid(message: string) {
+  return new AgentRunFacadeError("INVALID_INPUT", message, 400);
+}

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

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { AiArtifactCodec, AiArtifactCodecError } from "./codec.js";
+
+const claims = {
+  version: 1 as const,
+  moduleName: "evidence",
+  actorId: "user-1",
+  source: {
+    fileId: "file-secret-1",
+    purpose: "evidence.transcript-source",
+    resourceType: "evidence.transcript",
+    resourceId: "transcript-secret-1",
+  },
+  mediaType: "application/pdf",
+  byteSize: 128,
+  sha256: "a".repeat(64),
+  issuedAt: "2026-07-27T00:00:00.000Z",
+  expiresAt: "2026-07-27T00:05:00.000Z",
+};
+
+describe("AI Artifact Codec", () => {
+  test("签发不透明引用且可以完整恢复受保护声明", () => {
+    const codec = new AiArtifactCodec("artifact-secret-at-least-32-characters");
+    const token = codec.encode(claims);
+
+    expect(token).toStartWith("v1.");
+    expect(token).not.toContain(claims.source.fileId);
+    expect(token).not.toContain(claims.source.resourceId);
+    expect(codec.decode(token)).toEqual(claims);
+  });
+
+  test("拒绝被篡改或使用其他 Secret 的引用", () => {
+    const codec = new AiArtifactCodec("artifact-secret-at-least-32-characters");
+    const token = codec.encode(claims);
+    const tampered = `${token.slice(0, -1)}${token.endsWith("a") ? "b" : "a"}`;
+
+    expect(() => codec.decode(tampered)).toThrow(AiArtifactCodecError);
+    expect(() =>
+      new AiArtifactCodec(
+        "different-artifact-secret-at-least-32-characters",
+      ).decode(token),
+    ).toThrow(AiArtifactCodecError);
+  });
+});