create-windy 0.3.2 → 0.3.5

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

@@ -8,6 +8,7 @@ import {
   resolveToolNetworkPolicy,
 } from "@southwind-ai/modules";
 import type {
+  ModuleAiArtifactRef,
   ModuleAiJsonValue,
   ModuleAiOperationHandlerRegistration,
 } from "@southwind-ai/server-sdk";
@@ -17,15 +18,35 @@ 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 { ExecutionGrantStore } from "./execution-grants.js";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import {
+  AgentRunAuthorizationError,
+  type AgentExecutionAuthorization,
+  type AgentRunAuthorizationStore,
+} 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,
 } from "./provider-input-governance.js";
+import { rotateVisionArtifacts, validateOutputSchema } from "./vision-input.js";
+import {
+  assertInputSize,
+  digest,
+  publicRunPath,
+  runtimeErrorStatus,
+  toolDefinitions,
+} from "./run-definition-support.js";
+import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
+import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
+export { AgentRunFacadeError } from "./run-errors.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -37,29 +58,37 @@ export class AgentRunFacade {
     hosts: InitializedModuleHosts,
     private readonly runtime: ServerRuntime,
     private readonly remote: AgentRuntimePort,
-    private readonly grants: ExecutionGrantStore,
+    private readonly authorizations: AgentRunAuthorizationStore,
+    private readonly artifacts?: AiArtifactRuntime,
   ) {
     const handlers = new Map(
-      hosts.aiOperationHandlers.map(({ registration }) => [
+      hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
         registration.operationKey,
-        registration,
+        { registration, moduleName },
       ]),
     );
     const features = modules.flatMap(({ features }) => features);
     this.#operations = new Map(
       modules.flatMap((module) =>
-        (module.aiOperations ?? []).map(
-          (definition) =>
-            [
-              definition.key,
-              {
+        (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: handlers.get(definition.key),
-                feature: findFeature(features, definition.featureKey),
-                tools: toolDefinitions(modules, definition.allowedToolKeys),
-              },
-            ] as const,
-        ),
+                handler?.registration,
+              ),
+            },
+          ] as const;
+        }),
       ),
     );
   }
