create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import type { ModuleAgentToolInvocation } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { WorkflowService } from "../workflow/service.js";
+import type { RegisteredTool } from "./tool-registry.js";
+
+type ApprovalTool = Pick<
+  RegisteredTool,
+  "key" | "label" | "approval" | "approvalRoles" | "approvalTimeoutSeconds"
+>;
+
+export class AgentToolApprovalCoordinator {
+  constructor(private readonly workflow?: WorkflowService) {}
+
+  async requireApproved(
+    tool: ApprovalTool,
+    invocation: ModuleAgentToolInvocation,
+    context: RequestGuardContext,
+  ): Promise<string | undefined> {
+    if (tool.approval === "none") return undefined;
+    if (
+      !this.workflow ||
+      !tool.approvalRoles?.length ||
+      !tool.approvalTimeoutSeconds
+    ) {
+      throw new AgentToolApprovalError(
+        "APPROVAL_UNAVAILABLE",
+        "Agent Tool 审批服务不可用",
+      );
+    }
+    const idempotencyKey = approvalKey(invocation);
+    const workItemId = approvalWorkItemId(idempotencyKey);
+    const existing = await this.workflow.get(workItemId, context.actor);
+    const workItem =
+      existing ??
+      (await this.workflow.create(
+        {
+          id: workItemId,
+          title: `Agent 请求执行：${tool.label}`,
+          candidateRoles: [...tool.approvalRoles],
+          dueAt: new Date(
+            Date.parse(context.startedAt) + tool.approvalTimeoutSeconds * 1_000,
+          ).toISOString(),
+          target: {
+            type: "agent-tool-call",
+            id: `${invocation.runId}:${invocation.toolCallId}`,
+            route: `/system/workflow?workItemId=${encodeURIComponent(workItemId)}`,
+          },
+          idempotencyKey,
+        },
+        context.actor,
+      ));
+    const current =
+      (await this.workflow.get(workItem.id, context.actor)) ?? workItem;
+    if (current.status === "approved") return current.id;
+    if (current.status === "pending" || current.status === "claimed") {
+      throw new AgentToolApprovalPending(current.id);
+    }
+    throw new AgentToolApprovalError(
+      outcomeCode(current.status),
+      `Agent Tool 审批已${outcomeLabel(current.status)}`,
+      current.id,
+    );
+  }
+}
+
+export class AgentToolApprovalPending extends Error {
+  constructor(readonly workItemId: string) {
+    super("Agent Tool 等待人工审批");
+    this.name = "AgentToolApprovalPending";
+  }
+}
+
+export type AgentToolApprovalOutcome =
+  | "APPROVAL_REJECTED"
+  | "APPROVAL_CANCELLED"
+  | "APPROVAL_TIMED_OUT"
+  | "APPROVAL_UNAVAILABLE";
+
+export class AgentToolApprovalError extends Error {
+  constructor(
+    readonly code: AgentToolApprovalOutcome,
+    message: string,
+    readonly workItemId?: string,
+  ) {
+    super(message);
+    this.name = "AgentToolApprovalError";
+  }
+}
+
+function approvalKey(invocation: ModuleAgentToolInvocation): string {
+  return `agent-tool:${createHash("sha256")
+    .update(
+      `${invocation.runId}\u0000${invocation.toolCallId}\u0000${invocation.toolKey}`,
+    )
+    .digest("hex")}`;
+}
+
+function approvalWorkItemId(idempotencyKey: string): string {
+  return `agent-tool-${idempotencyKey.slice("agent-tool:".length, 56)}`;
+}
+
+function outcomeCode(
+  status: "rejected" | "cancelled" | "timed-out",
+): AgentToolApprovalOutcome {
+  if (status === "rejected") return "APPROVAL_REJECTED";
+  if (status === "cancelled") return "APPROVAL_CANCELLED";
+  return "APPROVAL_TIMED_OUT";
+}
+
+function outcomeLabel(status: "rejected" | "cancelled" | "timed-out") {
+  if (status === "rejected") return "拒绝";
+  if (status === "cancelled") return "取消";
+  return "超时";
+}

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

