create-windy 0.3.2 → 0.3.5

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

@@ -1,15 +1,25 @@
 import { timingSafeEqual } from "node:crypto";
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/routes.js";
 import type { AgentRunFacade } from "./run-facade.js";
-import { AgentRunFacadeError } from "./run-facade.js";
+import { AgentRunFacadeError } from "./run-errors.js";
 import type { AgentRuntimePort } from "./run-contracts.js";
 import {
   AgentToolHostError,
   attachExecutionGrant,
   type RestrictedAgentToolHost,
 } from "./tool-host.js";
+import {
+  AgentToolApprovalError,
+  AgentToolApprovalPending,
+} from "./tool-approval.js";
+import {
+  parseAttachRequest,
+  parseCursor,
+  parseOperationKey,
+  parseStartRequest,
+  parseToolRequest,
+} from "./run-route-input.js";
 
 interface RouteContext {
   body?: unknown;
@@ -39,6 +49,8 @@ export function registerAgentRunRoutes(
         request.input,
         idempotencyKey,
         context.guardContext,
+        request.artifacts,
+        context.request.signal,
       );
     } catch (error) {
       return facadeError(error);
@@ -49,7 +61,8 @@ export function registerAgentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
+      const operationKey = parseOperationKey(context.query.operationKey);
+      await facade.authorizeRun(operationKey, runId, context.guardContext);
       const cursor = parseCursor(
         context.query.after,
         context.request.headers.get("last-event-id"),
@@ -64,7 +77,8 @@ export function registerAgentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
+      const operationKey = parseOperationKey(context.query.operationKey);
+      await facade.authorizeRun(operationKey, runId, context.guardContext);
       return await remote.result(runId, context.request.signal);
     } catch (error) {
       return facadeError(error);
@@ -75,7 +89,8 @@ export function registerAgentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
+      const operationKey = parseOperationKey(context.query.operationKey);
+      await facade.authorizeRun(operationKey, runId, context.guardContext);
       const reason =
         isRecord(context.body) && typeof context.body.reason === "string"
           ? context.body.reason.slice(0, 200)
@@ -86,6 +101,23 @@ export function registerAgentRunRoutes(
     }
   });
 
