create-windy 0.3.17 → 0.3.19

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

@@ -1,17 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import type { ModuleManifest } from "@southwind-ai/modules";
-import { featureKey } from "@southwind-ai/shared";
-import { buildScopeContext } from "../data-access/context.js";
-import { createRequestGuardContext } from "../guards.js";
-import { initializeModuleHosts } from "../module-host.js";
-import { createServerRuntime } from "../runtime.js";
-import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
-import { FakeAgentRuntime } from "./fake-runtime.test-support.js";
-import { AgentRunFacade } from "./run-facade.js";
+import {
+  createRunFacadeFixture,
+  guardContext,
+} from "./run-facade.test-support.js";
 
 describe("Guarded Agent Run facade", () => {
   test("Guard 后由宿主 Handler 生成计划并签发短时 Grant", async () => {
-    const fixture = await createFixture();
+    const fixture = await createRunFacadeFixture();
     const created = await fixture.facade.start(
       "business.answer",
       { question: "你好", internalCaseId: "case-secret" },
@@ -64,7 +59,7 @@ describe("Guarded Agent Run facade", () => {
   });
 
   test("客户端输入不能覆盖 Operation、Tool 或授权", async () => {
-    const fixture = await createFixture();
+    const fixture = await createRunFacadeFixture();
     await fixture.facade.start(
       "business.answer",
       {
@@ -84,7 +79,7 @@ describe("Guarded Agent Run facade", () => {
   });
 
   test("缺少 Operation 权限时不调用 Handler 或 Runtime", async () => {
-    const fixture = await createFixture([]);
+    const fixture = await createRunFacadeFixture([]);
     await expect(
       fixture.facade.start(
         "business.answer",
@@ -98,7 +93,7 @@ describe("Guarded Agent Run facade", () => {
   });
 
   test("恢复时权限已收回会返回不泄露 Run 存在性的 404", async () => {
-    const fixture = await createFixture();
+    const fixture = await createRunFacadeFixture();
     await fixture.facade.start(
       "business.answer",
       { question: "稍后恢复" },
@@ -115,234 +110,3 @@ describe("Guarded Agent Run facade", () => {
     });
   });
 });
-
-async function createFixture(
-  permissionKeys: string[] = ["business.ai.execute", "business.records.read"],
-) {
-  const module = manifest();
-  const prepared: unknown[] = [];
-  const hosts = await initializeModuleHosts({
-    modules: [module],
-    installations: [
-      {
-        manifest: module,
-        setup(host) {
-          host.registerAiOperationHandlers([
-            {
-              operationKey: "business.answer",
-              release: {
-                workflowVersion: "workflow-2",
-                promptVersion: "prompt-3",
-                routeVersion: "route-4",
-              },
-              prepare(input, context) {
-                prepared.push({ input, actorId: context.actor.id });
-                const question =
-                  typeof input === "object" &&
-                  input !== null &&
-                  !Array.isArray(input) &&
-                  typeof input.question === "string"
-                    ? input.question
-                    : "";
-                return {
-                  instructions: "只回答当前业务问题。",
-                  userPrompt: question,
-                };
-              },
-            },
-          ]);
-        },
-      },
-    ],
-  });
-  const runtime = createServerRuntime(
-    {},
-    {
-      featureCatalog: module.features,
-      licenseResolver: { resolve: () => ({ status: "valid" }) },
-    },
-  );
-  const context = guardContext(permissionKeys);
-  const remote = new FakeAgentRuntime();
-  const facade = new AgentRunFacade(
-    [module],
-    hosts,
-    runtime,
-    remote,
-    createTestRunAuthorizationStore(),
-  );
-  return { context, facade, prepared, remote, runtime };
-}
-
-function guardContext(permissionKeys: string[]) {
-  return createRequestGuardContext(
-    new Request("http://localhost/api/agent/runs"),
-    {
-      resolveActor: () => ({
-        id: "actor-1",
-        type: "user",
-        name: "测试用户",
-        roleCodes: ["user"],
-        permissionKeys,
-        scopeContext: buildScopeContext("actor-1", undefined, [
-          {
-            id: "role-user",
-            code: "user",
-            dataScope: "self",
-            departmentIds: [],
-          },
-        ]),
-      }),
-      resolveLicense: () => ({ status: "valid" }),
-    },
-  );
-}
-
-function manifest(): ModuleManifest {
-  return {
-    name: "business",
-    version: "0.1.0",
-    label: "业务",
-    description: "业务",
-    menus: [],
-    adminRoutes: [],
-    permissions: [
-      permission("business.ai.execute", "ai", "manage"),
-      permission("business.records.read", "records", "read"),
-    ],
-    apiPermissions: [],
-    features: [
-      enabledFeature("business.ai"),
-      enabledFeature("business.records"),
-    ],
-    migrations: [],
-    schemaExports: [],
-    jsonSchemas: [
-      {
-        key: "business.records.input.v1",
-        schema: { type: "object" },
-      },
-      {
-        key: "business.records.output.v1",
-        schema: { type: "object" },
-      },
-      {
-        key: "business.input.v1",
-        schema: { type: "object" },
-      },
-      {
-        key: "business.output.v1",
-        schema: { type: "object" },
-      },
-    ],
-    tasks: [],
-    tools: [
-      {
-        key: "business.records.list",
-        label: "查询记录",
-        description: "查询当前范围记录。",
-        inputSchemaKey: "business.records.input.v1",
-        outputSchemaKey: "business.records.output.v1",
-        operation: "query",
-        permissionKey: "business.records.read",
-        featureKey: "business.records",
-        auditAction: "business.records.read",
-        scopeMode: "request",
-        dataClassification: "internal",
-        idempotency: "none",
-        approval: "none",
-        limits: {
-          maxDurationSeconds: 10,
-          maxInputBytes: 4096,
-          maxOutputBytes: 4096,
-        },
-      },
-    ],
-    aiOperations: [
-      {
-        key: "business.answer",
-        kind: "agent",
-        featureKey: "business.ai",
-        permissionKey: "business.ai.execute",
-        auditAction: "business.ai.execute",
-        inputSchemaKey: "business.input.v1",
-        outputSchemaKey: "business.output.v1",
-        requiredCapabilities: ["text-generation"],
-        allowedToolKeys: ["business.records.list"],
-        dataClassification: "internal",
-        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: "tool-definitions",
-              classification: "internal",
-              dlpAction: "reject",
-            },
-            {
-              field: "provider-output",
-              classification: "internal",
-              dlpAction: "redact",
-            },
-            {
-              field: "tool-results",
-              classification: "sensitive",
-              dlpAction: "redact",
-            },
-          ],
-        },
-        toolNetworkPolicy: { mode: "forbidden" },
-        limits: {
-          maxDurationSeconds: 60,
-          maxInputBytes: 4096,
-          maxOutputBytes: 4096,
-        },
-      },
-    ],
-    providers: [],
-    auditActions: ["business.ai.execute", "business.records.read"],
-  };
-}
-
-function permission(key: string, resource: string, action: "read" | "manage") {
-  return {
-    key,
-    label: key,
-    module: "business",
-    moduleLabel: "业务",
-    resource,
-    resourceLabel: resource,
-    action,
-  };
-}
-
-function enabledFeature(key: string) {
-  return {
-    key: featureKey(key),
-    label: key,
-    module: "business",
-    visible: "visible" as const,
-    enabled: true,
-    stage: "stable" as const,
-  };
-}

package/template/apps/server/src/agent/run-facade.ts

@@ -1,8 +1,5 @@
 import { randomUUIDv7 } from "bun";
-import type {
-  ModuleAiOperationDefinition,
-  ModuleManifest,
-} from "@southwind-ai/modules";
+import type { ModuleManifest } from "@southwind-ai/modules";
 import {
   resolveProviderEgress,
   resolveToolNetworkPolicy,
@@ -10,14 +7,12 @@ import {
 import type {
   ModuleAiArtifactRef,
   ModuleAiJsonValue,
-  ModuleAiOperationHandlerRegistration,
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";
 import type { createServerRuntime } from "../runtime.js";
-import { findFeature } from "../route-guards.js";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import {
   AgentRunAuthorizationError,
@@ -26,12 +21,10 @@ import {
 } from "./run-authorization.js";
 import type {
   AgentRuntimePort,
-  AgentRuntimeOperation,
   AgentRuntimeStartResponse,
   AgentRuntimeStatusResponse,
 } from "./run-contracts.js";
 import { AgentRuntimeError } from "./run-contracts.js";
-import { buildAgentRuntimeRelease } from "./run-release.js";
 import {
   governProviderInput,
   ProviderInputGovernanceError,
@@ -42,10 +35,17 @@ import {
   digest,
   publicRunPath,
   runtimeErrorStatus,
-  toolDefinitions,
 } from "./run-definition-support.js";
 import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
 import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
+import {
+  assertSelectedDebugOperation,
+  debugActorAuditMetadata,
+} from "./run-debug-authorization.js";
+import {
+  buildRegisteredOperations,
+  type RegisteredOperation,
+} from "./run-operation-registry.js";
 export { AgentRunFacadeError } from "./run-errors.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
@@ -61,36 +61,7 @@ export class AgentRunFacade {
     private readonly authorizations: AgentRunAuthorizationStore,
     private readonly artifacts?: AiArtifactRuntime,
   ) {
-    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 ?? []).map((definition) => {
-          const handler = handlers.get(definition.key);
-          const tools = toolDefinitions(modules, definition.allowedToolKeys);
-          return [
-            definition.key,
-            {
-              definition,
-              ...handler,
-              feature: findFeature(features, definition.featureKey),
-              tools,
-              release: buildAgentRuntimeRelease(
-                modules,
-                module,
-                definition,
-                handler?.registration,
-              ),
-            },
-          ] as const;
-        }),
-      ),
-    );
+    this.#operations = buildRegisteredOperations(modules, hosts);
   }
 
   async start(
@@ -101,6 +72,12 @@ export class AgentRunFacade {
     artifacts: readonly ModuleAiArtifactRef[] = [],
     signal: AbortSignal = AbortSignal.timeout(10_000),
   ): Promise<AgentRuntimeStartResponse> {
+    assertSelectedDebugOperation(
+      this.runtime,
+      context.actor.id,
+      operationKey,
+      "forbidden",
+    );
     const operation = this.#operations.get(operationKey);
     if (
       !operation?.registration?.prepare ||
@@ -237,6 +214,7 @@ export class AgentRunFacade {
         },
         requestId: context.requestId,
         metadata: {
+          ...debugActorAuditMetadata(context.actor),
           artifactCount: rotatedArtifacts.length,
           artifactBytes: rotatedArtifacts.reduce(
             (total, artifact) => total + artifact.byteSize,
@@ -278,6 +256,12 @@ export class AgentRunFacade {
     runId: string,
     context: RequestGuardContext,
   ) {
+    assertSelectedDebugOperation(
+      this.runtime,
+      context.actor.id,
+      operationKey,
+      "hidden",
+    );
     const operation = this.#operations.get(operationKey);
     if (!operation || operation.definition.kind !== "agent") {
       throw inaccessibleRun();
@@ -334,12 +318,3 @@ export class AgentRunFacade {
     };
   }
 }
-
-interface RegisteredOperation {
-  definition: ModuleAiOperationDefinition;
-  registration?: ModuleAiOperationHandlerRegistration;
-  moduleName?: string;
-  feature: ReturnType<typeof findFeature>;
-  tools: AgentRuntimeOperation["allowedTools"];
-  release: AgentRuntimeOperation["release"];
-}

package/template/apps/server/src/agent/run-operation-registry.ts

@@ -0,0 +1,51 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { AgentRuntimeOperation } from "./run-contracts.js";
+import type { ModuleAiOperationHandlerRegistration } from "@southwind-ai/server-sdk";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { findFeature } from "../route-guards.js";
+import { toolDefinitions } from "./run-definition-support.js";
+import { buildAgentRuntimeRelease } from "./run-release.js";
+
+export interface RegisteredOperation {
+  definition: NonNullable<ModuleManifest["aiOperations"]>[number];
+  registration?: ModuleAiOperationHandlerRegistration;
+  moduleName?: string;
+  feature: ReturnType<typeof findFeature>;
+  tools: AgentRuntimeOperation["allowedTools"];
+  release: AgentRuntimeOperation["release"];
+}
+
+export function buildRegisteredOperations(
+  modules: readonly ModuleManifest[],
+  hosts: InitializedModuleHosts,
+): Map<string, RegisteredOperation> {
+  const handlers = new Map(
+    hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
+      registration.operationKey,
+      { registration, moduleName },
+    ]),
+  );
+  const features = modules.flatMap(({ features }) => features);
+  return new Map(
+    modules.flatMap((module) =>
+      (module.aiOperations ?? []).map((definition) => {
+        const handler = handlers.get(definition.key);
+        return [
+          definition.key,
+          {
+            definition,
+            ...handler,
+            feature: findFeature(features, definition.featureKey),
+            tools: toolDefinitions(modules, definition.allowedToolKeys),
+            release: buildAgentRuntimeRelease(
+              modules,
+              module,
+              definition,
+              handler?.registration,
+            ),
+          },
+        ] as const;
+      }),
+    ),
+  );
+}

package/template/apps/server/src/agent/runtime-bootstrap.ts

@@ -60,6 +60,9 @@ export function registerAgentPlatformRuntime(input: {
   backgroundAi: DeferredAgentBackgroundOperationPortFactory;
 }) {
   const features = input.modules.flatMap(({ features }) => features);
+  const resolveAgentActor = async (actorId: string) =>
+    (await input.runtime.resolveEphemeralActor(actorId)) ??
+    (await resolveCurrentSystemActor(input.systemRepositories, actorId));
   const toolHandlers = new Map([
     ...createSystemToolHandlers(input.systemRepositories, input.runtime),
     ...createModuleToolHandlerMap(input.hosts, {
@@ -95,7 +98,7 @@ export function registerAgentPlatformRuntime(input: {
     input.runtime,
     features,
     input.storage,
-    (actorId) => resolveCurrentSystemActor(input.systemRepositories, actorId),
+    resolveAgentActor,
   );
   registerAiArtifactRoutes(input.app, aiArtifacts, internalToken);
   const remote = new RemoteAgentRuntime({
@@ -173,7 +176,7 @@ export function registerAgentPlatformRuntime(input: {
       input.runtime,
       runAuthorizations,
       input.workflow,
-      (actorId) => resolveCurrentSystemActor(input.systemRepositories, actorId),
+      resolveAgentActor,
     ),
     internalToken,
   );

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

@@ -4,6 +4,7 @@ import type {
 } from "@southwind-ai/server-sdk";
 import type { AuditEvent } from "@southwind-ai/shared";
 import { auditActor, type RequestGuardContext } from "../guards.js";
+import { debugActorAuditMetadata } from "./run-debug-authorization.js";
 import type { RegisteredTool } from "./tool-registry.js";
 
 export function toolJsonBytes(value: ModuleToolInput | ModuleToolResult) {
@@ -26,6 +27,7 @@ export function toolEvent(
     module: tool.module,
     requestId: context.requestId,
     metadata: {
+      ...debugActorAuditMetadata(context.actor),
       inputBytes: toolJsonBytes(input),
       outputBytes: toolJsonBytes(result),
       executionMode,
@@ -53,6 +55,7 @@ export function sandboxFailureEvent(
     module: tool.module,
     requestId: context.requestId,
     metadata: {
+      ...debugActorAuditMetadata(context.actor),
       inputBytes: toolJsonBytes(input),
       executionMode: "sandbox",
       failureKind: policyDenied ? "policy-denied" : "business-failure",

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

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { ModuleToolHandlers } from "./tool-registry.js";
 import { createFoundationSnapshot, loadSystemModules } from "../foundation.js";
+import { bindModuleUserProjection } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
 import { createSystemRepositories } from "../system/seed.js";
 import { createSystemToolHandlers } from "./routes.js";
@@ -92,6 +93,34 @@ describe("Governed Tool Registry", () => {
     });
     expect(JSON.stringify(event)).not.toContain("permissionKeys");
   });
+
+  test("调试 Tool 审计保留服务主体并标注真实数据用户", async () => {
+    const fixture = await createFixture();
+    fixture.context.actor = bindModuleUserProjection(
+      {
+        ...fixture.context.actor,
+        id: "service_adk_debug",
+        type: "service",
+        name: "ADK 开发调试",
+      },
+      "user_dev_admin",
+    );
+
+    await fixture.registry.execute(
+      "system.features.list",
+      { page: 1 },
+      fixture.context,
+    );
+
+    const event = fixture.runtime.auditSink.list().at(-1);
+    expect(event?.actor).toMatchObject({
+      id: "service_adk_debug",
+      type: "service",
+    });
+    expect(event?.metadata).toMatchObject({
+      debugDataActorId: "user_dev_admin",
+    });
+  });
 });
 
 async function createFixture() {