@@ -69,9 +98,15 @@ export class AgentRunFacade {
     input: ModuleAiJsonValue,
     idempotencyKey: string,
     context: RequestGuardContext,
+    artifacts: readonly ModuleAiArtifactRef[] = [],
+    signal: AbortSignal = AbortSignal.timeout(10_000),
   ): Promise<AgentRuntimeStartResponse> {
     const operation = this.#operations.get(operationKey);
-    if (!operation?.handler) {
+    if (
+      !operation?.registration?.prepare ||
+      !operation.moduleName ||
+      operation.definition.kind !== "agent"
+    ) {
       throw new AgentRunFacadeError(
         "OPERATION_NOT_FOUND",
         "Agent Operation 不存在",
@@ -118,7 +153,7 @@ export class AgentRunFacade {
       }
       throw error;
     }
-    const plan = await operation.handler.prepare(governedInput, {
+    const plan = await operation.registration.prepare(governedInput, {
       actor: toModuleActor(context.actor),
       requestId: context.requestId,
     });
@@ -129,14 +164,48 @@ export class AgentRunFacade {
         400,
       );
     }
-    const grant = this.grants.issue(operation.definition, context);
+    validateOutputSchema(plan.outputSchema, operation.definition);
+    const rotatedArtifacts = await rotateVisionArtifacts(
+      artifacts,
+      operation.definition,
+      operation.moduleName,
+      this.artifacts,
+      context,
+      signal,
+    );
+    const release = operation.release;
+    const traceId = digest({
+      requestId: context.requestId,
+      operationKey,
+    }).slice(0, 32);
+    let authorization: AgentExecutionAuthorization | undefined;
     try {
+      authorization = await this.authorizations.issue({
+        operationKey,
+        releaseId: release.releaseId,
+        idempotencyKey,
+        authorizationSnapshot: {
+          permissionKey: operation.definition.permissionKey,
+          featureKey: operation.definition.featureKey,
+          allowedToolKeys: [...operation.definition.allowedToolKeys],
+          toolNetworkMode: resolveToolNetworkPolicy(operation.definition).mode,
+        },
+        context,
+      });
       const created = await this.remote.start(
         {
+          kind: "agent",
           operationKey,
           input: governedInput,
+          inputModalities: operation.definition.inputModalities ?? ["text"],
+          requiredCapabilities: operation.definition.requiredCapabilities,
+          artifacts: rotatedArtifacts,
           instructions: plan.instructions,
           userPrompt: plan.userPrompt,
+          outputSchemaKey: operation.definition.outputSchemaKey,
+          ...(plan.outputSchema === undefined
+            ? {}
+            : { outputSchema: plan.outputSchema }),
           allowedTools: operation.tools,
           limits: operation.definition.limits,
           providerEgress: resolveProviderEgress(operation.definition),
@@ -145,11 +214,17 @@ export class AgentRunFacade {
             envelopeFields: [],
           },
           toolNetworkPolicy: resolveToolNetworkPolicy(operation.definition),
-          executionGrant: grant.token,
+          executionGrant: authorization.token,
+          release,
+          traceId,
         },
-        idempotencyKey,
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
       );
-      this.grants.bindRun(grant.token, created.runId);
+      await this.authorizations.bind(authorization, created.runId);
       this.runtime.auditSink.recordEvent({
         id: randomUUIDv7(),
         action: operation.definition.auditAction,
@@ -161,65 +236,110 @@ export class AgentRunFacade {
           label: operationKey,
         },
         requestId: context.requestId,
+        metadata: {
+          artifactCount: rotatedArtifacts.length,
+          artifactBytes: rotatedArtifacts.reduce(
+            (total, artifact) => total + artifact.byteSize,
+            0,
+          ),
+          artifactSha256: rotatedArtifacts.map(({ sha256 }) => sha256),
+          requiredCapabilities: operation.definition.requiredCapabilities,
+          inputModalities: operation.definition.inputModalities ?? ["text"],
+          outputSchemaKey: operation.definition.outputSchemaKey,
+          releaseId: release.releaseId,
+          operationVersion: release.operationVersion,
+          workflowVersion: release.workflowVersion,
+          promptVersion: release.promptVersion,
+          routeVersion: release.routeVersion,
+          toolSchemaVersion: release.toolSchemaVersion,
+          traceId,
+        },
         occurredAt: new Date().toISOString(),
       });
       return {
         ...created,
-        eventsUrl: `/api/agent/runs/${created.runId}/events`,
+        eventsUrl: publicRunPath(created.runId, "events", operationKey),
       };
     } catch (error) {
-      this.grants.discard(grant.token);
+      if (authorization) await this.authorizations.discard(authorization);
+      if (error instanceof AgentRuntimeError) {
+        throw new AgentRunFacadeError(
+          error.code,
+          error.message,
+          runtimeErrorStatus(error.code),
+        );
+      }
       throw error;
     }
   }
 
-  authorizeRun(runId: string, context: RequestGuardContext): void {
-    this.grants.requireRun(runId, context.actor.id);
-  }
-}
-
-interface RegisteredOperation {
-  definition: ModuleAiOperationDefinition;
-  handler?: ModuleAiOperationHandlerRegistration;
-  feature: ReturnType<typeof findFeature>;
-  tools: Array<{ key: string; label: string; description: string }>;
-}
-
-export class AgentRunFacadeError extends Error {
-  constructor(
-    readonly code:
-      | "OPERATION_NOT_FOUND"
-      | "INVALID_INPUT"
-      | "FORBIDDEN"
-      | "RUNTIME_UNAVAILABLE",
-    message: string,
-    readonly status: number,
+  async authorizeRun(
+    operationKey: string,
+    runId: string,
+    context: RequestGuardContext,
   ) {
-    super(message);
+    const operation = this.#operations.get(operationKey);
+    if (!operation || operation.definition.kind !== "agent") {
+      throw inaccessibleRun();
+    }
+    try {
+      await this.authorizations.authorizeBrowser(operationKey, runId, context);
+    } catch (error) {
+      if (error instanceof AgentRunAuthorizationError) throw inaccessibleRun();
+      throw error;
+    }
+    const decision = await evaluateAccessGuards(this.runtime, context, {
+      permission: {
+        permissionKey: operation.definition.permissionKey,
+      },
+      feature: operation.feature,
+    });
+    if (!decision.decision.allowed) throw inaccessibleRun();
+    return operation;
   }
-}
 
-function toolDefinitions(
-  modules: readonly ModuleManifest[],
-  allowedKeys: readonly string[],
-) {
-  const tools = new Map(
-    modules.flatMap(({ tools }) => tools.map((tool) => [tool.key, tool])),
-  );
-  return allowedKeys.map((key) => {
-    const tool = tools.get(key);
-    if (!tool) throw new Error(`AI Operation 引用了未知 Tool：${key}`);
+  async attach(
+    operationKey: string,
+    runId: string,
+    cursor: number,
+    context: RequestGuardContext,
+    signal?: AbortSignal,
+  ) {
+    await this.authorizeRun(operationKey, runId, context);
+    let status: AgentRuntimeStatusResponse;
+    try {
+      status = await this.remote.status(runId, signal);
+    } catch (error) {
+      if (error instanceof AgentRuntimeError) {
+        if (error.code === "RUN_CONFLICT") throw inaccessibleRun();
+        throw new AgentRunFacadeError(
+          error.code,
+          error.message,
+          runtimeErrorStatus(error.code),
+        );
+      }
+      throw error;
+    }
+    if (status.runId !== runId) throw inaccessibleRun();
+    if (cursor > status.lastSequence) {
+      throw new AgentRunFacadeError(
+        "INVALID_INPUT",
+        "事件游标超出 Agent Run 当前序列",
+        400,
+      );
+    }
     return {
-      key: tool.key,
-      label: tool.label,
-      description: tool.description,
+      ...status,
+      eventsUrl: publicRunPath(runId, "events", operationKey),
     };
-  });
+  }
 }
 
-function assertInputSize(value: ModuleAiJsonValue, maxBytes: number): void {
-  const size = new TextEncoder().encode(JSON.stringify(value)).byteLength;
-  if (size > maxBytes) {
-    throw new AgentRunFacadeError("INVALID_INPUT", "Agent 输入超过上限", 400);
-  }
+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-release.ts

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type { ModuleAiOperationHandlerRegistration } from "@southwind-ai/server-sdk";
+import type { AgentRuntimeRelease } from "./run-contracts.js";
+
+export function buildAgentRuntimeRelease(
+  modules: readonly ModuleManifest[],
+  module: ModuleManifest,
+  definition: ModuleAiOperationDefinition,
+  registration: ModuleAiOperationHandlerRegistration | undefined,
+): AgentRuntimeRelease {
+  const versions = registration?.release ?? {
+    workflowVersion: module.version,
+    promptVersion: module.version,
+    routeVersion: module.version,
+  };
+  const coordinates = {
+    operationVersion: module.version,
+    ...versions,
+    toolSchemaVersion: operationSchemaDigest(modules, definition),
+    manifestDigest: digest(module),
+  };
+  return {
+    releaseId: `release_${digest(coordinates).slice(0, 40)}`,
+    ...coordinates,
+  };
+}
+
+function operationSchemaDigest(
+  modules: readonly ModuleManifest[],
+  definition: ModuleAiOperationDefinition,
+): string {
+  const schemas = new Map(
+    modules.flatMap(({ jsonSchemas }) =>
+      (jsonSchemas ?? []).map((schema) => [schema.key, schema.schema] as const),
+    ),
+  );
+  const tools = new Map(
+    modules.flatMap((item) =>
+      item.tools.map((tool) => [tool.key, tool] as const),
+    ),
+  );
+  return digest({
+    operationInput: schemas.get(definition.inputSchemaKey),
+    operationOutput: schemas.get(definition.outputSchemaKey),
+    tools: definition.allowedToolKeys.map((key) => {
+      const tool = tools.get(key);
+      return {
+        definition: tool,
+        inputSchema: tool ? schemas.get(tool.inputSchemaKey) : undefined,
+        outputSchema: tool ? schemas.get(tool.outputSchemaKey) : undefined,
+      };
+    }),
+  });
+}
+
+function digest(value: unknown): string {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+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;
+}

package/template/apps/server/src/agent/run-route-input.ts

@@ -0,0 +1,169 @@
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export function parseAttachRequest(body: unknown): {
+  operationKey: string;
+  cursor: number;
+} {
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some((key) => !["operationKey", "cursor"].includes(key))
+  ) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "请求格式无效", 400);
+  }
+  return {
+    operationKey: parseOperationKey(body.operationKey),
+    cursor: parseCursorValue(body.cursor),
+  };
+}
+
+export function parseOperationKey(value: unknown): string {
+  if (
+    typeof value !== "string" ||
+    !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value) ||
+    value.length > 200
+  ) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "Operation Key 无效", 400);
+  }
+  return value;
+}
+
+export function parseStartRequest(body: unknown): {
+  operationKey: string;
+  input: ModuleAiJsonValue;
+  artifacts: readonly ModuleAiArtifactRef[];
+} {
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some(
+      (key) => !["operationKey", "input", "artifacts"].includes(key),
+    )
+  ) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "请求格式无效", 400);
+  }
+  const operationKey = parseOperationKey(body.operationKey);
+  assertJson(body.input);
+  return {
+    operationKey,
+    input: body.input,
+    artifacts: parseArtifacts(body.artifacts),
+  };
+}
+
+export 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 请求字段无效");
+  }
+  if (
+    !body.runId.trim() ||
+    !body.toolCallId.trim() ||
+    body.runId.length > 160 ||
+    body.toolCallId.length > 200 ||
+    body.toolKey.length > 200
+  ) {
+    throw new Error("Tool 请求标识无效");
+  }
+  assertJson(body.arguments);
+  return {
+    executionGrant: body.executionGrant,
+    invocation: {
+      runId: body.runId,
+      toolCallId: body.toolCallId,
+      toolKey: body.toolKey,
+      arguments: body.arguments,
+    },
+  };
+}
+
+export 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 parseCursorValue(value: unknown): number {
+  if (value === undefined) return 0;
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "事件游标无效", 400);
+  }
+  return Number(value);
+}
+
+function parseArtifacts(value: unknown): readonly ModuleAiArtifactRef[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 32) {
+    throw new AgentRunFacadeError(
+      "INVALID_INPUT",
+      "Agent Artifact 列表无效",
+      400,
+    );
+  }
+  return value.map((item) => {
+    if (
+      !isRecord(item) ||
+      typeof item.value !== "string" ||
+      !item.value ||
+      /^[a-z][a-z0-9+.-]*:\/\//i.test(item.value) ||
+      typeof item.mediaType !== "string" ||
+      !item.mediaType ||
+      !Number.isSafeInteger(item.byteSize) ||
+      Number(item.byteSize) < 0 ||
+      typeof item.sha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(item.sha256)
+    ) {
+      throw new AgentRunFacadeError(
+        "INVALID_INPUT",
+        "Agent ArtifactRef 无效",
+        400,
+      );
+    }
+    return {
+      value: item.value,
+      mediaType: item.mediaType,
+      byteSize: Number(item.byteSize),
+      sha256: item.sha256,
+      expiresAt: typeof item.expiresAt === "string" ? item.expiresAt : "",
+    };
+  });
+}
+
+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);
+  }
+}