create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,205 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleSandboxToolHandlerRegistration,
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+import { requireModuleNamespace } from "@southwind-ai/server-sdk";
+
+export class SandboxToolRegistry {
+  readonly #handlers: ReadonlyMap<string, SandboxedHandler>;
+
+  constructor(
+    installations: readonly InstallableServerModule<ModuleManifest>[],
+  ) {
+    const handlers = new Map<string, SandboxedHandler>();
+    for (const installation of installations) {
+      installation.setupSandbox?.({
+        moduleName: installation.manifest.name,
+        registerToolHandlers: (registrations) => {
+          for (const registration of registrations) {
+            register(installation.manifest, registration, handlers);
+          }
+        },
+      });
+    }
+    this.#handlers = handlers;
+  }
+
+  keys(): readonly string[] {
+    return [...this.#handlers.keys()].sort();
+  }
+
+  async execute(
+    toolKey: string,
+    input: ModuleToolInput,
+    idempotencyKey: string,
+  ): Promise<ModuleToolResult> {
+    const handler = this.#handlers.get(toolKey);
+    if (!handler) {
+      throw new SandboxExecutionError(
+        "SANDBOX_POLICY_DENIED",
+        "Tool 未注册为隔离执行",
+        false,
+      );
+    }
+    enforceBytes(input, handler.maxInputBytes, "SANDBOX_INPUT_INVALID");
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort("timeout"),
+      handler.maxDurationSeconds * 1_000,
+    );
+    try {
+      const result = await executeHandler(
+        handler,
+        input,
+        idempotencyKey,
+        controller.signal,
+      );
+      if (!isRecord(result)) {
+        throw new SandboxExecutionError(
+          "SANDBOX_HANDLER_FAILED",
+          "隔离 Tool 输出必须是 JSON 对象",
+          false,
+        );
+      }
+      enforceBytes(result, handler.maxOutputBytes, "SANDBOX_HANDLER_FAILED");
+      return structuredClone(result);
+    } catch (error) {
+      if (error instanceof SandboxExecutionError) throw error;
+      if (controller.signal.aborted) {
+        throw new SandboxExecutionError(
+          "SANDBOX_TIMEOUT",
+          "隔离 Tool 执行超时",
+          true,
+        );
+      }
+      if (isNetworkDenied(error)) {
+        throw new SandboxExecutionError(
+          "SANDBOX_POLICY_DENIED",
+          "隔离策略拒绝 Tool 出网",
+          false,
+        );
+      }
+      throw new SandboxExecutionError(
+        "SANDBOX_HANDLER_FAILED",
+        "隔离 Tool 业务执行失败",
+        false,
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+async function executeHandler(
+  handler: SandboxedHandler,
+  input: ModuleToolInput,
+  idempotencyKey: string,
+  signal: AbortSignal,
+): Promise<ModuleToolResult> {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve()
+      .then(() => handler.execute(input, { idempotencyKey, signal }))
+      .then(
+        (value) => {
+          signal.removeEventListener("abort", abort);
+          resolve(value);
+        },
+        (error: unknown) => {
+          signal.removeEventListener("abort", abort);
+          reject(error);
+        },
+      );
+  });
+}
+
+export class SandboxExecutionError extends Error {
+  constructor(
+    readonly code:
+      | "SANDBOX_POLICY_DENIED"
+      | "SANDBOX_INPUT_INVALID"
+      | "SANDBOX_HANDLER_FAILED"
+      | "SANDBOX_TIMEOUT",
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+  }
+}
+
+interface SandboxedHandler extends ModuleSandboxToolHandlerRegistration {
+  readonly maxDurationSeconds: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+}
+
+function register(
+  manifest: ModuleManifest,
+  registration: ModuleSandboxToolHandlerRegistration,
+  handlers: Map<string, SandboxedHandler>,
+) {
+  requireModuleNamespace(
+    "Sandbox Agent Tool",
+    registration.toolKey,
+    manifest.name,
+  );
+  const definition = manifest.tools.find(
+    ({ key }) => key === registration.toolKey,
+  );
+  if (!definition) {
+    throw new Error(
+      `Sandbox Agent Tool Handler 未在 Manifest 声明：${registration.toolKey}`,
+    );
+  }
+  if (handlers.has(registration.toolKey)) {
+    throw new Error(`Sandbox Agent Tool Handler 重复：${registration.toolKey}`);
+  }
+  handlers.set(registration.toolKey, {
+    ...registration,
+    maxDurationSeconds: definition.limits.maxDurationSeconds,
+    maxInputBytes: definition.limits.maxInputBytes,
+    maxOutputBytes: definition.limits.maxOutputBytes,
+  });
+}
+
+function enforceBytes(
+  value: ModuleToolInput | ModuleToolResult,
+  maximum: number,
+  code: "SANDBOX_INPUT_INVALID" | "SANDBOX_HANDLER_FAILED",
+) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  if (bytes > maximum) {
+    throw new SandboxExecutionError(
+      code,
+      `隔离 Tool JSON 超过 ${maximum} 字节`,
+      false,
+    );
+  }
+}
+
+function isNetworkDenied(error: unknown): boolean {
+  const code =
+    isRecord(error) && typeof error.code === "string"
+      ? error.code
+      : isRecord(error) &&
+          isRecord(error.cause) &&
+          typeof error.cause.code === "string"
+        ? error.cause.code
+        : "";
+  return [
+    "EAI_AGAIN",
+    "ENETDOWN",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "EPERM",
+    "EACCES",
+  ].includes(code);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/apps/server/src/agent/sandbox-runtime.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+import { UnixSandboxToolClient } from "./sandbox-client.js";
+import { SandboxToolRegistry } from "./sandbox-registry.js";
+import { startSandboxWorker } from "./sandbox-worker-server.js";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe("Tool Sandbox Runtime", () => {
+  test("只通过 UDS 和短时 Grant 执行显式隔离 Handler", async () => {
+    const root = await temporaryRoot();
+    const socketPath = join(root, "worker.sock");
+    const registry = new SandboxToolRegistry([sandboxModule()]);
+    const worker = await startSandboxWorker(socketPath, registry);
+    const client = new UnixSandboxToolClient(socketPath);
+
+    await expect(
+      client.execute(
+        "business.safe.echo",
+        { value: "hello" },
+        "call-1",
+        new AbortController().signal,
+      ),
+    ).resolves.toEqual({ value: "hello", idempotencyKey: "call-1" });
+
+    await worker.close();
+  });
+
+  test("网络系统调用失败与业务异常使用不同稳定错误", async () => {
+    const registry = new SandboxToolRegistry([sandboxModule()]);
+
+    await expect(
+      registry.execute("business.safe.network", {}, "call-network"),
+    ).rejects.toMatchObject({
+      code: "SANDBOX_POLICY_DENIED",
+      message: "隔离策略拒绝 Tool 出网",
+    });
+    await expect(
+      registry.execute("business.safe.failure", {}, "call-failure"),
+    ).rejects.toMatchObject({
+      code: "SANDBOX_HANDLER_FAILED",
+      message: "隔离 Tool 业务执行失败",
+    });
+  });
+});
+
+function sandboxModule(): InstallableServerModule<ModuleManifest> {
+  const manifest = sandboxManifest();
+  return {
+    manifest,
+    setup() {},
+    setupSandbox(host) {
+      host.registerToolHandlers([
+        {
+          toolKey: "business.safe.echo",
+          execute(input, context) {
+            return {
+              value: input.value ?? null,
+              idempotencyKey: context.idempotencyKey,
+            };
+          },
+        },
+        {
+          toolKey: "business.safe.network",
+          execute() {
+            throw Object.assign(new Error("blocked"), {
+              code: "ENETUNREACH",
+            });
+          },
+        },
+        {
+          toolKey: "business.safe.failure",
+          execute() {
+            throw new Error("private business detail");
+          },
+        },
+      ]);
+    },
+  };
+}
+
+function sandboxManifest(): ModuleManifest {
+  const tools = ["echo", "network", "failure"].map((name) => ({
+    key: `business.safe.${name}`,
+    label: name,
+    description: name,
+    inputSchemaKey: "business.safe.input.v1",
+    outputSchemaKey: "business.safe.output.v1",
+    operation: "query" as const,
+    permissionKey: "business.safe.read",
+    featureKey: "business.safe",
+    auditAction: "business.safe.execute",
+    scopeMode: "request" as const,
+    dataClassification: "internal" as const,
+    idempotency: "supported" as const,
+    approval: "none" as const,
+    limits: {
+      maxDurationSeconds: 5,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 4_096,
+    },
+  }));
+  return {
+    name: "business",
+    version: "1.0.0",
+    label: "业务",
+    description: "业务",
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [],
+    tasks: [],
+    tools,
+    providers: [],
+    auditActions: [],
+  };
+}
+
+async function temporaryRoot() {
+  const root = await mkdtemp(join(tmpdir(), "windy-tool-sandbox-"));
+  roots.push(root);
+  return root;
+}

package/template/apps/server/src/agent/sandbox-worker-server.ts

@@ -0,0 +1,195 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createServer, type Socket } from "node:net";
+import {
+  type SandboxToolFailure,
+  type SandboxToolRequest,
+  type SandboxToolResponse,
+  validSandboxGrant,
+} from "./sandbox-protocol.js";
+import {
+  SandboxExecutionError,
+  type SandboxToolRegistry,
+} from "./sandbox-registry.js";
+
+const maxMessageBytes = 2 * 1_024 * 1_024;
+
+export async function startSandboxWorker(
+  socketPath: string,
+  registry: SandboxToolRegistry,
+) {
+  assertSocketPath(socketPath);
+  await mkdir(dirname(socketPath), { recursive: true });
+  await removeIfPresent(socketPath);
+  const key = randomBytes(32);
+  await writeFile(`${socketPath}.key`, key, { mode: 0o600 });
+  const server = createServer((socket) => consume(socket, registry, key));
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  return {
+    async close() {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+      await Promise.all([
+        removeIfPresent(socketPath),
+        removeIfPresent(`${socketPath}.key`),
+      ]);
+    },
+  };
+}
+
+export async function runSandboxWorkerUntilSignal(
+  socketPath: string,
+  registry: SandboxToolRegistry,
+) {
+  const worker = await startSandboxWorker(socketPath, registry);
+  await new Promise<void>((resolve) => {
+    process.once("SIGINT", resolve);
+    process.once("SIGTERM", resolve);
+  });
+  await worker.close();
+}
+
+function consume(
+  socket: Socket,
+  registry: SandboxToolRegistry,
+  key: Uint8Array,
+) {
+  let body = "";
+  socket.setEncoding("utf8");
+  socket.on("data", (chunk: string) => {
+    body += chunk;
+    if (Buffer.byteLength(body) > maxMessageBytes) {
+      socket.end(
+        response({
+          invocationId: "unknown",
+          ok: false,
+          code: "SANDBOX_INPUT_INVALID",
+          message: "隔离 Tool 请求超过上限",
+          retryable: false,
+        }),
+      );
+      return;
+    }
+    const newline = body.indexOf("\n");
+    if (newline < 0) return;
+    const line = body.slice(0, newline);
+    body = "";
+    void handle(line, registry, key).then((value) =>
+      socket.end(response(value)),
+    );
+  });
+}
+
+async function handle(
+  line: string,
+  registry: SandboxToolRegistry,
+  key: Uint8Array,
+): Promise<SandboxToolResponse> {
+  let request: SandboxToolRequest;
+  try {
+    request = parseRequest(JSON.parse(line));
+  } catch {
+    return failure("unknown", "SANDBOX_INPUT_INVALID", "隔离 Tool 请求无效");
+  }
+  if (
+    request.deadline <= Date.now() ||
+    request.deadline > Date.now() + 10 * 60_000 ||
+    !validSandboxGrant(request, key)
+  ) {
+    return failure(
+      request.invocationId,
+      "SANDBOX_AUTH_INVALID",
+      "隔离 Tool 调用授权无效",
+    );
+  }
+  try {
+    return {
+      invocationId: request.invocationId,
+      ok: true,
+      result: await registry.execute(
+        request.toolKey,
+        request.input,
+        request.idempotencyKey,
+      ),
+    };
+  } catch (error) {
+    if (error instanceof SandboxExecutionError) {
+      return {
+        invocationId: request.invocationId,
+        ok: false,
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+      };
+    }
+    return failure(
+      request.invocationId,
+      "SANDBOX_HANDLER_FAILED",
+      "隔离 Tool 执行失败",
+    );
+  }
+}
+
+function parseRequest(value: unknown): SandboxToolRequest {
+  if (
+    !isRecord(value) ||
+    Object.keys(value).some(
+      (key) =>
+        ![
+          "invocationId",
+          "toolKey",
+          "idempotencyKey",
+          "deadline",
+          "input",
+          "grant",
+        ].includes(key),
+    ) ||
+    typeof value.invocationId !== "string" ||
+    typeof value.toolKey !== "string" ||
+    typeof value.idempotencyKey !== "string" ||
+    !Number.isSafeInteger(value.deadline) ||
+    !isRecord(value.input) ||
+    typeof value.grant !== "string"
+  ) {
+    throw new Error("invalid request");
+  }
+  return value as unknown as SandboxToolRequest;
+}
+
+function failure(
+  invocationId: string,
+  code: SandboxToolFailure["code"],
+  message: string,
+): SandboxToolFailure {
+  return { invocationId, ok: false, code, message, retryable: false };
+}
+
+function response(value: SandboxToolResponse) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+function assertSocketPath(value: string) {
+  if (!value.startsWith("/") || value.includes("..") || value.length > 180) {
+    throw new Error("Tool Sandbox Socket 路径无效");
+  }
+}
+
+async function removeIfPresent(path: string) {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (!isRecord(error) || error.code !== "ENOENT") throw error;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/apps/server/src/agent/sandbox-worker.ts

@@ -0,0 +1,12 @@
+import { installedBusinessModules } from "../installed-business-modules.js";
+import { SandboxToolRegistry } from "./sandbox-registry.js";
+import { runSandboxWorkerUntilSignal } from "./sandbox-worker-server.js";
+
+const socketPath =
+  process.env.TOOL_SANDBOX_SOCKET?.trim() ||
+  "/run/windy-tool-sandbox/worker.sock";
+
+await runSandboxWorkerUntilSignal(
+  socketPath,
+  new SandboxToolRegistry(installedBusinessModules),
+);

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAgentToolInvocation } from "@southwind-ai/server-sdk";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { InMemoryWorkflowRepository } from "../workflow/repository.js";
+import { WorkflowService } from "../workflow/service.js";
+import {
+  AgentToolApprovalCoordinator,
+  AgentToolApprovalPending,
+} from "./tool-approval.js";
+
+const actor: RequestActor = {
+  id: "actor-1",
+  type: "user",
+  name: "复核员",
+  roleCodes: ["case-reviewer"],
+  permissionKeys: [],
+};
+const context: RequestGuardContext = {
+  requestId: "request-1",
+  actor,
+  startedAt: "2026-07-27T00:00:00.000Z",
+};
+const invocation: ModuleAgentToolInvocation = {
+  runId: "run-1",
+  toolCallId: "tool-1",
+  toolKey: "case.finding.merge",
+  arguments: { expectedVersion: 3 },
+};
+const tool = {
+  key: "case.finding.merge",
+  label: "归并线索",
+  approval: "required" as const,
+  approvalRoles: [{ code: "case-reviewer", name: "案件复核员" }],
+  approvalTimeoutSeconds: 3_600,
+};
+
+describe("Agent Tool 审批协调器", () => {
+  test("副作用前等待持久化 Work Item，批准后复用同一审批", async () => {
+    const workflow = new WorkflowService(
+      new InMemoryWorkflowRepository(),
+      { resolve: async () => undefined },
+      () => new Date("2026-07-27T00:00:00.000Z"),
+    );
+    const coordinator = new AgentToolApprovalCoordinator(workflow);
+    let workItemId = "";
+
+    try {
+      await coordinator.requireApproved(tool, invocation, context);
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentToolApprovalPending);
+      workItemId = (error as AgentToolApprovalPending).workItemId;
+    }
+
+    const pending = await workflow.get(workItemId, actor);
+    expect(pending?.target.id).toBe("run-1:tool-1");
+    const claimed = await workflow.claim(
+      workItemId,
+      { expectedVersion: pending!.version, idempotencyKey: "claim-1" },
+      actor,
+    );
+    await workflow.approve(
+      workItemId,
+      {
+        expectedVersion: claimed.workItem.version,
+        idempotencyKey: "approve-1",
+        reason: "事实与版本均已核对",
+      },
+      actor,
+    );
+
+    await expect(
+      coordinator.requireApproved(tool, invocation, context),
+    ).resolves.toBe(workItemId);
+  });
+});