@@ -0,0 +1,62 @@
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+import type { AuditEvent } from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { RegisteredTool } from "./tool-registry.js";
+
+export function toolJsonBytes(value: ModuleToolInput | ModuleToolResult) {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+
+export function toolEvent(
+  context: RequestGuardContext,
+  tool: RegisteredTool,
+  input: ModuleToolInput,
+  result: ModuleToolResult,
+  executionMode: "host" | "sandbox",
+): 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: toolJsonBytes(input),
+      outputBytes: toolJsonBytes(result),
+      executionMode,
+    },
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+export function sandboxFailureEvent(
+  context: RequestGuardContext,
+  tool: RegisteredTool,
+  input: ModuleToolInput,
+  error: unknown,
+): AuditEvent {
+  const policyDenied =
+    error instanceof Error &&
+    "code" in error &&
+    error.code === "SANDBOX_POLICY_DENIED";
+  return {
+    id: crypto.randomUUID(),
+    action: tool.auditAction,
+    outcome: policyDenied ? "denied" : "failure",
+    actor: auditActor(context),
+    target: { type: "agent-tool", id: tool.key, label: tool.label },
+    module: tool.module,
+    requestId: context.requestId,
+    metadata: {
+      inputBytes: toolJsonBytes(input),
+      executionMode: "sandbox",
+      failureKind: policyDenied ? "policy-denied" : "business-failure",
+    },
+    occurredAt: new Date().toISOString(),
+  };
+}

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

@@ -7,7 +7,9 @@ import { featureKey } from "@southwind-ai/shared";
 import { buildScopeContext } from "../data-access/context.js";
 import { createRequestGuardContext } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