+  app.post("/agent/runs/:runId/attach", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      const request = parseAttachRequest(context.body);
+      return await facade.attach(
+        request.operationKey,
+        runId,
+        request.cursor,
+        context.guardContext,
+        context.request.signal,
+      );
+    } catch (error) {
+      return facadeError(error);
+    }
+  });
+
   app.post("/internal/agent/tools/execute", async (raw) => {
     const context = raw as RouteContext;
     if (!validInternalToken(context.request, internalToken)) {
@@ -97,6 +129,28 @@ export function registerAgentRunRoutes(
         attachExecutionGrant(parsed.invocation, parsed.executionGrant),
       );
     } catch (error) {
+      if (error instanceof AgentToolApprovalPending) {
+        return Response.json(
+          {
+            code: "APPROVAL_REQUIRED",
+            message: error.message,
+            workItemId: error.workItemId,
+            retryable: true,
+          },
+          { status: 202 },
+        );
+      }
+      if (error instanceof AgentToolApprovalError) {
+        return Response.json(
+          {
+            code: error.code,
+            message: error.message,
+            workItemId: error.workItemId,
+            retryable: false,
+          },
+          { status: error.code === "APPROVAL_UNAVAILABLE" ? 503 : 409 },
+        );
+      }
       if (error instanceof AgentToolHostError) {
         return errorResponse(error.code, error.message, 403);
       }
@@ -107,69 +161,10 @@ export function registerAgentRunRoutes(
   return app;
 }
 
-function parseStartRequest(body: unknown): {
-  operationKey: string;
-  input: ModuleAiJsonValue;
-} {
-  if (
-    !isRecord(body) ||
-    Object.keys(body).some((key) => !["operationKey", "input"].includes(key))
-  ) {
-    throw new AgentRunFacadeError("INVALID_INPUT", "请求格式无效", 400);
-  }
-  if (typeof body.operationKey !== "string" || !body.operationKey.trim()) {
-    throw new AgentRunFacadeError("INVALID_INPUT", "Operation Key 无效", 400);
-  }
-  assertJson(body.input);
-  return { operationKey: body.operationKey, input: body.input };
-}
-
-function parseToolRequest(body: unknown) {
-  const allowed = [
-    "executionGrant",
-    "runId",
-    "toolCallId",
-    "toolKey",
-    "arguments",
-  ];
-  if (
-    !isRecord(body) ||
-    Object.keys(body).some((key) => !allowed.includes(key))
-  ) {
-    throw new Error("Tool 请求格式无效");
-  }
-  if (
-    typeof body.executionGrant !== "string" ||
-    typeof body.runId !== "string" ||
-    typeof body.toolCallId !== "string" ||
-    typeof body.toolKey !== "string" ||
-    !isRecord(body.arguments)
-  ) {
-    throw new Error("Tool 请求字段无效");
-  }
-  assertJson(body.arguments);
-  return {
-    executionGrant: body.executionGrant,
-    invocation: {
-      runId: body.runId,
-      toolCallId: body.toolCallId,
-      toolKey: body.toolKey,
-      arguments: body.arguments,
-    },
-  };
-}
-
-function parseCursor(after: string | undefined, header: string | null): number {
-  const values = [after, header].filter(
-    (value): value is string => value !== undefined && value !== null,
-  );
-  if (values.some((value) => !/^\d+$/.test(value))) {
-    throw new AgentRunFacadeError("INVALID_INPUT", "事件游标无效", 400);
-  }
-  return Math.max(0, ...values.map(Number));
-}
-
-function validInternalToken(request: Request, expected: string): boolean {
+export function validInternalToken(
+  request: Request,
+  expected: string,
+): boolean {
   const provided = request.headers
     .get("authorization")
     ?.replace(/^Bearer /, "");
@@ -212,11 +207,3 @@ function required(value: string | undefined): string {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
-
-function assertJson(value: unknown): asserts value is ModuleAiJsonValue {
-  try {
-    if (JSON.stringify(value) === undefined) throw new Error();
-  } catch {
-    throw new AgentRunFacadeError("INVALID_INPUT", "请求必须是 JSON", 400);
-  }
-}

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

@@ -3,12 +3,49 @@ import type { ModuleManifest } from "@southwind-ai/modules";
 import type { InitializedModuleHosts } from "../module-host.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { RouteApp } from "../system/routes.js";
+import type { createStorageRuntime } from "../storage/runtime.js";
+import type { SystemRepositories } from "../system/seed.js";
+import { resolveCurrentSystemActor } from "../system/actor.js";
+import { AiArtifactCodec } from "../ai-artifact/codec.js";
+import { registerAiArtifactRoutes } from "../ai-artifact/routes.js";
+import { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { DocumentRunFacade } from "../document/facade.js";
+import {
+  RemoteDocumentRuntime,
+  unavailableDocumentRuntime,
+} from "../document/remote-runtime.js";
+import { registerDocumentRunRoutes } from "../document/routes.js";
+import { EmbeddingFacade } from "../embedding/facade.js";
+import {
+  RemoteEmbeddingRuntime,
+  unavailableEmbeddingRuntime,
+} from "../embedding/remote-runtime.js";
+import { registerEmbeddingRoutes } from "../embedding/routes.js";
+import { SpeechRunFacade } from "../speech/facade.js";
+import {
+  RemoteSpeechRuntime,
+  unavailableSpeechRuntime,
+} from "../speech/remote-runtime.js";
+import { registerSpeechRunRoutes } from "../speech/routes.js";
 import { ExecutionGrantStore } from "./execution-grants.js";
 import { RemoteAgentRuntime } from "./remote-runtime.js";
-import type { GovernedToolRegistry } from "./tool-registry.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
 import { AgentRunFacade } from "./run-facade.js";
 import { registerAgentRunRoutes } from "./run-routes.js";
 import { RestrictedAgentToolHost } from "./tool-host.js";
+import { createSystemToolHandlers, registerAgentRoutes } from "./routes.js";
+import { createModuleToolHandlerMap } from "../module-host.js";
+import { PlatformMcpAdapter } from "../mcp/adapter.js";
+import { registerMcpRoutes } from "../mcp/routes.js";
+import type { WorkflowService } from "../workflow/service.js";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleAgentRunBindingRepository } from "./drizzle-run-binding-repository.js";
+import { AgentRunAuthorizationStore } from "./run-authorization.js";
+import { InMemoryAgentRunBindingRepository } from "./run-binding-repository.js";
+import { AgentBackgroundOperationExecutor } from "./background-operation.js";
+import type { DeferredAgentBackgroundOperationPortFactory } from "./background-operation-port.js";
+import { UnixSandboxToolClient } from "./sandbox-client.js";
+import { createModuleAiOperationPort } from "../module-host/ai-operation-port.js";
 
 export function registerAgentPlatformRuntime(input: {
   app: RouteApp;
@@ -16,34 +53,153 @@ export function registerAgentPlatformRuntime(input: {
   modules: readonly ModuleManifest[];
   hosts: InitializedModuleHosts;
   runtime: ReturnType<typeof createServerRuntime>;
-  toolRegistry: GovernedToolRegistry;
-}): void {
-  if (!input.platformConfig.enableAI) return;
+  systemRepositories: SystemRepositories;
+  storage: ReturnType<typeof createStorageRuntime>;
+  workflow: WorkflowService;
+  db?: NodePgDatabase;
+  backgroundAi: DeferredAgentBackgroundOperationPortFactory;
+}) {
+  const features = input.modules.flatMap(({ features }) => features);
+  const toolHandlers = new Map([
+    ...createSystemToolHandlers(input.systemRepositories, input.runtime),
+    ...createModuleToolHandlerMap(input.hosts, {
+      runtime: input.runtime,
+      features,
+      storage: input.storage,
+      sandbox: process.env.TOOL_SANDBOX_SOCKET?.trim()
+        ? new UnixSandboxToolClient(process.env.TOOL_SANDBOX_SOCKET)
+        : undefined,
+    }),
+  ]);
+  const toolRegistry = new GovernedToolRegistry(
+    input.modules,
+    toolHandlers,
+    input.runtime,
+  );
+  registerAgentRoutes(input.app, toolRegistry);
+  registerMcpRoutes(
+    input.app,
+    new PlatformMcpAdapter(toolRegistry, input.runtime, features),
+  );
+  if (!input.platformConfig.enableAI) {
+    return {
+      toolHandlers,
+      aiArtifacts: undefined,
+      aiOperations: undefined,
+    };
+  }
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
+  const aiArtifacts = new AiArtifactRuntime(
+    new AiArtifactCodec(requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET")),
+    input.hosts,
+    input.runtime,
+    features,
+    input.storage,
+    (actorId) => resolveCurrentSystemActor(input.systemRepositories, actorId),
+  );
+  registerAiArtifactRoutes(input.app, aiArtifacts, internalToken);
   const remote = new RemoteAgentRuntime({
     baseUrl: process.env.AGENT_SERVER_URL || "http://agent-server:8080",
     internalToken,
     toolHostUrl: process.env.AGENT_TOOL_HOST_URL || "http://server:9747",
   });
   const grants = new ExecutionGrantStore();
+  const runAuthorizations = new AgentRunAuthorizationStore(
+    input.db
+      ? new DrizzleAgentRunBindingRepository(input.db)
+      : new InMemoryAgentRunBindingRepository(),
+    internalToken,
+  );
+  const documentRemote = process.env.DOCUMENT_SERVER_URL?.trim()
+    ? new RemoteDocumentRuntime({
+        baseUrl: process.env.DOCUMENT_SERVER_URL,
+        internalToken,
+      })
+    : unavailableDocumentRuntime;
+  const documentFacade = new DocumentRunFacade(
+    input.modules,
+    input.hosts,
+    input.runtime,
+    documentRemote,
+    aiArtifacts,
+    grants,
+  );
+  registerDocumentRunRoutes(input.app, documentFacade, documentRemote);
+  const speechRemote = process.env.SPEECH_SERVER_URL?.trim()
+    ? new RemoteSpeechRuntime({
+        baseUrl: process.env.SPEECH_SERVER_URL,
+        internalToken,
+      })
+    : unavailableSpeechRuntime;
+  const speechFacade = new SpeechRunFacade(
+    input.modules,
+    input.hosts,
+    input.runtime,
+    speechRemote,
+    aiArtifacts,
+    grants,
+  );
+  registerSpeechRunRoutes(input.app, speechFacade, speechRemote);
+  const embeddingRemote = process.env.EMBEDDING_SERVER_URL?.trim()
+    ? new RemoteEmbeddingRuntime({
+        baseUrl: process.env.EMBEDDING_SERVER_URL,
+        internalToken,
+      })
+    : unavailableEmbeddingRuntime;
+  const embeddingFacade = new EmbeddingFacade(
+    input.modules,
+    input.hosts,
+    input.runtime,
+    embeddingRemote,
+    aiArtifacts,
+  );
+  registerEmbeddingRoutes(input.app, embeddingFacade);
+  const agentFacade = new AgentRunFacade(
+    input.modules,
+    input.hosts,
+    input.runtime,
+    remote,
+    runAuthorizations,
+    aiArtifacts,
+  );
   registerAgentRunRoutes(
     input.app,
-    new AgentRunFacade(
-      input.modules,
-      input.hosts,
-      input.runtime,
-      remote,
-      grants,
-    ),
+    agentFacade,
     remote,
     new RestrictedAgentToolHost(
       input.modules,
-      input.toolRegistry,
+      input.hosts,
+      toolRegistry,
       input.runtime,
-      grants,
+      runAuthorizations,
+      input.workflow,
+      (actorId) => resolveCurrentSystemActor(input.systemRepositories, actorId),
     ),
     internalToken,
   );
+  input.backgroundAi.bind(
+    new AgentBackgroundOperationExecutor(
+      input.modules,
+      input.hosts,
+      agentFacade,
+      remote,
+    ),
+  );
+  const aiOperations = (
+    moduleName: string,
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    signal: AbortSignal,
+  ) =>
+    createModuleAiOperationPort(moduleName, guardContext, signal, {
+      agentFacade,
+      agentRemote: remote,
+      documentFacade,
+      documentRemote,
+      speechFacade,
+      speechRemote,
+      embeddingFacade,
+    });
+  return { toolHandlers, aiArtifacts, aiOperations };
 }
 
 function requiredEnvironment(key: string): string {

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

@@ -0,0 +1,200 @@
+import { readFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+import {
+  type SandboxToolRequest,
+  type SandboxToolResponse,
+  signSandboxRequest,
+} from "./sandbox-protocol.js";
+
+const maxResponseBytes = 2 * 1_024 * 1_024;
+
+export interface SandboxToolExecutor {
+  execute(
+    toolKey: string,
+    input: ModuleToolInput,
+    idempotencyKey: string,
+    signal: AbortSignal,
+  ): Promise<ModuleToolResult>;
+}
+
+export class UnixSandboxToolClient implements SandboxToolExecutor {
+  constructor(private readonly socketPath: string) {
+    if (
+      !socketPath.startsWith("/") ||
+      socketPath.includes("..") ||
+      socketPath.length > 180
+    ) {
+      throw new Error("Tool Sandbox Socket 路径无效");
+    }
+  }
+
+  async execute(
+    toolKey: string,
+    input: ModuleToolInput,
+    idempotencyKey: string,
+    signal: AbortSignal,
+  ): Promise<ModuleToolResult> {
+    signal.throwIfAborted();
+    const invocationId = crypto.randomUUID();
+    let lastError: unknown;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        return await this.attempt(
+          { invocationId, toolKey, idempotencyKey, input },
+          signal,
+        );
+      } catch (error) {
+        lastError = error;
+        if (
+          signal.aborted ||
+          (error instanceof SandboxToolClientError &&
+            !error.retryableConnection)
+        ) {
+          throw error;
+        }
+      }
+    }
+    throw asClientError(lastError);
+  }
+
+  private async attempt(
+    input: Omit<SandboxToolRequest, "deadline" | "grant">,
+    signal: AbortSignal,
+  ) {
+    const key = await readFile(`${this.socketPath}.key`);
+    if (key.byteLength !== 32) {
+      throw new SandboxToolClientError(
+        "SANDBOX_AUTH_INVALID",
+        "Tool Sandbox 授权材料无效",
+        true,
+      );
+    }
+    const unsigned = {
+      ...input,
+      deadline: Date.now() + 5 * 60_000,
+    };
+    const request: SandboxToolRequest = {
+      ...unsigned,
+      grant: signSandboxRequest(unsigned, key),
+    };
+    const response = await exchange(this.socketPath, request, signal);
+    if (response.invocationId !== input.invocationId) {
+      throw new SandboxToolClientError(
+        "SANDBOX_AUTH_INVALID",
+        "Tool Sandbox 响应标识无效",
+        true,
+      );
+    }
+    if (!response.ok) {
+      throw new SandboxToolClientError(
+        response.code,
+        response.message,
+        response.code === "SANDBOX_AUTH_INVALID",
+      );
+    }
+    return response.result;
+  }
+}
+
+export class SandboxToolClientError extends Error {
+  constructor(
+    readonly code:
+      | "SANDBOX_UNAVAILABLE"
+      | "SANDBOX_AUTH_INVALID"
+      | "SANDBOX_POLICY_DENIED"
+      | "SANDBOX_INPUT_INVALID"
+      | "SANDBOX_HANDLER_FAILED"
+      | "SANDBOX_TIMEOUT",
+    message: string,
+    readonly retryableConnection: boolean,
+  ) {
+    super(message);
+  }
+}
+
+async function exchange(
+  socketPath: string,
+  request: SandboxToolRequest,
+  signal: AbortSignal,
+): Promise<SandboxToolResponse> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    let body = "";
+    const fail = (error: unknown) => {
+      socket.destroy();
+      reject(asClientError(error));
+    };
+    const abort = () => fail(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    socket.setEncoding("utf8");
+    socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", (chunk: string) => {
+      body += chunk;
+      if (Buffer.byteLength(body) > maxResponseBytes) {
+        fail(new Error("Tool Sandbox 响应超过上限"));
+        return;
+      }
+      const newline = body.indexOf("\n");
+      if (newline < 0) return;
+      try {
+        resolve(parseResponse(JSON.parse(body.slice(0, newline))));
+        socket.end();
+      } catch (error) {
+        fail(error);
+      }
+    });
+    socket.once("error", fail);
+    socket.once("close", () => {
+      signal.removeEventListener("abort", abort);
+      if (!body.includes("\n")) {
+        reject(
+          new SandboxToolClientError(
+            "SANDBOX_UNAVAILABLE",
+            "Tool Sandbox 连接中断",
+            true,
+          ),
+        );
+      }
+    });
+  });
+}
+
+function parseResponse(value: unknown): SandboxToolResponse {
+  if (
+    !isRecord(value) ||
+    typeof value.invocationId !== "string" ||
+    typeof value.ok !== "boolean"
+  ) {
+    throw new Error("Tool Sandbox 响应无效");
+  }
+  if (value.ok && isRecord(value.result)) {
+    return value as unknown as SandboxToolResponse;
+  }
+  if (
+    !value.ok &&
+    typeof value.code === "string" &&
+    typeof value.message === "string" &&
+    typeof value.retryable === "boolean"
+  ) {
+    return value as unknown as SandboxToolResponse;
+  }
+  throw new Error("Tool Sandbox 响应字段无效");
+}
+
+function asClientError(error: unknown) {
+  if (error instanceof SandboxToolClientError) return error;
+  return new SandboxToolClientError(
+    "SANDBOX_UNAVAILABLE",
+    "Tool Sandbox 暂不可用",
+    true,
+  );
+}
+
+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-protocol.ts

@@ -0,0 +1,76 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type {
+  ModuleToolInput,
+  ModuleToolResult,
+} from "@southwind-ai/server-sdk";
+
+export interface SandboxToolRequest {
+  readonly invocationId: string;
+  readonly toolKey: string;
+  readonly idempotencyKey: string;
+  readonly deadline: number;
+  readonly input: ModuleToolInput;
+  readonly grant: string;
+}
+
+export interface SandboxToolSuccess {
+  readonly invocationId: string;
+  readonly ok: true;
+  readonly result: ModuleToolResult;
+}
+
+export interface SandboxToolFailure {
+  readonly invocationId: string;
+  readonly ok: false;
+  readonly code:
+    | "SANDBOX_AUTH_INVALID"
+    | "SANDBOX_POLICY_DENIED"
+    | "SANDBOX_INPUT_INVALID"
+    | "SANDBOX_HANDLER_FAILED"
+    | "SANDBOX_TIMEOUT";
+  readonly message: string;
+  readonly retryable: boolean;
+}
+
+export type SandboxToolResponse = SandboxToolSuccess | SandboxToolFailure;
+
+export function signSandboxRequest(
+  request: Omit<SandboxToolRequest, "grant">,
+  key: Uint8Array,
+): string {
+  return createHmac("sha256", key).update(canonicalJson(request)).digest("hex");
+}
+
+export function validSandboxGrant(
+  request: SandboxToolRequest,
+  key: Uint8Array,
+): boolean {
+  if (!/^[a-f0-9]{64}$/.test(request.grant)) return false;
+  const expected = signSandboxRequest(
+    {
+      invocationId: request.invocationId,
+      toolKey: request.toolKey,
+      idempotencyKey: request.idempotencyKey,
+      deadline: request.deadline,
+      input: request.input,
+    },
+    key,
+  );
+  return timingSafeEqual(Buffer.from(request.grant), Buffer.from(expected));
+}
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalValue(item)]),
+    );
+  }
+  return value;
+}