-import { ExecutionGrantStore } from "./execution-grants.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { buildAgentRuntimeRelease } from "./run-release.js";
 import {
   AgentToolHostError,
   attachExecutionGrant,
@@ -37,7 +39,7 @@ const operation: ModuleAiOperationDefinition = {
 
 describe("受限 Agent Tool Host", () => {
   test("只接受 Grant 绑定 Operation 的 allowedToolKeys", async () => {
-    const fixture = createFixture();
+    const fixture = await createFixture();
     const invocation = attachExecutionGrant(
       {
         runId: "run_1",
@@ -56,7 +58,7 @@ describe("受限 Agent Tool Host", () => {
   });
 
   test("未知 Tool fail closed 且客户端不能提供权限事实", async () => {
-    const fixture = createFixture({
+    const fixture = await createFixture({
       allowedToolKeys: ["business.unknown"],
     });
     const invocation = attachExecutionGrant(
@@ -78,7 +80,7 @@ describe("受限 Agent Tool Host", () => {
   });
 
   test("Tool 不继承 Provider 出网权限且未知网络模式 fail closed", async () => {
-    const fixture = createFixture({
+    const fixture = await createFixture({
       providerEgress: {
         mode: "configured-endpoint",
         deploymentKey: "ai.openai-compatible",
@@ -103,7 +105,7 @@ describe("受限 Agent Tool Host", () => {
   });
 
   test("使用宿主颁发 Actor 与 Scope 执行 Handler", async () => {
-    const fixture = createFixture();
+    const fixture = await createFixture();
     const result = await fixture.host.execute(
       attachExecutionGrant(
         {
@@ -132,7 +134,9 @@ describe("受限 Agent Tool Host", () => {
   });
 });
 
-function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
+async function createFixture(
+  overrides: Partial<ModuleAiOperationDefinition> = {},
+) {
   const currentOperation = { ...operation, ...overrides };
   const module = manifest(currentOperation);
   const runtime = createServerRuntime(
@@ -163,9 +167,30 @@ function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
       resolveLicense: () => ({ status: "valid" }),
     },
   );
-  const grants = new ExecutionGrantStore();
-  const grant = grants.issue(currentOperation, context);
-  grants.bindRun(grant.token, "run_1");
+  const hosts = {
+    aiOperationHandlers: [],
+  } as unknown as InitializedModuleHosts;
+  const authorizations = createTestRunAuthorizationStore();
+  const grant = await authorizations.issue({
+    operationKey: currentOperation.key,
+    releaseId: buildAgentRuntimeRelease(
+      [module],
+      module,
+      currentOperation,
+      undefined,
+    ).releaseId,
+    idempotencyKey: "tool-host-test",
+    authorizationSnapshot: {
+      permissionKey: currentOperation.permissionKey,
+      featureKey: currentOperation.featureKey,
+      allowedToolKeys: [...currentOperation.allowedToolKeys],
+      toolNetworkMode: ((
+        currentOperation.toolNetworkPolicy as { mode?: string } | undefined
+      )?.mode ?? "forbidden") as "forbidden",
+    },
+    context,
+  });
+  await authorizations.bind(grant, "run_1");
   const called: unknown[] = [];
   const handlers = new Map([
     [
@@ -197,12 +222,15 @@ function createFixture(overrides: Partial<ModuleAiOperationDefinition> = {}) {
   return {
     called,
     grant,
-    grants,
+    grants: authorizations,
     host: new RestrictedAgentToolHost(
       [module],
+      hosts,
       new GovernedToolRegistry([module], handlers, runtime),
       runtime,
-      grants,
+      authorizations,
+      undefined,
+      async () => context.actor,
     ),
   };
 }

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

@@ -1,5 +1,6 @@
 import {
   resolveToolNetworkPolicy,
+  type ModuleAiOperationDefinition,
   type ModuleManifest,
 } from "@southwind-ai/modules";
 import type {
@@ -11,47 +12,148 @@ import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import { evaluateAccessGuards } from "../access-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { findFeature } from "../route-guards.js";
-import type { ExecutionGrantStore } from "./execution-grants.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import {
+  AgentRunAuthorizationError,
+  type AgentRunAuthorizationStore,
+} from "./run-authorization.js";
+import { buildAgentRuntimeRelease } from "./run-release.js";
 import { GovernedToolRegistry, ToolExecutionError } from "./tool-registry.js";
+import {
+  AgentToolApprovalCoordinator,
+  AgentToolApprovalError,
+  AgentToolApprovalPending,
+} from "./tool-approval.js";
+import type { WorkflowService } from "../workflow/service.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
   readonly #features: FeatureFlagDefinition[];
+  readonly #operations: Map<string, CurrentAgentOperation>;
+  readonly #approvals: AgentToolApprovalCoordinator;
+  readonly #executions = new Map<
+    string,
+    Promise<{ value: ModuleAiJsonValue }>
+  >();
 
   constructor(
     modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
     private readonly tools: GovernedToolRegistry,
     private readonly runtime: ServerRuntime,
-    private readonly grants: ExecutionGrantStore,
+    private readonly authorizations: AgentRunAuthorizationStore,
+    workflow?: WorkflowService,
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined> = async () => undefined,
   ) {
     this.#features = modules.flatMap(({ features }) => features);
+    const handlers = new Map(
+      hosts.aiOperationHandlers.map(({ registration }) => [
+        registration.operationKey,
+        registration,
+      ]),
+    );
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter((definition) => definition.kind === "agent")
+          .map((definition) => [
+            definition.key,
+            {
+              definition,
+              releaseId: buildAgentRuntimeRelease(
+                modules,
+                module,
+                definition,
+                handlers.get(definition.key),
+              ).releaseId,
+            },
+          ]),
+      ),
+    );
+    this.#approvals = new AgentToolApprovalCoordinator(workflow);
   }
 
   async execute(invocation: ModuleAgentToolInvocation) {
-    const grant = this.grants.require(
-      readGrantToken(invocation),
-      invocation.runId,
-    );
-    if (resolveToolNetworkPolicy(grant.operation).mode !== "forbidden") {
+    let binding;
+    try {
+      binding = await this.authorizations.authorizeTool(
+        readGrantToken(invocation),
+        invocation.runId,
+      );
+    } catch (error) {
+      if (error instanceof AgentRunAuthorizationError) {
+        throw new AgentToolHostError("TOOL_DENIED", error.message);
+      }
+      throw error;
+    }
+    const current = this.#operations.get(binding.operationKey);
+    const currentNetworkMode = current
+      ? safeToolNetworkMode(current.definition)
+      : undefined;
+    if (current && currentNetworkMode !== "forbidden") {
+      throw new AgentToolHostError(
+        "TOOL_DENIED",
+        "Tool 网络策略不受当前 Host 支持",
+      );
+    }
+    if (
+      !current ||
+      current.releaseId !== binding.releaseId ||
+      !sameOperationAuthorization(
+        current.definition,
+        currentNetworkMode,
+        binding,
+      )
+    ) {
+      throw new AgentToolHostError(
+        "TOOL_DENIED",
+        "Agent Operation 版本不再可用",
+      );
+    }
+    if (binding.authorizationSnapshot.toolNetworkMode !== "forbidden") {
       throw new AgentToolHostError(
         "TOOL_DENIED",
         "Tool 网络策略不受当前 Host 支持",
       );
     }
-    if (!grant.operation.allowedToolKeys.includes(invocation.toolKey)) {
+    if (
+      !binding.authorizationSnapshot.allowedToolKeys.includes(
+        invocation.toolKey,
+      )
+    ) {
       throw new AgentToolHostError("TOOL_DENIED", "Operation 未授权该 Tool");
     }
+    const actor = await this.resolveActor(binding.actorId);
+    if (!actor || actor.id !== binding.actorId || actor.type === "anonymous") {
+      throw new AgentToolHostError("TOOL_DENIED", "Agent Run Actor 当前不可用");
+    }
     const context = await this.runtime.createGuardContextForActor(
       new Request("http://agent-tool.internal"),
-      grant.context.actor,
+      actor,
     );
+    try {
+      this.authorizations.assertCurrentScope(binding, context);
+    } catch (error) {
+      if (error instanceof AgentRunAuthorizationError) {
+        throw new AgentToolHostError("TOOL_DENIED", error.message);
+      }
+      throw error;
+    }
     const operationDecision = await evaluateAccessGuards(
       this.runtime,
       context,
       {
-        permission: { permissionKey: grant.operation.permissionKey },
-        feature: findFeature(this.#features, grant.operation.featureKey),
+        permission: {
+          permissionKey: binding.authorizationSnapshot.permissionKey,
+        },
+        feature: findFeature(
+          this.#features,
+          binding.authorizationSnapshot.featureKey,
+        ),
       },
     );
     if (!operationDecision.decision.allowed) {
@@ -60,20 +162,85 @@ export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
         "Agent Operation 当前无权继续执行",
       );
     }
+    const definition = this.tools.definition(invocation.toolKey);
+    if (!definition) {
+      throw new AgentToolHostError("TOOL_DENIED", "Agent Tool 不存在");
+    }
     try {
-      const result = await this.tools.execute(
-        invocation.toolKey,
-        invocation.arguments,
-        context,
-      );
-      return { value: toJsonValue(result) };
+      await this.#approvals.requireApproved(definition, invocation, context);
+      return await this.executeOnce(invocation, context);
     } catch (error) {
+      if (
+        error instanceof AgentToolApprovalPending ||
+        error instanceof AgentToolApprovalError
+      ) {
+        throw error;
+      }
       if (error instanceof ToolExecutionError) {
         throw new AgentToolHostError("TOOL_DENIED", error.message);
       }
       throw error;
     }
   }
+
+  private executeOnce(
+    invocation: ModuleAgentToolInvocation,
+    context: RequestGuardContext,
+  ): Promise<{ value: ModuleAiJsonValue }> {
+    const key = `${invocation.runId}\u0000${invocation.toolCallId}`;
+    const existing = this.#executions.get(key);
+    if (existing) return existing;
+    if (this.#executions.size >= 10_000) {
+      throw new AgentToolHostError(
+        "TOOL_DENIED",
+        "Agent Tool 幂等缓存容量已满",
+      );
+    }
+    const execution = this.tools
+      .execute(
+        invocation.toolKey,
+        invocation.arguments,
+        context,
+        invocation.toolCallId,
+      )
+      .then((result) => ({ value: toJsonValue(result) }));
+    this.#executions.set(key, execution);
+    execution.catch(() => this.#executions.delete(key));
+    return execution;
+  }
+}
+
+interface CurrentAgentOperation {
+  readonly definition: ModuleAiOperationDefinition;
+  readonly releaseId: string;
+}
+
+function sameOperationAuthorization(
+  definition: ModuleAiOperationDefinition,
+  networkMode: "forbidden" | undefined,
+  binding: Awaited<ReturnType<AgentRunAuthorizationStore["authorizeTool"]>>,
+): boolean {
+  const snapshot = binding.authorizationSnapshot;
+  return (
+    definition.permissionKey === snapshot.permissionKey &&
+    definition.featureKey === snapshot.featureKey &&
+    networkMode === snapshot.toolNetworkMode &&
+    definition.allowedToolKeys.length === snapshot.allowedToolKeys.length &&
+    definition.allowedToolKeys.every(
+      (key, index) => key === snapshot.allowedToolKeys[index],
+    )
+  );
+}
+
+function safeToolNetworkMode(
+  definition: ModuleAiOperationDefinition,
+): "forbidden" | undefined {
+  try {
+    const mode = resolveToolNetworkPolicy(definition).mode;
+    return mode === "forbidden" ? mode : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 export class AgentToolHostError extends Error {